Web Console
CoreLib 内置了一个轻量级 HTTP Web Console。它由 WebConsoleService 启动，前端资源打包在 EmakiCoreLib/src/main/resources/web，运行时通过浏览器访问服务端内置 HTTP 端口，可查看模块状态、浏览配置树、编辑结构化 YAML、打开源码编辑器、管理脚本/GUI/物品文件，并加载各业务模块声明的 Web 端扩展。
Web Console 是高权限维护入口。启用前必须修改默认密码，并优先绑定到
127.0.0.1、内网地址或受保护的反向代理后方。
命令入口
CoreLib 在 plugin.yml 中注册主命令 /emakicorelib，别名 /corelib、/emakicore。
| 命令 | 说明 | 权限 |
|---|---|---|
/emakicorelib help | 显示 CoreLib 命令帮助。 | 无 |
/emakicorelib web | 输出 Web Console 地址，并在可点击环境中给出打开链接。别名：webconsole、url、link。 | emakicorelib.web |
/emakicorelib reload | 重载 CoreLib 配置、动作系统与 Web Console。 | emakicorelib.reload |
| `/emakicorelib webdebug [all | frontend | backend]` |
权限节点：
| 权限 | 默认 | 说明 |
|---|---|---|
emakicorelib.admin | op | 管理总权限，包含 Web Console 与 reload。 |
emakicorelib.web | op | 查看 Web Console 链接。 |
emakicorelib.reload | op | 重载 CoreLib，并允许切换 Web Console 调试日志。 |
启用配置
配置位于 plugins/EmakiCoreLib/config.yml > web_console。当前默认资源文件只写出最小安全配置：
yaml
web_console:
enabled: false
host: "127.0.0.1"
port: 38765
public_access_warning: true
auth:
username: "EmakiAdmin"
password: "EmakiAdminPassword"
session_timeout_minutes: 60
security:
allow_config_write: false
max_request_body_kb: 256源码还支持以下可选节点；旧配置文件缺少这些节点时会使用内置默认值：
yaml
web_console:
security:
allowed_modules: []
config_browser:
max_file_size_kb: 512
allowed_extensions:
- ".yml"
- ".yaml"
- ".json"
- ".txt"allowed_modules: [] 表示不额外限制模块列表，Web Console 会使用已经注册的模块 ID。只有需要把某些已安装模块从 Web Console 中隐藏或隔离时，才需要显式填写白名单。
字段说明
| 字段 | 类型 | 默认 | 说明 |
|---|---|---|---|
enabled | boolean | false | 是否启动内置 HTTP 服务。关闭时不会监听端口。 |
host | string | 127.0.0.1 | 绑定地址。0.0.0.0 会监听所有网卡，必须配合防火墙、反代鉴权或可信网络使用。 |
port | int | 38765 | 监听端口。非法端口会回退到 38765。 |
public_access_warning | boolean | true | 登录响应中返回公网访问提示标记，供前端显示安全提醒。 |
auth.username | string | 资源默认 EmakiAdmin，内置默认 admin | 登录用户名。 |
auth.password | string | 资源默认 EmakiAdminPassword，内置默认 change-me | 登录密码。启用前必须修改。 |
auth.session_timeout_minutes | int | 60 | 登录 token 有效时间，最小为 1 分钟。 |
security.allow_config_write | boolean | false | 是否允许保存配置、脚本、GUI、物品或自定义资源文件。 |
security.max_request_body_kb | int | 256 | 单次请求体大小上限，保存较大的 YAML 或脚本时需要相应提高。 |
security.allowed_modules | list | [] | 允许显示/访问的模块 ID 白名单。为空时使用已注册模块列表。 |
config_browser.max_file_size_kb | int | 512 | 配置浏览器允许读取的单文件大小上限。 |
config_browser.allowed_extensions | list | .yml/.yaml/.json/.txt | 配置浏览器允许读取的扩展名，会自动补齐 . 并转为小写。 |
安全行为
源码中的启动和请求保护逻辑如下：
enabled=false时不启动 HTTP 服务。- 如果配置缺失并落入内置默认密码
change-me，服务会拒绝启动。 - 当前资源文件中的示例密码是
EmakiAdminPassword，不会被change-me检查拦截；启用前仍必须改为强密码。 - 登录成功后前端使用 bearer token 调用
/api/*接口，token 到期后需要重新登录。 allow_config_write=false时，保存、创建和删除类接口会拒绝写入；读取与预览类能力仍可使用。/extensions/下的前端扩展脚本通过<script>加载，浏览器无法附带 Authorization header，因此该资源入口不做登录校验；服务端只允许返回已注册的插件内资源路径。- 所有文件路径都会做越界检查，禁止绝对路径、
..、跨模块访问和未注册扩展资源。
推荐部署方式：
- 日常只绑定
127.0.0.1或可信内网地址。 - 如果需要公网访问，放在 HTTPS 反向代理后方，并额外配置访问控制。
- 正式服默认保持
allow_config_write=false，只在维护窗口临时开启写入。 - 修改 Web Console 配置后执行
/emakicorelib reload。 - 排查页面或接口问题时临时使用
/emakicorelib webdebug frontend、backend或all，完成后再关闭。
当前页面能力
Web Console 当前由 CoreLib 前端壳和各模块扩展共同组成：
| 能力 | 说明 |
|---|---|
| 登录与会话 | 使用账号密码登录，前端保存 token 并在 API 请求中携带。 |
| 模块树 | 从服务端注册表读取模块、文件入口、子文件、图标、版本与启用状态。 |
| 结构化配置编辑 | 对单文件 CONFIG 执行节点级编辑；glob 配置目录会按子文件懒加载节点。 |
| 源码编辑 | 对配置、GUI、物品、脚本和自定义资源显示源码，支持保存时 revision 冲突检测。 |
| 文件创建/删除 | 对 **/*.yml、**/*.js 等 glob 注册入口创建或删除子文件。 |
| GUI 编辑器 | 通用 GUI surface 支持 Bukkit InventoryType、标题、行数、槽位、显示物品、声音和组件字段。 |
| 物品编辑器 | 通用 ITEM surface 支持字段表单、源码编辑、物品预览和插件自定义字段渲染器。 |
| 运行时信息 | 可查看运行时库、经济提供器、name/lore 操作类型和 Bukkit DamageCause 枚举等运行数据。 |
| 变量映射编辑 | variablesMap 字段使用专用键值编辑器，不再只能按普通对象或文本处理。 |
| 变更高亮 | 结构化编辑器会追踪本次修改过的路径，并在保存前高亮已变更字段。 |
| 前端扩展 | 注册表返回 extensions 后，前端动态加载模块 IIFE 脚本，扩展脚本通过 window.EmakiWebConsole 注册页面、字段、翻译和预览逻辑。 |
声明式注册机制
当前各业务模块主要通过 src/main/resources/web-console.yml 声明 Web Console 入口，再在插件启用阶段调用：
java
WebConsoleRegistry.registerFromYaml(this);关闭或 reload 时调用：
java
WebConsoleRegistry.unregisterModule(this);WebConsoleYamlRegistrar 会扫描已启用插件的 web-console.yml，并将其转换为 WebConsoleRegistry 注册项。声明式注册文件支持以下顶级节点：
| 节点 | 类型 | 说明 |
|---|---|---|
module | object | 模块外观信息。支持 name、summary、tone、icon。当前内置模块主要写 tone 与 SVG icon，展示文案交给前端 i18n。 |
files | list | 文件入口列表。每项支持 path、kind、title、comment、editor。 |
extensions | list | 前端扩展脚本列表。每项支持 id 与 resource。 |
nodes | list | 结构化配置节点元信息。每项支持 path、type、label、comment、creatableChildren。 |
comments | object | 旧格式字段注释，仍兼容；新文件建议使用 nodes 或前端扩展注册。 |
files.kind
| kind | 服务端注册方法 | 前端默认行为 |
|---|---|---|
CONFIG | registerConfigFile | 单文件结构化编辑；glob 路径显示子文件。 |
GUI | registerGuiFile | 使用通用 GUI 编辑器；可通过 editor 绑定专属 GUI editor。 |
ITEM | registerItemFile | 使用通用物品编辑器；可通过 editor 绑定专属物品 editor。 |
SCRIPT | registerScriptFile | 使用脚本文本读写接口。 |
| 其他值 | registerResourceFile | 作为自定义资源类型暴露给前端 surface registry，例如 SET。 |
path 可以是固定文件，例如 config.yml，也可以是 glob 目录，例如 recipes/**/*.yml。glob 入口本身不会直接读取全部内容，前端点击子文件时再按需读取。
nodes.type
服务端可识别的基础类型包括：text、number、boolean、list、object。此外还支持：
| 类型 | 说明 |
|---|---|
stringList / numberList / actions | list 的前端展示类型覆盖；actions 会使用 CoreLib 统一 Name/Lore 动作链编辑器。 |
effects | 统一效果列表编辑器。效果类型由模块注册表决定，只显示当前效果类型自己的 payload 字段。 |
economyProvider | 统一经济提供器下拉，选项来自 CoreLib 运行时经济系统，默认包含 auto 并按已加载桥接补充。 |
variablesMap | 变量映射键值编辑器，适合 variables 这类动态变量表。 |
dynamic_map | 对象节点不继续展开，而是作为可动态新增键的 map 编辑。 |
enum:A,B,C | 静态枚举选项。 |
dynamic_enum:目录 | 扫描模块数据目录下 YAML 文件的 id 字段或文件名作为枚举选项。 |
当前模块注册入口
源码中的业务模块都已改为 web-console.yml 声明式注册，并在启用/关闭阶段注册或反注册。
| 模块 | 注册文件入口 | 前端扩展 |
|---|---|---|
| EmakiCoreLib | config.yml、scripts/**/*.js | CoreLib 自身前端壳与通用组件，不通过 extensions 额外加载。 |
| EmakiAttribute | config.yml、attribute_balance.yml、attributes/**/*.yml、damage_types/**/*.yml、lore_formats/**/*.yml、conditions/**/*.yml | emakiattribute:locale，补充属性、伤害、条件等配置字段说明和运行时枚举。 |
| EmakiForge | config.yml、recipes/**/*.yml、item_adjustments/**/*.yml、gui/**/*.yml | emakiforge:gui-surface，补充锻造配置、品质列表 schema 和 GUI editor。 |
| EmakiStrengthen | config.yml、recipes/**/*.yml、gui/**/*.yml | emakistrengthen:gui-surface，补充强化配置、配方和 GUI editor。 |
| EmakiCooking | config.yml、recipes/**/*.yml、gui/**/*.yml | emakicooking:gui-surface，补充工位、展示实体、配方和 GUI editor。 |
| EmakiGem | config.yml、conditions/**/*.yml、resonances/**/*.yml、gui/**/*.yml、items/**/*.yml、gems/**/*.yml | emakigem:item-surface，补充宝石/插槽物品 editor、成本编辑、升级编辑、本地预览兜底和 GUI editor。 |
| EmakiSkills | config.yml、skills/**/*.yml、resources/**/*.yml、gui/**/*.yml | emakiskills:gui-surface，补充技能、资源、触发器与 GUI editor。 |
| EmakiItem | config.yml、items/**/*.yml、sets/**/*.yml | emakiitem:locale，注册 SET 文件类型、物品/套装 editor、套装字段渲染和文档适配。 |
HTTP API 概览
Web Console 使用 JDK 内置 HttpServer。主要接口如下：
| 路径 | 方法 | 说明 |
|---|---|---|
/api/auth/login | POST | 登录并获取 token。 |
/api/session | GET | 校验当前 token 会话。 |
/api/modules | GET | 查看允许模块的安装、启用、版本和状态。 |
/api/registry | GET | 获取模块注册树、文件入口、编辑器描述、GUI 类型、运行时枚举和扩展脚本列表。 |
/api/registry/file | GET | 获取 glob 子文件的结构化 YAML 节点。 |
/api/registry/save | POST | 保存结构化配置节点。 |
/api/files/create | POST | 在 glob 文件入口下创建新文件。 |
/api/files/delete | POST | 删除注册入口下的子文件，需要确认路径。 |
/api/configs/create | POST | 兼容配置文件创建入口，内部复用文件创建逻辑。 |
/api/configs/tree | GET | 浏览模块配置目录。 |
/api/configs/read | GET | 读取指定配置文件源码。 |
/api/configs/save | POST | 保存指定配置文件源码。 |
/api/libraries | GET | 查看 CoreLib 运行时库信息。 |
/api/debug/frontend-error | POST | 前端错误上报。 |
/api/scripts/read | GET | 读取脚本文件。 |
/api/scripts/save | POST | 保存脚本文件。 |
/api/gui/read / /api/gui/save | GET / POST | 读取或保存 GUI YAML。 |
/api/items/read / /api/items/save | GET / POST | 读取或保存物品 YAML。 |
/api/resources/read / /api/resources/save | GET / POST | 读取或保存自定义 kind 的 YAML 资源。 |
/api/items/preview | POST | 根据 YAML 内容生成物品展示预览。 |
/api/items/action-types | GET | 返回当前 name/lore 操作类型。 |
/api/economy/providers | GET | 返回经济提供器选项与当前可用提供器。 |
/extensions/{moduleId}/{resource} | GET | 返回已注册的前端扩展脚本资源。 |
这些接口主要供 Web Console 前端使用。除联调、反代或二次开发外，不建议直接手写调用。
物品预览
WebItemPreviewService 可以基于 YAML 内容模拟物品展示：
- 普通物品：读取
display_name/item_name/id、lore、name_actions、lore_actions。 - Gem 宝石：识别
gem_type、levels、effects、inlay_cost、extract_cost、upgrade。 - Gem 插槽物品：识别
match.item_sources、slots、default_open_slots、allowed_gem_types、max_same_type、max_same_id。
预览会返回渲染后的名称和 Lore、变量计算结果、name/lore 操作步骤、效果摘要、升级摘要、材料与费用摘要。它只是配置编辑辅助，不会替代服务端真实物品生成、PDC 写入或外部物品源解析。
Gem 扩展还注册了本地预览兜底：当服务端预览不可用或编辑器需要即时反馈时，前端会基于当前草稿生成宝石或插槽物品预览。
常见问题
执行 /emakicorelib web 后打不开
检查：
web_console.enabled是否为true。host是否是当前浏览器所在机器可访问的地址。- 如果
host=0.0.0.0，命令给出的可点击链接会回退到127.0.0.1，远程访问时需要手动换成服务器实际 IP 或域名。 - 防火墙、容器端口映射或反向代理是否放行。
- 控制台是否有 Web Console 启动失败日志。
保存按钮不可用或保存失败
确认：
security.allow_config_write=true。- 登录 token 未过期。
- 请求体没有超过
security.max_request_body_kb。 - 文件扩展名在
config_browser.allowed_extensions中。 - 模块在
security.allowed_modules中，或白名单为空。 - 服务器进程对目标文件有写入权限。
- 没有 revision 冲突；如果提示文件已被其他会话修改，先刷新再重新保存。
模块没有出现在左侧树
确认对应插件已启用，并检查：
- 插件启用阶段是否调用
WebConsoleRegistry.registerFromYaml(this)。 - 插件 JAR 内是否包含
web-console.yml。 web-console.yml的files节点是否至少注册了一个入口。- 如果配置了
security.allowed_modules，列表中必须包含该模块 ID，例如EmakiGem。 - reload 后旧注册会被
unregisterModule清理，再重新注册；如果仍缺失，检查控制台是否有web-console.yml解析警告。
前端扩展加载失败
检查：
web-console.yml > extensions[].resource是否与 JAR 内资源路径一致。- 资源路径不能以
/开头，也不能包含..。 - Vite 是否输出到
src/main/resources/web-extensions，并随 JAR 一起打包。 - 扩展构建是否使用 IIFE 格式，并把
react与emaki-web-consoleexternal 到全局React、EmakiWebConsole。 - 浏览器控制台与
/emakicorelib webdebug frontend日志中是否有脚本错误。
更多接入细节见：Web 端扩展接入。