远程Docker主机下用BuildKit执行Docker Compose构建遇网络及容器冲突

问题概述 #

在GitLab CI环境中开发应用，构建阶段需要访问部署在外部Docker网络中的Strapi实例。禁用BuildKit（DOCKER_BUILDKIT=0）时，docker compose build能正常运行；但启用BuildKit后执行该命令时，出现容器名冲突错误，BuildKit陷入异常：

Error response from daemon: Conflict. The container name "/buildx_buildkit_www-builder0" is already in use by container "8791d0757fce91ae84f600df2927fae2b0033458721cbaae0823123548cfa067". You have to remove (or rename) that container to be able to reuse that name.

核心原因 #

1. 手动创建了名为www-builder的buildx构建器，但docker compose build默认会尝试启动独立的BuildKit容器，两者名称冲突
2. BuildKit容器默认未加入目标外部网络，导致构建阶段无法访问Strapi实例
3. 未明确指定docker compose使用已创建的buildx构建器，引发重复容器创建

解决方案 #

1. 清理残留冲突容器 #

在CI步骤开头添加清理命令，避免旧容器干扰：

- docker rm -f buildx_buildkit_www-builder0 || true

2. 修改CI配置，确保compose使用指定构建器并配置网络 #

调整后的CI脚本：

- docker context create remote_dev_server --docker "host=ssh://$DEV_SERVER_USER@$DEV_SERVER_IP"
- docker context use remote_dev_server
# 清理旧容器
- docker rm -f buildx_buildkit_www-builder0 || true
# 创建buildx构建器，指定网络并启用
- docker buildx create --name www-builder --driver docker-container --driver-opt "network=${NETWORK_NAME}" --platform linux/amd64,linux/386 --use
# 强制初始化构建器容器
- echo "FROM scratch" | docker buildx build -
# 启用Compose BuildKit并执行构建
- COMPOSE_BUILDKIT=1 docker compose build
- docker compose push

3. 确认Docker Compose配置有效性 #

确保Compose文件中build.network配置指向正确的外部网络，且环境变量NETWORK_NAME在CI环境中正确传递：

version: '3.8'
services:
  app-static:
    image: ${IMAGE_APP_TAG_STATIC}
    build:
      dockerfile: ./Dockerfile.static
      network: ${NETWORK_NAME}
      args:
        PORT: ${PORT}
        STRAPI_URL: ${STRAPI_URL}
        STATIC_PAGE: true
    env_file: .env
    deploy:
      restart_policy:
        condition: on-failure
    networks:
      - ansible-controlled-network
  app-ssr:
    image: ${IMAGE_APP_TAG_SSR}
    build:
      dockerfile: ./Dockerfile.ssr
      network: ${NETWORK_NAME}
      args:
        PORT: ${PORT}
        STRAPI_URL: ${STRAPI_URL}
        STATIC_PAGE: false
    env_file: .env
    deploy:
      restart_policy:
        condition: on-failure
    networks:
      - ansible-controlled-network
networks:
  ansible-controlled-network:
    name: ${NETWORK_NAME}
    external: true

关键说明 #

• 禁用BuildKit时，Docker使用传统构建流程，直接复用宿主或指定的外部网络，无需创建额外BuildKit容器，因此能正常访问Strapi
• 启用BuildKit后，必须确保BuildKit容器本身加入目标外部网络，同时让docker compose明确使用已创建的构建器，避免重复创建容器引发冲突

内容的提问来源于stack exchange，提问作者Taavi Ansper