Compose 项目结构与实践——AI教你学Docker

3.5 Compose 项目结构与实践

在实际多容器项目开发、部署和团队协作中，良好的 Compose 项目结构和管理规范能够大幅提升开发效率、部署一致性与可维护性。下面详细解读 Compose 项目目录规范、与 CI/CD 的集成方式、以及版本管理与团队协作的最佳实践。

一、项目目录规范

1. 推荐目录结构

一个标准的 Docker Compose 项目通常包含如下目录与文件：

project-root/
├── docker-compose.yml           # 主 Compose 配置
├── docker-compose.override.yml  # 本地覆盖配置（如开发环境专用）
├── docker-compose.prod.yml      # 生产环境覆盖配置（可选）
├── .env                         # 环境变量文件（不建议提交敏感内容）
├── services/                    # 各服务源码目录
│   ├── web/
│   │   ├── Dockerfile
│   │   └── ...
│   ├── api/
│   │   ├── Dockerfile
│   │   └── ...
│   └── db/
│       └── ...
├── volumes/                     # 本地挂载（如开发用数据，避免 Git 跟踪）
├── scripts/                     # 辅助脚本（如初始化、备份、CI 脚本等）
├── .dockerignore                # 排除文件列表
├── README.md
└── ...（其他项目文件）

2. 规范说明

• 分服务管理：每个服务一个子目录，源码与 Dockerfile 独立，便于维护与升级。
• 多环境配置：通过 docker-compose.override.yml（开发）和 docker-compose.prod.yml（生产）等多文件组合，实现不同环境下的参数覆盖。
• 环境变量：统一在 .env 文件配置，敏感数据（如密码）可用 .env.example 作为模板，实际敏感变量通过环境下发。
• 脚本归档：初始化、测试、备份、CI 相关脚本统一放在 scripts/ 目录，避免污染主目录。

二、与 CI/CD 集成

1. 典型集成方式

• 自动化测试：在 CI 流水线（如 GitHub Actions、GitLab CI、Jenkins）中，利用 Compose 启动各依赖服务环境，实现端到端集成测试。
• 自动构建与推送镜像：CI 可根据服务目录下的 Dockerfile 构建镜像，并推送到镜像仓库。
• 自动部署：CD 阶段可用 Compose 命令在目标服务器上拉取最新镜像并重启服务。

2. CI/CD 示例（以 GitHub Actions 为例）

# .github/workflows/ci.yml
name: CI

on:
  push:
    branches: [main]

jobs:
  build-and-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: 启动依赖服务
        run: docker compose -f docker-compose.test.yml up -d
      - name: 运行测试
        run: docker compose exec web npm test
      - name: 停止服务
        run: docker compose down

3. 实践建议

• CI 流程建议用单独的 docker-compose.test.yml 或通过 -f 参数临时覆盖配置（如挂载测试数据卷、关闭持久化等）。
• 构建产物（如镜像 tag）建议与代码分支/提交 hash 关联，便于追溯和回滚。

三、版本管理与团队协作

1. 配置文件纳入 Git 管理

• docker-compose.yml、docker-compose.override.yml、.env.example 等配置应纳入版本控制，便于团队成员共享和溯源。
• .env 文件一般不提交，只提供 .env.example 模板。

2. 多环境协作

• 本地开发用 docker-compose.override.yml，开发人员可根据需要定制端口、挂载等。
• 生产环境用 docker-compose.prod.yml，通过 docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d 启动，覆盖敏感配置和生产参数。
• 推荐用分支、环境变量管理多环境差异，避免硬编码环境特有配置。

3. 团队协作建议

• 明确并规范各服务目录结构与命名。
• 沟通并约定 Compose 配置变更流程，避免多人同时修改引发冲突。
• 使用 PR、Code Review 等机制保障配置和脚本安全。
• 为新成员提供完善的 README 和启动脚本，降低上手门槛。
• 定期清理无用数据卷、镜像，保持项目整洁。

四、参考资料

• Compose 项目结构最佳实践
• Docker 官方 Compose 多环境部署建议
• GitHub Actions 官方文档