一、问题背景
去年底我把一个内部工具从"手动docker run"迁移到Docker Compose。项目结构不复杂:一个Nginx托管的前端静态站、一个Node.js API、一个PostgreSQL 16、一个Redis 7。四个服务,听起来用Compose一把梭就完事了。
结果上线第一周就出问题。API容器启动时PostgreSQL还没完成初始化,Node进程连不上数据库直接exit(1),restart策略把它拉起来,再崩,再拉。日志里刷了几十条ECONNREFUSED 5432。更烦的是Redis偶尔也慢半拍,导致API的session模块初始化失败。
我一开始用depends_on写了顺序,以为能解决——后来才发现默认的depends_on只保证容器启动顺序,不保证服务就绪。容器起来了,但Postgres还在跑initdb,端口根本没监听。
这篇文章就把我最终的配置方案完整写出来,包括网络规划、卷挂载策略、健康检查探针设计、启动顺序控制,以及几个踩过的坑。环境是Ubuntu 22.04 + Docker Engine 25.0.3 + Docker Compose v2.24.5。
二、环境与版本
先固定版本,避免"我这里能跑"的扯皮:
| 组件 | 版本 |
|---|---|
| 宿主机 | Ubuntu 22.04.3 LTS |
| Docker Engine | 25.0.3 |
| Docker Compose | v2.24.5 (Compose Spec) |
| Node.js 镜像 | node:20.11-alpine |
| PostgreSQL | postgres:16.2-alpine |
| Redis | redis:7.2-alpine |
| Nginx | nginx:1.25-alpine |
Compose文件用name:顶层字段指定项目名(v2.20+支持),不再依赖目录名。这点很重要,因为CI里checkout的目录名经常变。
三、方案设计
整体思路四句话:
- 网络分层:前端和后端放一个自定义bridge网络
app-net,数据库和Redis单独放data-net,API同时接入两个网络。这样Nginx碰不到数据库,减少攻击面。 - 卷挂载:数据库和Redis用命名卷(named volume)持久化,前端静态文件和Nginx配置用bind mount方便改。
- 健康检查:Postgres用
pg_isready,Redis用redis-cli ping,API自己暴露/healthz端点,Nginx用wget探本地。 - 启动顺序:
depends_on配合condition: service_healthy,让API等Postgres和Redis健康后再启动,Nginx等API健康后再启动。
这里有个细节:service_healthy条件在Compose v2里是原生支持的,不需要version: "3.8"那套老写法。我直接把version字段删了,用最新Compose Spec。
四、核心实现
完整docker-compose.yml如下,我加了注释说明每个参数为什么这么配:
name: internal-tool
services:
postgres:
image: postgres:16.2-alpine
restart: unless-stopped
environment:
POSTGRES_USER: app
POSTGRES_PASSWORD: ${DB_PASSWORD:?err}
POSTGRES_DB: appdb
PGDATA: /var/lib/postgresql/data/pgdata
volumes:
- pg-data:/var/lib/postgresql/data
- ./initdb:/docker-entrypoint-initdb.d:ro
networks:
- data-net
healthcheck:
test: ["CMD-SHELL", "pg_isready -U app -d appdb"]
interval: 5s
timeout: 3s
retries: 10
start_period: 15s
deploy:
resources:
limits:
memory: 512M
logging:
driver: json-file
options:
max-size: "10m"
max-file: "3"
redis:
image: redis:7.2-alpine
restart: unless-stopped
command: ["redis-server", "--appendonly", "yes", "--maxmemory", "256mb", "--maxmemory-policy", "allkeys-lru"]
volumes:
- redis-data:/data
networks:
- data-net
healthcheck:
test: ["CMD", "redis-cli", "ping"]
interval: 5s
timeout: 2s
retries: 5
start_period: 5s
deploy:
resources:
limits:
memory: 320M
api:
build:
context: ./api
dockerfile: Dockerfile
image: internal-tool/api:1.4.2
restart: unless-stopped
environment:
NODE_ENV: production
DATABASE_URL: postgres://app:${DB_PASSWORD}@postgres:5432/appdb
REDIS_URL: redis://redis:6379
PORT: "3000"
depends_on:
postgres:
condition: service_healthy
redis:
condition: service_healthy
networks:
- app-net
- data-net
healthcheck:
test: ["CMD", "wget", "-qO-", "http://127.0.0.1:3000/healthz"]
interval: 10s
timeout: 3s
retries: 6
start_period: 20s
deploy:
resources:
limits:
memory: 256M
logging:
driver: json-file
options:
max-size: "10m"
max-file: "3"
web:
image: nginx:1.25-alpine
restart: unless-stopped
ports:
- "80:80"
volumes:
- ./web/dist:/usr/share/nginx/html:ro
- ./nginx/default.conf:/etc/nginx/conf.d/default.conf:ro
depends_on:
api:
condition: service_healthy
networks:
- app-net
healthcheck:
test: ["CMD", "wget", "-qO-", "http://127.0.0.1/"]
interval: 15s
timeout: 3s
retries: 3
networks:
app-net:
driver: bridge
data-net:
driver: bridge
internal: true
volumes:
pg-data:
redis-data:
几个关键点说明:
internal: true 加在data-net上,这个网络里的容器无法访问外网,只能内部互通。数据库和Redis本来就不该出网,这条配置直接堵死数据外泄的一个通道。API同时挂两个网络,所以它既能连数据库,又能被Nginx访问。
start_period 是很多人忽略的参数。Postgres首次启动要跑initdb,15秒内pg_isready失败不算数,不会计入retries。没有这个参数,健康检查会在初始化阶段就把容器标记为unhealthy。
${DB_PASSWORD:?err} 是Compose的变量语法,没设这个环境变量就直接报错退出,避免用默认密码裸奔。
API的Dockerfile里健康检查端点很简单:
// api/src/health.js
const db = require('./db');
const redis = require('./redis');
module.exports = async function healthz(req, res) {
const checks = { db: false, redis: false };
try {
await db.query('SELECT 1');
checks.db = true;
} catch (e) { /* 记录但不抛 */ }
try {
checks.redis = (await redis.ping()) === 'PONG';
} catch (e) { /* 同上 */ }
const ok = checks.db && checks.redis;
res.status(ok ? 200 : 503).json({ status: ok ? 'ok' : 'degraded', checks });
};
健康检查探的是依赖项,不是简单的return 200。这样如果运行中数据库挂了,API会被标记unhealthy,配合外部监控能触发告警。
五、踩坑与优化
坑1:depends_on不解决重启场景。 service_healthy只在首次启动生效。如果Postgres中途重启,API不会自动跟着重启,它的连接池会进入重连循环。我的处理是在API里加了连接池重试(pg-pool的connectionTimeoutMillis: 5000配合指数退避),并且用Compose的restart: unless-stopped兜底。彻底方案要上编排平台,Compose层面做到这步够了。
坑2:命名卷和bind mount混用踩权限。 一开始我把./pg-data目录bind mount进去,宿主机uid和容器内postgres用户的uid(999)对不上,启动报could not change permissions。换成命名卷pg-data后问题消失——命名卷由Docker管理,权限自动对齐。教训:数据库数据目录永远用命名卷,别用bind mount。
坑3:日志把磁盘写满。 没配logging.options之前,一个API容器跑两周写了40GB json日志。加上max-size: "10m"和max-file: "3"后,单容器日志上限30MB。
坑4:internal: true网络里DNS解析。 刚开始API连不上postgres主机名,查了半天发现是API只挂了app-net。加上data-net后正常。Compose的网络别名机制要求容器加入对应网络才能解析该网络内的服务名。
优化项:给每个服务加了deploy.resources.limits.memory。Compose本地模式(非Swarm)下deploy字段部分生效,内存限制实测有效(Docker 25 + Compose v2.24)。Postgres给512M,Redis 320M(含maxmemory 256mb余量),API 256M,总内存占用控制在1.2G以内,跑在2C4G的机器上很稳。
六、效果数据
改完配置后跑了两周,数据对比:
| 指标 | 改造前 | 改造后 |
|---|---|---|
| 冷启动失败率 | 12%(约每8次启动失败1次) | 0% |
冷启动耗时(up -d到全健康) |
不稳定,常卡在API重试 | 稳定18秒左右 |
| 因启动顺序导致的重启次数 | 日均3次 | 0 |
| 单容器日志磁盘占用(两周) | 峰值40GB | ≤30MB |
| 数据库数据丢失事件 | 1次(bind mount权限问题重建) | 0 |
docker compose up -d之后docker compose ps能看到所有服务healthy状态,depends_on的条件启动链路按预期执行:postgres/redis并行启动 → 健康后api启动 → api健康后web启动。
七、总结
Docker Compose做多服务编排,核心就三件事:网络隔离划清楚、卷挂载选对类型、健康检查配好start_period和condition。depends_on的service_healthy条件是启动顺序控制的正解,但别指望它处理运行时的依赖故障,那需要应用层重试兜底。
配置文件里那些看起来啰嗦的参数——start_period、internal: true、max-size——都是踩过坑之后加的。建议直接抄这份结构,把镜像版本和密码换掉就能用。Compose v2已经不需要version字段了,看到还在写version: "3.8"的教程可以直接跳过。