# XFEServerManager

XFEServerManager 是一个可仅安装在服务器端的 Minecraft Forge 管理模组，提供浏览器管理面板、语义化命令策略、实时状态、经过审计的玩家操作，以及可扩展的世界治理能力。当前仓库是开发实现，不是生产发行版。模组不注册客户端必需内容或网络通道；普通玩家可继续使用原版客户端连接。若玩家端额外安装同版本 JAR，则会启用增强可视化 UI 菜单；未安装时自动使用安全的聊天可点击菜单回退。两种模式仍需逐版本完成握手验收。

项目分别构建 Minecraft 1.20.1、1.20.6、1.21.1、1.21.11 四个 JAR，不承诺一个 JAR 跨版本运行。

## 目录结构

- `common/api`：与 Minecraft 无关的公共类型和扩展接口。
- `common/core`：策略、权限、操作与审计领域逻辑。
- `common/infra`：内置 HTTP、认证、SQLite 和状态采集。
- `web-ui`：React/TypeScript 管理面板。
- `platform`：四个彼此隔离的 Forge 构建根。
- `docs`：部署、安全、API 与兼容性说明。

## 构建

仓库自带 Gradle Wrapper，无需全局安装 Gradle。公共模块和 1.20.1 使用 Java 17，其余三个版本使用 Java 21。

```text
gradlew.bat check
cd web-ui
npm ci
npm test
npm run build
..\scripts\build-all.ps1
```

管理面板默认只监听 `127.0.0.1:8765`。需要远程访问时，必须通过受信任的 Nginx/Caddy HTTPS 反向代理暴露。

## 首次启动

1. 只安装与服务器 Minecraft、Forge 版本完全匹配的 JAR；正式发布前仍须验证对应版本的原版客户端握手。
2. 启动 Forge 专用服务器，并保持管理端口仅监听回环地址。
3. 在服务器物理终端执行 `/xfesm web bootstrap`。
4. 用十分钟有效、仅能使用一次的引导码创建首位 `owner`，随后完成 TOTP 设置，再启用高危 Web 功能。

配置、密钥和数据库写入 XFEServerManager 数据目录。备份前应先执行 WAL checkpoint 或正常关闭服务器。

登录 Web 面板后，`设置` 页顶部直接提供功能开关、默认消息发送者（默认为 `XFEServerManager`）和完整服务器配置。默认发送者保存后立即生效，未指定发送者的消息会继承它；每条富文本仍可单独覆盖或隐藏发送者。Web 控制台、处罚、认领、追踪和回滚等运行时安全开关保存后立即生效；只有监听地址、代理、线程/会话参数和 OpenMetrics 初始化等启动项显示“待重启”，并可从同一区域预览标准优雅关服。左侧 `触发器` 页面是定时公告、首次/每次入服欢迎、按玩家每日公告、规则与维护提醒及其他事件自动化的唯一编辑入口；旧消息配置及原入服体验总开关首次启动时会幂等迁移到“已迁移消息”组。管理员默认使用“事件 → 条件 → 有序操作”的模块化界面，也可切换到受限且可校验的 XFE Script；任意命令操作仍只允许 owner 保存。命令策略采用多个命名策略组，每组可独立启停、复制和包含多条可视化规则；JSON 只作为高级只读预览，“保存并立即生效”会校验后原子发布，无需重启。

左侧 `UI 菜单` 页面提供任意坐标画布、14 种控件、富文本和触发器变量、可搜索的上传/原版/模组图片、子菜单及控件事件绑定。菜单文档和会话始终由服务端掌控；增强客户端只回传有大小限制的会话事件，服务端会重新校验玩家归属、有效期、菜单版本、控件和事件后才执行触发器。

左侧 `经济系统` 页面提供最多 64 种精确十进制货币、可搜索图标、主货币、初始/最低/最高余额、玩家转账开关、账户检索、管理员余额调整和不可变流水。余额和转账在单个 SQLite 事务中提交，并用修订号避免并发覆盖。玩家可用 `/xfesm-money balance [货币]`、`/xfesm-money currencies` 和 `/xfesm-money pay <玩家> <金额> [货币]`；这些命令同样进入命令策略和审计链路。经济余额可用于触发器条件、富文本和 UI 菜单，经济变动也可触发后续自动化。

“设置 → 崩服防护”提供可热更新的掉落物、生物、总实体、第三方模组实体、生成突发、命令方块速率、加载区块、慢刻和内存阈值。玩家不会被实体上限拦截，自动清理只处理超额掉落物；九类 `protection.*` 事件可继续联动触发器通知和处置流程。

计划关服在创建时立即广播目标时间，目标前一小时内每五分钟提醒一次，最后一分钟逐秒倒计时；到点后执行 `save-all flush`、SQLite checkpoint 和原版 `stop`。

OP 4 或物理控制台可使用 `/xfesm tick <0|1..1000>` 控制 Tick 流速；`0` 暂停世界模拟但保留玩家移动和网络处理，`/xfesm tick status` 查看当前状态。

## 文档

- [架构](docs/architecture.md)
- [触发器与自动化](docs/triggers.md)
- [崩服防护与自动化](docs/crash-protection.md)
- [多货币经济系统](docs/economy.md)
- [安全模型](docs/security.md)
- [部署与运维](docs/deployment.md)
- [构建与发布](docs/building.md)
- [兼容性边界](docs/compatibility.md)
- [OpenAPI 3.1 接口](docs/openapi.yaml)
- [实现与验收状态](docs/implementation-status.md)

## 安全默认值

- 新安装只生成策略草稿，不会自动改变原版 OP 行为。
- `owner` 不能由 OP 等级自动获得。
- offline-mode 玩家保留原版 OP 权限；未认证身份不能通过策略 `GRANT` 获得超出当前 OP 等级的额外权限。
- 任意 Web 控制台默认关闭；高危操作要求 TOTP，近期认证过期时会弹出验证码窗口并在验证后重试原操作。
- 所有修改操作在服务端重新鉴权并写入审计。

## 开发状态

仓库已经接通中立策略引擎、玩家操作、认证、SQLite、HTTP/SSE、Web 控制台，以及 v2 的处罚、维护计划、区块认领、Forge 事件保护、世界事件日志、预览回滚、暂停续跑与 redo。四套 Forge 源码均能在对应映射 API 下编译，但只有当每个 JAR 都完成专服启动、原版客户端握手、正常停止和数据库恢复验收后，才应作为生产版本发布；单纯编译成功不等于完成兼容性验收。

## 许可

MIT © XFEstudio。
