Docker-Compose on Liangweidong's blog

Docker Compose 完全参考：v2 配置字典与实战

Thu, 15 Sep 2022 00:00:00 +0800

Compose 是 Docker 官方推出的多容器编排工具——把一组容器 / 网络 / 卷 / 配置用一份 YAML 描述，docker compose up 一键拉起。从 v1（Python 实现）到 v2（Go 插件化，2020-08 GA）经历了一次大重构，v2 速度更快、不再是 Python 副作用、字段语义和 v1 大体兼容。

这一篇把 compose 文件的所有常用字段按 services / networks / volumes 三大块组织成速查字典，配实战示例。

阅读对象：用 docker compose 编排多服务、想系统了解每个字段的开发者 / 运维 覆盖范围：compose v1 vs v2 差异 + service 字段字典 + networks / volumes 顶层 + 实战 YAML + compose 常用命令

一、Compose v1 vs v2：先搞清楚用哪个

维度	v1	v2
命令	`docker-compose`（带横线）	`docker compose`（空格）
实现	Python	Go（Docker CLI 插件）
启动速度	慢（要启 Python 解释器）	快（Go 二进制）
Compose Spec	1.x - 3.x	3.8+ 兼容 Spec
K8s 集成	实验性 `kompose`	内置 `docker compose convert`
维护	已停止新特性	当前主推

2023 年后：docker compose (v2) 是事实标准。新项目不要再用 v1。

二、Compose 文件结构总览

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


# 顶层 keys（按规范顺序）
version: "3.8" # 文件格式版本（v2 中可选，但建议保留）
name: "my-project" # v2.20+ 项目名（影响容器前缀）

services: # 必填：所有服务
 web:
 image: nginx:latest
 # ... 50+ 字段

networks: # 可选：自定义网络
 frontend:
 backend:

volumes: # 可选：命名卷
 db-data:

configs: # 可选：配置文件
 app-config:

secrets: # 可选：密钥
 db-password:

Spec 是什么：Compose Spec 是 v2.0 起的"格式规范"——docker compose、Kompose、docker stack deploy、podman compose 都按这个规范解析 YAML。比 v1 的 version: 3.x 更通用。

三、service 字段字典

3.1 镜像 / 构建

字段	作用	版本
`image`	指定镜像	全部
`build`	构建路径或对象	全部
`build.context`	Dockerfile 所在目录	v2 起
`build.dockerfile`	Dockerfile 名（默认 `Dockerfile`）	v2 起
`build.args`	`ARG` 参数	v2 起
`build.cache_from`	缓存来源镜像列表	v3.2+
`build.labels`	构建后打 labels	v3.3+
`build.shm_size`	`/dev/shm` 大小	v3.5+

示例：

1
2
3
4
5
6
7
8
9


services:
 web:
 build:
 context: ./app
 dockerfile: Dockerfile.prod
 args:
 NODE_ENV: production
 cache_from:
 - myapp:cache

3.2 启动 / 运行时

字段	作用
`command`	覆盖默认启动命令（支持 shell 格式或 `[]` 格式）
`entrypoint`	覆盖默认入口点
`container_name`	指定容器名（`docker run --name` 等价）
`working_dir`	工作目录
`user`	容器内运行用户
`tty` / `stdin_open`	是否分配 TTY / 保持 stdin
`privileged`	特权模式
`init`	容器内跑 init 进程（PID 1，正确转发信号）

示例：

1
2
3
4
5
6
7
8


services:
 api:
 image: myapi:latest
 command: ["python", "manage.py", "runserver", "0.0.0.0:8000"]
 user: "1000:1000"
 init: true
 tty: true
 working_dir: /app

3.3 端口 / 网络

字段	作用
`ports`	端口映射（`HOST:CONTAINER`）
`expose`	暴露端口（容器间可访问，不映射到宿主机）
`networks`	加入指定网络
`network_mode`	单一网络模式（如 `host`）
`dns` / `dns_search`	自定义 DNS
`extra_hosts`	加 `/etc/hosts` 条目
`hostname`	容器主机名
`domainname`	域名
`mac_address`	MAC 地址

ports 短语法：

1
2
3
4
5
6
7


ports:
 - "3000" # 容器 3000 端口，宿主机随机
 - "3000-3005" # 范围
 - "8000:8000" # 宿主机 8000:容器 8000
 - "9090-9091:8080-8081" # 范围映射
 - "127.0.0.1:8001:8001" # 指定宿主机 IP
 - "6060:6060/udp" # 指定协议

