升级、回滚与备份
装好之后的日常运维。
← 文档索引
先看这张表:四种改动,四条路
Bundle 不是"全量真相源",它只负责一件事——把集群收敛到「这些 release 都存在」。 所以别默认"改 YAML 再 apply"对所有改动都有效:
| 想改什么 | 走哪里 | 为什么不能走别的 |
|---|---|---|
| 换镜像(同一大版本内,重新打 tag 再推) | 控制台「次版本升级」 | 只改 Bundle 的 version 再 apply 是空操作,见下 |
| 跨大版本(v3 → v4) | Bundle:改 releaseVersion 后重新 apply |
大版本必须建新 Deployment,operator 只认 Bundle 这条路 |
| 小版本升级出问题,退回上一个 ReplicaSet | 控制台「回滚」 | 只在同一个 release 内生效 |
| 大版本升级出问题,流量退回旧 release | 控制台「降级」 | Bundle 会拒绝往回升,见下 |
| 改环境变量 / 挂载文件 | 控制台「重新配置」 | Bundle 只在首次安装和大版本升级时写这两样 |
「回滚」和「降级」是两件事,别混:前者换的是同一个 Deployment 里的镜像,后者换的是整个 Deployment(大版本)。看 Deployment 名有没有变就知道了。
后两条下面各有小节。kubectl 能做的只是同一件事的另一种入口(kubectl set image 等等),
但 kubectl 绕过记录,控制台会把每次变更写进 change-cause。
版本身份与镜像 tag
Bundle pack 里有两个不同的字段,升级时别混:
version是镜像 tag,可以带点,例如v3.1。releaseVersion是版本身份,形如v3,决定 Deployment 名(<app>-v3)、version/releaselabel 与 Istio subset。
两者不同时才需要写 releaseVersion;留空时按第一个点截断推断(v3.1 → v3)。点号不能进
Istio subset,所以身份必须是 DNS label。存量 Bundle 如果没有这个字段,导入时会自动按上面的
规则推断,不需要手工补。
主版本升级(v1 → v2)的镜像 tag 请直接写成 v2 或 v2.x,不要用 v1.1 这种「看起来像
次版本」的值去表示新的大版本——身份和 tag 是两回事。
升级:同一大版本内换镜像
重新构建、推送同一个大版本的 tag(例如把 v3.1 重新推到 v3.1,或推 v3.2),然后在控制台
对每个服务执行「次版本升级」。
- 这是就地滚动更新:只替换容器的 image,Deployment 名、
versionlabel、Istio subset 全都不动。 因此滚动期间新旧 Pod 共用同一个 subset,流量自然过渡,不需要全量发布。 - 一次只能升一个服务,按依赖顺序来:Themis → Rhea → Thia → 其余。
⚠️
kubectl apply -f bundle.yaml不会做这件事。 operator 的收敛规则是「目标 release 的 Deployment 不存在才动手」,同一大版本的 Deployment 一直在,于是整段跳过——apply 成功、 什么都没变,日志里也不会报错。只改version重新 apply 属于这一类。这个设计是有意的:Bundle 管"有哪些版本在跑",不管"某个版本里跑的是哪一版镜像"。
验收:kubectl get deploy <app>-v3 -o jsonpath='{.spec.template.spec.containers[0].image}'
看到新 tag;kubectl rollout status deploy/<app>-v3 收敛。
升级:跨大版本
Bundle 里把这个 pack 改成:
- app: thia-web version: v4 # 镜像 tag releaseVersion: v4 # 版本身份(可省略,从 tag 推断)kubectl apply -f bundle.yaml。operator 依次做三件事:新建 Deployment
<app>-v4→ 等它就绪 → 全量发布(Promote)。全量发布会把 Service、VirtualService、DestinationRule 全部收敛到
v4这一个 subset, 再把旧版本<app>-v3的副本数缩到 0。观察:
kubectl get deploy -n <您的命名空间> -l app=thia-web kubectl get pods -n <您的命名空间> -l version=v4
读 Deployment 列表时注意:旧版本不会消失,它是 0/0。这不是残留,是回滚的载体(见下节)。
kubectl get deploy 里同时看到 thia-web-v3 和 thia-web-v4 是正常状态。
⚠️ 大版本升级会按 Bundle 里的值重写环境变量和挂载文件。 如果这个服务在线上通过控制台 「重新配置」改过 env,那些改动不在 Bundle 里,会被升上去的 Bundle 值覆盖。升级前把线上值 回填进 Bundle,或者升级后在控制台重新 merge 一次。
验收同首次安装的「首次启动验收」,至少跑到第 4 项(能发一次对话),确认没问题再对旧版本 执行「删除版本」——它会连同 Deployment 和路由规则一起清掉,删完就没有降级这条路了。
回退
两条路,按故障的范围选。
小版本升级出问题 →「回滚」
在控制台的版本列表里对该 release 执行「回滚」,默认目标是上一个版本(也可以选具体 revision)。
- 把 Deployment 的 Pod 模板换回目标 ReplicaSet 的那份(镜像、env、挂载一起回去);
- Deployment 名不变,流量不用切——
<app>-v3还是那个 subset。
这就是 kubectl rollout undo 的等价物。它只在同一个大版本内有效:换大版本之后,
上一个 ReplicaSet 属于另一个 Deployment,要用下面的降级。
大版本升级出问题 →「降级」
在版本列表里对旧的 release(v3)执行「降级」。发生的事:
v3的 Deployment 副本数拉回到当前活动版本的副本数;- Service 的
versionlabel、VirtualService、DestinationRule 指回v3; - 被替换掉的
v4副本数缩到 0(Deployment 仍然保留)。
即降级不重建、不拉镜像、不走数据库——旧版本一直在集群里,所以它是秒级的。
⚠️ 不能改小
releaseVersion再 apply Bundle 来回退。 两种结局都不是回退: 旧版本的 Deployment 还在(0/0),operator 直接跳过;旧版本已经从集群里删掉的话, operator 会以UPGRADE_MAJOR_INVALID_VERSION拒绝——它要求新身份大于当前身份。 这是为了防止「apply 一份旧 Bundle」这种看起来无害、实际会把「回退」和「部署」 两种语义混在一起的操作。
降级之后再 apply 同一份 Bundle 是无操作的(<app>-v4 已经存在),流量不会自己弹回新版本;
要回到新版本,在控制台对 v4 再「全量发布」一次。这意味着 Bundle 文件和集群的实际路由可能
暂时不一致,回退期间别用 Bundle 做其他变更。
数据库回滚
镜像回退不等于 schema 回退。 迁移脚本只向前:把服务退回 v3,它面对的是 v4 改过的表结构。
判断标准只有一条——v4 有没有跑过破坏性迁移(删列 / 改类型 / 重命名):
- 没有(只加表、加列、加索引):回滚安全,旧代码会忽略新结构;
- 有:不能只回滚应用,必须连数据库一起恢复到变更前的备份。先按下一节做一份当前备份, 再从备份恢复。
备份
需要备份的只有三样,其中前两样是"重建不出来"的:
| 对象 | 内容 | 丢了会怎样 |
|---|---|---|
| PostgreSQL | 用户、积分账本、会话与消息(含附件 base64)、Agent 定义、发布记录 | 数据没了 |
| Secret | JWT 密钥对、会话签名密钥、SMTP 与支付凭据、DATABASE_URL |
数据还在,但所有人被登出、外部服务要重配 |
| Bundle 文件 | 哪个版本在跑、配了哪些 env | 集群仍在跑,但"照原样重建一次"没有参照 |
不需要备份的:镜像(在镜像仓库里)、集群结构(Bundle 描述的就是它)、
用户上传的附件(以 base64 随消息存库,已经在 PostgreSQL 里)、
tethys-shipping 的 SQLite(没挂 PVC 的话它本来就随 Pod 走,见手动部署里那一条)。
数据库
多服务共用一个库,整库导一次即可:
pg_dump -Fc -h <数据库主机> -U <用户名> -d <库名> -f backup-$(date +%Y%m%d).dump
恢复:
pg_restore -h <主机> -U <用户名> -d <库名> --clean --if-exists backup-YYYYMMDD.dump
先停服务再恢复,否则运行中的服务会连着半恢复的库继续写。最小的停机范围是把会写库的
服务都缩到 0——thia-agent(会话与消息,持续写)、themis-auth(注册与登录)、
rhea-payment(账本);恢复完再拉回来。只读的服务可以不停。
Secret
kubectl get secret -n <您的命名空间> -o json > secrets-backup-$(date +%Y%m%d).json
⚠️ 这个文件是明文(base64 不是加密),等同于集群的密钥。存进密码管理器或加密卷, 不要提交到 git、不要走邮件。
恢复顺序
首次安装时是「Secret 先于 Bundle」,恢复也一样:
- Secret —— Bundle 引用的 Secret 必须存在,否则 Pod 卡在
CreateContainerConfigError; - 数据库 —— 应用起来之前恢复,避免新旧版本混写;
- Bundle ——
kubectl apply,operator 把 Deployment / Service 建回来。
任何一步失败,都回到排障对应的迹象。