备份、恢复与迁移

备份完整状态

仅下载交付文件不能恢复 Agent、会话、账号与连接器配置。完整恢复需要匹配的数据、凭据密钥和程序版本。

默认状态根示意如下；自定义目录以运行环境实际配置为准。

~/.nexus/
  app/                    Nexus 宿主数据库与服务状态
  control/                服务端 Control 身份与会话数据
  control-public/         供 Nexus 读取的公钥镜像
  users/<owner>/
    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 或外部账号已经被撤销时，还需重新配置外部授权。

用恢复清单验收备份

备份开始前选一段已知会话、一份工作区文件和一个记忆条目，记录它们的名称与内容特征。恢复后检查同样的对象，避免只看到空工作台可以登录就认为恢复成功。

连接器配置看得到但无法解密时，先找原密钥。生成新密钥只适合重新配置，不能恢复旧密文。若外部账号本身已撤销授权，需要在该平台重新处理。

避免恢复副本同时工作

演练环境应先隔离外部访问，避免启动时与原实例同时收取 IM 消息或执行定时任务。确认通道和任务已停用后，再按需要开放模型与只读工具用于验证。

将正式环境切到恢复副本时，先停止旧实例的相关工作，再让新实例接管。保留已发送消息和已生成文件的记录，恢复后的首次运行先检查目标现状，减少重复执行。

备份记录应包含什么

记录备份日期、程序版本、实际状态目录、配置文件位置和密钥来源。使用外部数据库时，还应记录数据库备份对应的时间点。记录里不写明文密码；秘密配置按原有受限方式保存。

确认恢复清单通过后再按自己的保留策略清理旧副本。成功复制文件只能证明有副本，能够恢复并完成小任务才证明这份副本可用。

桌面迁移数据目录

打开 设置 → 数据目录，查看当前目录并选择新位置。阅读确认信息后启动迁移；Nexus 会迁移完整状态并立即重启。

迁移前保留备份，确认目标磁盘空间和访问权限。不要在线拆分 app/ 与 users/，也不要在迁移中手动搬动子目录。重启后检查页面显示的实际目录与历史文件。

迁移或升级失败

先保留原目录和新目录，检查应用提示与日志，保留可用于恢复的数据副本。看到结果不明确的提示时先核对当前目录，避免重复发起迁移。

跨版本回退使用升级前的数据快照与对应旧版本。新的数据库结构未必能被旧程序读取，单独降级二进制不保证可用。