Skip to content

第 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/Shanghai
bash
# .env 放在服务器上,权限收紧
chmod 600 .env
chown deploy:deploy .env

四条纪律:

  1. .env 不进仓库,.gitignore 里必须有它;
  2. 密钥不进镜像:镜像会被推到 registry,写进镜像等于公开;
  3. 区分环境变量与密钥:日志级别、端口是配置;数据库密码、模型 API Key 是密钥,后者要能轮换;
  4. 一个变量一个来源:别出现"代码里有默认值、.env 里又有另一份"的双份配置。

轮换这件事平时用不上,出事时救命:密钥泄露后的第一动作是换新密钥 + 重启服务,而不是先去查日志。所以平时就要知道"这个 Key 从哪改、改了要重启什么"。


4.3 数据库迁移:三步走 ​

改表结构最常见的两种事故:新代码上线后,旧表结构对不上;或者迁移脚本跑了一半失败,留下半新半旧的库。

扩展—迁移—收缩(expand / migrate / contract):

以「把 price 列改名为 amount」为例① 扩展新增 amount 列(可空)旧代码不受影响不改任何现有读写可随时回退:删掉新列即可② 双写 + 回填新代码同时写两列读时优先新列、回退旧列跑脚本把历史数据补齐此阶段两版代码都能跑③ 收缩确认新列稳定后再删旧列这一步不可逆放在下一次发布做别和②挤在同一次一次发布就做完三段?绝大多数事故都出在这里三段压成一段意味着:上线那一刻,旧代码读写不到新列、新代码读不到旧数据,任何一次回滚都会丢数据简化原则:只加不改、改名靠新增、删除单独排一次。这三条能挡掉八成事故。迁移脚本必须能重复执行(幂等),因为失败后你会想"再跑一遍试试"。

配套的三条硬规矩:

规矩原因
迁移先于新代码,但只限"新增"类新增可空列不会破坏旧代码
删除类迁移晚于代码下线先让旧代码停止使用该列,再删
每次发布前先备份迁移失败时,备份是唯一退路

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
上传报 413Nginx client_max_body_size 太小改配置 reload
权限错误(写文件失败)容器内用户与卷属主不一致检查卷权限与 user: 配置
时间差 8 小时容器时区没设TZ=Asia/Shanghai

排查顺序建议固定为:容器状态 → 端口监听 → 应用日志 → 代理配置。从内往外查,比从外往里猜快得多。


4.7 一次能做对的发布 ​

环节做对的标准
镜像tag 带版本号或 digest,不用 latest
配置只从环境变量读,缺了就启动失败(快失败好过带病运行)
迁移只做新增,能重复执行,先备份
启动健康检查通过才宣告成功
验证域名访问 + 一条关键业务路径

最后一条最容易被省:发布后不是"容器起来了"就算完成,而是"用户那条主流程能走通"。


本章小结 ​

要点说明
三条件可复现、配置外置、数据可迁移
密钥不进仓库、不进镜像、可轮换
迁移扩展 → 双写回填 → 收缩,分两次发布
迁移纪律幂等、先备份、先加后删
健康检查存活不查库,就绪才查依赖
部署顺序备份 → 迁移 → 起服务 → 两层检查 → 业务验证
排查容器 → 端口 → 日志 → 代理

下一章 ​

手工发布跑通了,接下来让它自动跑:push 触发、构建、部署,以及失败时怎么退回去。

本文阅读--次|全站访问--次|访客--人