当前位置：首页 > 文章列表 > 文章 > 软件教程 > Docker Compose 怎么用 profile 只启动调试服务

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

来源：17golang原创 2026-09-08 05:08:24 0浏览收藏

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

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

要点速览

基础服务不要写 profile，调试服务写 profiles: [debug]。
命令行可用 --profile debug，也可在环境文件中设置 COMPOSE_PROFILES=debug。
用 config 检查服务集合，用 --parallel 1 pull 控制镜像拉取并发。

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

在项目目录创建 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 # 调试工具需要先有数据库服务

图1：项目入口状态显示基础服务与 debug 可选服务的边界。

按菜单路径或命令启用 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 条件。

图2：启用 debug 后，项目详情中的调试服务与数据库依赖已进入运行状态。

用 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 用到的变量。

图3：在配置核对状态中确认 env-file、profile 和解析后的服务集合一致。

拉取镜像时限制并发，完成后按 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，能避免项目名或变量路径切换导致“看起来没删干净”。