用途
Docker Compose 技能用于指导编写生产级的 Docker Compose 配置，面向多容器应用的编排。当用户提到 docker compose、docker-compose.yml、compose 文件、compose 怎么写、compose 配置、多容器、multi-container、服务编排、depends_on、profiles、override、compose network、compose volume 等关键词时，应使用该技能。
主要能力
完整文件结构
compose.yml 的顶层结构包括：
- name：项目名称
- services：容器定义
- networks：网络拓扑
- volumes：持久化存储
- secrets：敏感数据（Swarm）
- configs：非敏感配置（Swarm）
服务核心配置
services 下可配置：
- image：从镜像仓库拉取，如 myapp:${TAG:-latest}
- build：从 Dockerfile 构建，可指定 context 与 dockerfile
- container_name：显式容器名（可选）
- hostname：主机名
- ports：端口映射，支持 host:container、绑定到 localhost（如 127.0.0.1:8443:443）、UDP（如 8080:8080/udp）
- environment：环境变量，服务名即主机名
- env_file：从文件加载环境变量
- volumes：命名卷、只读绑定挂载（:ro）、读写绑定挂载
- depends_on：依赖控制，可配合 condition: service_healthy 或 service_started
- healthcheck：健康检查，含 test、interval、timeout、retries、start_period
- restart：重启策略，如 unless-stopped
- deploy：仅 Swarm 使用，含 replicas、resources.limits（cpus、memory）
- profiles：可选服务标记
网络
- 默认网络：Compose 自动创建默认 bridge 网络，所有服务可通过服务名互相访问。未暴露端口的服务仅能被其他服务访问。
- 自定义网络：可定义 frontend（对外）与 backend（internal: true，禁止外部访问），服务可加入多个网络，实现隔离。
环境变量
三种方式：
- environment：写在 compose.yml 中，适合简单、少量变量
- env_file：外部文件如 .env.production，适合大量变量、区分环境
- .env 文件：项目根目录自动加载，用于默认值与 $VARIABLE 替换
.env 示例：TAG=v1.2.3、DB_PASSWORD=secret123，在 compose.yml 中通过 ${TAG:-latest}、${DB_PASSWORD} 引用。
依赖与启动顺序
depends_on 可指定 condition：service_healthy（等待健康检查通过）或 service_started（等待启动）。配合 healthcheck 使用，例如 db 服务使用 pg_isready 检查。
Profiles 可选服务
通过 profiles 标记可选服务，如 debug-tools 标记 [debug]、elasticsearch 标记 [analytics]，仅在 docker compose --profile debug up 时启动。
多环境 Override
- compose.yml：基础配置
- compose.override.yml：本地开发覆盖（自动应用）
- compose.prod.yml：生产覆盖
本地使用 docker compose up -d 自动合并 override；生产使用 docker compose -f compose.yml -f compose.prod.yml up -d 显式指定。
迁移到 Kubernetes
使用 kompose convert -f compose.yml 生成 K8s YAML，再 kubectl apply -f .
使用方式（推荐编排流程）
- 规划服务：列出所有服务、端口、数据卷、环境变量
- 编写 compose.yml：定义 services/networks/volumes
- 配置依赖：depends_on + condition: service_healthy
- 本地验证：docker compose up -d → docker compose ps → docker compose logs
- 生产部署：添加资源限制、重启策略、日志轮转 → docker compose -f compose.yml -f compose.prod.yml up -d
常见陷阱
- depends_on 无 healthcheck：depends_on 只等待容器启动，不等待就绪。应添加 condition: service_healthy 与 healthcheck 块，并用 docker compose ps 验证健康状态。
- 端口冲突：多个服务不能绑定同一主机端口。应使用不同主机端口，或对仅内部访问的服务移除 ports（通过服务名通信）。
- 绑定挂载路径：相对路径基于 compose 文件所在位置解析。应使用 ./config 而非 config/，并用 docker compose config 验证解析路径。
- .env 文件安全：.env 常含密钥。应将 .env 加入 .gitignore，Swarm 使用 Docker secrets，使用 .env.example 存放占位值。
- docker compose 与 docker-compose：现代语法为 docker compose（插件），docker-compose（独立二进制）已弃用，应始终使用带空格的 docker compose。
适用场景与限制
能做：
- 多容器应用编排：services/networks/volumes/secrets/configs 完整定义
- 环境管理：.env / env_file / override 文件策略
- 依赖控制：depends_on + healthcheck + profiles
需条件：
- 多主机部署：需迁移到 Swarm（docker stack deploy）或 K8s
- 滚动更新/自动扩缩：Compose 不支持，需 Swarm 或 K8s
超范围：
- 编写 Dockerfile：使用 docker-dockerfile
- K8s 部署：使用 kompose convert + K8s 技能
- 云服务编排（Terraform）：IaaC 工具
不适用场景：单容器应用（用 docker-run）、编写 Dockerfile（用 docker-dockerfile）、Kubernetes 部署（用 K8s manifests / Helm charts）、Docker 基础（用 docker-basics）。
安全与稳定性建议
- 后端网络使用 internal: true 防止外部访问
- 不要提交含密钥的 .env 文件，使用 CI secrets 或 Docker Swarm secrets
- 单主机生产 Compose：结合 systemd 实现开机自启
- 多主机生产：迁移到 Swarm（docker stack deploy）或 Kubernetes
官方文档参考
- Docker Compose 概述：https://docs.docker.com/compose/
- Compose 文件参考：https://docs.docker.com/reference/compose-file/
- Compose CLI：https://docs.docker.com/reference/cli/docker/compose/
- 环境变量：https://docs.docker.com/compose/environment-variables/
- Compose 网络：https://docs.docker.com/compose/networking/
- 生产环境 Compose：https://docs.docker.com/compose/production/