跳到主要内容
版本：1.6.0

权限、安全、备份与维护

本文覆盖生产运行的最小安全与维护流程。示例中的地址、账号、口令和令牌均为占位符；凭据只能通过受控部署系统、环境变量或受限密钥库传递。

1. 访问控制​

身份适用场景要点
管理台登录人工运维管理员凭据换取会话令牌；所有写操作带操作者审计。
API Key：full受控自动化写操作仅给必须创建、发布或回滚的服务。
API Key：readonly报表、监控和只读集成写端点统一拒绝，遵循最小权限。
Agent bootstrap tokenAgent 接入与身份注册只用于定位所属环境，并判定注册阶段的受信内部调用方；数据面另需管理台确认过的实例身份。不等同于管理员凭据，也不是公网安全边界。

API Key 明文仅会在创建或重置时显示一次。立即保存到受控密钥库；遗失时重置，旧密钥立即失效。不要把 Key、登录令牌、Agent token、数据库 DSN、完整公网地址或端口写进仓库、Wiki、截图、日志和工单。

1.1 管理 API 密钥：创建、重置、吊销​

入口在侧栏「系统 → 密钥」。列表顶部汇总密钥总数与生效 / 已过期 / 已吊销数量，点任意一行打开详情。

创建

  1. 点「创建密钥」，填名称（写清用途，例如「巡检脚本」）、角色、过期时间（可留空表示永不过期），并填写审批原因后提交。
  2. 提交后拿到的是审批申请，不是可用的密钥。页面会提示申请已创建，可一键跳到审批中心看进度。
  3. 审批批准并执行完成后，由原申请人一次性领取明文。明文只在领取时显示一次，关闭后无法再查看——当场存进受控密钥库。