ports 长语法（v3.2+）：

1
2
3
4
5


ports:
 - target: 80
 published: 8080
 protocol: tcp
 mode: host

networks 与固定 IP：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


services:
 test:
 image: nginx:1.14-alpine
 networks:
 app_net:
 ipv4_address: 172.16.238.10

networks:
 app_net:
 driver: bridge
 ipam:
 driver: default
 config:
 - subnet: 172.16.238.0/24

3.4 存储 / 卷

字段	作用
`volumes`	挂载卷 / 目录
`tmpfs`	挂载 tmpfs（v2+）
`read_only`	根文件系统只读

短语法：

1
2
3
4
5
6


volumes:
 - /var/lib/mysql  # 匿名卷
 - /opt/data:/var/lib/mysql  # bind mount
 - ./cache:/tmp/cache  # 相对路径 bind
 - ~/configs:/etc/configs/:ro  # 只读
 - datavolume:/var/lib/mysql  # 引用顶层命名卷

长语法（v3.2+）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


volumes:
 - type: volume
 source: mydata
 target: /data
 volume:
 nocopy: true
 - type: bind
 source: ./static
 target: /opt/app/static
 read_only: true

3.5 环境变量 / 配置

字段	作用
`environment`	内联环境变量
`env_file`	从文件读环境变量
`secrets`	挂载 secret（来自顶层 secrets）
`configs`	挂载 config（来自顶层 configs）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


services:
 app:
 environment:
 DB_HOST: db
 DB_PORT: 5432
 env_file:
 - .env
 - .env.production
 configs:
 - source: app-config
 target: /app/config.json

优先级：environment > env_file > 镜像内 ENV

3.6 依赖 / 健康检查

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


services:
 web:
 depends_on:
 db:
 condition: service_healthy  # v2 起
 redis:
 condition: service_started  # 默认

 db:
 image: postgres:14
 healthcheck:
 test: ["CMD-SHELL", "pg_isready -U postgres"]
 interval: 10s
 timeout: 5s
 retries: 5
 start_period: 30s

condition: service_healthy 必须配 healthcheck 才生效——v2 起推荐用这个替代 wait-for-it 脚本。

3.7 资源限制 / 重启

字段	作用
`restart`	`no` / `always` / `on-failure` / `unless-stopped`
`deploy.resources.limits`	CPU / 内存上限（`docker stack` 用）
`cpus` / `cpuset`	v1 兼容字段，`docker compose` 仍支持
`mem_limit` / `memswap_limit`	v1 兼容内存限制
`ulimits`	ulimit 列表
`pids_limit`	PID 上限
`logging`	日志驱动（`json-file` / `syslog` / `fluentd`）
`shm_size`	`/dev/shm` 大小
`stop_grace_period`	收到 SIGTERM 后等待秒数（默认 10s）
`stop_signal`	停止信号（默认 SIGTERM）

资源限制示例：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


services:
 api:
 image: myapi:latest
 deploy:
 resources:
 limits:
 cpus: "0.5" # 50% 单核
 memory: 512M
 reservations:
 cpus: "0.2" # 预留 20%
 memory: 128M
 logging:
 driver: json-file
 options:
 max-size: "50m"
 max-file: "3"

Why 用 deploy.resources 而不是 mem_limit：前者是 Compose Spec 规范字段，后者是 v1 兼容字段。新项目用前者。

3.8 其他

字段	作用
`labels`	Docker 标签（`LABEL` 等价）
`pid`	`host` 表示共享宿主机 PID namespace
`ipc`	共享 IPC namespace
`security_opt`	SELinux / AppArmor 选项
`cap_add` / `cap_drop`	Linux capabilities
`devices`	设备映射（`docker run --device`）
`links`	链接到其他容器（已废弃，用 networks）
`external_links`	链接到 compose 外的容器
`isolation`	隔离技术（仅 `default` / `process` / `hyperv`）
`runtime`	指定 runtime（`runc` / `runsc` 沙箱）
`profiles`	启用 profile（条件启动）

profiles 示例：

1
2
3
4
5
6
7


services:
 api:
 image: myapi:latest

 debug-tools:
 image: mydebug:latest
 profiles: ["debug"]

1
2
3
4


# 默认 up 不启动 debug-tools
docker compose up
# 加 profile 启动
docker compose --profile debug up

