Docker Compose的项目命名机制

发表于 更新于 分类于
Docker Compose的项目命名机制

前言

当两个全路径不同但上层文件夹名称相同的 docker-compose.yml 同时启动时，出现服务错乱（例如服务被意外重启、替换或无法同时运行），其根本原因在于 Docker Compose 的项目命名机制。

项目名冲突

Docker Compose 默认会使用启动配置文件所在目录的最底层子目录名称作为项目的标识前缀（即 com.docker.compose.project 标签）。

例如，以下两个配置文件：

  • /data1/app/docker-compose.yml
  • /data2/app/docker-compose.yml

它们所在目录的最底层子目录都是 app，因此 Docker Compose 会认为这两个配置属于同一个项目。

在底层机制中：

  1. 容器名冲突与覆盖：Docker 默认基于“项目名 + 服务名 + 序号”生成容器名称（如 app_db_1）。

    当两个同名项目启动时，会生成完全相同的容器名，触发冲突或导致一个项目把另一个项目的容器强行停止/替换。

  2. 网络与卷隔离失效：由于被视为同一项目，两个环境可能会意外共享同一个默认的桥接网络（Bridge Network）或命名卷（Named Volume），从而导致数据混用、DNS解析错误或端口占用。

解决方案

要彻底解决这种跨路径的服务错乱问题，您可以根据实际情况选择以下几种方法：

指定项目名

使用 -p 参数手动指定项目名（推荐）

在执行 docker-compose up 时，使用 -p (project) 参数为每个服务显式指定一个唯一的项目名称，强制 Docker 将它们视为独立的环境：

1
2
3
4
5
# 在 /data1/app/ 目录下执行
docker-compose -f ./docker-compose.yml -p app_project1 up -d

# 在 /data2/app/ 目录下执行
docker-compose -f ./docker-compose.yml -p app_project2 up -d

调整目录结构

从规范化管理的角度出发，将包含 docker-compose.yml 的文件夹重命名，确保每个项目的最底层目录名称全局唯一。

例如将其调整为：

  • /data1/app-old/docker-compose.yml
  • /data2/app-new/docker-compose.yml

通过环境变量设置项目名

如果您习惯使用脚本或 CI/CD 流程部署，可以在执行命令前设置环境变量 COMPOSE_PROJECT_NAME：

1
2
export COMPOSE_PROJECT_NAME=unique_project_name
docker-compose up -d

注意

⚠️ 重要避坑提醒：

避免中途更改项目名

如果您之前已经以“裸奔”方式（未加 -p 参数）启动了服务，后来突然加上 -p 参数重新启动，Docker 会认为这是一个全新的项目。

这会导致：

  • 旧项目的容器变成孤立状态（Orphan containers）。
  • 新项目的数据卷和网络是全新的，导致旧数据“凭空消失”（实际上还在旧卷中）。

补救措施： 如果已经发生了这种情况，可以使用 --remove-orphans 参数清理残留的旧容器；或者通过 docker volume ls 找到旧的卷并将数据迁移到新卷中。

建议

所有使用Docker Compose启动的脚本都放在相同的文件夹下，如/data/tools/docker-compose-root

下面再是项目名/docker-compose.yml

例如

  • xhzy-api/docker-compose.yml
  • xhzy-fileapi/docker-compose.yml