Docker Compose up偶发“容器名称已被占用”冲突错误求助

问题现象 #

多次执行docker compose up正常，但偶尔触发以下冲突错误：

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

未修改Docker Compose配置或手动启动容器，且仅foo容器频繁出现该问题；移除container_name字段后错误频率降低，但仍偶发，同时存在无配置变更时Compose自动重建容器的情况。

相关配置片段：

foo:
    image: server
    depends_on:
      - broker
      - schema-registry
      - connect
      - redis
    restart: always
    user: root
    environment:
      - SERVER=production
      - NODE_ENV=production
    command:
      - node
      - '--experimental-specifier-resolution=node'
      - '--no-warnings'
      - build/production/foo.js
    volumes:
      - ./env:/usr/src/env
      - ./.env:/usr/src/.env
    deploy:
      resources:
        limits:
          cpus: '1'
          memory: 2G

执行命令：

node ./docker-compose.js | docker compose -f - -p foo --compatibility up -d --remove-orphans

版本信息：

• Docker: v25.0.1
• Docker Compose: v2.23.3

可能原因 #

1. 状态同步延迟：Docker daemon与Compose之间的容器状态同步存在延迟，当Compose尝试重建或启动容器时，旧容器仍处于终止/清理过程中，导致新容器命名冲突。
2. 动态配置不一致：通过node ./docker-compose.js生成的YAML配置存在细微差异（如键顺序、空行、注释变化），触发Compose的容器重建逻辑，重建过程中因并发操作导致命名冲突。
3. 版本已知bug：Docker Compose v2.23.3存在部分容器命名与状态管理的bug，后续版本已修复相关问题。
4. 容器重启机制冲突：restart: always配置导致容器意外重启时，与Compose的容器管理逻辑产生冲突，引发命名重复。

解决方案 #

1. 显式指定容器名并添加前置清理 #

显式配置固定容器名，同时在启动命令前强制清理可能残留的容器：

• 修改配置，添加container_name：

foo:
  container_name: foo-production-service
  # 原有其他配置保持不变

• 修改启动命令：

docker compose -p foo rm -f foo-production-service || true && node ./docker-compose.js | docker compose -f - -p foo --compatibility up -d --remove-orphans

2. 确保动态配置的一致性 #

检查docker-compose.js的输出，确保每次生成的YAML完全一致：

• 使用js-yaml库的dump方法时，指定sortKeys: true，保证键顺序固定：

const yaml = require('js-yaml');
const config = generateConfig(); // 你的配置生成逻辑
console.log(yaml.dump(config, { sortKeys: true }));

• 避免生成随机注释、空行等无关内容，确保配置哈希值稳定，减少无意义的容器重建。

3. 升级Docker Compose版本 #

当前使用的v2.23.3存在部分已知bug，升级到最新稳定版可修复状态同步与命名相关问题：

docker compose upgrade

4. 调整容器重建策略 #

在foo服务配置中添加recreate策略，避免无意义的重建：

foo:
  # 原有配置...
  recreate: never # 仅当配置变更时重建，需根据实际需求调整

或使用recreate: forced配合前置清理，确保重建过程无冲突。

临时应急处理 #

当出现冲突错误时，手动清理冲突容器后重新启动：

docker rm -f e672c49f717291b19dbad4a25a372f96b6af5c7cbe70d50d5f169adf09dcb495
node ./docker-compose.js | docker compose -f - -p foo --compatibility up -d --remove-orphans

内容的提问来源于stack exchange，提问作者Leo Jiang