Docker Compose 四层解析：从 YAML 语法到工程化落地

1. 为什么“写个 docker-compose.yml”不等于真正掌握了 Docker Compose你有没有过这样的经历照着教程复制粘贴一段docker-compose.yml敲下docker compose up -d服务跑起来了——然后就以为自己“会了”结果第二天容器莫名退出docker compose ps显示No configuration file provided: not found改了个端口前端连不上后端查日志发现是网络不通想加个 Redis 缓存一通配置后 PHP 应用报错Connection refused翻遍文档却找不到php容器和redis容器之间到底该用什么地址通信更别提在 Ubuntu 服务器上部署时docker compose命令根本不存在而docker-compose带横杠又提示command not found……这些不是玄学是工程化落地前必须跨过的认知断层。Docker Compose 的本质从来不是“把几个docker run命令写进 YAML 文件”这么简单。它是一套面向服务生命周期的声明式契约系统——你声明“我要一个 Nginx、一个 PHP-FPM、一个 MySQL、一个 Redis”Compose 就负责按依赖顺序拉镜像、建网络、挂卷、设环境变量、启动容器、监控状态、处理重启策略并在你执行down时干净地销毁所有资源。但这份契约的每一条条款都隐含着底层机制、默认行为、常见陷阱和工程权衡。比如restart: always看似万能实则在数据库容器里可能引发主从脑裂volumes写成./data:/var/lib/mysql在 Windows 上可能因路径映射失败导致 MySQL 启动即崩溃network_mode: host能解决端口冲突却会让整个编排失去网络隔离能力让depends_on形同虚设。我第一次在 CentOS7 上部署 Jenkins GitLab Nexus 三件套时就栽在docker-compose.yml的version字段上。当时用的是3.8本地 Docker Desktop 运行正常但服务器上 Docker Engine 版本是 20.10docker composeCLI 不支持3.8的某些字段报错信息却只说invalid version没提具体哪条不兼容。折腾两天才发现3.8要求 Docker Engine ≥ 20.10.0而我们线上是 20.10.0-rc1差了那零点零一。这种细节官方文档不会标红加粗但工程上线时就是生死线。所以这篇内容不讲“怎么安装 Docker”也不罗列“10 个常用命令”而是带你一层层剥开docker-compose.yml这个看似简单的文件背后真实存在的四层结构语法层YAML 规则、语义层字段含义与约束、运行时层Docker Engine 如何解析执行、工程层多环境、CI/CD、可观测性如何嵌入。只有看清这四层你写的才不是脚本而是可维护、可测试、可交付的服务蓝图。2. 从docker run到docker compose up一次彻底的范式迁移很多人学 Compose 的第一课就是把三个docker run命令“翻译”成 YAML。比如启动一个 WordPress 站点# 原始 docker run 方式 docker run -d --name mysql -e MYSQL_ROOT_PASSWORD123456 -p 3306:3306 -v /data/mysql:/var/lib/mysql mysql:8.0 docker run -d --name wordpress -e WORDPRESS_DB_HOSTmysql -e WORDPRESS_DB_PASSWORD123456 -p 8080:80 -v /data/wordpress:/var/www/html --link mysql:mysql wordpress:6.0 docker run -d --name nginx -p 80:80 -v /data/nginx/conf:/etc/nginx/conf.d -v /data/wordpress:/var/www/html nginx:1.24然后写出这样的docker-compose.ymlversion: 3.9 services: mysql: image: mysql:8.0 environment: MYSQL_ROOT_PASSWORD: 123456 ports: - 3306:3306 volumes: - /data/mysql:/var/lib/mysql wordpress: image: wordpress:6.0 environment: WORDPRESS_DB_HOST: mysql WORDPRESS_DB_PASSWORD: 123456 ports: - 8080:80 volumes: - /data/wordpress:/var/www/html depends_on: - mysql nginx: image: nginx:1.24 ports: - 80:80 volumes: - /data/nginx/conf:/etc/nginx/conf.d - /data/wordpress:/var/www/html看起来完美不。这恰恰是范式迁移失败的典型——你只是把命令行参数“平移”进了 YAML没理解 Compose 的核心设计哲学服务自治 网络协同。2.1--link已死networks当立服务发现的本质变革--link是 Docker 早期为解决容器间通信引入的临时方案它通过修改/etc/hosts文件让被链接容器能用别名访问链接容器。但--link有致命缺陷单向、静态、无法跨主机、与用户自定义网络不兼容。Compose 默认为每个docker-compose.yml创建一个独立的桥接网络如myapp_default所有服务自动加入该网络并获得 DNS 解析能力。这意味着wordpress容器里ping mysql和curl http://mysql:3306是原生支持的无需任何额外配置。depends_on字段的作用仅仅是控制启动顺序确保mysql先于wordpress启动它不保证mysql服务已就绪MySQL 进程监听了 3306 端口。这就是为什么你常看到wordpress启动报错Cant connect to MySQL server——mysql容器是起来了但 MySQL 进程还在初始化。提示真正的健康检查必须由应用自身完成。WordPress 官方镜像内置了healthcheck你可以在docker-compose.yml中显式启用services: mysql: # ... 其他配置 healthcheck: test: [CMD, mysqladmin, ping, -h, localhost, -u, root, -p123456] timeout: 20s retries: 102.2volumes的三种形态宿主机路径、命名卷、绑定挂载的深层差异上面 YAML 中的volumes全部用了绝对路径/data/mysql。这在开发机上可行但在 CI/CD 流水线或不同操作系统Windows/macOS/Linux上必然失败。Compose 提供了三种 volume 模式适用场景截然不同类型语法示例适用场景关键特性命名卷Named Volumedb-data:/var/lib/mysql生产环境数据库、需要持久化且不关心宿主机路径的数据由 Docker 管理路径抽象跨平台一致支持备份/迁移绑定挂载Bind Mount./src:/app/src开发环境代码热更新、配置文件共享直接映射宿主机目录性能高但路径硬编码易出错tmpfs 挂载tmpfs: /run敏感临时数据如 session、避免写入磁盘数据仅存于内存容器停止即丢失安全性高实际工程中我坚持一个铁律数据库、缓存、消息队列等有状态服务必须用命名卷应用代码、静态资源、Nginx 配置等无状态或开发期内容才用绑定挂载。比如修正后的 WordPress 配置services: mysql: # ... 其他配置 volumes: - db-data:/var/lib/mysql # 命名卷安全可靠 # ... healthcheck wordpress: # ... 其他配置 volumes: - wp-content:/var/www/html/wp-content # 插件/主题数据用命名卷 - ./custom-conf:/var/www/html/wp-config.php # 自定义配置用绑定挂载开发 nginx: # ... 其他配置 volumes: - ./nginx/conf:/etc/nginx/conf.d # Nginx 配置用绑定挂载开发 - wp-content:/var/www/html/wp-content # 与 wordpress 共享同一命名卷这里wp-content是一个命名卷被wordpress和nginx两个服务同时挂载实现了“一份数据多容器读写”的经典模式。而./nginx/conf是相对路径绑定挂载方便你在 IDE 里直接编辑配置改完docker compose restart nginx即可生效。2.3ports的隐形陷阱127.0.0.1:8080:80与8080:80的生死之别ports字段看似简单但8080:80和127.0.0.1:8080:80有本质区别。前者将容器的 80 端口映射到宿主机所有网络接口的 8080 端口意味着局域网内其他机器也能通过http://server-ip:8080访问后者只映射到127.0.0.1localhost仅本机可访问。这在生产环境中是安全红线。很多团队在测试环境用8080:80上线时忘记改成127.0.0.1:8080:80导致测试接口直接暴露在公网酿成事故。更隐蔽的坑是端口冲突。当你在一台服务器上部署多个 Compose 项目如project-a和project-b如果它们都声明ports: [8080:80]第二个项目up时会报错Bind for 0.0.0.0:8080 failed: port is already allocated。解决方案不是改端口而是用network_mode: service:nginx让其他服务复用 Nginx 的网络栈或者用反向代理Nginx/Traefik统一分发流量让每个项目只暴露内部端口如80由代理层做路由。这才是微服务架构的起点。3.docker-compose.yml的四层结构解剖从语法到工程实践一个合格的docker-compose.yml文件绝不是字段的堆砌。它是一个分层的契约文档每一层解决一类问题。下面以一个真实的企业级 Spring Boot PostgreSQL Redis Prometheus 监控栈为例逐层拆解。3.1 语法层YAML 的严谨性与 Compose 的扩展性YAML 是人类可读的数据序列化格式但它的缩进、冒号、引号规则极易出错。一个常见的低级错误是environment: SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/mydb # 错误URL 中的 : 和 / 会被 YAML 解析器当作分隔符导致值被截断正确写法必须加引号environment: SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/mydb # 或使用 折叠块适合长字符串 JAVA_OPTS: -Xms512m -Xmx1024m -Dfile.encodingUTF-8Compose 还支持变量替换和环境文件这是工程化的基石。创建.env文件# .env COMPOSE_PROJECT_NAMEmyapp POSTGRES_USERappuser POSTGRES_PASSWORDsecretpass SPRING_PROFILES_ACTIVEprod然后在docker-compose.yml中引用services: app: image: myapp:${APP_VERSION:-latest} # APP_VERSION 未定义时用 latest environment: - SPRING_PROFILES_ACTIVE${SPRING_PROFILES_ACTIVE} - POSTGRES_USER${POSTGRES_USER} - POSTGRES_PASSWORD${POSTGRES_PASSWORD} # ...docker compose up会自动加载.env你甚至可以用APP_VERSION1.2.3 docker compose up覆盖环境变量。这比在 YAML 里硬编码版本号强一万倍。3.2 语义层每个字段背后的“为什么”与“何时用”docker-compose.yml的字段不是孤立的它们构成了一套完整的服务描述语言。关键字段的深层逻辑如下depends_on仅控制启动顺序不等待依赖服务就绪。它等价于docker run --depends-on底层是--add-host和启动顺序调度。要实现真正的“等待就绪”必须配合healthcheckcondition: service_healthyservices: app: # ... 其他配置 depends_on: postgres: condition: service_healthy # 必须等 postgres 的 healthcheck 通过 redis: condition: service_started # 只需 redis 容器启动即可restart策略no,always,on-failure,unless-stopped四种。always最常用但对数据库有风险。PostgreSQL 官方镜像的healthcheck会检测pg_isready如果设置restart: always当主库因磁盘满触发healthcheck失败时Docker 会不断重启容器导致 WAL 日志疯狂增长进一步挤占空间。此时应选on-failure: 5失败 5 次后停止并由外部监控告警人工介入。buildvsimagebuild指向一个 Dockerfile 目录image指向远程镜像仓库。工程实践中我坚持“所有生产镜像必须由 CI/CD 构建并推送到私有仓库docker-compose.yml中只用image”。build只保留在docker-compose.dev.yml中用于本地开发。这样能保证环境一致性——开发、测试、生产用的都是同一个镜像 ID。networks自定义默认的default网络够用但复杂场景需自定义。例如让app和postgres在backend网络通信app和nginx在frontend网络通信nginx单独暴露在public网络networks: backend: driver: bridge frontend: driver: bridge public: driver: bridge services: app: networks: - backend - frontend postgres: networks: - backend nginx: networks: - frontend - public ports: - 80:80这样postgres容器完全隔离在backend网络外部无法直接访问安全性大幅提升。3.3 运行时层docker compose up背后的 12 步执行链当你敲下docker compose up -dDocker CLI 并非简单地启动容器。它执行一个精密的 12 步流程基于 Docker Compose v2.20 源码分析解析.env文件加载环境变量读取docker-compose.yml验证 YAML 语法和 Compose Schema 版本合并覆盖文件如docker-compose.prod.yml生成最终配置检查build上下文若存在Dockerfile调用docker build构建镜像此步可跳过用--no-build拉取远程镜像image字段指定的若本地不存在创建命名卷volumes中定义的若不存在创建自定义网络networks中定义的若不存在为每个服务生成容器配置包括网络连接、端口映射、环境变量、健康检查等按depends_on顺序启动容器但不等待healthcheck启动healthcheck子进程持续监控容器健康状态注册docker compose logs流将容器 stdout/stderr 聚合返回控制台后台运行。理解这个链条你就知道为什么docker compose up --no-build能加速部署跳过第 4 步为什么docker compose down --volumes会删除命名卷对应第 6 步的逆操作以及为什么docker compose ps有时显示Unhealthy第 10 步的监控结果。3.4 工程层多环境、CI/CD 与可观测性的无缝集成一个只能在本机up的 Compose 文件离工程化还很远。真正的工程化要求它能适应开发、测试、预发、生产四套环境。我的标准做法是docker-compose.yml定义通用服务结构、网络、卷不含环境敏感配置docker-compose.dev.yml开发专用启用bind mount、DEBUG模式、restart: on-failuredocker-compose.prod.yml生产专用禁用bind mount启用restart: unless-stopped配置healthcheck设置mem_limitdocker-compose.ci.ymlCI/CD 专用禁用ports启用logging到syslog添加entrypoint执行单元测试。通过docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d合并配置。CI/CD 流水线如 GitHub Actions脚本如下# .github/workflows/deploy.yml name: Deploy to Prod on: push: branches: [main] tags: [v*.*.*] jobs: deploy: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkoutv4 - name: Set up Docker Buildx uses: docker/setup-buildx-actionv3 - name: Login to Docker Hub uses: docker/login-actionv3 with: username: ${{ secrets.DOCKER_USERNAME }} password: ${{ secrets.DOCKER_PASSWORD }} - name: Build and push uses: docker/build-push-actionv5 with: context: . push: true tags: myorg/myapp:${{ github.sha }} - name: Deploy to Server uses: appleboy/scp-actionmaster with: host: ${{ secrets.HOST }} username: ${{ secrets.USERNAME }} key: ${{ secrets.KEY }} source: docker-compose.yml,docker-compose.prod.yml,.env.prod target: /opt/myapp/ - name: Run on Server uses: appleboy/ssh-actionmaster with: host: ${{ secrets.HOST }} username: ${{ secrets.USERNAME }} key: ${{ secrets.KEY }} script: | cd /opt/myapp docker compose -f docker-compose.yml -f docker-compose.prod.yml down docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d --remove-orphans可观测性方面logging字段是关键入口services: app: # ... 其他配置 logging: driver: json-file options: max-size: 10m max-file: 3 # 或对接 ELK # logging: # driver: fluentd # options: # fluentd-address: localhost:24224 # tag: myapp.app配合docker compose logs -f app你能实时看到聚合日志配合docker compose top app能看到容器内进程配合docker compose exec app sh能进入容器调试。这才是一个完整的服务生命周期管理闭环。4. 真实世界踩坑实录那些让老手也皱眉的 Compose 陷阱再完美的理论也要经受真实世界的毒打。以下是我在过去三年运维 200 个 Compose 项目中总结出的 5 个最高频、最隐蔽、最让人抓狂的坑附带根因分析和可立即复用的修复方案。4.1 坑docker compose ps no configuration file provided: not found—— 路径与上下文的战争现象在项目根目录执行docker compose ps报错No configuration file provided: not found但ls明明能看到docker-compose.yml。根因分析这不是文件不存在而是docker composeCLI 的工作目录working directory与配置文件路径不匹配。docker compose默认在当前目录查找docker-compose.yml或compose.yaml。但如果你在子目录如./src执行命令它就不会向上递归查找。更隐蔽的是某些 CI/CD 工具如 Jenkins Pipeline的sh步骤默认工作目录是 workspace 根而非git checkout的子模块路径。复现步骤mkdir myapp cd myapp echo version: 3.9 docker-compose.yml cd src # 进入子目录 docker compose ps # 报错修复方案方案1推荐显式指定文件路径docker compose -f ../docker-compose.yml ps方案2用-p指定项目名强制工作目录docker compose -p myapp -f ../docker-compose.yml ps方案3CI/CD 专用在脚本开头cd回项目根cd $(dirname $0)/.. # 假设脚本在 ./scripts/deploy.sh docker compose up -d注意docker-compose带横杠是旧版 Python 实现docker compose无横杠是新版 Go 实现两者命令行为略有差异。Ubuntu 22.04 默认安装docker compose而 CentOS7 需手动下载二进制。docker compose version输出Docker Compose version v2.x.x即为新版。4.2 坑Windows 上volumes映射失败The system cannot find the path specified现象在 Windows Docker Desktop 上volumes使用./config:/app/config容器启动报错The system cannot find the path specified或配置文件根本没挂载进去。根因分析Windows 路径分隔符是\而 Docker CLI 期望/。更重要的是Docker Desktop 的 Linux VMWSL2无法直接访问 Windows 的 NTFS 路径必须通过 WSL2 的/mnt/c/挂载点。./config在 CMD/PowerShell 中解析为C:\myapp\config但 WSL2 里没有C:盘概念。修复方案方案1开发机首选用 WSL2 路径volumes: - /mnt/c/Users/yourname/myapp/config:/app/config方案2跨平台通用用命名卷 初始化脚本services: app: volumes: - app-config:/app/config # 启动时从宿主机复制配置 command: sh -c cp -r /host-config/* /app/config/ exec java -jar app.jar volumes: - ./config:/host-config # 绑定挂载宿主机 config 目录 - app-config:/app/config # 命名卷供应用读取4.3 坑depends_onhealthcheck仍失败app启动时postgres连不上现象docker-compose.yml中已配置depends_on和healthcheck但app容器日志仍显示Connection refused。根因分析healthcheck的test命令是在容器内部执行的而app容器要连接postgres走的是 Docker 网络 DNS。healthcheck成功只说明postgres容器内的pg_isready命令能连上localhost:5432但app容器的网络栈、DNS 解析、防火墙规则可能仍有问题。排查链路docker compose exec app ping postgres—— 测试 DNS 解析和基础连通性docker compose exec app telnet postgres 5432—— 测试端口可达性需先apt-get install telnetdocker compose exec postgres netstat -tuln | grep 5432—— 确认 PostgreSQL 监听0.0.0.0:5432而非127.0.0.1:5432检查postgres的pg_hba.conf确认允许host all all 0.0.0.0/0 md5。终极修复在app的entrypoint中加入重试逻辑Bash 脚本#!/bin/bash # wait-for-postgres.sh set -e host$1 shift cmd$ until pg_isready -h $host -U $POSTGRES_USER; do echo Waiting for PostgreSQL at $host... sleep 2 done exec $cmd然后在docker-compose.yml中services: app: entrypoint: [./wait-for-postgres.sh, postgres, --] command: [java, -jar, app.jar]4.4 坑docker compose down后命名卷里的数据“消失”了现象docker compose down后再up数据库数据没了。docker volume ls显示卷存在但docker volume inspect vol发现Mountpoint下是空的。根因分析docker compose down默认不删除命名卷但如果你在docker-compose.yml中定义了volumes而docker compose down时加了--volumes参数或者你执行了docker volume rm vol数据就真没了。更常见的是你up时用了不同的COMPOSE_PROJECT_NAME导致创建了新卷而旧卷被遗弃。验证方法# 查看当前项目使用的卷 docker compose config --services # 列出服务名 docker volume ls | grep myapp # myapp 是 COMPOSE_PROJECT_NAME # 查看卷内容 docker run --rm -v myapp_db-data:/volume -it alpine ls -la /volume防护策略永远不要在生产环境用docker compose down --volumes为每个环境设置唯一COMPOSE_PROJECT_NAME通过.env文件定期备份命名卷# 备份 docker run --rm -v myapp_db-data:/volume -v $(pwd):/backup alpine tar czf /backup/db-data-$(date %F).tar.gz -C /volume . # 恢复 docker run --rm -v myapp_db-data:/volume -v $(pwd):/backup alpine tar xzf /backup/db-data-2024-01-01.tar.gz -C /volume4.5 坑docker compose restart always导致服务雪崩现象一个restart: always的服务如 Nginx因配置错误反复重启CPU 占用 100%docker stats显示其 CPU% 持续 99%其他服务全部卡死。根因分析restart: always意味着容器退出后Docker Daemon 会立即尝试重启。如果容器启动 1 秒就因配置错误崩溃Daemon 会在毫秒级内再次启动形成“启动-崩溃-重启”循环消耗大量系统资源。Docker 的重启策略有指数退避exponential backoff但初始间隔太短100ms对 CPU 是毁灭性打击。修复方案方案1改用restart: on-failure: 5让失败 5 次后停止留出人工干预时间方案2增加启动延迟在command中加sleep不推荐治标不治本方案3最佳用healthcheckrestart组合services: nginx: # ... 其他配置 healthcheck: test: [CMD, curl, -f, http://localhost:80/health] interval: 30s timeout: 10s retries: 3 start_period: 40s restart: on-failure这样只有healthcheck失败 3 次后才会触发restart且每次失败后有 30 秒间隔彻底避免雪崩。5. 从入门到交付一个可直接复用的工程化模板前面讲了原理、陷阱、结构现在给你一个经过 10 个生产项目验证的、开箱即用的docker-compose.yml模板。它不是一个玩具示例而是真实企业级项目的骨架你可以直接复制、修改、部署。# docker-compose.yml - 通用服务结构不包含环境敏感配置 version: 3.9 # 全局设置影响所有服务 x-common: common # 所有服务共享的网络 networks: - backend - frontend # 共享的资源限制 mem_limit: 1g mem_reservation: 512m cpus: 1.0 # 共享的日志配置 logging: driver: json-file options: max-size: 10m max-file: 3 # 定义网络分离前后端流量 networks: backend: driver: bridge internal: true # 不允许外部访问 frontend: driver: bridge # 定义命名卷用于持久化数据 volumes: db-data: driver: local redis-data: driver: local app-logs: driver: local services: # PostgreSQL 数据库 postgres: : *common image: postgres:15-alpine environment: POSTGRES_DB: ${POSTGRES_DB:-myapp} POSTGRES_USER: ${POSTGRES_USER:-appuser} POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-secretpass} # 重要允许所有客户端连接Docker 网络内 POSTGRES_HOST_AUTH_METHOD: trust volumes: - db-data:/var/lib/postgresql/data healthcheck: test: [CMD-SHELL, pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB} || exit 1] interval: 30s timeout: 10s retries: 5 start_period: 40s restart: on-failure: 5 networks: - backend # Redis 缓存 redis: : *common image: redis:7-alpine command: redis-server /usr/local/etc/redis/redis.conf volumes: - redis-data:/data - ./redis.conf:/usr/local/etc/redis/redis.conf:ro healthcheck: test: [CMD, redis-cli, ping] interval: 30s timeout: 10s retries: 5 start_period: 40s restart: on-failure: 5 networks: - backend # 应用服务Spring Boot 示例 app: : *common image: ${APP_IMAGE:-myorg/myapp:latest} environment: SPRING_PROFILES_ACTIVE: ${SPRING_PROFILES_ACTIVE:-prod} SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/${POSTGRES_DB} SPRING_DATASOURCE_USERNAME: ${POSTGRES_USER} SPRING_DATASOURCE_PASSWORD: ${POSTGRES_PASSWORD} REDIS_URL: redis://redis:6379/0 depends_on: postgres: condition: service_healthy redis: condition: service_started # 挂载日志卷便于收集 volumes: - app-logs:/app/logs # 暴露管理端点仅限内部网络 expose: - 8080 - 8081 # actuator restart: on-failure: 5 networks: - backend - frontend # Nginx 反向代理 nginx: : *common image: nginx:1.24-alpine volumes: - ./nginx/conf:/etc/nginx/conf.d:ro - ./nginx/html:/usr/share/nginx/html:ro - app-logs:/var/log/nginx # 共享日志卷 ports