跳转到内容

第 9 章 Docker、Kubernetes、部署与发布恢复

来自《系统架构与工程化学习》 · 原稿更新 2026-11-09 · 服务器只读阅读视图

9.1 Dockerfile、Image、Container 与 Volume

Dockerfile 是构建说明,Image 是可分发镜像,Container 是用镜像创建的运行实例,Docker CLI 通过引擎(daemon)实际管理两者。

我踩过的坑

  • 把 Dockerfile、镜像、容器看成同一个东西。
  • 以为停掉旧容器就会自动用上新镜像,以为多服务用了 Compose 就会被合成一份镜像。
  • 想保留容器里的日志或任务文件,直接跳到“用 MongoDB”。

正确理解

  • docker pull 拉下来的是 Image,不是别人正在跑的 Container。CLI 能用之后,还要确认它连的是哪个 Docker daemon 和 Context。
  • 停掉旧容器不会自动升级,要用新镜像重新创建容器。Compose 负责组合多个服务、网络和依赖,不会把镜像合并;同一个镜像也可以启动多个容器。
  • depends_on 默认只保证启动顺序。要等业务真正就绪,需要配健康检查和对应的等待条件。
  • 同一网络里的服务按服务名互相访问,不要写死容器 IP;用 HTTP 还是 WebSocket 是另一层的选择。
  • Volume 和 Bind Mount 负责持久化文件,数据库负责查询和约束,集中日志方便跨实例检索。Volume 也不是异地备份。
  • 在容器里临时 pip install 改的只是可写层,重建后可能就没了。正确做法是更新依赖和锁文件,重新构建并测试镜像,再按发布流程替换。

9.2 环境配置、Secret 与配置中心

代码定义规则,配置表达环境差异,Secret 保存凭据,数据库保存运行状态,日志提供排障证据。

我踩过的坑

  • 知道 .env 加 .gitignore 不等于秘密管理,但说不清容器 Secret 为什么常采用文件方式。
  • 部署代码时顺手把本地配置覆盖到了服务器。

正确理解

  • 密钥不进 Git、不进镜像、不进普通配置文件。生产数据库给每个服务单独开最小权限账号。
  • Config 解析非敏感的 YAML,SecretSettings 从环境变量读敏感值,Settings 把两者组合起来统一使用。以后换成远程配置中心时,这层接口能否保持不变还需要验证。
  • 同一个验证过的镜像,按环境注入不同配置;Compose 可以用多个配置文件或环境变量来区分。.env 加 .gitignore 仍然不算密钥管理,生产环境还需要权限控制和轮换,见第 8.4 节。
  • 容器 Secret 以受控文件的方式提供,可以限制谁能读;部分平台还支持加密、审计和轮换。但文件挂载本身不保证安全,要具体核对 Compose、Swarm、K8s 或外部密钥服务的实现。
  • 环境变量解决的是“进程怎么读到值”,配置中心解决的是“集中分发和管理”。热更新必须由应用自己监听、轮询或重新读取,接了 Nacos 或 Consul 也不会让所有配置自动生效。
  • 旧 StudyBuddy 项目本地通过 SSH 隧道用 3307 端口,服务器本机 MySQL 是 3306,误把本地 .env 传上去就会弄坏生产连接。同步代码时要排除环境配置,并核对进程实际读到的值。这只是旧部署的例子。

Finder 与 launchd 两套环境、MCP 反弹、cron 离线、原生依赖、Bash 版本、Node 版本和 CLI 路径的具体故障,案例见附录 A.9.1 至 A.9.7。

来源

旧库 90-归档/20-个人/参考资料与规范/项目运维/studybuddy后端部署到腾讯云指南.md 第 45—71 行;凭据不进入主书。

9.3 Nginx、TLS 与服务器安全

常见外部入口是 80/443 → Nginx → 内网服务端口;数据库尽量不直接对公网开放,必要时用 SSH 隧道管理。

正确理解

  • 改共享的 Nginx 之前,先确认是哪个环境,并看清所有站点的配置,不能覆盖无关服务。
  • 语法检查通过之后才 reload。
  • TLS(AI 补充,待学习):常在 Nginx 终止 HTTPS,证书要有自动续期和到期告警。Nginx 到内网服务默认是明文,敏感内网要另行评估。

9.4 Kubernetes 控制器与收敛

Deployment 等控制器管理期望副本,Scheduler 为 Pod 选择节点,Service 为一组实例提供稳定访问入口。

图解:Kubernetes:控制平面与工作节点

Kubernetes:控制平面与工作节点(官方原图)

读图: 先区分控制平面和工作节点,再找控制器、调度器与 kubelet 各自的位置。声明目标之后由相关组件持续协调,不是 Pod 自己保证副本数。

