灾难恢复

灾难恢复是当部署没了——主机死了、集群丢了、卷毁了——你需要在别处把它带回来时做的事。它不是事故（系统不是行为异常，是缺席），也不是升级（没有东西要往前滚）。本页是端到端恢复形态，建立在其它指南覆盖的备份纪律与迁移机制之上。

先把决定性的性质说清楚：恢复是在一个全新部署上还原，不是修旧的。你从零部署 Ankole、从备份还原 PostgreSQL 和 Agent Home、重输入引导 secret。你恢复的恰是你备份的——不多不少——而未经演练的恢复是计划，不是能力。

什么可恢复，什么不可

状态	可恢复？	从什么
主体、Agent、会话、任务、Brain 知识、审计和 AuthZ 授权	是	PostgreSQL `pg_dump` 归档
每个 Agent 的工作区、长期文档、已安装 Skill、会话与任务文件	是	Agent Home 卷快照
Provider 凭证、聊天渠道凭证、加密环境变量	是	它们保存在 PostgreSQL 和 Agent Home 中，会随备份还原
引导 secret（`ANKOLE_SECRET_BASE`、worker 认证 key）	手工重输入	它们不在备份里；生成新的或复用记录的
进行中的回合、运行中的后台任务、live worker 状态	否	临时；随进程丢失
从未发往外部摄入器的日志	否	住在丢失的主机上

引导 secret 那一行让人意外：派生其它密钥的 secret 是部署时输入，不是 PostgreSQL 状态，所以不在 pg_dump 里。把它们存在你的 secret 管理器里（不在部署备份里，而是与之并列），或重新生成并接受派生密钥变化。

恢复流程

第 1 步：从零部署 Ankole

在新主机或集群上按照快速开始部署一个新实例。不要让新实例直接连接旧主机的卷或数据库，因为这些正是需要恢复的对象。请先使用新数据库、新 Agent Home 卷和新的引导 Secret；如果恢复方案要求复用旧 Secret，请按第 4 步操作。

第 2 步：还原 PostgreSQL

在真正启动控制面之前，从归档还原数据库：

# 在全新部署上，控制面停止或处于 setup 模式
docker compose exec -T postgresql \
  pg_restore -U ankole -d ankole --clean --if-exists \
  < "ankole-YYYYMMDD.dump"

然后执行 Migration（本地运行 bun run control-plane:setup，或由 Helm Init Container 执行），把恢复后的 Schema 更新到镜像要求的版本。数据库中会保留备份时刻的主体、Agent、会话、任务、Brain 知识和 AuthZ 授权。

第 3 步：还原 Agent Home

从快照还原 ankole_agents_data 卷（或 Helm 上的 RWX PVC）到同一 /agents 挂载路径。按 agent-key 的目录结构精确重建 /agents/<agent-key>/...。把它与 PostgreSQL 还原配对——数据库行引用 Agent Home 下的文件，不匹配的一对产生看起来活着却指向缺失文件的部署。

第 4 步：处理引导 secret

引导 secret（ANKOLE_SECRET_BASE、ANKOLE_RUNTIME_FABRIC_WORKER_AUTH_KEY、POSTGRES_PASSWORD）不在备份里。两条路径：

复用记录的——如果你把它们存在一个 secret 管理器里、与部署备份并列（不在其内），重输入它们。还原的 PostgreSQL 里的加密行正确解密，因为派生密钥相同。
重新生成——在 .env（Compose）或 Secret（Helm）里生成新的。还原的 PostgreSQL 完整，但使用旧 ANKOLE_SECRET_BASE 加密的 Provider 凭证、聊天渠道凭证和环境变量将无法解密。恢复后需要在 Console 中重新输入这些值。

复用更简单且保留 secret；若旧 secret 可能在灾难中被入侵，重新生成更安全。选匹配你为何恢复的路径。

第 5 步：重输入不在备份里的东西

还原后，走一遍配置界面，确认每一项完整：

Provider 与 model profile——住在 PostgreSQL，已还原。
信号路由规则——存储在 PostgreSQL 中，会随数据库恢复。如果你在第 4 步重新生成了 ANKOLE_SECRET_BASE，可能需要重新填写规则引用的聊天渠道凭证。
身份源提供商——记录会随数据库恢复，但可能需要重新填写凭证。
Control Plane Plugin 启用清单——已还原，但下次进程启动生效。

通过一个 binding 发一个真实回合，确认端到端路径在新部署上工作。

跨主机迁移（计划版本）

到新主机的计划迁移是同一流程，刻意做：

停旧部署（让 worker 静默、停写）。
取最终 PostgreSQL 备份和 Agent Home 快照——这些是迁移的事实来源。
在新主机全新部署、还原这对、处理引导 secret。
在新主机用一个真实回合验证。
把 DNS（或负载均衡器）切到新主机；确认后旧的可下线。

与灾难恢复的差异是“停旧部署”这一步——灾难里旧部署自己停了，你有的备份是那之前的。取最终备份尽量接近切换，以最小化差距。

演练

未经演练的恢复是计划，不是能力。演练是本指南单一最高杠杆的事：

每月一次，在随手主机上，还原昨晚的 PostgreSQL 和 Agent Home、部署镜像、跑一个真实回合。若还原奏效，你的恢复是真实的。若不奏效，你在随手主机上发现，不在灾难中。
包含引导 secret 步骤。 跳过它的演练没测那个让人意外的部分。要么复用记录的 secret，要么重新生成并重输入凭证——做你真正会做的那一个。
换主机。 每次还原到同一主机测的是备份，不是恢复。定期还原到不同主机（不同 OS、不同云），因为那正是灾难给你的。

与其它指南的关系

备份与还原是让恢复可能的纪律——备份是来源。
系统仍在但行为异常时，先定位故障；本页处理的是实例已经不可用或数据已经丢失。
计划升级是在原实例上向前迁移；灾难恢复是在新环境中从备份重建。
安全加固假设你会还原的备份经过测试——本页是那个测试。

本指南不是什么

它不是无数据丢失的保证——不在备份里的都没了，进行中的工作总是临时的。它不是演练的替代；演练是全部要点。它也不是单一命令——恢复是全新部署+还原这对+secret，每步有自己的验证。为省时间跳步是恢复产出坏部署的方式。

下一步

恢复所依赖的备份纪律，读备份与还原。
全新部署步骤，读快速开始。
系统仍在运行但行为异常时，先按日志阅读找到第一处故障。