# 备份、恢复与迁移 完整保存状态与密钥，验证恢复结果并迁移桌面数据目录。 ## 备份完整状态 仅下载交付文件不能恢复 Agent、会话、账号与连接器配置。完整恢复需要匹配的数据、凭据密钥和程序版本。 默认状态根示意如下；自定义目录以运行环境实际配置为准。 ```text ~/.nexus/ app/ Nexus 宿主数据库与服务状态 control/ 服务端 Control 身份与会话数据 control-public/ 供 Nexus 读取的公钥镜像 users// workspace/ Agent 文件与 Room 公共附件 runtime/ 运行配置、会话与项目记录 state/rooms/ Room 协作记录 ``` NXS 长期记忆位于相应 Agent 工作区的 `MEMORY.md` 与 `memory/`。服务端 `HOST_DATA_DIR` 挂载的数据、`.env` 中的必要密钥和外部数据库也需要一起纳入恢复计划。 ## 做一次一致的备份 1. 记录 Nexus 与 Control 版本、状态目录、部署配置和密钥来源。 2. 结束正在写入的任务。桌面版完整退出；Compose 部署使用 `make stop` 停止相关服务。 3. 复制完整状态目录，保留文件权限。使用 SQLite 时，需停止服务后复制数据库及相关文件，以免遗漏尚未写回主文件的数据。 4. 单独保护部署配置与凭据加密密钥。使用外部数据库时，按数据库的一致性备份方式备份。 5. 在独立位置保存备份，并记录日期和对应程序版本。 6. 重新启动服务，检查原环境正常。 备份完成并验证前，应保留原数据目录和数据卷。日志可以帮助排错，但不能替代数据库与工作区备份。 ## 验证恢复 在隔离位置准备与备份兼容的程序版本，停止目标服务后恢复整套数据和密钥，再启动。验证期间暂停定时任务和消息通道，避免与原环境同时执行外部工作。 依次检查登录、成员和 Agent 列表、历史会话、工作区文件、记忆、模型配置，以及连接器能否读取。最后运行一项不会造成重复外部写入的小任务。 恢复验证用于确认备份能否重建工作环境。模型 API Key 或外部账号已经被撤销时，还需重新配置外部授权。 ## 用恢复清单验收备份 备份开始前选一段已知会话、一份工作区文件和一个记忆条目，记录它们的名称与内容特征。恢复后检查同样的对象，避免只看到空工作台可以登录就认为恢复成功。 | 项目 | 验收方式 | 异常时先看哪里 | | --- | --- | --- | | 身份 | 使用预期账号登录 | Control 状态、签名与会话配置 | | Agent 和历史 | 找到备份前选定的成员与会话 | owner 与状态根是否一致 | | 工作文件 | 打开预先记录的文件并比较内容 | 工作区是否完整恢复 | | 记忆 | 查看选定主题与索引 | Agent 和引擎是否一致 | | 连接器 | 用已授权账号做只读验证 | 密文与加密密钥是否配套 | | 定时任务 | 检查定义、启用状态和下次时间 | 时区、依赖与投递目标 | 连接器配置看得到但无法解密时，先找原密钥。生成新密钥只适合重新配置，不能恢复旧密文。若外部账号本身已撤销授权，需要在该平台重新处理。 ## 避免恢复副本同时工作 演练环境应先隔离外部访问，避免启动时与原实例同时收取 IM 消息或执行定时任务。确认通道和任务已停用后，再按需要开放模型与只读工具用于验证。 将正式环境切到恢复副本时，先停止旧实例的相关工作，再让新实例接管。保留已发送消息和已生成文件的记录，恢复后的首次运行先检查目标现状，减少重复执行。 ## 备份记录应包含什么 记录备份日期、程序版本、实际状态目录、配置文件位置和密钥来源。使用外部数据库时，还应记录数据库备份对应的时间点。记录里不写明文密码；秘密配置按原有受限方式保存。 确认恢复清单通过后再按自己的保留策略清理旧副本。成功复制文件只能证明有副本，能够恢复并完成小任务才证明这份副本可用。 ## 桌面迁移数据目录 打开 **设置 → 数据目录**，查看当前目录并选择新位置。阅读确认信息后启动迁移；Nexus 会迁移完整状态并立即重启。 迁移前保留备份，确认目标磁盘空间和访问权限。不要在线拆分 `app/` 与 `users/`，也不要在迁移中手动搬动子目录。重启后检查页面显示的实际目录与历史文件。 ## 迁移或升级失败 先保留原目录和新目录，检查应用提示与日志，保留可用于恢复的数据副本。看到结果不明确的提示时先核对当前目录，避免重复发起迁移。 跨版本回退使用升级前的数据快照与对应旧版本。新的数据库结构未必能被旧程序读取，单独降级二进制不保证可用。