四、networks 顶层

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


networks:
 frontend:
 driver: bridge
 backend:
 driver: bridge
 internal: true # 不通外网
 monitoring:
 driver: overlay  # 跨主机
 external_net:
 external: true # 引用已创建的网络
 name: my-pre-existing-network

internal: true：内网隔离的 bridge——容器能互相访问，不能访问外网。数据库 / 缓存很适合。

五、volumes 顶层

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


volumes:
 db-data:
 driver: local
 driver_opts:
 type: "nfs"
 o: "addr=10.0.0.10,nolock,soft,rw"
 device: ":/path/to/dir"
 shared:
 external: true
 name: my-pre-existing-volume

六、完整实战示例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62


version: "3.8"

services:
 redis:
 image: redis:alpine
 ports:
 - "6379"
 networks:
 - frontend
 deploy:
 replicas: 2
 update_config:
 parallelism: 2
 delay: 10s
 restart_policy:
 condition: on-failure
 healthcheck:
 test: ["CMD", "redis-cli", "ping"]
 interval: 10s
 timeout: 3s
 retries: 3

 db:
 image: postgres:14
 volumes:
 - db-data:/var/lib/postgresql/data
 networks:
 - backend
 environment:
 POSTGRES_PASSWORD: ${DB_PASSWORD}
 deploy:
 placement:
 constraints: [node.role == manager]

 web:
 build: ./app
 ports:
 - "8080:8080"
 networks:
 - frontend
 - backend
 depends_on:
 redis:
 condition: service_healthy
 db:
 condition: service_started
 environment:
 REDIS_HOST: redis
 DB_HOST: db
 deploy:
 resources:
 limits:
 cpus: "0.5"
 memory: 512M

networks:
 frontend:
 backend:
 internal: true

volumes:
 db-data:

关键点：

web 同时加入 frontend 和 backend 网络——能访问 redis 和 db

db 在 internal: true 的 backend 网络——不能访问外网

redis 多副本 + 滚动更新配置

web 资源限制

七、Compose 常用命令

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


# 启动
docker compose up -d

# 启动指定服务
docker compose up -d web

# 不重建已停止的容器
docker compose up -d --no-recreate

# 停止 / 启动
docker compose stop
docker compose start

# 停掉 + 销毁容器
docker compose down # 保留卷
docker compose down -v # 同时删卷（**危险**）
docker compose down --rmi all # 同时删镜像

# 查看状态
docker compose ps
docker compose logs -f web

# 进入容器
docker compose exec web bash

# 在 web 容器内跑一次性命令
docker compose run --rm web python manage.py migrate

八、字段优先级与兼容性

字段类型	优先级
`environment`	> `env_file` > 镜像 `ENV`
`command`	覆盖镜像 `CMD`
`entrypoint`	覆盖镜像 `ENTRYPOINT`
`ports` + `expose`	都可以，`ports` 同时映射到宿主机

v1 → v2 字段迁移：

v1 字段	v2 推荐
`mem_limit`	`deploy.resources.limits.memory`
`memswap_limit`	`deploy.resources.limits.memory`（swap 用 flag）
`cpus` / `cpuset`	`deploy.resources.limits.cpus`
`volume_driver`	`driver_opts`（在 volumes 顶层）
`extends`	已移除（用 `include` 或合并 YAML）

九、要点回顾

Compose v2 (docker compose) 是当前主推，不要再用 v1 (docker-compose)
services 是必填顶层，networks / volumes / configs / secrets 可选
build 支持对象语法（context + dockerfile + args）
depends_on: condition: service_healthy 替代 wait-for-it 脚本
deploy.resources.limits 才是规范字段，mem_limit 是 v1 兼容
internal: true 给敏感服务（数据库）做网络隔离
profiles 区分"开发 / 调试 / 生产"不同场景
docker compose down -v 是核弹——会删数据卷

十、小结

Compose v2 是个"看似简单、字段多到爆炸"的工具。日常用到的不到 20 个字段：

image / build
ports / networks / volumes
environment / env_file
depends_on + healthcheck
restart / deploy.resources.limits
logging

把这十几个字段摸熟，80% 的多服务编排就够用了。剩下冷门字段（cap_add / secrets / configs / pid）需要时查文档即可。

下一步：理解了 Compose，下一步是 Kubernetes——把"compose 文件"换成"YAML manifest"，把 docker compose up 换成 kubectl apply，把"单机多服务"换成"集群多副本"。K8s 的 Pod 抽象比 Container 更进一步——把"应用 + 卷 + 网络"打包成不可变单元，跨节点调度。

