备份与恢复

备份与恢复完全由 Manager 的“集群 → 备份”管理。没有 wukongim.toml 备份分区，也没有 WK_BACKUP_* 环境变量。集群只有一个由 Controller 持有的计划、一个活动任务和有界历史。

权限与仓库

支持文件仓库、阿里云 OSS、腾讯云 COS 与兼容 S3 的对象存储。凭据加密保存在 Controller 状态中且不会通过 API 返回，但归档内容不会由 WuKongIM 加密；需要机密性时启用存储侧加密与访问审计。

文件仓库默认位于每个节点 data_dir 下的 backup-repository。在多节点集群中，它必须由所有活动数据节点访问同一个共享存储；每个节点各自的本地目录不是集群备份仓库。

建立计划

1. 选择仓库并填写保留、计划、并发和截止时间。
2. 保存设置，记录返回的计划版本。
3. 测试这一版本：协调节点写入一次性 marker；每个活动数据节点使用独立打开的仓库客户端读取并校验 marker，再写入自己的 receipt。协调节点重新读取所有 receipt、列出预期对象集，并清理这组有界探针对象，从而验证跨节点可见性。
4. 仓库测试成功后再启用计划。首次启用会启动一个初始全量备份。
5. 检查下一次调度时间、活动任务和历史。错过的调度不会补跑，任务重叠会记录为跳过。

改变仓库会把计划重新标记为未验证；仅改变调度可保留仓库验证。最小调度间隔为 12 小时，Worker 范围为 1–4，任务截止时间为 1–48 小时。不要把最大并发直接用于生产，先验证 IO、网络和业务延迟。

归档完成条件

一次全量备份覆盖全部 256 个物理哈希槽，使用 64 MiB 分块、Zstd 压缩和 SHA-256 校验。只有所有分块写入、校验并发布 COMPLETE 标记后，归档才可见为完成。

“验证归档”会重新读取并校验每个分块。保留策略默认保留最新七个归档，同时保留被 hold 的归档。删除需要输入 DELETE <archive-id>，且不应删除当前恢复或合规保留所依赖的归档。

恢复前置条件

• 归档属于当前集群身份，状态为完整且全量验证成功；
• 所有 256 个 Slot 和 Controller 状态可用，没有冲突的控制任务；
• 可用空间至少覆盖当前业务数据、归档逻辑大小的两倍和额外 1 GiB；
• 客户端、Webhook、插件、投递和管理人员已知晓维护窗口；
• 所有 Controller voters 不会同时被终止，操作者具备显式恢复权限并完成密码重新认证；
• 已记录当前制品、配置、节点清单和终止/升级条件。

恢复流程

1. 在 Manager 选择归档，执行完整预检和验证。
2. 输入 RESTORE <archive-id>。集群进入维护：断开客户端，排空写入与投影，暂停投递、Webhook 和插件，并 fence 新写入。
3. 系统保存回滚镜像，分阶段恢复全部 256 个 Slot，并再次验证。
4. 所有节点和 Slot 验证通过后切换；失败则使用回滚镜像恢复原状态。
5. 成功后 Manager 会话失效。重新登录，等待 /readyz，验证历史消息、客户端 Token、新写入、收发、重连和下游集成，再逐步恢复流量。