# 部署与运维

## 安装

1. 正式版本发布后，从 Release 选择与 Minecraft **完全一致**的 Forge JAR，并验证 `SHA256SUMS`；当前开发构建不可按生产发行包部署。
2. 安装下表指定 Forge，接受 EULA，先启动一次确认服务器本身正常。
3. 将 JAR 放入 `mods/`。客户端无需安装本模组。
4. 首次启动后保持 Web 监听为 `127.0.0.1:8765`，在服务器物理终端运行 `/xfesm web bootstrap` 获取十分钟单次码。
5. 用本机或经 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 构建间直接替换运行。回退到旧版本前应恢复其对应数据库备份，不能假设新迁移可逆。
