升级与回滚

适用版本：ChengOS v0.1.0+ ｜ 最后核对：2026-08-12 ｜ 来源：chengflow/docs/release-operations-guide.md、deploy/chengos.sh、CHANGELOG.md

更新是仅升级、经过校验且可恢复的。在新版本通过校验之前不会发生任何不可逆的操作，在新版本被证明健康之前也不会把它记录为已安装。

命令

./chengos.sh status              # 版本 + 健康状况 + 最新稳定版检查
./chengos.sh update              # 仅升级，经校验，可恢复
./chengos.sh update --force      # 刻意重装或降级
./chengos.sh rollback            # 恢复上一个版本
./chengos.sh version             # 纯版本号，供脚本使用

Docker 安装需加 --mode docker，而且 update 额外接受 --to <version> 指定确切目标。

update 的执行顺序

1. 读取并规范化 .chengos_version（v1.2.3 与 1.2.3 都读作 1.2.3）。
2. 解析最新稳定版本。查询失败是一次清晰、非破坏性的失败——绝不会被谎报为「已是最新」。
3. 严格比较 remote > local。相同或更旧不会更新。
4. 下载到一个唯一的 mktemp -d 目录。
5. 先校验校验和，再校验签名。
6. 校验归档布局，以及内嵌的 VERSION 与所选版本一致。
7. 检查暂存与安装两个文件系统的可用空间。
8. 把当前属于安装包的状态备份到 .chengos_backups/。
9. 停止服务——如果停止失败则中止，此时尚未触碰任何文件。
10. 用同文件系统的重命名操作替换属于安装包的目录。
11. 启动服务并执行有时限的健康检查。
12. 到此刻才写入 .chengos_version 并清理旧备份。

如果第 10、11 步或健康检查失败，会自动恢复此前的状态并重启此前的服务。

这个顺序中有两个性质值得记住：版本记录最后才写入，因此崩溃的更新绝不会在磁盘上留下一条谎言；服务停止是一道闸门，因此无法干净停止的主机绝不会被升级到一半。

归属边界

这条边界从不被跨越，这也是在承载真实数据的系统上放心执行更新的前提：

备份只包含属于安装包的内容。你的配置、数据、日志和工作区永远不会被复制进备份，也永远不会被回滚删除。

备份与保留

备份位于 .chengos_backups/<version>-<timestamp>/，保留最新的 CHENGOS_BACKUP_KEEP 份（默认 3 份）。

一次回滚会消耗它的回滚点，因此第二次回滚会再往前走一个版本，而不是重复同一次恢复。

Docker 更新

四个服务的标签都来自同一个 CHENGOS_VERSION，因此不同版本的镜像绝不会被混用。更新流程是：固定版本 → 拉取 → 重建 api ui app → 校验 /health。若拉取、重建或健康检查失败，会恢复此前的版本固定值并重建此前的服务。

针对 latest 执行 docker compose pull 不是更新。 它破坏可复现性，也使回滚变得含糊，因为不存在一个确定的可返回版本。

只要设置了任何 CHENGOS_<SERVICE>_IMAGE 覆盖项，协调式版本更新就会被禁用，status 会明确说明。

数据卷——PostgreSQL、Valkey、Qdrant 以及用户卷——永远不会被更新或回滚删除或重建。

何时会拒绝回滚

自动回滚是一个文件层面的操作。只要旧版本仍能读取当前数据库，它就是安全的。

一旦某个版本应用了删除列或表、破坏性改写数据，或以非扩宽方式改变类型的迁移，回滚就不再安全。这样的版本会在发布说明中声明 Migration policy: irreversible，两条回滚路径都会拒绝执行。

变更日志中每个版本条目都必须声明其策略：

从不可逆版本手工恢复

1. ./chengos.sh stop
2. 恢复更新之前所做的数据库备份。发布说明会给出该版本所需的确切 dump/restore 命令。
3. 从最新的 .chengos_backups/ 目录恢复安装包（原生），或在 .env 中手工把 CHENGOS_VERSION 改回去（Docker）。
4. 把恢复后的纯版本号写入 .chengos_version。
5. ./chengos.sh start
6. 确认 /health 报告的是恢复后的版本。

在更新声明了不可逆迁移的版本之前，务必先做数据库备份。 更新器无法重建被迁移删除的数据。

离线更新

把校验过的 chengos-full-linux-amd64-v<version>.tar.gz（最好连同它的 .sha256）放在 chengos.sh 旁边，更新器就会使用它而不走网络。没有内嵌 chengos/VERSION 的本地包早于发布契约，会被拒绝。

网络超时

status 中的元数据超时会打印 latest version unavailable——这不是在说你已是最新版。update 中的元数据超时会中止，且不触碰安装。

事故恢复

下一步

• 部署模式——你在更新的是什么。
• 安装问题排查——首次安装的故障。