新版本镜像上线后出现启动失败、接口异常或就绪探针不通过时，第一优先级往往不是立刻定位根因，而是尽快把业务恢复到上一个稳定版本。Kubernetes 的 Deployment 会保留发布历史，一条回滚指令就能让控制器重新拉起旧镜像的 Pod。

一、回滚前先确认当前发布状态

执行回滚前，先用几条只读命令确认问题确实来自新版本，避免误操作扩大影响。

• 查看发布历史：kubectl rollout history deployment/my-app -n prod
• 查看某个版本的详情：kubectl rollout history deployment/my-app --revision=3 -n prod
• 查看发布进度：kubectl rollout status deployment/my-app -n prod
• 查看 Pod 与事件：kubectl get pods -n prod -l app=my-app、kubectl describe pod pod-name -n prod

如果确认异常集中在新版本 Pod，且旧版本在历史记录中可查，就可以直接进入回滚。

二、最常用方式：kubectl rollout undo

回到上一个版本

不带参数时，默认回退到当前版本的前一个 revision：

kubectl rollout undo deployment/my-app -n prod

回到指定历史版本

当最近一个历史版本同样存在问题，可以指定目标 revision：

kubectl rollout undo deployment/my-app -n prod --to-revision=3

回滚原理

Deployment 每次更新 Pod 模板都会生成新的 ReplicaSet。rollout undo 的本质是把 spec.template 切回目标 revision 对应的 ReplicaSet，随后由控制器按原有策略创建新 Pod、逐步替换异常 Pod。整个过程仍然遵循滚动更新规则，因此不会一次性中断全部实例。

对于 DaemonSet，以及较新版本 Kubernetes 中的 StatefulSet，kubectl 也提供了对应的回滚子命令，使用前建议先用 kubectl rollout undo --help 确认当前客户端与集群版本的支持情况。

三、直接指定镜像的回退方式

如果历史版本记录不完整，或需要明确指定某个稳定 tag，可以直接修改镜像：

kubectl set image deployment/my-app web=registry.example.com/my-app:1.2.3 -n prod

其中 web 是容器名称，必须与 Deployment 中定义的容器名一致。该方式同样会触发一次新的滚动发布，因此也会产生新的 revision。

四、回滚后的验证动作

回滚指令返回成功只代表变更已提交，业务是否真正恢复还需要验证：

1. 观察发布状态：执行 kubectl rollout status deployment/my-app -n prod，确认滚动更新完成。
2. 确认 Pod 就绪：用 kubectl get pods -n prod 检查 READY 列与重启次数，异常 Pod 可用 describe 查看事件。
3. 核对运行镜像：用 kubectl describe deployment/my-app -n prod 确认 Image 字段已回到目标 tag。
4. 检查日志与探针：查看容器日志，确认启动日志、依赖连接与健康检查均正常。
5. 确认流量恢复：结合 Service、Ingress 与监控面板，确认请求成功率、延迟等指标回到正常区间。

五、容易被忽略的注意事项

• 回滚范围有限：Kubernetes 只回滚工作负载的 Pod 模板，不会回退 ConfigMap、Secret、数据库结构变更、PVC 中的数据以及集群外部的配置。
• 镜像 tag 必须可区分：如果一直使用 latest 或内容被覆盖的固定 tag，回滚后的镜像内容可能仍然是新的，回滚会失去意义。
• 历史版本数量有限：Deployment 通过 revisionHistoryLimit 控制保留的历史版本数量（默认通常为 10），设置过小会导致旧版本被清理，无法再回退到目标 revision。
• 补充可读的变更说明：为发布添加 kubernetes.io/change-cause 注解，可以让 rollout history 中的记录更容易辨认。
• 回滚是止血而非修复：业务恢复后仍应结合日志、事件与监控定位新版本的问题，修复后再安排下一次发布。

把回滚指令、验证步骤和责任人写入发布预案，并在预发环境演练一次，才能在真正出现故障时做到几分钟内恢复业务。