★ FEATURED ARTICLE docker-compose 文件听起来像个特别基础的话题但说句实在话我见过太多被这个基础文件困住的人。明明只是开发环境里起几个容器怎么写出来的compose文件别人看不懂、自己也维护不了明明照着官方文档抄了为什么一部署就报网络错误为什么在本机跑得好好的换台机器就起不来这些问题十有八九都出在这个几百行的 yml 文件上。docker-compose 文件本质上就是一个容器编排的清单它让你用声明式的方式定义我要跑哪些服务、它们之间怎么连接、数据放哪里、挂了怎么办。它的核心价值不是省去几条 docker run 命令而是把一套多容器的运行拓扑固化成了可版本化、可评审、可复用的配置文件。这一篇我就从实际使用角度出发把 compose 文件拆开揉碎讲清楚结构、原理、常用写法、生产落地细节以及我在真实项目中踩过的坑。无论你是刚接触容器的小白还是已经用了一段时间但总觉得配置文件写得别扭的开发者这篇文章都值得收藏后慢慢看。1. 为什么compose文件值得认真对待1.1 从命令到清单的进化逻辑很多人刚开始学容器时习惯这么干要跑一个数据库敲docker run mysql:8要跑一个后端再敲一个docker run backend要跑前端再敲一个。跑起来之后发现三个容器之间要互通还得手动建网络、查 IP、改端口折腾半天。到了第二天机器重启了全部容器没了一切重来。docker-compose 文件解决的就是这种一次性手工操作带来的混乱。它把容器的定义、网络关系、存储挂载、环境变量这些信息统一写进一个 yml 文件用docker compose up -d一条命令完成启动用docker compose down一键清理。这个转变的本质是什么是从操作过程到声明目标的转变。你不关心容器怎么一个个启动你只关心最终应该有一整套互相连通的服务在运行。这就像以前装机要手动调 BIOS、分区、装驱动后来用镜像文件直接刷——你在写的是最终状态不是过程。1.2 compose文件在整个交付流程里的位置别小看这个文件。在真实的软件交付链路里compose 文件承担着承上启下的角色。往上它描述了应用的完整运行拓扑是架构评审时最直观的沟通载体往下它是测试环境、预发环境、甚至部分生产环境部署的基准。很多团队做 CI/CD 时测试阶段跑的就是docker compose up构建产物一旦和 compose 文件里的镜像没有对应关系线上交付就会出大问题。我的经验是但凡一个项目需要用两个以上容器就应该立刻引入 compose 文件而不是继续靠 shell 脚本堆docker run。写脚本的方式有一个致命问题——脚本是命令序列它隐含了先后顺序但容器编排的场景里服务之间的关系是并发的、网状的不是一条直线。compose 文件的声明式模型天然适合表达这种复杂关系。2. compose文件的核心骨架services、networks与volumes2.1 services的职责拆分与容器拓扑设计一个 compose 文件最核心的顶级字段就是services它下面每个键代表一个服务。服务这个概念要理解到位它不是一个容器而是一个容器模板。同一个服务可以通过docker compose up --scale api3启动出多个副本这在做负载均衡测试时非常有用。设计 services 列表时我习惯遵循一个容器只做一件事的原则。比如一个 Web 应用我不会把 Nginx 和 PHP-FPM 塞进同一个容器而是拆成两个 service通过内部网络通信。这样做的好处是可以单独升级 Nginx 版本而不影响 PHP 环境可以单独对 Nginx 做水平扩展日志也可以按服务分开采集。很多新人容易犯的错是把所有东西都塞进一个容器里美其名曰简化部署实际上是把故障域扩大了——容器一挂整个应用全挂。每个 service 下最基础的配置是image和container_name。image决定容器运行时的镜像来源container_name是给容器起的自定义名字。这里我建议大多数场景下不要设置container_name因为一旦设置了固定名称这个服务就无法水平扩展了。如果两个副本都用同一个container_name第二个会直接起不来。让 Compose 自动生成带项目名前缀的容器名反而更省心。2.2 networks如何塑造服务间的通信边界很多人写 compose 文件时习惯性地只配置services完全不管networks结果容器之间靠默认网络互相访问。这在简单场景下确实能跑通但这其实是一个巨大的隐患。你要理解 Compose 的默认行为如果你不显式声明 networksCompose 会给整个项目创建一个默认网络所有 service 都在这个网络里互相通过服务名访问。这看起来很方便但问题是——你的数据库、缓存、后端、前端全在一个平面网络里没有任何隔离。一旦某个服务被攻破攻击者可以横向访问所有服务。合理的做法是显式声明 networks并按业务边界拆分。比如networks: frontend: backend: services: web: networks: - frontend - backend api: networks: - backend db: networks: - backend这样 Web 只能访问 APIAPI 才能访问数据库Web 和数据库之间直接隔离。你可能会觉得这有点过度设计但在生产环境中多一层网络隔离就多一层安全保障。更重要的是显式声明网络后你可以给网络指定driver_opts或 IP 段方便和外部网络打通。2.3 volumes的数据持久化与善后问题容器是用完即弃的但数据不能丢。volumes字段就是解决这个问题的。它有两种用法一种是顶层声明命名卷另一种是直接绑定宿主机路径。顶层命名卷的写法是这样volumes: db-data: services: db: image: mysql:8.0 volumes: - db-data:/var/lib/mysql这种写法的好处是数据不受容器生命周期影响docker compose down也不会删卷。但它也有个坑卷的实际存储位置由 Docker 管理如果你需要备份或者想直接查看数据文件得通过docker volume inspect找到宿主机路径挺绕的。绑定路径的写法则是直接把宿主机目录挂进去services: db: image: mysql:8.0 volumes: - ./data/mysql:/var/lib/mysql这种方式开发时非常好用你可以在宿主机上直接查看数据文件。但用起来要注意不同操作系统下路径的差异、权限问题、以及 bind mount 和镜像内目录的覆盖关系这些都需要留意。把 bind mount 挂到镜像内有内容的目录时宿主机目录里的东西会直接顶掉镜像内的原目录内容如果该目录是空的且镜像内有初始数据数据会消失——实际不是没了而是被空目录遮住了。这个问题我后面会专门讲。3. 生产级compose文件的必备配置项3.1 depends_on与healthcheck的配合用法很多新手用depends_on来控制服务启动顺序比如 API 依赖数据库就写services: api: depends_on: - db这个写法能保证 db 容器先启动但并不能保证数据库准备好接受连接。MySQL 容器启动和 MySQL 进程就绪之间往往有几十秒的间隔。API 容器过早去连数据库连接失败后如果应用没有重试机制就会直接崩掉然后在restart策略下反复重启直到数据库就绪——这个过程很浪费资源。生产级的做法是depends_on配合healthcheckservices: db: image: mysql:8.0 healthcheck: test: [CMD, mysqladmin, ping, -h, localhost] interval: 5s timeout: 3s retries: 10 api: image: myapp:1.0 depends_on: db: condition: service_healthy这样 API 容器只会在数据库健康检查通过后才启动从顺序可控升级为状态可控。我在实际项目里遇到的容器连不上数据库问题绝大多数都是因为少了这个condition: service_healthy。3.2 资源限制与重启策略的选择容器不加限制地使用宿主机资源是造成一台机器跑着跑着就卡死的常见原因。compose 文件里可以给每个 service 设置资源上限services: api: deploy: resources: limits: cpus: 1.0 memory: 512M注意deploy下的resources在旧版docker-compose和 新版docker compose里的支持情况不同。新版 Compose v2 支持得比较好旧版则需要开启version: 3.x配合 swarm 相关配置才能部分生效。更通用的做法是使用mem_limit和cpus这种顶层指令但新版已经推荐统一走deploy.resources。重启策略就是restart字段可取值有no、always、on-failure、unless-stopped。我个人的推荐数据库这类有状态服务用unless-stopped这样手动 stop 后不会因为守护进程反复拉起无状态 API 服务用on-failure配合restart_policy: max_attempts防止无限重启批处理任务用no跑完就结束挂了也不重试。3.3 环境变量与配置管理把配置写死在 compose 文件里是维护灾难。比如同一个服务在不同环境里数据库地址不同如果每次改动都去改 yml那 compose 文件很快就变成一团乱麻。Compose 的变量替换机制必须用起来。你可以在 compose 文件里直接写${DB_HOST}然后让 Compose 自动读取宿主机环境变量或者.env文件里的值。.env文件放在项目根目录Compose 加载时会自动识别。services: api: image: myapp:${APP_VERSION:-latest} environment: - DB_HOST${DB_HOST} - DB_PASSWORD${DB_PASSWORD}这里有个关键的细节env_file和environment的优先级。env_file把文件里的键值对注入容器环境变量environment则是在 compose 文件里直接定义。当键冲突时environment里的值会覆盖env_file里的。另外别忘了容器环境变量并不等于安全的配置存储数据库密码这类敏感信息更稳妥的做法是使用 Docker secrets 或专门的管理系统别直接以明文形式写在.env里再提交到仓库。4. 从开发环境到生产部署的落地细节4.1 镜像版本固定与tag策略compose 文件里最容易忽略但影响最大的是image的 tag 写法。如果你写的是nginx:latest每次pull都会拉到最新版而最新版的镜像内容是不可预期。今天能跑明天官方发了个破坏性更新一拉下来整个环境就挂了。所谓的可复现部署前提就是镜像版本可固定。我的建议是开发环境可以用语义化标签比如myapp:1.2.3测试和生产环境用不可变标签——即基于某个 commit 构建出的完整镜像 ID 或带 commit 短哈希的 tag。比如myapp:1.2.3-b9f23a1这样任何人看到 tag 都能追溯到源代码版本排查问题时就能精确定位。还有一种常见做法是用${APP_VERSION}这种变量统一控制版本这样升级版本时只需要改.env里的一个变量而不是在所有 service 配置里寻找image字段逐个替换。4.2 端口映射与对外暴露的取舍ports和expose是两个容易混淆的字段。ports是把容器的端口映射到宿主机端口外部可以直接访问expose只是声明容器在内部网络里开放某个端口外部不可达。生产部署时我的经验是尽量少暴露端口。假如你的服务只应该被另一个服务访问那就不要用ports映射到宿主机只需要让它在内部网络里通过服务名通信即可。比如 API 有 8080 端口前端 Nginx 转发到 API 时直接通过 HTTP 访问 API 服务名即可根本不需要把 8080 暴露到宿主机。只有真正需要对外服务的入口比如 Nginx 的 80/443才用ports。还要注意ports的端口冲突问题。如果宿主机某个端口已经被占用启动会直接失败。合理的做法是使用高段位端口比如 8000-10000映射容器端口尽量避免使用系统常用端口。调试时可以用127.0.0.1:8080:80这种写法只绑定回环地址避免服务直接暴露在外网网卡上这对安全挺重要。4.3 日志、时区与基础镜像的优化容器内的应用默认是 UTC 时区和本地时间差了 8 小时排查问题看日志时间会非常难受。解决办法很简单在 service 里设置services: api: environment: - TZAsia/Shanghai注意时区设置最好配合基础镜像里的 tzdata 包有些精简镜像没有时区数据设置了也不生效。更彻底的做法是挂载宿主机的/etc/localtime到容器但不同系统的路径差异比较大建议优先用环境变量的方式。日志方面容器默认的日志驱动是 json-file会往宿主机写一大堆 JSON 文件时间长了磁盘会被塞满。compose 文件里可以限制日志大小services: api: logging: driver: json-file options: max-size: 10m max-file: 3这个配置建议放在每个 service 里或者统一通过 config 管理。做过线上运维的人都懂日志撑爆磁盘导致整个宿主机卡死是所有事故里最冤的一种。5. 我经常踩的坑compose排查全链路5.1 网络连接失败的排查顺序本机 curl 端口能通但容器间访问就是不通——这类问题上我碰到过太多次了。排查时要按顺序来第一确认目标容器是否真的在运行。docker compose ps看状态如果显示Restarting那大概率是进程崩溃或健康检查没通过这时候去docker compose logs看输出。第二确认网络是否连通。进入调用方容器用docker compose exec api sh然后ping目标服务名。如果 ping 不通可能是两个 service 不在同一个 network 里。检查 compose 文件里 network 分配。第三确认端口是否监听。服务名能 ping 通不代表端口能通可能是服务的监听地址被写死成127.0.0.1导致容器外部访问不到。应用监听时必须监听0.0.0.0这一点网络排查里最隐蔽——容器里看到的回环地址是容器自身的不是宿主机的。第四确认防火墙或安全组。当网络访问跨越宿主机时就要检查宿主机防火墙和云安全组这部分和 compose 无关但很容易误判。5.2 目录挂载与权限问题常见的坑有两个。第一个是目录挂载覆盖导致数据消失前面提到过。比如 MySQL 镜像在/var/lib/mysql里有初始化脚本如果你把宿主机空目录 bind 过去初始化脚本就看不到数据了。解决方法是初次初始化时先不挂载或者把初始化脚本放到/docker-entrypoint-initdb.d目录这个目录才是官方镜像专门用来做初始化的。第二个坑是权限不足。容器内进程以不同 UID 运行而 bind mount 的宿主机目录权限往往不匹配。比如宿主机目录属于 1000 用户容器内进程以 uid 999 运行写入时就会 Permission denied。我的经验是提前用id命令确认镜像里运行用户的 UID然后调整宿主机目录的属主或者在 compose 文件里用user字段指定运行身份。还有一种做法是避开 bind mount用命名卷。Docker 在初始化命名卷时如果卷是空的会自动把镜像内对应目录的内容拷贝到卷里这一步能规避掉不少权限和初始化问题。5.3 Compose版本与语法兼容问题网上搜到的 compose 文件鱼龙混杂。有些带着version: 2.4有些用version: 3.8还有一些完全没有 version 字段。这背后其实有一套演化逻辑旧版 docker-compose 用 version 字段区分语法规则新版 Docker Compose v2 已经逐步弱化它。从实际效果看语法差异主要体现在部分字段的支持和继承规则上。遇到本地能跑放在 CI 里跑不起来的问题优先检查两边的 Compose 版本。由于旧版不支持某些高级字段例如long syntax那套写法如果两端的 compose 插件版本相差太大很容易出现无法解析配置文件的情况。最好的方式是把团队用的 compose 版本固定下来并在项目的 README 里写明。更要注意的是即使文件语法相同不同版本的解释也可能不同比如 network 和 volume 的默认行为升级前一定要看官方 release notes。6. 让compose文件更好维护的习惯6.1 命名与服务拓扑的清晰度处理过几百个 compose 文件之后我发现一个问题service 的名称往往能决定这个文件的质量。命名要自解释比如web、api、db、redis这种一看就知道是什么服务。有些人喜欢叫app1、app2、service_a隔一个月自己都看不懂。网络和卷的命名也同理。命名卷可以在顶层加name字段比如volumes: db-data: name: ${PROJECT_NAME}-mysql-data否则 Compose 会自动生成projectname_db-data这种名字不同项目之间容易混淆。网络也建议指定自定义名称特别是在多个 compose 项目需要互相通信时name字段能让你明确知道这个网络具体属于哪个项目、用途是什么。6.2 分文件管理与多环境适配一个 compose 文件打天下往往意味着不同环境的配置在同一个文件里互相污染。我的做法是拆分基础文件和覆盖文件docker-compose.yml存放公共配置比如镜像、网络、卷、基础环境变量docker-compose.override.yml开发环境覆盖比如工具链、调试日志、测试端口docker-compose.prod.yml生产环境覆盖比如资源限制、副本数、发布策略启动时用-f参数组合docker compose -f docker-compose.yml -f docker-compose.prod.yml up -dCompose 的合并规则是后加载的文件覆盖先加载的文件列表类型的字段例如ports会做合并。这意味着你可以在基础文件里声明服务在生产文件里只覆盖必要字段大幅减少重复配置。官方推荐把docker-compose.override.yml作为自动加载的开发配置也就是说直接运行docker compose up时它会自动使用这个文件。6.3 把compose文件当代码来review最后想强调一个习惯问题把 compose 文件当代码对待。做 code review 时不光看业务代码也要看编排文件的改动。镜像 tag 有没有升级端口有没有新暴露网络边界有没有变化资源限制有没有遗漏新服务这些都是架构级的变化值得严肃评审。另外别把 compose 文件做成一次性手写然后再也不看。它应该和项目代码一起演进。每次基础镜像有安全更新需要改 compose 文件里的 tag 并重新验证每次服务拆分或合并也要同步调整服务和网络拓扑。放任不管的 compose 文件最后一定会在某个深夜的部署事故里亮出獠牙。最后分享两个小习惯我做项目收尾时一定会做两个检查。第一个在所有服务之间画一张通信图对着 compose 文件的 networks 逐条勾选确保图上每一条边都对应文件里的配置没有暗藏没验证过的连接。第二个在干净环境里执行一次完整的docker compose down -v加docker compose up -d确认数据卷被清空后整个环境依然能重新拉起这样能提前暴露掉一堆只能靠手工恢复的隐性依赖。compose 文件看着简单真正用好了需要长期积累。容器化部署是一件利落的事情别让一个松散的 yml 文件毁了整个体验。希望这篇经验总结能帮你在写 compose 文件的路上少走几步弯路。
阅读完成 · 觉得有帮助？
