跳到主要内容

本机升级与回滚

升级会让四个产品和数据库结构一起前进；回滚会把上一个发布连同升级前写的数据库备份一起恢复。

第 1 步：看看现在装的是哪个版本​

soln status --dir "$HOME/soln-tenant-runtime"
  • 成功：打印已安装的发布版本、四个产品的容器状态，以及 ready
  • DEPLOYMENT_NOT_INSTALLED: No Soln deployment state exists in this directory. —— 这个目录不是部署目录，路径写法见部署文件与目录

想知道控制面里有没有更新的发布：

soln upgrade --check --dir "$HOME/soln-tenant-runtime"
  • Soln <版本> is up to date. —— 已是最新，无需操作
  • Update available: <当前> -> <新版本> —— 继续第 2 步
  • Update required: <当前> -> <新版本> —— 控制面已强制要求这个版本，尽快升级以免 Runtime 断连

第 2 步：先确认磁盘空间​

df -h "$HOME"
  • 成功：Avail 一列至少 10 GiB。升级期间新旧镜像会短暂共存，并且会写一份数据库备份
  • 不足 10 GiB —— 先清理磁盘；否则升级会在动手前以 DEPLOYMENT_DISK_INSUFFICIENT 中止

第 3 步：升级​

soln upgrade --dir "$HOME/soln-tenant-runtime"

非交互执行可以加 --yes；只有在必须装某个确切版本时才加 --release <版本>。CLI 依次做这些事：

  1. 跑 soln doctor 检查，任何一项失败就停下
  2. 校验环境变量与已记录的部署状态是否一致（不一致报 DEPLOYMENT_BINDING_MISMATCH）
  3. 把 PostgreSQL 备份写到 <部署目录>/.soln/backups/postgres-tenant-<时间戳>.sql.gz.enc
  4. 在 .soln/deployment.json 里记录这次升级未完成，中途崩溃也能恢复
  5. 重新校验签名发布清单和每个镜像的 Cosign 签名，再用短期只读凭据拉取镜像
  6. 执行 Database Migrator
  7. 重启 Runtime Service、Runtime Web 和 Workflow Worker
  8. 等待 /health/ready，然后清除未完成标记
  • 成功：Soln upgraded to <版本>. Backup: <部署目录>/.soln/backups/postgres-tenant-<时间戳>.sql.gz.enc
  • DEPLOYMENT_ALREADY_CURRENT —— 这个版本已经装好了
  • DEPLOYMENT_RECOVERY_REQUIRED —— 上一次升级没有走完，先按第 5 步回滚
  • 签名校验或 doctor 检查失败时，升级在改数据库之前就会停下；修好原因再执行同一条命令

第 4 步：验证新版本​

soln status --dir "$HOME/soln-tenant-runtime"
  • 成功：版本号是新版本，状态仍是 ready
curl -fsS -o /dev/null -w '%{http_code}\n' https://soln-<租户子域名>.localhost:8443/health/ready
  • 成功：200
  • 不是 200：按第 5 步回滚，不要手改文件

第 5 步：回滚​

soln rollback --dir "$HOME/soln-tenant-runtime"

迁移或健康检查失败、或新版本表现更差时使用。CLI 依次做这些事：

  1. 确认上一个发布和它的数据库备份还在（没有则报 DEPLOYMENT_ROLLBACK_UNAVAILABLE）
  2. 停止业务服务
  3. 恢复 PostgreSQL 备份
  4. 用上一个发布执行 Database Migrator
  5. 启动上一个发布并等待 /health/ready
  • 成功：Soln rolled back to <版本>.
  • No previous release and database backup are available. —— 要么还没升级过，要么备份已经被上一次回滚用掉了；用 soln status 看一下
  • 回滚后上一个发布成为当前版本，并且不再保留回滚目标，所以下次升级会重新写一份备份

注意事项​

  • 不要手改 .soln/deployment.json 和 .soln/docker-compose.release.yml：它们记录当前发布、镜像摘要和未完成的操作
  • .soln/backups 要留在同一块加密磁盘上，且不要删掉属于当前发布的那份备份
  • 只有打算重连 Runtime 时才轮换 Agent 密钥；本机部署里密钥只存在于部署目录的 .env
  • 不要在这个目录里重新执行 soln install（会报 DEPLOYMENT_ALREADY_INSTALLED），升级和回滚才是正确路径