升级

本指南涵盖 Open ACE 的升级：准备与备份、升级步骤、数据库迁移失败处置与回滚。更换应用镜像不会触碰数据——所有状态都在命名卷（postgres-data、config-data、workspace-data、agent-state）中。

升级前准备

备份数据库。 数据存放在 postgres-data 命名卷中，用 pg_dump 备份（已不存在 usage.db 文件）：
```
docker compose exec postgres pg_dump -U ace ace > openace_backup_$(date +%Y%m%d).sql
```
若在 .env 中改过 DB_USER / DB_NAME，请相应调整 -U <DB_USER> 和库名。定时备份策略见 DATABASE_BACKUP.md。
确认密钥。 .env 中的 SECRET_KEY、OPENACE_ENCRYPTION_KEY、DB_PASSWORD 必须在升级中原样保留（见密钥兼容注意）。
确定目标版本。 Compose 默认跟踪 openace/open-ace:latest；可控升级建议在 .env 中固定版本标签：
```
# 指定版本（写入 .env）
echo "IMAGE_NAME=openace/open-ace:v1.2.0" >> .env
```

最低升级基线

最低支持升级起点为 baseline_2026_06_23。

若数据库已处于 baseline_2026_06_23 或受支持迁移链上的任意更新 revision，scripts/check_min_revision.py 会放行，容器启动时 alembic upgrade head 自动补齐缺失的迁移。
若数据库仍停留在基线之前的 revision（如历史 hash revision），check_min_revision.py 会直接报错并阻止容器启动，拒绝在不受支持的迁移路径上运行。
全新数据库（无 alembic_version 表）在开发模式下自动放行；生产模式要求先显式完成迁移。

出现这类失败说明数据库已偏离受支持的迁移链：请先从已位于 baseline_2026_06_23 链上的健康备份恢复，再升级。不要对着过期 revision 反复重试。

升级步骤

Docker Compose（推荐）

cd /path/to/open-ace

# 1. 备份（见「升级前准备」）

# 2. 拉取新镜像
docker compose pull

# 3. 重建容器
docker compose up -d

# 4. 观察启动与自动迁移
docker compose logs -f open-ace

镜像更换后的首次启动，docker-entrypoint.sh 会自动完成：

等待 PostgreSQL 就绪
检查应用 schema 是否已存在
运行 scripts/check_min_revision.py 校验当前 revision 在受支持的迁移链上（全新库自动放行）
执行 alembic upgrade head
对全新数据库创建默认管理员账号

手动执行校验与迁移：

docker compose exec open-ace sh -c 'python3 scripts/check_min_revision.py && alembic upgrade head'

带 scheduler profile 或多用户 overlay 时，用同样方式升级整个栈（多用户：docker compose -f docker-compose.yml -f docker-compose.multi-user.yml up -d）。

裸机（package / 源码安装）

# 先备份，然后：
git pull

# 运行数据库迁移
alembic upgrade head

# 重启服务
python3 scripts/manage.py stop
python3 scripts/manage.py start
# systemd 安装则：
sudo systemctl restart open-ace

package 方式安装可直接复用 install.sh：脚本会检测既有安装并提示升级，迁移前同样运行 check_min_revision.py，对基线之前的数据库直接拒绝。

离线服务器

在有网络的机器上导出新镜像并传输：

./scripts/install-central/docker-method/export-image.sh --build --compress
# 将 open-ace-images.tar.gz 拷贝到服务器后：
gunzip -c open-ace-images.tar.gz | docker load
docker compose up -d

scripts/install-central/docker-method/upgrade-remote.sh 可自动完成远程升级流程。

迁移失败处置

启动在迁移阶段失败时：

docker compose logs open-ace

check_min_revision.py 失败——数据库 revision 早于 baseline_2026_06_23。从受支持链上的健康备份恢复；不存在从远古 revision 就地升级的路径。
alembic upgrade head 失败——入口脚本会记录 ERROR: alembic upgrade head failed。保持失败容器停止，从日志定位失败的迁移，修复报告的原因（磁盘空间、PostgreSQL 连接、上次迁移被中断）后重试。Alembic 按迁移文件粒度以事务方式执行。
任何手工数据库修复之后，先重跑上面的校验命令，再让服务对外提供服务。

不要让两个版本的应用同时连着一个迁移到一半的数据库：运行时 schema 检查（schema_guard.py）比安装期检查更严格（require-head 策略），会拒绝在未完全迁移的数据库上启动服务。

回滚

回滚 = 固定旧镜像 + 恢复数据库：

在 .env 中固定回旧版镜像（如升级前使用的 IMAGE_NAME=openace/open-ace:v1.2.0）。
从升级前备份恢复数据库：
```
docker compose down
cat openace_backup_YYYYMMDD.sql | docker compose run --rm postgres psql -U ace -d ace
docker compose up -d
```
条件允许时恢复到干净的数据库（先删后建，或恢复进卷），而不是在更新的 schema 上重放。
回退为新版所做的 .env 变更（例如新增的必需变量）并重启。

注意：

alembic downgrade 不是受支持的回滚路径——schema 降级脚本并不维护。数据一律从备份回滚。
docker compose down 会保留命名卷；只有 docker compose down -v 或显式 docker volume rm 才会删除数据。
若新版期间轮换过密钥（升级过程中不应轮换），回滚时需一并把 .env 恢复为升级前的值。

密钥兼容注意

升级时 SECRET_KEY、OPENACE_ENCRYPTION_KEY、DB_PASSWORD 必须原样保留。换了与旧值不匹配的 OPENACE_ENCRYPTION_KEY 会导致所有已存储的敏感数据（SSO client secret、SMTP 密码、API Key、集成凭据）永久无法解密。
针对早于「会话签名与敏感数据加密拆分」的历史部署：已有加密数据的部署升级前，请先把 OPENACE_ENCRYPTION_KEY 设置为旧版曾用于 SECRET_KEY 的同一个值；确认升级后的服务能读取既有密文后，再在计划维护窗口轮换为专用密钥。
完整轮换流程、单密钥覆盖的 8 类加密存储、OPENACE_ENCRYPTION_KEYS 数据密钥注册表见 KEY_MANAGEMENT.md。

升级后验证

docker compose ps 显示 open-ace（及 postgres）健康；健康检查探测 /readyz
docker compose logs open-ace 显示迁移完成、服务监听 19888
登录正常；既有用户、会话与配置完好
工作区与各集成（SSO、SMTP、钉钉/飞书、Webhook）认证正常——这同时证明加密钥被正确保留
验证后归档或删除数据库备份

目录​

升级前准备​

最低升级基线​

升级步骤​

Docker Compose（推荐）​

裸机（package / 源码安装）​

离线服务器​

迁移失败处置​

回滚​

密钥兼容注意​

升级后验证​

目录