备份、恢复与迁移

备份完整状态

仅下载交付文件不能恢复 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 中的必要密钥和外部数据库也需要一起纳入恢复计划。

做一次一致的备份

记录 Nexus 与 Control 版本、状态目录、部署配置和密钥来源。
结束正在写入的任务。桌面版完整退出；Compose 部署使用 make stop 停止相关服务。
复制完整状态目录，保留文件权限。使用 SQLite 时，需停止服务后复制数据库及相关文件，以免遗漏尚未写回主文件的数据。
单独保护部署配置与凭据加密密钥。使用外部数据库时，按数据库的一致性备份方式备份。
在独立位置保存备份，并记录日期和对应程序版本。
重新启动服务，检查原环境正常。

备份完成并验证前，应保留原数据目录和数据卷。日志可以帮助排错，但不能替代数据库与工作区备份。

验证恢复

在隔离位置准备与备份兼容的程序版本，停止目标服务后恢复整套数据和密钥，再启动。验证期间暂停定时任务和消息通道，避免与原环境同时执行外部工作。

依次检查登录、成员和 Agent 列表、历史会话、工作区文件、记忆、模型配置，以及连接器能否读取。最后运行一项不会造成重复外部写入的小任务。

恢复验证用于确认备份能否重建工作环境。模型 API Key 或外部账号已经被撤销时，还需重新配置外部授权。

桌面迁移数据目录

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

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

迁移或升级失败

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

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