GitLab CI 中使用 Docker Compose 的核心前提是 Runner 必须能执行 docker-compose 命令且底层 Docker 守护进程可用，需运行在支持 Docker 的宿主机上（如 docker 或 shell executor），预装 docker-compose（v2.2+ 推荐），并正确配置权限与 socket 挂载。
GitLab CI 中使用 Docker Compose 的核心前提是：Runner 必须能执行 docker-compose 命令，且底层 Docker 守护进程可用。这通常意味着 Runner 需运行在支持 Docker 的宿主机上（如 docker 或 shell executor），并已预装 docker-compose（v2.2+ 推荐）。
确保 Runner 环境支持 Docker 和 docker-compose
Shell 或 Docker 类型的 Runner 可直接调用本地 Docker 服务。若使用 docker executor，需启用 privileged: true 并挂载宿主机 Docker socket（/var/run/docker.sock），否则容器内无法访问 Docker daemon。
- 检查 Runner 主机是否已安装
docker和docker-compose：运行which docker docker-compose - 确认
docker-compose在 PATH 中，或在.gitlab-ci.yml中指定完整路径（如/usr/local/bin/docker-compose） - 若用 shared runner，建议自建专用 Runner 并配置为
shellexecutor，避免权限和资源隔离问题
在 .gitlab-ci.yml 中调用 docker-compose
只需把 docker-compose 当作普通命令写入 job script。常见用途包括启动测试环境、运行集成测试、构建多服务镜像等。
- 将
docker-compose.yml放在项目根目录或指定路径，CI 中通过-f参数指定 - 使用
--project-directory显式设置工作目录，避免路径错误 - 推荐使用
docker-compose --no-ansi避免 ANSI 控制符干扰日志解析 - 示例片段：
script:- docker-compose -f docker-compose.test.yml --project-directory . up -d- sleep 10- curl -f http://localhost:8080/health || exit 1- docker-compose -f docker-compose.test.yml down
构建镜像并推送到仓库（配合 CI 流程）
当 docker-compose.yml 中服务定义了 build: 节点，CI 可直接构建并打 tag，无需额外写 docker build 命令。
- 确保
docker-compose build在 CI 中可执行（依赖 Docker daemon） - 使用
--build-arg传参（如COMMIT_SHA）给 Dockerfile - 构建后用
docker-compose push推送所有服务镜像（需提前docker login） - 注意：推送前应设好镜像名前缀（如
registry.example.com/myapp），并在 compose 文件中用image:显式声明
安全与调试建议
避免在 CI 中暴露敏感信息，同时提升可维护性。
- 不要在
docker-compose.yml中硬编码密码；改用env_file:或 CI 变量（$CI_REGISTRY_USER等） - 使用
docker-compose config验证 YAML 语法和变量替换是否正确（适合调试阶段） - 对关键 job 加
interruptible: true，便于手动取消长时间运行的 compose 启动任务 - 若遇到 “Cannot connect to the Docker daemon”，先确认 Runner 是否挂载了
/var/run/docker.sock，再检查用户是否在docker组中
