第 4 章:打包发布:镜像、配置与迁移
发布最怕的不是"发不上去",是"发上去了但数据坏了"。这一章的重点在顺序:镜像、配置、迁移、健康检查,谁先谁后是有讲究的。
学习目标
- 把配置和密钥从代码里彻底剥离,并知道密钥该放哪
- 用"扩展—迁移—收缩"三步走改表结构,做到任何一步都能回退
- 区分存活检查与就绪检查,别让健康检查把服务自己搞挂
- 拿到一份首次部署的执行顺序清单
4.1 发布要满足的三个条件
| 条件 | 含义 | 不满足的后果 |
|---|---|---|
| 可复现 | 同一份代码,任何时候构建出同样的镜像 | "我这儿是好的"无法复现 |
| 配置外置 | 环境差异靠环境变量,不靠改代码 | 每次切环境都要改代码 |
| 数据可迁移 | 表结构变化有脚本、有顺序、可回退 | 发布即数据事故 |
4.2 配置与密钥
yaml
# docker-compose.yml 只引用,不写值
services:
api:
image: ghcr.io/you/app:1.2.3
env_file: .env
environment:
- TZ=Asia/Shanghaibash
# .env 放在服务器上,权限收紧
chmod 600 .env
chown deploy:deploy .env四条纪律:
.env不进仓库,.gitignore里必须有它;- 密钥不进镜像:镜像会被推到 registry,写进镜像等于公开;
- 区分环境变量与密钥:日志级别、端口是配置;数据库密码、模型 API Key 是密钥,后者要能轮换;
- 一个变量一个来源:别出现"代码里有默认值、.env 里又有另一份"的双份配置。
轮换这件事平时用不上,出事时救命:密钥泄露后的第一动作是换新密钥 + 重启服务,而不是先去查日志。所以平时就要知道"这个 Key 从哪改、改了要重启什么"。
4.3 数据库迁移:三步走
改表结构最常见的两种事故:新代码上线后,旧表结构对不上;或者迁移脚本跑了一半失败,留下半新半旧的库。
扩展—迁移—收缩(expand / migrate / contract):
配套的三条硬规矩:
| 规矩 | 原因 |
|---|---|
| 迁移先于新代码,但只限"新增"类 | 新增可空列不会破坏旧代码 |
| 删除类迁移晚于代码下线 | 先让旧代码停止使用该列,再删 |
| 每次发布前先备份 | 迁移失败时,备份是唯一退路 |
4.4 健康检查:两种,别混
| 类型 | 回答的问题 | 该检查什么 |
|---|---|---|
| 存活(liveness) | 进程还活着吗 | 进程能响应即可,不查数据库 |
| 就绪(readiness) | 能接流量吗 | 数据库连接、必要依赖可用 |
python
@app.get("/healthz") # 存活:极轻,1ms 内返回
def healthz():
return {"ok": True}
@app.get("/readyz") # 就绪:查一次轻量查询
async def readyz():
await db.execute("SELECT 1")
return {"ok": True}为什么存活检查不能查数据库:数据库短暂抖动时,存活检查失败 → 编排器重启应用 → 应用重启后又连不上(数据库还在抖)→ 循环重启,把一个"等几秒就好"的小故障变成"服务雪崩"。
4.5 首次部署的顺序
按这个顺序走,每一步失败都能停在原地,而不是"整个系统半死不活"。
4.6 五种常见失败
| 现象 | 常见原因 | 排查 |
|---|---|---|
| 容器起来就退出 | 启动命令错、缺环境变量、端口被占 | docker compose logs --tail=50 |
| 502 Bad Gateway | 应用没监听 127.0.0.1,或端口不匹配 | ss -ltnp | grep 8000 |
| 上传报 413 | Nginx client_max_body_size 太小 | 改配置 reload |
| 权限错误(写文件失败) | 容器内用户与卷属主不一致 | 检查卷权限与 user: 配置 |
| 时间差 8 小时 | 容器时区没设 | TZ=Asia/Shanghai |
排查顺序建议固定为:容器状态 → 端口监听 → 应用日志 → 代理配置。从内往外查,比从外往里猜快得多。
4.7 一次能做对的发布
| 环节 | 做对的标准 |
|---|---|
| 镜像 | tag 带版本号或 digest,不用 latest |
| 配置 | 只从环境变量读,缺了就启动失败(快失败好过带病运行) |
| 迁移 | 只做新增,能重复执行,先备份 |
| 启动 | 健康检查通过才宣告成功 |
| 验证 | 域名访问 + 一条关键业务路径 |
最后一条最容易被省:发布后不是"容器起来了"就算完成,而是"用户那条主流程能走通"。
本章小结
| 要点 | 说明 |
|---|---|
| 三条件 | 可复现、配置外置、数据可迁移 |
| 密钥 | 不进仓库、不进镜像、可轮换 |
| 迁移 | 扩展 → 双写回填 → 收缩,分两次发布 |
| 迁移纪律 | 幂等、先备份、先加后删 |
| 健康检查 | 存活不查库,就绪才查依赖 |
| 部署顺序 | 备份 → 迁移 → 起服务 → 两层检查 → 业务验证 |
| 排查 | 容器 → 端口 → 日志 → 代理 |
下一章
手工发布跑通了,接下来让它自动跑:push 触发、构建、部署,以及失败时怎么退回去。