参考资料

Docker 启动依赖等待：wait-for-it 与 healthcheck 实战

Thu, 15 Sep 2016 00:00:00 +0800

docker-compose up 时一个经典坑：app 容器比 mysql 容器起得还快，app 启动时报 “connection refused”。depends_on 只控制"启动顺序"，不等待依赖服务真的可用——你需要更稳的解法。

这一篇把"启动依赖等待"的所有主流方案收齐：wait-for-it.sh、docker-compose-wait、depends_on 的局限、healthcheck 主动检查。

阅读对象：用 docker-compose 编排多服务、被"启动顺序"问题坑过的开发者 覆盖范围：wait-for-it + docker-compose-wait + healthcheck + depends_on 局限 + 最佳实践

一、问题的本质：依赖启动的"就绪"问题

1
2
3
4
5
6
7


services:
 db:
 image: mysql:8
 app:
 image: myapp:latest
 depends_on:
 - db

depends_on: db 的真实行为：

✅ 控制启动顺序——db 一定先于 app 启动
❌ 不等待 db 真的可用——db 容器起来后，MySQL 进程可能还要 5-10 秒才能接受连接

结果：app 启动时 mysql:3306 可能还没监听，连接失败。

二、解法 1：wait-for-it.sh

wait-for-it 是社区里最常用的"端口可达性探测"小脚本。

2.1 基础用法

1
2


chmod +x ./wait-for-it.sh
./wait-for-it.sh www.baidu.com:80 -t 30 -- echo "baidu is up"

参数：

<host>:<port>——要等待的地址
-t <seconds>——超时时间，默认 15s，设为 0 表示无限等
-- 后跟"等到了执行的命令"

输出示例：

1
2
3


wait-for-it.sh: waiting 15 seconds for www.baidu.com:80
wait-for-it.sh: www.baidu.com:80 is available after 0 seconds
baidu is up

2.2 在 docker-compose 中使用

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


services:
 my_nacos:
 image: nacos/nacos-server:latest
 container_name: my_nacos

 test-app:
 container_name: test-app
 image: java:8
 restart: always
 environment:
 TZ: Asia/Shanghai
 ports:
 - "9001:9001"
 volumes:
 - ./backend/test-app.jar:/data/test-app.jar
 - ./wait-for-it.sh:/wait-for-it.sh
 # 关键：用 wait-for-it 等 nacos 起来再启动应用
 command: [
 "/wait-for-it.sh", "my_nacos:8848", "--",
 "java", "-jar", "/data/test-app.jar"
 ]
 depends_on:
 - my_nacos

机制：

wait-for-it.sh 轮询 my_nacos:8848 是否 TCP 可达

可达后执行后面的 java -jar 命令

30 秒超时（默认 15s）后放弃，启动失败

2.3 host 网络模式下的特例

如果 network_mode: "host"，容器名解析失效——my_nacos:8848 不通。

1
2
3
4


services:
 app:
 network_mode: "host"
 command: ["/wait-for-it.sh", "localhost:8848", "--", "java", "-jar", "/data/app.jar"]

Why：host 网络下容器共享宿主机网络栈，容器内看到的 localhost 就是宿主机的 localhost——my_nacos 容器名解析不到，得用 localhost。

三、解法 2：docker-compose-wait

docker-compose-wait 是用 Python 写的"等待一组服务"工具，比 wait-for-it 强大：

✅ 支持 多个 host:port
✅ 支持 环境变量配置（不用改 compose 文件）
✅ 支持 健康检查命令（不仅是端口）
✅ 支持 自定义等待策略

3.1 安装

在 Dockerfile 里装：

1
2
3
4


RUN pip install docker-compose-wait
# 或
RUN curl -Lo /wait https://github.com/ufoscout/docker-compose-wait/releases/download/2.7.3/wait \
 && chmod +x /wait

3.2 compose 文件

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


services:
 db:
 image: mysql:8
 environment:
 WAIT_HOSTS: db:3306

 app:
 build: .
 environment:
 WAIT_HOSTS: db:3306, redis:6379
 WAIT_TIMEOUT: 60
 command: ["/wait", "&&", "java", "-jar", "/data/app.jar"]
 depends_on:
 - db
 - redis

优势：

多端口一行配置