来源:Kubernetes 官方文档 Components of Kubernetes;原SVG等比转PNG,未改图中内容。2026-10-28 核对。

我踩过的坑

  • 把“声明式”理解成 Pod 自己按规则运行,Control Plane 只在突发故障时发一次通知。

正确理解

  • 声明期望 5 个副本后,控制器会持续把实际副本数往这个目标上拉;Pod 自己不会维护副本数。
  • Scheduler 负责给新 Pod 选节点。控制器平时就在持续收敛,故障只是让期望和实际的差距变大,并不是平时没事、出事才介入。
  • 把副本恢复回来是平台的职责,业务结果对不对,仍要按第 9.6 节验收。

9.5 Liveness、Readiness、制品与灰度

Liveness 判断应用是否需要重启,Readiness 判断实例是否适合接流量;两者目的不同,误配会导致反复重启或流量进入异常实例。

我踩过的坑

  • 能解释“怎么知道不健康”,却没继续问“检测到后谁负责摘流量、重启、告警或恢复”。
  • 2026-07 我以为 Canary 能持续指向 Test 的 Latest;但 Test 仍在迭代,灰度版本就会漂移。当时还缺统一 release_id,只是待完善方案,尚未上线。

探针

  • Startup Probe 给启动慢的服务多留时间,避免 Liveness 过早把它重启。
  • Readiness 失败通常会把 Pod 从 Service 端点里摘掉。Docker HEALTHCHECK 报 unhealthy 并不保证自动重启或摘流量,这些动作要靠编排器执行。
  • 探针要明确服务“是否活着”和“是否适合接某类流量”。Liveness 只要进程能继续运行就可以保持健康,局部非关键依赖故障可能报 degraded;Readiness 是否仍返回成功,要看该依赖是否影响正在接收的业务请求,不能统一写成“所有 degraded 都返回 HTTP 200 才不会摘流量”。
  • 细粒度状态能帮运维,但监控和负载均衡实际用哪个 Endpoint 必须核对。

制品与灰度

  • 先固定代码、配置、Prompt 和 Schema,再把测试通过的那一个镜像制品升到灰度。同一提交重新构建一次,得到的不一定是同一个制品。
  • 用 release_id 把镜像摘要、流程、Prompt、Schema、模型参数和必要的配置版本绑在一起,放量和回滚都只针对这个候选版本。
  • Canary 先验证真实 API、业务结果和日志,再扩大放量。回滚时要处理在途任务,降到 0%、重试和补偿见第 6.9 节。
  • 一套具体的正式环境灰度对接(按业务主键哈希分桶、5 个透传字段、topic 隔离、配置不合法按 0 处理、replay 不重新分桶、验收清单)见服务拆分与发布。

历史方案冲突不能靠最后一段总结消掉

2026-08至10月的环境调研同时保留“两套常驻核心实例”“一套稳定面加临时集成环境与影子通道”等建议,尚无统一落地验收。本轮只吸收共同约束:共享仓库和制品可以,测试与正式共用进程仍有共同故障域;flag不能隔离启动失败或资源耗尽;影子差异不提供语义真值,首次上线还缺可信旧版。

待确认:是否常驻第二套,取决于发布频率、破坏性测试、语义质量基线、成本及故障隔离要求。原稿“AI质量永远无法前移预览”的断言过强,能固定真实输入、模型和依赖的部分仍可做离线回放;不能验证的部分才留到受控在线观察。清除最终输出也不等于无副作用,仍须限制数据库、缓存、外部调用和资源配额。

正式环境与灰度历史方案。

滚动发布(AI 补充,待学习)

  • Deployment 分批用新版本替换旧实例:maxSurge 控制最多多开几个,maxUnavailable 控制最多少几个;新实例通过 Readiness 才接流量。
  • 滚动期间新旧版本同时在跑,API 和数据库要兼容,见第 6.2 节。来源:Kubernetes Deployment。

影子运行与 Canary

影子运行和 Canary 应分开验收

阶段 正式结果由谁产生 验证重点
离线测试 无线上输出 已收集用例是否通过
Shadow(影子) 稳定版;候选只对经许可的真实输入做隔离计算 分歧、错误、延迟、成本,候选不得产生真实副作用
Canary(灰度) 小流量由候选真正处理 用户影响、版本和成本,触发失败门禁就停止扩大
  • Shadow 也要隔离发消息、写库、下单和调用第三方工具这些副作用,并遵守隐私授权;它还会带来额外的模型成本。历史上这只是设计方案,没有验证过全面上线。
  • 采样和用户落桶要分别设计:顺序放行可能造成流量突刺,随机抽样不容易复现,计数器采样在单实例容易均匀但多实例不共享计数就不一定全局均匀。要确保同一用户或会话一直用同一版本,可用稳定身份的确定性哈希分桶,匿名流量另设策略。
  • 2026-08 三方案评审选了计数器,那是当时测试环境的方案,不是已跨实例验证的通用最优。

