部署与运维

安装

正式版本发布后，从 Release 选择与 Minecraft 完全一致的 Forge JAR，并验证 SHA256SUMS；当前开发构建不可按生产发行包部署。
安装下表指定 Forge，接受 EULA，先启动一次确认服务器本身正常。
将 JAR 放入 mods/。客户端无需安装本模组。
首次启动后保持 Web 监听为 127.0.0.1:8765，在服务器物理终端运行 /xfesm web bootstrap 获取十分钟单次码。
用本机或经 TLS 反代的浏览器完成 owner 设置，并扫描二维码后用首个 TOTP 验证码完成绑定。

后续管理账户只能由已启用 TOTP 且具有近期二次认证的 owner 创建、改权、禁用或删除；近期认证过期时 Web 会弹出 TOTP 窗口，验证成功后更新原会话并重试操作。系统以事务方式保护最后一位启用的 owner，并在角色或禁用状态变化时撤销该账户的既有会话。

数据目录包含配置、master key、控制数据库、遥测数据库和世界事件分片。停止服务器或调用“保存并检查点”后再制作一致性备份；不要只复制仍在变化的 .db 而遗漏 -wal/-shm。

Linux/其他 POSIX 平台应让数据目录归 Minecraft 服务账号所有，并限制为 0700；应用会尽力把新建密钥文件设为 0600。Windows 部署应预先禁用该目录面向普通用户的继承读取 ACL，仅授予 Minecraft 服务账号及必要的 SYSTEM/Administrators 权限，并在首次启动后复核 master.key、指标令牌和数据库文件。应用不会擅自重写已有 Windows ACL。

反向代理

deploy/Caddyfile.example 和 deploy/nginx.conf.example 展示最小 TLS 终止方式。管理页面不应直接暴露在公网；建议额外使用 VPN、mTLS 或来源 IP 控制。应用配置中的 trusted proxy CIDR 必须精确覆盖代理地址，不能使用 0.0.0.0/0。

systemd 与 Docker

deploy/xfeservermanager.service.example 仅负责 Minecraft JVM 生命周期；模组不会自行拉起或重启 JVM。deploy/compose.yaml.example 展示只映射游戏端口、由 Caddy 私网访问管理端口的布局。使用 Compose 前先把 deploy/xfeservermanager.docker.json.example 复制为 xfeservermanager.docker.json，修改域名，并保持其中的固定 Caddy 地址与 trusted proxy /32 一致。请固定镜像 digest、限制资源并将持久卷纳入备份。

可观测性与健康处置

OpenMetrics 端点必须配置 bearer token，并只允许监控网络访问。
SSE 断开后客户端使用最后事件 ID 恢复；服务端可要求全量刷新。
世界事件队列出现 gap、SQLite 写入失败或磁盘低水位时可在 health/gap 状态中体现；外部告警配置接线尚待完成。存在 gap 时不能宣称完整回滚。
Web 标准关服要求 owner 二次确认，执行 save-all flush → SQLite checkpoint → 原版 stop；结构化计划在创建时广播目标时间，最后一小时每五分钟提醒、最后一分钟逐秒倒计时后进入同一流程。外部进程重启仍由 systemd、Docker 或面板负责。
JVM 重启、进程拉起和备份由 systemd、Docker 或托管面板完成。

升级与回退

升级前执行 WAL checkpoint 并备份小型控制库。替换同一 MC 版本的 JAR 后检查迁移日志；若控制库迁移失败，管理 HTTP 与全部写功能会停止，模组只会尝试从原库无迁移地只读恢复经过 schema、checksum 与策略校验的 ACTIVE（或最新已发布）策略。恢复成功时既有拒绝/约束继续生效，但任何策略提权因审计不可用而拒绝；没有有效快照时不得假定策略仍在执行。不要在不同 MC 构建间直接替换运行。回退到旧版本前应恢复其对应数据库备份，不能假设新迁移可逆。