Docker Compose run 怎样执行一次性任务

如果只是想在 Compose 已有的服务环境里跑一次数据库迁移、测试命令或管理脚本，不必修改服务的长期启动命令。使用 docker compose run 服务名 命令 即可创建一次性容器；配合 --rm，任务结束后还能自动清理。它适合短任务，不等于启动整套服务。

官方地址：https://docs.docker.com/reference/cli/docker/compose/run/

先记住三个边界：run 创建一次性容器并覆盖服务命令，up 用来启动编排中的长期服务，exec 则是在已经运行的容器里执行命令。

• 一次性迁移、测试、初始化：优先使用 run。
• 需要服务持续运行：使用 up。
• 进入现有运行容器排查：使用 exec。

先从服务定义派生一次性任务

假设 compose.yaml 中已经有名为 web 的服务。下面的命令会复用该服务的镜像、卷和网络等配置，但把服务原本的默认命令替换成一次性命令：

# 使用 web 服务的运行环境执行一次测试命令
docker compose run --rm web python manage.py check

# 使用同一服务环境执行数据库迁移
docker compose run --rm web python manage.py migrate

这里的 web 是 Compose 服务名，不是容器名；最后的命令只对这次任务生效，不会永久改写服务定义。--rm 表示命令退出后删除由 run 创建的临时容器，适合测试和迁移这类不需要保留容器的工作。

按任务决定依赖和端口

run 默认可能启动服务依赖。如果只想使用当前服务的镜像执行一个不依赖其他服务的脚本，可以加 --no-deps：

# 只创建 web 的一次性任务，不主动启动它声明的依赖服务
docker compose run --rm --no-deps web python scripts/export.py

需要注意，run 默认不会创建服务定义中的端口映射，这是为了避免一次性任务与已运行服务争抢端口。如果这次命令确实要通过服务端口访问应用，再显式加上 --service-ports：

# 让一次性容器使用 web 服务定义的端口映射
docker compose run --rm --service-ports web python scripts/smoke_test.py

端口是否需要打开取决于任务本身：纯迁移通常不需要，端到端冒烟测试可能需要。不要把 --service-ports 当作默认开关。

执行结束后怎样确认任务行为

一次性任务完成后，先看命令退出状态，再确认临时容器是否按预期清理。把命令写进脚本时，可以保留明确的失败处理：

# 任务失败时立即停止后续步骤，避免把失败误报成成功
set -e

# --rm 负责清理临时容器，退出码仍由任务命令返回
docker compose run --rm web python manage.py migrate

# 只有上一条成功，才继续启动长期服务
docker compose up -d web

如果需要查看任务容器的输出，应在命令执行时直接保留终端日志；如果需要反复进入一个已经运行的服务，应改用 docker compose exec web sh。如果希望让任务容器保留以便稍后检查，则先去掉 --rm，确认完成后再用 Compose 的容器清理命令处理。

run、up、exec 的快速选择

最容易出错的是把 run 当成“启动服务的另一种写法”。如果目标是跑一次命令，就用 run --rm；如果目标是让服务长期提供端口，就用 up -d；如果容器已经在运行，只需临时检查，就用 exec。

常见问题

为什么 docker compose run 后访问不到服务端口？

因为 run 默认不创建服务定义中的端口映射。需要端口时使用 --service-ports，或者把长期服务交给 up。

什么时候应该加 --no-deps？

当一次性命令只依赖当前服务的镜像、文件或卷，不需要 Compose 自动启动依赖服务时使用；如果脚本必须访问数据库或缓存，就不要为了省步骤强行加它。