Docker Compose编排指南：YAML语法精讲与服务依赖配置
- 一、YAML语法核心规范
- 1.1 基础结构解析
- 1.2 多文档与锚点引用
- 二、服务依赖管理深度配置
- 2.1 基础依赖声明
- 2.2 高级依赖策略矩阵
- 三、生产级编排实战
- 3.1 全栈应用示例
- 四、依赖配置进阶技巧
- 4.1 级联启动控制
- 4.2 跨服务健康检查
- 五、调试与排错指南
- 5.1 启动顺序验证
- 5.2 常见错误处理
- 六、最佳实践清单
一、YAML语法核心规范
1.1 基础结构解析
# 注释以#开头
version: '3.8' # 版本声明必须首行services: # 服务定义区块webapp: # 服务名称（小写字母+下划线）image: nginx:alpine # 键值对（冒号后空格）ports:- "80:80" # 列表项（短横线+空格）- "443:443"environment: # 复杂值缩进两空格NGINX_ENV: productionTZ: Asia/Shanghai
1.2 多文档与锚点引用
# 公共配置锚点
x-common: &common-configrestart: unless-stoppedlogging:driver: json-fileoptions:max-size: "10m"services:frontend:<<: *common-config # 锚点继承image: frontend:v1.2backend:<<: *common-configimage: backend:v2.3
二、服务依赖管理深度配置
2.1 基础依赖声明
services:redis:image: redis:7-alpinehealthcheck:test: ["CMD", "redis-cli", "ping"]interval: 10stimeout: 5sretries: 3webapp:depends_on:redis:condition: service_healthy # 等待Redis健康postgres:condition: service_started # 仅需启动完成
2.2 高级依赖策略矩阵
| 依赖类型 | 配置语法 | 行为特征 |
|---|---|---|
| 启动顺序控制 | depends_on: [service1] | 仅控制启动顺序 |
| 健康检查依赖 | condition: service_healthy | 等待目标服务通过健康检查 |
| 混合依赖模式 | 组合使用长短语法 | 精细控制多服务启动条件 |
| 跨项目依赖 | external_links + 网络共享 | 依赖其他Compose项目的服务 |
三、生产级编排实战
3.1 全栈应用示例
version: '3.8'services:# 后端服务api:build: ./backendenvironment:- DB_URL=postgres://prod_user:Pass123@db:5432/appdbdepends_on:db:condition: service_healthyredis:condition: service_starteddeploy:resources:limits:cpus: '2'memory: 1G# 数据库服务db:image: postgres:15-alpinevolumes:- pg_data:/var/lib/postgresql/datahealthcheck:test: ["CMD-SHELL", "pg_isready -U postgres"]interval: 5stimeout: 3sretries: 5# 缓存服务 redis:image: redis:7-alpinecommand: redis-server --save 60 1 --loglevel warningvolumes:- redis_data:/datavolumes:pg_data:redis_data:networks:default:driver: bridgeipam:config:- subnet: 172.22.0.0/24
四、依赖配置进阶技巧
4.1 级联启动控制
services:init-db:image: postgres:15-alpinecommand: /docker-entrypoint-initdb.d/init.shvolumes:- ./init-scripts:/docker-entrypoint-initdb.dnetworks:- db-netapp-db:depends_on:init-db:condition: service_completed_successfully # 等待初始化完成image: postgres:15-alpinenetworks:- db-netnetworks:db-net:driver: bridge
4.2 跨服务健康检查
services:web:image: nginxhealthcheck:test: ["CMD", "curl", "-f", "http://localhost/service-status"]interval: 30stimeout: 10sstart_period: 20smonitor:image: prometheusdepends_on:web:condition: service_healthy # 等待Web服务健康
五、调试与排错指南
5.1 启动顺序验证
# 显示服务启动顺序
docker compose events --json | grep 'container start'# 查看依赖关系树
docker compose config --services | xargs -n1 docker compose depends_on
5.2 常见错误处理
错误现象：ERROR: Service 'webapp' depends on service 'db' which is undefined
解决方案：
- 检查服务名称拼写一致性
- 确认服务定义区块缩进正确
- 验证compose文件版本是否支持
depends_on条件语法
六、最佳实践清单
- 版本锁定：始终明确指定
version字段 - 网络隔离：为不同服务组创建独立网络
- 资源限制：为生产服务设置CPU/内存限制
- 健康检查：所有关键服务必须配置健康检查
- 环境分离：使用多个compose文件管理不同环境
docker compose -f docker-compose.yml -f docker-compose.prod.yml up - 敏感数据保护：使用外部secrets管理凭证
secrets:db_password:file: ./secrets/db_password.txt
架构师建议：将服务依赖视为系统可靠性基石，推荐使用
condition: service_healthy确保服务真正可用。对于复杂系统，建议结合Circuit Breaker模式实现弹性架构。
