第一次把服务容器化,很多人会经历同一个下午:镜像构建了二十分钟,推上去 1.8 GB;容器启动十秒后被编排系统杀掉,日志显示「健康检查失败」,可服务其实已经起来了,只是探针打到了一个需要登录的接口;改数据库地址时发现配置写死在镜像里,只能重新构建、重新推送、重新部署。三件事凑在一起,一次小改动耗掉半天。
容器化本身不难,难的是把「镜像、网络入口、进程状态、配置来源」这四件事的边界划清楚。这篇按这四个部分讲,每部分给一份可以直接改用的配置,并说明换语言时哪一层要动。
先看几个常见现象
| 现象 | 真实原因 | 第一步查什么 |
|---|---|---|
| 镜像 1 GB 以上,构建十几分钟 | 把编译工具、源码、测试文件全打进运行镜像 | 看 docker history 里哪一层最大 |
| 容器启动后很快被重启 | 存活探针路径返回 401 或 500,或探针超时太短 | 看探针配置的路径、端口、初始延迟和超时 |
| 服务已经能处理请求,流量却迟迟不来 | 就绪探针和存活探针用了同一个宽松条件 | 查 readiness 是否真的检查依赖就绪 |
| 日志里客户端 IP 全是网关地址 | 反向代理没有透传 X-Forwarded-For | 抓请求头,看应用读的是哪个字段 |
| 改一个数据库地址就要重新发版 | 配置写死在镜像或代码里 | 查镜像内是否有环境相关配置文件 |
| 滚动更新时一半请求 502 | 旧实例先被停,新实例还没就绪,或优雅停机时间太短 | 查发布策略、就绪探针和停机宽限期 |
| 容器内是 root,安全扫描一堆高危 | 基础镜像默认用户,没有切换非 root | 看 Dockerfile 是否有 USER 指令 |
这七条里,只有第一条是「镜像大小」问题,其余都是边界问题:谁负责判断进程活着,谁负责转发真实信息,配置从哪里来。边界清楚,部署脚本才稳定。
镜像:只放运行需要的东西
镜像分层的规则很简单:每条指令生成一层,层会缓存。把变化频繁的放在后面,变化少的放前面。先拷依赖清单再装依赖,最后拷源码,这样改业务代码时不会重装依赖。
多阶段构建是控制体积最有效的手段。第一阶段用完整镜像编译,第二阶段只拷产物到运行时镜像。Node、Go、Java、Rust 都适用:编译工具留在第一阶段,运行镜像只留运行时和产物。
# 第一阶段:构建
FROM node:24-alpine AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build
# 第二阶段:运行
FROM node:24-alpine
WORKDIR /app
ENV NODE_ENV=production
COPY --from=build /app/dist ./dist
COPY --from=build /app/node_modules ./node_modules
USER node
EXPOSE 8080
CMD ["node", "dist/main.js"]
几个细节容易漏。.dockerignore 要排除 node_modules、.git、测试数据和本地配置,否则构建上下文会把这些全传给 Docker。基础镜像尽量固定到具体版本甚至 digest,不要用 latest,否则今天和明天构建出的环境可能不同。运行时切到非 root 用户,减少容器逃逸后的影响面。
构建缓存要利用好,也要懂得失效。把依赖清单放在源码之前拷贝,改业务代码时依赖层还能命中缓存;但如果依赖清单变了,缓存会失效并重新安装,这是正常的。不要为了「每次都干净」加 --no-cache,那会让每次构建都多花几分钟。CI 里可以给构建器配置远程缓存,多个流水线共享依赖层,省下来的时间比调优镜像大小更直接。
基础镜像的选择也是长期成本。官方镜像、维护活跃的发行版、定期打补丁,比「体积最小」更重要。选一个没人维护的精简镜像,半年后漏洞扫描一片红,再换基础镜像又要重新验证一遍运行环境。镜像扫描要进 CI,发现高危漏洞就挡住发布,而不是等上线后再补。
镜像里不要放密钥。有人为了省事把 .env 拷进去,结果镜像推到仓库后,任何有拉取权限的人都能看到数据库密码。密钥应该在运行时注入,下面会讲。
反向代理:入口要传对信息
反向代理是流量进入容器的第一站,常见选择是 nginx、Traefik、云厂商的负载均衡。它至少要做四件事:转发请求、透传真实客户端信息、设置合理的超时、限制请求体大小。
server {
listen 80;
server_name api.example.com;
client_max_body_size 10m;
location / {
proxy_pass http://api:8080;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_connect_timeout 5s;
proxy_send_timeout 30s;
proxy_read_timeout 30s;
}
}
应用侧要显式信任代理,再读取 X-Forwarded-For 的第一个地址。不同框架默认行为不一样,有的默认不信任任何代理头,有的信任全部。信任全部的风险是客户端可以伪造 IP,绕过基于 IP 的限流。正确做法是配置可信代理的网段,只对来自这些网段的请求解析转发头。
超时要分层设置。代理的读超时应该比应用自身的处理超时略长,否则应用还在算,代理已经断开,用户看到 504,应用日志却是成功。上传接口和大报表接口要单独放宽超时,不要全局设成十分钟。
长连接和 WebSocket 要单独配置。默认的短连接代理会在空闲一段时间后断开,前端表现为「过一会儿就重连」。需要设置 proxy_read_timeout 或心跳,并在代理和应用之间约定保活间隔。连接数也要限制,单个客户端开几百条长连接,代理的连接表会先满,正常用户连不进来。
代理还承担限流和日志的第一层。按 IP 限流放在这里成本最低,但要注意 NAT 会把很多用户合并成一个 IP;更细的按用户限流还是放应用层。访问日志至少要记录真实 IP、状态码、耗时、上游地址和请求 ID,方便和应用日志对齐。
访问日志的格式要和应用日志的字段名对得上。代理记 request_time,应用记 duration_ms,两边算出来的耗时含义也不一样:代理包含网络和排队,应用只包含处理。排障时先明确看的是哪一段,不要把两个数直接相减当成「网络延迟」。日志里还要记录上游响应时间,否则分不清是代理慢还是应用慢。
健康检查:活着的和能干的,是两件事
健康检查分两种。存活探针回答「进程要不要重启」,就绪探针回答「现在能不能接流量」。很多事故来自把两者混成一个接口。
存活探针
只检查进程自身是否卡死,比如能不能响应一个极轻量的本地请求。不要检查数据库、Redis、第三方接口。下游一抖,所有实例都被判死重启,故障反而扩大。
就绪探针
检查服务是否具备接流量的条件:迁移是否跑完、缓存是否预热、必需的下游是否可达。未就绪时编排系统会把实例摘出流量,但不重启它,等它恢复。
探针参数要给启动留时间。initialDelaySeconds 太短,应用还在启动就被判失败;timeoutSeconds 太短,GC 或高负载时一次慢响应就触发重启。通常启动探针单独设一个较长的失败阈值,存活探针用较短周期,就绪探针介于两者之间。
启动慢的服务最好用专门的启动探针。startupProbe 在成功之前会一直等,不会让存活探针提前介入;启动成功后,存活探针才开始计时。这比把 initialDelaySeconds 调得很大更精确,也不会让已经启动的服务多等几分钟。Java、Node 的大型应用、需要预热缓存的服务,都值得单独配。
livenessProbe:
httpGet: { path: /healthz, port: 8080 }
initialDelaySeconds: 10
periodSeconds: 10
timeoutSeconds: 3
failureThreshold: 3
readinessProbe:
httpGet: { path: /readyz, port: 8080 }
initialDelaySeconds: 5
periodSeconds: 5
timeoutSeconds: 3
failureThreshold: 3
健康检查接口不要做重活。/healthz 只返回进程状态,/readyz 可以查一次本地缓存标记或轻量依赖,但不要每次都跑全量 SQL、不要调用收费的第三方接口。探针每秒都在打,重活会把服务自己拖慢。
优雅停机也要配。收到终止信号后,先停止接新请求,把在途请求处理完,再退出。宽限期要大于最长请求耗时,否则用户会看到连接被重置。异步消费者还要在停机前提交位点或释放租约。
优雅停机要和就绪探针配合。收到终止信号后,先把就绪状态置为 false,让编排系统把实例摘出流量,等几秒再开始关闭监听。顺序反了,流量还在进来,进程已经开始退出,用户就会看到连接错误。这个「先摘流量、再停进程」的窗口通常设五到十秒,比任何重试都有效。
配置注入:镜像不变,环境可变
同一个镜像应该能部署到开发、测试、生产,只靠外部配置区分。这是容器化的基本要求,也是滚动更新和回滚的前提。配置写进镜像,等于每个环境打一个镜像,回滚时连配置一起回滚,很难受。
配置分三类。普通配置(端口、日志级别、超时)用环境变量或挂载的配置文件;密钥(数据库密码、API key)用 Secret 机制,不要混在普通配置里;启动参数(副本数、资源限制)属于编排层,不要塞进应用配置。
| 配置类型 | 放哪 | 注意什么 |
|---|---|---|
| 环境差异配置 | 环境变量或 ConfigMap | 要有默认值,但生产必须显式覆盖 |
| 密钥 | Secret 或密钥管理服务 | 不要打印到日志,不要写进镜像层 |
| 功能开关 | 配置中心或数据库 | 要能热更新,并有回滚开关 |
| 资源与副本 | 编排层配置 | 与应用代码解耦,按环境调整 |
应用启动时要「快速失败」。必需的配置缺失或格式错误,直接退出并打印清晰的错误,不要用默认值硬撑。比如数据库地址为空却连到 localhost,容器看起来启动成功,实际每个请求都失败,排查会多花很久。
配置变更后的生效方式要提前定。能热更新的是日志级别、功能开关、限流阈值;必须重启的是端口、数据库连接串、密钥。改前者不需要发版,改后者要走发布流程。把两类混在一起,运维改一个日志级别就重启服务,用户会莫名其妙掉线。配置中心可以支持热更新,但应用要显式监听变更并校验新值,不能读到一半的配置就用。
# .env.example 只放示例,真实值由部署平台注入
PORT=8080
DATABASE_URL=postgres://user:pass@db:5432/app
LOG_LEVEL=info
FEATURE_NEW_CHECKOUT=false
换语言时,读取配置的方式会变:Node 用 process.env,Java 用 Spring 的 @Value 或环境变量映射,Go 用 os.Getenv,Python 用 os.environ。原则不变:启动时集中读取、集中校验、缺失即失败。
密钥要能轮换。数据库密码、第三方 API key 都有有效期,不能写死在部署文件里然后永远不动。轮换时准备新旧两份,应用同时接受,等旧密钥的调用方全部迁移后再删旧的。容器环境里,密钥通常由 Secret 挂载成文件或环境变量;挂载文件的好处是更新后不重启也能读到,环境变量的好处是简单,但更新必须重启。两种方式都要确保密钥不出现在镜像层和日志里。
一套可复制的部署骨架
单机部署可以用 Docker Compose,把应用、数据库、反向代理串起来。生产环境通常用 Kubernetes 或云平台,但镜像和探针的写法是一样的。
资源限制要设,但别拍脑袋。只设 CPU 请求不设上限,一个跑飞的进程会吃掉整台机器;只设上限不设请求,调度器不知道该把容器放哪,可能把多个重负载挤在一起。内存上限尤其要留余量,超过限制的容器会被直接杀掉,表现是「进程无缘无故重启」。先按压测得到的实际用量设,再留百分之二十到三十的缓冲。
services:
api:
image: registry.example.com/order-api:1.4.2
env_file: [.env]
expose: ["8080"]
healthcheck:
test: ["CMD", "wget", "-qO-", "http://localhost:8080/healthz"]
interval: 10s
timeout: 3s
retries: 3
restart: unless-stopped
proxy:
image: nginx:1.27-alpine
ports: ["80:80"]
volumes: ["./nginx.conf:/etc/nginx/conf.d/default.conf:ro"]
depends_on: [api]
目录上把部署相关文件集中放在 deploy/,不要散落在源码根目录。
滚动更新的参数要按服务调整。maxSurge 控制一次最多多起几个实例,maxUnavailable 控制一次最多停几个。核心服务宁可多占资源,也不要让可用实例掉太多;内部服务可以激进一点,缩短发布窗口。这两个值和就绪探针、优雅停机一起决定发布期间会不会掉请求,不能只改镜像不看它们。
deploy/
Dockerfile
.dockerignore
nginx.conf
compose.yaml
k8s/
deployment.yaml
service.yaml
configmap.yaml
secret.example.yaml
验证方法:本地构建镜像,确认体积在预期范围;启动容器后访问 /healthz 和 /readyz,确认状态码;把数据库地址改错,确认就绪探针变红但容器没有被反复重启;通过反向代理请求一次,确认应用日志里的客户端 IP 是真实 IP,不是容器网关地址。Docker 与 Kubernetes 命令需在具备相应环境时执行,本文配置未在本机实测。
docker build -t order-api:test .
docker run --rm -p 8080:8080 --env-file .env order-api:test
curl -i http://localhost:8080/healthz
curl -i -H "X-Forwarded-For: 203.0.113.9" http://localhost/healthz
边界与代价
容器不是虚拟机。容器共享宿主内核,隔离性弱于虚拟机。需要强隔离、特殊内核模块或多租户运行不可信代码时,容器不一定合适。安全边界要靠非 root、只读文件系统、最小权限和镜像扫描来补。
编排系统也会带来复杂度。Kubernetes 能解决调度、扩缩容、滚动更新,但它的网络、存储、权限模型都要学。小团队没有专人维护,一个配置写错就可能让服务起不来。单机 Compose 加一台备用机,很多时候比硬上集群更稳。
小镜像有维护成本。Alpine 用 musl libc,某些二进制依赖会不兼容;裁剪过度的镜像缺少调试工具,出事时连 curl 都没有。体积和可维护性要平衡,别为了几十 MB 牺牲排障能力。
健康检查会带来额外流量。探针频率高、接口重,会给服务增加稳定负载。探针接口要足够轻,且不要和业务接口共用限流额度。
配置注入不是越多越好。所有东西都做成环境变量,配置项会爆炸,没人知道哪些组合是合法的。分组、给默认值、启动时校验,比无限增加开关更可控。
过度设计的信号:一个日请求量几千的服务,上了多集群、服务网格、自动扩缩容、蓝绿发布全套。先把镜像、探针、配置三件事做对,稳定性收益更大。
当天可以自验的五件事
- 构建一次镜像,用
docker history看最大的三层是什么,判断有没有把编译工具带进运行镜像。 - 启动容器,分别访问存活和就绪接口,确认它们检查的内容不同。
- 把数据库地址改成错误值,观察容器是「就绪变红」还是「被反复重启」;后者说明探针设计有问题。
- 通过反向代理发一次请求,确认应用拿到的客户端 IP 是真实 IP;再伪造一个
X-Forwarded-For,确认不可信来源被忽略。 - 检查镜像里有没有
.env、密钥文件或构建缓存;有就移出,并改用运行时注入。
下一篇讲灰度、回滚与故障演练。部署骨架解决「能稳定地发上去」,但发上去不等于发对了。新旧代码混跑、流量切多少、出事几分钟能退回,这些需要单独设计。