Docker Compose 怎么用 profile 只启动调试服务

想在同一个 Docker Compose 项目里保留基础服务，又只在排查问题时启动调试容器，最省事的做法是把调试容器放进 debug profile。api、db 这类没有 profiles 的服务始终参与模型；执行 docker compose --profile debug up -d 后，才会额外启动 debug-tools。如果需要切换变量文件，再把 --env-file 放在命令前面，最后用 config 看解析结果。

核心判断是：profile 决定“哪些可选服务进入本次 Compose 模型”，env-file 决定“本次解析使用哪些变量”，--parallel 只控制拉取或构建的并发度，三者不要混为一个开关。

先把基础服务和调试服务分开

在项目目录创建 compose.yaml。这里故意让 api 和 db 没有 profile，让它们成为每次启动的基础；只有 debug-tools 使用 debug。调试服务依赖数据库，因此三者启用时会按依赖关系启动。

services:
  api:
    image: example/api:dev
    ports:
      - "8080:8080"

  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: devpass # 仅用于本地示例，生产环境应改用安全凭据

  debug-tools:
    image: example/debug-tools:dev
    profiles: [debug]
    depends_on:
      - db # 调试工具需要先有数据库服务

按菜单路径或命令启用 debug

在 Docker Desktop 中打开 Containers，选择当前 Compose 项目后，先确认服务列表只有基础服务。回到项目目录执行下面的命令；Compose 会启用 debug，并把没有 profile 的服务一并启动。

# 进入包含 compose.yaml 的项目目录
cd compose-lab

# 只额外启用 debug profile，-d 让服务在后台运行
docker compose --profile debug up -d

# 观察本次项目中实际运行的服务
docker compose ps

成功时，Docker Desktop 的项目详情会同时出现 api、db 和 debug-tools；如果只执行 docker compose up -d，则不会自动启动带 profile 的调试服务。需要单独运行一个显式目标时，也可以直接指定服务名，但它的依赖仍要满足 profile 条件。

用 env-file 固定调试环境并核对解析模型

如果开发、测试有不同变量，不要反复改 Compose 文件。创建 config/.env.dev：

# 让 Compose 本次默认启用 debug profile
COMPOSE_PROFILES=debug
IMAGE_TAG=dev

用 --env-file 指定它，并在启动前先看模型：

# --env-file 的路径相对当前执行目录
docker compose --env-file ./config/.env.dev config

# 确认解析无误后再启动，变量文件同时提供 COMPOSE_PROFILES
docker compose --env-file ./config/.env.dev up -d

这里的 config 很重要：它打印的是 Compose 解析后的模型，可用于确认调试服务是否出现、镜像标签是否为 dev。若 shell 里也设置了同名变量，优先级会影响结果；必要时用 docker compose config --environment 查看 Compose 用到的变量。

拉取镜像时限制并发，完成后按 profile 清理

profile 解决的是服务选择，不负责限制镜像下载速度。需要降低本机或内网仓库压力时，使用全局选项 --parallel：

# 每次只发起一个可并行的引擎调用，便于低带宽环境拉取
docker compose --env-file ./config/.env.dev --parallel 1 pull

# 调试结束后清理本次启用的基础和 debug 服务
docker compose --env-file ./config/.env.dev down

--parallel 1 不会改变 profile，也不会让服务变成串行启动规则；它只控制并发引擎调用。清理时保留同一个 env-file，能避免项目名或变量路径切换导致“看起来没删干净”。

常见问题

为什么普通 up 看不到 debug-tools？

因为它带有 profiles: [debug]。请在命令前加 --profile debug，或通过 COMPOSE_PROFILES=debug 启用。

env-file 能直接替代 compose.yaml 吗？

不能。它主要为 Compose 文件插值提供变量，也可以设置 Compose 的预定义变量；服务和依赖关系仍然写在 Compose 文件中。

为什么启用 debug 后仍然报依赖错误？

检查调试服务的 depends_on 服务是否也被 profile 限制。如果依赖服务带了不同 profile，需让两者共享 profile，或让依赖服务不绑定 profile。

如何确认当前到底启用了哪些服务？

先运行 docker compose config 看解析模型，再运行 docker compose ps 看实际容器状态；不要只凭 Docker Desktop 列表猜测。