9.6 进程状态与业务健康

docker ps 的 Up 或 pm2 的 Running 只说明主进程还在,业务是否成功仍要查真实接口、依赖和部署版本。

我踩过的坑

  • 服务器容器很多时,我一开始纠结要背哪个名字,甚至把 grep 误当成“查错误”的命令。
  • 早期只想到把日志文件挂 Volume 来防丢,忽略了日志散落、积压、磁盘耗尽,也忽略了运行日志和审计日志职责不同。

进程与健康状态

  • docker ps 显示 Up、pm2 显示 Running,只说明进程在;HEALTHCHECK 的 starting、healthy、unhealthy 反映的是探测结果。最终还要查 API、数据库、MQ、Worker、外部依赖和实际运行的版本。已经停止的容器要用 docker ps -a 才看得到。

  • 健康状态不是沿 starting→healthy→unhealthy 单向走的,也可以从 unhealthy 恢复成 healthy。start_period、interval、timeout、retries 的含义和 Compose 的行为,要按实际版本和配置核对。

  • 监控要记录容器 health、真实接口耗时、MQ 的 backlog 和消费确认。进程内队列是空的,不代表外部没有积压,见第 7.3 节。

  • 常驻采集任务迁移时,停旧并处理在途任务后记录最后确认的进度,接管和回退都检查缺口、重复与归属。见实时数据链路第九节。

  • 排查 CPU 时,先统一百分比的分母,再把资源消耗与有效产出、重启和失败次数放在同一时间窗比较。见采集系统第十节。

找容器与读日志

  • 按业务、环境、API 或 Worker 角色找容器:先用 docker ps 列出名字,再用 grep 过滤,确认目标后再读日志。服务也可能不是 Docker 跑的,而是由其他进程管理器托管。
  • 排查先只读。要改数据库或回滚之前,先核对权限、影响范围和恢复路径。
  • 容器的运行日志走 stdout/stderr,交给 Docker 日志驱动或集中收集,并做好轮转和保留;审计日志另外管理操作主体、访问权限和留存期限。
  • 2026-07 我在开发服务器通过 SSH 核对 hostname、whoami、pwd 和 docker ps,按业务和角色定位容器,没有为了练习去读无关的生产日志或 Trace。故障时按“列出容器 → 选准确目标 → docker logs --since 2h --timestamps <容器名> → 按请求 ID 查 Trace”逐层找证据;没有日志时先核对容器、日志出口、时间与筛选词,不能直接判断“系统没错”。

连接排查与凭据

  • 远程数据库 TCP 连得上,仍可能是数据库协议、认证、访问规则或服务端配置失败。只看 nc 的端口探测结果,不能断言安全组已放行全部数据库通信。
  • 历史项目曾用已授权的 SSH 本地端口转发避开易变的公网客户端 IP,但这是特定部署方案,不表示生产数据库一律适合 SSH 隧道;要限制连接用户权限、检查端口绑定和隧道生命周期,也不要随意对占用某端口的进程 kill -9。
  • 旧草稿里有明文凭据和服务地址,这些不写进知识书或日志;要按它们现在是否仍有效,检查是否需要轮换以及历史访问权限。

Bridge 从 worktree 修好到生产真正换代码之间的缺口,案例见附录 A.9.8。

来源

健康检查补充来源:10-wiki/personal/wiki/queries/验证docker-ps的Up状态与业务健康之间的边界.md、Docker-HEALTHCHECK三态与重试参数的真实状态迁移.md、进程内队列与MQ积压如何通过指标和代码验证.md;Docker HEALTHCHECK 官方参考。

本章原始笔记

Docker · K8s · 服务器部署与排障

9.7 部署对齐源码、制品、进程与恢复来源(待学习)

供应商记录、live 配置和恢复快照都可能写回旧值;切换前保护状态,逐应用查接管开关,重启后核对实际请求。部署要把提交、部署文件和运行镜像 ID/digest/revision 对上,health 200 与 detached HEAD 都不能单独说明版本错误或一致。

重贴标签不等于重构建:以构建记录绑定镜像,再核对候选与合并提交的 tree;源码树相同不证明依赖和环境相同。PM2 online 还要查 ESM main、监听和业务;切脚本也要核对 pm_cwd,必要时只重建目标进程并验证旁边服务没重启。回滚还需查数据兼容,恢复旧文件不保证旧上游可用。

来源与当时边界

原始记录 2026-10-29 · 原始记录 2026-10-29 · 原始记录 2026-10-29 · 原始记录 PM2 显示 onl · 原始记录 PM2 切换脚本不一