升级、备份与恢复

升级应保持应用元数据、知识索引与上传文件一致。容器部署需要同时保护数据库和数据卷；桌面客户端则由整包更新维护 Web、API 与 Python sidecar 的版本一致性。

Docker 更新

git pull --ff-only
docker compose up -d --build

这会重建服务但保留默认 sagdata 卷。更新后检查：

docker compose ps
docker compose logs --tail=200 api web

不要用 docker compose down -v 作为“干净重装”，除非已经确认要永久删除全部知识数据。

PostgreSQL 部署备份

升级前至少保存两部分：

1. pgdata：应用元数据、关系记录与 pgvector 数据。
2. sagdata：上传文件与引擎数据目录。

备份必须在一致的时间点完成。最稳妥的方式是在短暂停写期间创建数据库逻辑备份并快照文件卷。

恢复演练应在独立环境完成，并验证登录、文档数量、检索、引用与文件预览，而不只是确认容器能启动。

桌面客户端更新

桌面版通过 GitHub Releases 的稳定通道整包更新。Electron、Next.js、Python API 及原生依赖共享同一发布版本，不能单独替换其中一个组件。

数据目录不会写入安装目录：

覆盖安装与自动更新默认保留这些目录；Windows 卸载器也默认保留用户数据。

发布包完整性

公开 Release 提供 SHA256SUMS.txt。下载后可以校验安装包是否完整。macOS 产物应完成签名与公证；Windows 当前可能显示未知发布者提示。

兼容性原则

• 只使用正式非草稿 Release 作为稳定更新来源；
• 不移动或复用已经公开的版本标签；
• Web、API 与 Desktop 使用同一整包版本；
• 存储后端切换应通过配置和受控迁移完成，不能直接复制不兼容索引目录。