用途
Docker Compose 用于定义和运行多容器 Docker 应用。通过一个 YAML 文件（Compose V2 中为 compose.yml，也支持 docker-compose.yml）声明服务、网络和卷，即可在本地开发或生产环境中统一编排多个容器。当用户提到 "docker-compose"、"docker compose"、"multi-container" 等关键词时适用。
主要能力
Compose 文件语法
compose.yml 定义 services、networks、volumes 三大部分。示例中 web 服务使用 nginx:1.25-alpine 镜像，映射 8080:80 端口，挂载只读的 nginx.conf，加入 frontend 网络，并通过 depends_on 等待 api 服务健康。api 服务从 ./api 构建，暴露 3000 端口，设置 DATABASE_URL 与 REDIS_URL 环境变量，同时加入 frontend 和 backend 网络，并配置 healthcheck。db 使用 postgres:16-alpine，挂载 pgdata 命名卷和 init.sql 初始化脚本，设置数据库环境变量，仅加入 backend 网络。cache 使用 redis:7-alpine，通过 command 设置内存上限与淘汰策略。
常见服务组合模式
- Web + API + 数据库 + 缓存：Web 服务器反向代理到 API，API 通过共享 backend 网络访问数据库与缓存。
- 前端 + 后端 + 数据库：frontend 构建自 ./frontend，映射 5173 端口并挂载源码目录，设置 VITE_API_URL；backend 构建自 ./backend，映射 4000 端口，挂载源码，depends_on 等待 db 健康，设置 DB_HOST；db 使用 mysql:8，挂载 mysql_data 命名卷，配置 root 密码与数据库名，并设置 mysqladmin ping 健康检查。
服务间网络
同一网络内的服务可通过服务名互相访问，DNS 解析自动完成。网络可配置 driver: bridge，backend 可设置 internal: true 禁止外部访问。同时加入 frontend 和 backend 的服务可与两个网络中的服务通信；仅加入 internal backend 的服务无法访问互联网。使用服务名作为主机名，例如 postgres://db:5432、http://api:3000。运行时排查网络问题可使用 docker network ls、docker network inspect myproject_backend、docker compose exec api ping db。
卷管理
- 命名卷：跨容器重启持久化数据，由 Docker 管理存储位置，如 volumes: pgdata: driver: local。
- 绑定挂载：将主机目录映射进容器，开发热重载必备，如 ./src:/app/src，以及用匿名卷 /app/node_modules 防止覆盖。
- tmpfs：内存存储，适合不应持久化的密钥或临时数据，如 /tmp、/run:size=64M。
- 只读挂载：如 ./config:/etc/app/config:ro。
环境变量
- 内联：在 environment 下直接写 NODE_ENV: production、LOG_LEVEL: info。
- 从 .env 文件：通过 env_file 指定 .env、.env.local。
- 变量替换：Compose 自动读取项目根目录的 .env 文件用于 YAML 中的变量替换，如 image: postgres:${POSTGRES_VERSION}-alpine、ports: "${APP_PORT}:3000"。支持默认值 ${VAR:-default} 和必填变量 ${VAR:?error message}。
健康检查与 depends_on
仅用 depends_on 只等待容器启动，不等待服务就绪。需使用 condition：service_started（默认）、service_healthy（健康检查通过）、service_completed_successfully（容器以 0 退出）。Postgres 健康检查示例：test: ["CMD-SHELL", "pg_isready -U $$POSTGRES_USER -d $$POSTGRES_DB"]，并设置 interval、timeout、retries、start_period。
开发覆盖文件
Compose 会自动将 compose.override.yml 合并到基础文件之上，用于开发专用设置。基础文件设置 NODE_ENV: production，覆盖文件可设置 build.target: development、挂载源码、设置 NODE_ENV: development 与 DEBUG、暴露调试端口 9229。也可显式指定文件：docker compose -f compose.yml -f compose.prod.yml up -d。
常用命令
- docker compose up -d：后台启动所有服务
- docker compose up -d --build：启动并强制重建
- docker compose down：停止并移除容器、网络
- docker compose down -v：同时移除卷（销毁数据）
- docker compose logs -f --tail=100：跟踪日志，显示最后 100 行；可指定服务如 docker compose logs -f api db
- docker compose exec api sh：在运行中的容器执行命令；docker compose exec db psql -U app -d myapp
- docker compose run --rm api npm test：运行新容器
- docker compose ps：列出运行中的服务
- docker compose pull：拉取最新镜像
- docker compose restart api：重启单个服务
- docker compose up -d --scale worker=3：扩缩服务（仅无状态服务）
- docker compose top、docker stats：查看资源使用
生产环境注意事项
可配置 restart: unless-stopped（或 always、on-failure、no）、read_only: true、security_opt: no-new-privileges:true、tmpfs: /tmp、日志驱动 json-file 及 max-size/max-file、deploy.resources 的 limits 与 reservations（cpus、memory）、secrets 引用（如 db_password 来自 ./secrets/db_password.txt，挂载于 /run/secrets/db_password）。
调试
- 容器无法启动：docker compose ps -a、docker compose logs api、docker compose run --rm api sh 交互式诊断。
- 服务无法访问另一服务：docker compose exec api getent hosts db、docker network inspect myproject_backend。
- 检查容器内环境与挂载：docker compose exec api env | sort、docker inspect $(docker compose ps -q db) --format '{{json .Mounts}}' | jq。
- 资源使用：docker stats --no-stream。
- 不启动仅校验文件：docker compose config --quiet。
适用场景
需要搭建多容器本地开发环境、管理服务依赖与启动顺序、配置服务间网络与数据持久化、区分开发与生产配置、排查容器网络与启动问题的开发者。
限制
资料未提供关于平台支持范围、版本兼容性、收费或许可的说明。