一、问题背景:7 条 docker run 和一堆 sleep
我们做的是一个内部工单系统,服务不多但该有的都有:
api:Node.js 20 写的后端,端口 3000postgres:PostgreSQL 16,主数据库redis:Redis 7.2,做会话缓存和限流计数nginx:反向代理 + 静态资源,对外暴露 80
最早的部署方式是写在 deploy.sh 里的一串 docker run:
docker network create ticket-net
docker run -d --name pg --network ticket-net -e POSTGRES_PASSWORD=xxx -v pgdata:/var/lib/postgresql/data postgres:16
sleep 10
docker run -d --name redis --network ticket-net redis:7.2
docker run -d --name api --network ticket-net -e DATABASE_URL=... -p 3000:3000 ticket-api:1.4.2
sleep 5
docker run -d --name nginx --network ticket-net -p 80:80 -v ./nginx.conf:/etc/nginx/nginx.conf:ro nginx:1.25
痛点非常具体:
- 启动顺序靠
sleep。sleep 10在开发机上够用,到了 CI 的冷机器上 PostgreSQL 初始化要 20 多秒,API 一连库就ECONNREFUSED退出,然后整个流水线红掉。 - 网络配置重复。每条
docker run都要带--network,漏一条就连不上。 - 环境变量散落。数据库密码在脚本里硬编码,改一次要动三处。
- 无法一键清理。
docker rm -f要写五个容器名,卷还得单独docker volume rm。
这篇文章就是把我们迁移到 Docker Compose 的完整配置和踩坑过程写出来,重点在网络、卷挂载、健康检查和启动顺序这四件事上。
二、环境与版本
先交代版本,Compose 的 depends_on.condition 在不同版本行为差异很大,这个必须说清楚:
| 组件 | 版本 |
|---|---|
| Docker Engine | 25.0.3 |
| Docker Compose | v2.24.6(插件形式,docker compose 而非 docker-compose) |
| Compose Spec | 对应 version 字段已废弃,不再写 |
| Node.js 镜像 | node:20.11-alpine |
| PostgreSQL | postgres:16.2-alpine |
| Redis | redis:7.2-alpine |
| Nginx | nginx:1.25-alpine |
两个关键提醒:
- 不要再写
version: "3.8"。Compose V2 已经忽略这个字段,写了只会看到the attribute 'version' is obsolete的警告。 condition: service_healthy需要 Compose V2。老的单机docker-compose1.x 在 v3 格式下不支持这个条件,只有service_started,这正是很多人误以为"Compose 不能控制启动顺序"的原因。
三、方案设计
整体设计思路四条:
- 一个自定义 bridge 网络
ticket-net,所有服务接入,靠服务名做 DNS 解析。Nginx 里proxy_pass http://api:3000直接可用,不用管容器 IP。 - 三类卷:
pgdata命名卷存数据库、redisdata命名卷存 AOF 持久化文件、./nginx/conf.d和./static用 bind mount 方便改配置热重载。 - 健康检查全覆盖。PostgreSQL 用
pg_isready,Redis 用redis-cli ping,API 用容器内wget打自己的/healthz,Nginx 依赖 API 健康。 - 启动顺序用
depends_on+condition:api等postgres和redis都 healthy 再启动,nginx等apihealthy 再启动。
另外加两个工程化细节:restart: unless-stopped 保证崩溃自愈,logging 限制日志大小防止磁盘被撑爆。
四、核心实现
4.1 目录结构
ticket-system/
├── docker-compose.yml
├── .env
├── api/
│ └── Dockerfile
├── nginx/
│ └── conf.d/
│ └── default.conf
└── static/
.env 放敏感配置,Compose 会自动读取:
POSTGRES_USER=ticket
POSTGRES_PASSWORD=Ch4ngeMeInProd
POSTGRES_DB=ticket
API_IMAGE=ticket-api:1.4.2
4.2 docker-compose.yml 完整配置
name: ticket-system
services:
postgres:
image: postgres:16.2-alpine
environment:
POSTGRES_USER: ${POSTGRES_USER}
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
POSTGRES_DB: ${POSTGRES_DB}
volumes:
- pgdata:/var/lib/postgresql/data
networks:
- ticket-net
healthcheck:
test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
interval: 5s
timeout: 3s
retries: 10
start_period: 15s
restart: unless-stopped
logging:
driver: json-file
options:
max-size: "10m"
max-file: "3"
redis:
image: redis:7.2-alpine
command: ["redis-server", "--appendonly", "yes"]
volumes:
- redisdata:/data
networks:
- ticket-net
healthcheck:
test: ["CMD", "redis-cli", "ping"]
interval: 5s
timeout: 3s
retries: 5
restart: unless-stopped
api:
image: ${API_IMAGE}
build:
context: ./api
dockerfile: Dockerfile
environment:
NODE_ENV: production
DATABASE_URL: postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}
REDIS_URL: redis://redis:6379
PORT: "3000"
expose:
- "3000"
depends_on:
postgres:
condition: service_healthy
redis:
condition: service_healthy
healthcheck:
test: ["CMD", "wget", "-qO-", "http://127.0.0.1:3000/healthz"]
interval: 10s
timeout: 3s
retries: 5
start_period: 20s
restart: unless-stopped
logging:
driver: json-file
options:
max-size: "10m"
max-file: "3"
nginx:
image: nginx:1.25-alpine
ports:
- "80:80"
volumes:
- ./nginx/conf.d:/etc/nginx/conf.d:ro
- ./static:/usr/share/nginx/html:ro
depends_on:
api:
condition: service_healthy
networks:
- ticket-net
restart: unless-stopped
volumes:
pgdata:
redisdata:
networks:
ticket-net:
driver: bridge
几个值得单独说的参数:
start_period:容器启动后这段时间内的健康检查失败不计入retries。PostgreSQL 首次初始化要跑initdb,我们的 CI 机器上大约 12 秒,所以给 15 秒余量。没有这个参数,retries: 10 × interval 5s很容易被初始化阶段消耗掉。api用expose而非ports:API 不需要对宿主机暴露,只让 Nginx 通过ticket-net访问,减少攻击面。调试时临时用docker compose exec api sh进去。pg_isready用CMD-SHELL:因为要展开${POSTGRES_USER}环境变量,数组形式不会经过 shell 展开。name: ticket-system:顶层项目名,决定容器名前缀(ticket-system-api-1)和默认网络名,避免和其他项目撞名。
4.3 Nginx 配置里的服务名解析
# nginx/conf.d/default.conf
upstream api_backend {
server api:3000;
keepalive 32;
}
server {
listen 80;
server_name _;
location /api/ {
proxy_pass http://api_backend/;
proxy_http_version 1.1;
proxy_set_header Connection "";
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_read_timeout 30s;
}
location / {
root /usr/share/nginx/html;
index index.html;
try_files $uri $uri/ /index.html;
}
}
server api:3000 能生效的前提就是两个容器都在 ticket-net 上,Docker 内置 DNS 会把 api 解析到容器 IP。这里有个坑后面细说:Nginx 启动时解析 upstream 域名,如果 api 容器此时不存在,Nginx 会直接启动失败——这正是我们给 nginx 加 depends_on: api: service_healthy 的原因之一。
4.4 API 的 Dockerfile 与健康检查端点
FROM node:20.11-alpine AS deps
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
FROM node:20.11-alpine
WORKDIR /app
ENV NODE_ENV=production
COPY --from=deps /app/node_modules ./node_modules
COPY . .
USER node
EXPOSE 3000
CMD ["node", "src/server.js"]
健康检查端点要轻量,不要在里面查数据库,否则数据库抖动会让 API 被误判不健康进而触发重启风暴:
// src/server.js 片段
app.get('/healthz', (req, res) => res.status(200).send('ok'));
五、踩坑与优化
坑 1:健康检查通过 ≠ 服务可用
最早 pg_isready 一通过我们就让 API 启动,结果 API 迁移脚本偶尔报 database "ticket" does not exist。原因是 PostgreSQL 官方镜像的初始化流程:先起一个临时实例执行 initdb 和 docker-entrypoint-initdb.d 里的脚本,完成后关闭再重启正式实例。pg_isready 在临时实例阶段就可能返回成功。
解决办法是把 start_period 从 5s 提到 15s,并且把迁移逻辑改成 API 启动时带重试(我们用的是 node-pg-migrate 加 3 次指数退避)。健康检查只是第一道闸,应用侧的重试不能省。
坑 2:depends_on 不会等待,只有 condition 才会
团队里有人写了:
depends_on:
- postgres
这等价于 condition: service_started,只保证容器被创建并启动,不保证进程能接受连接。必须写成 map 形式带 condition: service_healthy。
坑 3:bind mount 的权限
./static 挂到 Nginx 的 /usr/share/nginx/html,宿主机文件属主是开发者的 UID 1000,Nginx worker 以 nginx 用户跑,读没问题。但如果哪天改成挂载需要写的目录,就会 permission denied。命名卷没这个问题,因为 Docker 会用镜像里目录的属主初始化卷。
坑 4:docker compose down -v 会删数据
这个不用多解释,但值得在 README 里加粗。我们现在的约定是:日常 docker compose down(保留卷),只有需要重置环境时才 down -v。
优化:日志与资源限制
生产环境加了 logging 限制后,单容器日志目录从最高见过 4.2GB 降到稳定在 30MB 以内(max-size 10m × max-file 3)。资源限制我们没在 Compose 里写 deploy.resources(那是 Swarm 语法,Compose 下部分字段被忽略),而是用 mem_limit 这种 V2 支持的写法,给 api 限了 512m,实测 P99 内存占用 310MB 左右,够用。
六、效果数据
迁移前后对比(同一台 4C8G 的 CI runner,冷缓存):
| 指标 | 迁移前(docker run 脚本) | 迁移后(Compose) |
|---|---|---|
| 冷启动到全部服务可用 | 约 95s(含固定 sleep 25s) | 38s |
| 部署脚本行数 | 60 行 | 8 行 |
| 因启动顺序导致的失败率 | 约 15%(近 20 次流水线挂 3 次) | 0(近 50 次无相关失败) |
| 环境变量维护点 | 3 处 | 1 处(.env) |
| 一键清理 | 手动 6 条命令 | docker compose down |
日常开发里最直观的变化是 docker compose up -d 之后可以直接打开浏览器,不用再盯着 docker logs 看数据库起来没有。另外 docker compose config 能校验并展开最终配置,改 yml 时先在 CI 里跑一遍这个命令,语法错误在合并前就能拦住。
七、总结
Docker Compose 编排这件事,配置本身不难,难的是几个容易想当然的点:depends_on 默认不等健康、start_period 要给足初始化时间、Nginx 的 upstream 在启动时就解析域名、命名卷和 bind mount 的权限行为不同。把这四件事处理对,一个四服务的项目用一份 100 行左右的 docker-compose.yml 就能稳稳跑起来。
最后给两条实践建议:一是健康检查端点务必轻量,别把依赖服务的可用性绑进去;二是 .env 永远不要提交到仓库,用 .env.example 加 CI 注入的方式管理。Compose 的定位是单机编排,服务再往上长到需要多节点调度的时候,就该考虑 Kubernetes 了,但在那之前,它足够好用。