GitLab CI中Docker Compose执行报错，如何修复及正确使用？

问题描述 #

在GitLab CI中配置任务运行Docker Compose，CI配置如下：

docker-compose-playgroound:
    stage: docker-compose-playgroound
    image: docker:18
    services:
        - docker:18-dind
    tags:
        - docker-main
    variables:
        DOCKER_TLS_CERTDIR: ""
        DOCKER_HOST: tcp://docker:2375
    script:
        - docker compose -f .gitlab/docker-compose-autotests.yml up

执行后触发报错：

unknown shorthand flag: 'f' in -f
See 'docker --help'.
Usage:    docker [OPTIONS] COMMAND
A self-sufficient runtime for containers
Options: ...

对应的GitLab Runner配置：

[[runners]]
  name = "xxxx"
  url = "https://gitlab.xxxxx/"
  token = "xxx"
  executor = "docker"
  [runners.custom_build_dir]
  [runners.cache]
    [runners.cache.s3]
    [runners.cache.gcs]
    [runners.cache.azure]
  [runners.docker]
    tls_verify = true
    image = "docker:18"
    privileged = false
    disable_entrypoint_overwrite = false
    oom_kill_disable = false
    disable_cache = false
    volumes = ["/home/gitlab-runner/cache"]
    cache_dir = "/home/gitlab-runner/cache"
    shm_size = 0

修复方案及正确配置方式 #

核心问题 #

Docker 18.x版本未集成docker compose子命令（该命令是Docker Compose v2的新格式），当时仅支持独立的docker-compose命令（v1版本）。使用docker compose会被Docker识别为无效命令，进而导致-f参数报错。

具体修复步骤 #

• 替换命令格式：将script中的docker compose改为docker-compose
• 安装docker-compose工具：docker:18基础镜像默认不带该工具，需在执行前安装
• 调整Runner权限：docker-in-dind模式要求Runner开启privileged权限
• （可选）升级Docker版本：若想使用docker compose，需升级到Docker 20.10+版本（默认集成Compose v2）

修复后的CI配置示例

docker-compose-playgroound:
    stage: docker-compose-playgroound
    image: docker:18
    services:
        - docker:18-dind
    tags:
        - docker-main
    variables:
        DOCKER_TLS_CERTDIR: ""
        DOCKER_HOST: tcp://docker:2375
    script:
        - apk add --no-cache docker-compose
        - docker-compose -f .gitlab/docker-compose-autotests.yml up

调整后的Runner配置关键项

[runners.docker]
    # 保留其他原有配置
    privileged = true

（可选）升级到Docker 24.x的CI配置

docker-compose-playgroound:
    stage: docker-compose-playgroound
    image: docker:24
    services:
        - docker:24-dind
    tags:
        - docker-main
    variables:
        DOCKER_TLS_CERTDIR: "/certs"
    script:
        - docker compose -f .gitlab/docker-compose-autotests.yml up

注：升级后建议保留DOCKER_TLS_CERTDIR默认值（开启TLS），无需手动设为空。

内容的提问来源于stack exchange，提问作者Руслан Пилипюк