角色怎么选

  • 读写：可发起写操作，但每一次写仍各自走审批；只给确实需要创建、发布、回滚的自动化。
  • 只读：写端点统一拒绝（403）。但它仍可直读日志、文件资产正文、受限目录浏览与消息载荷——这些读取走管理读权限、只留审计。所以只读密钥同样要按最小权限发放；发现过度发放就收敛，而不是假定「只读就安全」。
  • 需要 full 角色的入口（例如 /debug/pprof/* 取证）只认读写凭据，只读密钥一律被 403 拒绝。

重置（轮换）与吊销

  • 重置是同一把密钥换新内容：立即换出新明文，旧明文立即失效。用于定期轮换或疑似泄露后的换钥；先准备好更新调用方，或挑可接受短暂中断的窗口做。
  • 吊销是这把密钥作废：立即生效且不可恢复，不必审批，用于止损（凭据已泄露、调用方已下线）。被吊销的调用方一律被拒，需要重新创建一把。
  • 设了过期时间的密钥到期后状态显示为「已过期」，调用方被拒。临时性自动化优先设过期时间，而不是永不过期。

排障提示：调用方报错先分清 401 与 403——401 是凭据无效、过期或已吊销，403 是权限不足（最常见的原因是拿只读密钥做写操作）。不要把管理员凭据复制给多个自动化共用。

管理台、管理 API、Prometheus 指标和数据库均应置于受控网络或反向代理之后。不要将管理端口直接公开到互联网；如需跨网络访问，使用组织认可的 HTTPS、网络准入和访问日志。

2. 配置与密钥卫生​

  1. 从 config.example.yml 或 .env.example 创建本机配置，真实 .env 不入库。
  2. 将数据库口令、管理员口令、签名密钥、Agent token 和发布仓库凭据经环境变量或密钥管理系统注入。
  3. 区分启动/安全项与可热更新的运维设置：改数据库、监听地址、认证或 token 后按部署流程重启；热设置在管理台变更并保留审计。
  4. 轮换前先建立新凭据、灰度验证依赖方，再撤销旧凭据，避免一次性断开所有 Agent 或自动化。
  5. 对配置预览、日志、审计导出和文件资产预览执行脱敏与最小可见原则。
  6. 控制面首次创建的本地加密密钥必须保存在私有目录；不要复制、放宽 ACL 或用共享临时目录覆盖密钥文件。权限检查失败时应修正部署目录，而不是跳过启动保护。
  7. MCP 自动化使用独立 OAuth client 和 HTTPS 反向代理。仅信任明确配置的代理 CIDR；不要将 MCP bearer 用于普通管理 REST，也不要把 client secret 写入脚本、日志或仓库。

3. 备份与恢复演练​

备份不是只复制控制面二进制。至少覆盖：

  • 主数据库，以及启用时的归档数据库；
  • 控制面配置和由部署系统管理的密钥恢复材料；
  • 每个 Agent 的 plugins/Beacon* 状态目录，包括身份、配置快照和传输账本；
  • 已核验的控制面与 Agent GA 产品包及其 SHA-256 清单。

建议流程：先完成一致性数据库备份并校验可读；将备份加密后存放在独立受控位置；定期在隔离环境恢复数据库和一个 Agent 快照，验证能登录、身份仍被识别、历史审计可查且玩家链路不会因控制面恢复过程被阻断。恢复时不要把测试环境的 token 或地址带回生产。

热数据到期前应先归档、校验行数和抽样哈希，再清理热库。归档不可用时控制面可以降级运行，但必须告警并在恢复后处理积压；不要直接删除尚未验证归档的数据。

4. 升级、在线更新与回滚​

  1. 阅读目标 GA 的变更说明和兼容性要求，确认控制面、Agent 和业务 SDK 的版本矩阵。
  2. 备份后在测试或小批服务器完成升级和玩家验收。
  3. 仅使用已校验 SHA-256 的 GA 资产。RC 和开发构建不能作为自动更新来源。
  4. 先升级控制面或按发布说明要求的顺序升级；Agent 按批替换 JAR 并保留其本地状态目录。
  5. 观察健康、命令结果、配置交付和玩家落点；确认稳定后再推广。
  6. 出现回归时停止推广，按已验证版本回滚控制面或相应批次。线上自替换依赖 Docker/systemd 等外部监督进程来完成异常重启和自动回退闭环。

不要通过删除数据库、清空 Agent 状态或强制改写版本文件来“修复”升级问题；这会丢失身份与审计证据。

4.1 识别正在运行的版本（--version 带候选后缀）​

候选（RC）构建的运行时版本会带上候选后缀，例如 1.5.0-rc.2。该串在 --version、启动日志、状态页和更新页原样输出。

  • 根目录的 VERSION 文件仍是 1.5.0（它驱动 tag、资产名与 GA 校验），不要因为看到 -rc.2 就以为版本文件错了。
  • GA 安装同样会报告带后缀的串——GA 直接复用 RC 的同一份字节资产、不重新构建，这是原样晋级的必然结果，不是装错了包。
  • 在线更新只消费严格的 vX.Y.Z GA 发布，候选版本不会进入自动更新候选集。
  • 报障与验收时请把**完整串（含后缀）**写进记录：旧版本下 rc.1 与 rc.2 的版本串、启动日志乃至二进制字节大小都可能完全相同，仅凭「1.5.0」无法区分测的是哪个候选。

5. 维护窗口检查表​

  • 备份已完成并验证，回滚版本和负责人明确。
  • 管理员、API Key 和 Agent token 均按最小权限保存，未出现在操作记录中。
  • 目标服务器已 drain 或已评估玩家影响。
  • 发布后检查 Dashboard、Servers、命令观测、告警和审计。
  • 更新结束后撤销临时权限，记录版本、时间和异常处理结果。

6. 归档与升级的权限边界​

维护、归档与升级的实际边界如下，按上文各节执行即可，不需要额外的授权入口：

  • 归档沿用管理面登录令牌和 API Key 的既有权限，不单独设权限体系；归档库数据默认长期保留，不做自动二次清理。热库数据只有在归档完成行数与抽样哈希校验、确认可读之后才会被清理，不要手工删除尚未验证归档的热数据。
  • 升级只使用已校验 SHA-256 的 GA 资产，RC 和开发构建不能作为自动更新来源。自替换失败会就地回退并以旧版重启；异常重启与自动回退闭环依赖 Docker/systemd 等外部监督进程，容器形态的生产升级一律以重拉镜像为准。
  • 部署、真实 Agent 验收与版本回滚的完整流程见 运维手册。