超时、间隔都走环境变量

支持 healthcheck 字符串——WAIT_HOSTS: "tcp://db:3306, http://api/health"

四、解法 3：depends_on 长语法（Docker Compose v2）

Docker Compose v2（2020-08 GA）扩展了 depends_on：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


services:
 db:
 image: mysql:8
 healthcheck:
 test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
 interval: 5s
 timeout: 3s
 retries: 10

 app:
 image: myapp:latest
 depends_on:
 db:
 condition: service_healthy

What：

condition: service_healthy——等 db 的 healthcheck 通过再启动 app

condition: service_started——等 db 容器启动（默认行为）

不需要 wait-for-it 这种外部脚本

但：

必须配 healthcheck——不带 healthcheck，service_healthy 永远不通过
Docker Compose v1 不支持——必须升 v2（docker compose 插件）

五、解法 4：healthcheck + restart

最朴素但有效的方案：给容器加 healthcheck，启动失败自动重试。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


services:
 app:
 image: myapp:latest
 healthcheck:
 test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
 interval: 10s
 timeout: 3s
 retries: 5
 start_period: 30s
 restart: on-failure

机制：

容器启动后 30s 内（start_period）不计入健康检查失败次数

之后每 10s 查一次，连续 5 次失败标 unhealthy

Docker Compose v2 的 service_healthy 会等这个状态

配合 depends_on 长语法：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


services:
 db:
 image: mysql:8
 healthcheck:
 test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
 interval: 5s
 timeout: 3s
 retries: 10

 app:
 image: myapp:latest
 depends_on:
 db:
 condition: service_healthy

这是 Docker Compose v2 时代的最佳实践——不需要外部脚本，配置即文档。

六、解法 5：应用层重试

最不优雅但最 robust 的方案：应用启动时自带重试。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


// Spring Boot 风格
@SpringBootApplication
public class App {
 public static void main(String[] args) {
 // 启动时重试 N 次
 for (int i = 0; i < 10; i++) {
 try {
 SpringApplication.run(App.class, args);
 break;
 } catch (Exception e) {
 Thread.sleep(5000);
 }
 }
 }
}

或用 Spring Boot 的 datasource retry：

1
2
3
4


spring:
 datasource:
 hikari:
 initialization-fail-timeout: 60000 # 60s 内持续重试

优势：不依赖任何外部编排——裸跑 docker run 也能 work 劣势：耦合进应用代码、不是纯基础设施问题

七、对比表

方案	配置复杂度	适用场景	推荐度
wait-for-it.sh	低	单端口、简单场景、Compose v1	⭐⭐⭐
docker-compose-wait	中	多端口、需要可配置	⭐⭐⭐
depends_on + healthcheck (v2)	中	Compose v2 + 多服务依赖	⭐⭐⭐⭐⭐
应用层重试	高	框架级稳健性	⭐⭐⭐⭐

2020 年后推荐：

Compose v2 + depends_on: condition: service_healthy + 每个服务配 healthcheck

裸 docker run + 应用层重试

wait-for-it / docker-compose-wait 仅在 Compose v1 或老项目使用

八、最佳实践总结

每个长跑服务都加 healthcheck——不只是依赖方
depends_on 用长语法——condition: service_healthy（Compose v2）
避免 wait 外部脚本——能配置的不用脚本
超时一定要设——start_period: 30s 给慢启动服务缓冲
应用层有兜底——基础设施层等不到时，应用自己重试
用 restart: on-failure——启动失败时容器自动重试（不是 always，避免无谓重启）

九、要点回顾

depends_on 不等待可用——只控制启动顺序
wait-for-it 适合单端口、Compose v1 项目
docker-compose-wait 适合多端口
healthcheck + service_healthy 是 Compose v2 最佳实践
应用层重试是最 robust 的兜底
host 网络下容器名解析失效，用 localhost

十、小结

“启动依赖等待"是 docker-compose 里最经典的"看起来能 work 但实际跑起来就崩"的问题。把 healthcheck + depends_on: service_healthy 配成肌肉记忆，比写一堆 wait 脚本清爽。

下一步：理解了启动顺序，下一步是 K8s 的 Init Container + Readiness Probe——把"启动依赖等待"从编排层下沉到容器层，配合 Pod lifecycle hook（postStart / preStop）做更精细的启动 / 关停控制。K8s 1.20+ 的 startupProbe 专门解决"慢启动服务"的 readiness 判断问题。