DockerCompose怎么执行python脚本服务

洛溪
洛溪
发布时间:2026-11-19 | 9人浏览过
原创

详细讲解如何使用 Docker Compose 执行 Python 脚本服务,包括常驻后台脚本服务与一次性批处理任务的完整配置、Dockerfile 编写、输出无缓冲设置、代码热重载与信号处理机制。

使用 Docker Compose 执行 Python 脚本服务,核心在于把 Python 脚本运行所需的解释器环境、依赖包和工程文件打包为容器服务,并通过 docker compose up -d 将其作为常驻服务在后台拉起,或者使用 docker compose run 进行一次性调试执行。整个闭环只需要准备三个基础文件:用于定义执行入口与运行环境的 Dockerfile、用于组织卷挂载和环境变量的 docker-compose.yml,以及包含业务执行逻辑的 Python 脚本。
DockerCompose怎么执行python脚本服务
概览:Docker Compose 统一驱动 Python 脚本服务的容器架构与管控链路

一、Docker Compose 执行 Python 脚本的基础机制

在很多初学者的直觉中,Docker 更多被用来运行 Nginx、MySQL 或者 Django、FastAPI 这样的 Web 应用程序。但对于数据抓取、队列消费、周期性数据同步或设备遥测采集这类“纯后台 Python 脚本”,Docker Compose 同样是非常理想的运行载体。

容器启动的本质是执行一个前台主进程。Web 框架之所以能够一直运行,是因为内部内置了持续监听 HTTP 端口的事件循环;而普通 Python 脚本如果执行完最后一行代码,Python 进程便会正常退出(Exit 0),容器也随之停止。因此,要让 Docker Compose 成功执行 Python 脚本服务,通常对应两种具体形态:

  • 常驻守护服务(Continuous Service):脚本内部包含长期运行的事件循环(如 while True 轮询或消息队列消费者),在 Compose 中配置 restart: unless-stopped,由 Docker 负责异常退出后的自愈重启。
  • 按需一次性任务(One-off Task):用于数据库初始化、脚本跑批计算或临时调试,通过 docker compose run --rm 在隔离环境中执行,运行完毕即刻自动销毁容器。
DockerCompose怎么执行python脚本服务
图1:Docker Compose 编排 Python 脚本服务的架构与工作流

二、从零搭建完整的 Python 脚本服务

我们以一个典型的数据定时采集与处理服务为例,演示完整工程的搭建步骤。首先在宿主机上建立一个干净的工程目录,并在其中创建以下四个文件:

python-service/
├── docker-compose.yml   # 编排服务配置
├── Dockerfile           # 镜像构建描述
├── requirements.txt     # Python 依赖清单
└── app.py               # 核心业务脚本

1. 编写业务脚本 app.py

脚本中需要注意两个工程细节:一是定期输出运行日志,便于后续通过 Compose 跟踪进度;二是注册系统信号(SIGTERM),确保在执行 docker compose down 或 stop 时能够妥善释放资源,而不是被强制杀死。

import os
import time
import signal
import sys
from datetime import datetime

# 运行标志位
running = True

def handle_exit(sig, frame):
    global running
    print(f"[{datetime.now()}] 收到停止信号 ({sig}),准备平滑退出...")
    running = False

# 注册容器终止信号 (SIGTERM/SIGINT)
signal.signal(signal.SIGTERM, handle_exit)
signal.signal(signal.SIGINT, handle_exit)

def main():
    service_name = os.getenv("SERVICE_NAME", "Default-Worker")
    interval = int(os.getenv("POLL_INTERVAL", "5"))
    print(f"[{datetime.now()}] 服务 {service_name} 启动成功,检查间隔: {interval}秒")

    step = 1
    while running:
        print(f"[{datetime.now()}] 正在执行第 {step} 次批处理任务...")
        # 此处编写实际的业务逻辑,例如查询数据库、拉取 API 或处理消息
        step += 1
        
        # 拆分 sleep,以便快速响应终止信号
        for _ in range(interval):
            if not running:
                break
            time.sleep(1)

    print(f"[{datetime.now()}] 资源已清理完毕,进程安全退出。")
    sys.exit(0)

if __name__ == "__main__":
    main()

2. 编写依赖清单 requirements.txt

即便脚本暂时只使用了标准库,也建议保留该文件。后续引入 requests、pymongo 或 redis 等三方库时,直接按行添加即可。

# 依赖清单示例(无三方库时可留空或指定基础工具)
requests>=2.31.0

3. 编写 Dockerfile

在构建 Python 脚本镜像时,推荐选用体积小巧且兼顾稳定性的官方 python:3.11-slim 基础镜像。特别关键的一点是设置 ENV PYTHONUNBUFFERED=1,这能彻底禁用 Python 的标准 I/O 缓冲,让控制台实时输出每一条 print 内容。

# 使用官方精简镜像
FROM python:3.11-slim

# 设置工作目录
WORKDIR /app

# 禁用标准输出缓冲,保证 docker compose logs 能即时抓取输出
ENV PYTHONUNBUFFERED=1

# 先复制依赖定义,充分利用 Docker 缓存层
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# 复制脚本源码
COPY . .

# 默认启动命令(推荐使用 Exec 格式的中括号语法)
CMD ["python", "app.py"]

4. 编写 docker-compose.yml

在 docker-compose.yml 中定义我们的 Python 服务节点。通过 volumes 将当前工作目录挂载至容器内的 /app,这样在本地修改脚本文件后无需每次重新构建镜像;通过 environment 注入业务参数。

version: '3.8'

services:
  py-worker:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: python_script_worker
    restart: unless-stopped
    volumes:
      - ./:/app
    environment:
      - SERVICE_NAME=TelemetryCollector
      - POLL_INTERVAL=3
      - PYTHONUNBUFFERED=1
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"
DockerCompose怎么执行python脚本服务
图2:从零配置并运行 Python 脚本服务的四个操作步骤

三、服务的启动、监控与停止操作

完成上述配置后,在包含 docker-compose.yml 的目录下打开终端,执行以下命令进入完整的生命周期操作:

1. 构建镜像并在后台拉起服务

docker compose up -d --build

参数说明:-d 表示后台分离模式(Detached Mode),不会阻塞当前终端;--build 强制触发镜像层重新检查,保证修改过的依赖或 Dockerfile 指令生效。

2. 查看服务运行状态

docker compose ps

此时控制台应输出类似如下的运行状态(示例输出):

NAME                   IMAGE                     COMMAND           SERVICE     STATUS         PORTS
python_script_worker   python-service-py-worker  "python app.py"   py-worker   Up 12 seconds  

3. 实时跟踪脚本输出日志

docker compose logs -f py-worker

参数 -f(follow)会持续监听标准输出,你会看到 app.py 中带有时间戳的循环日志实时刷新(示例输出):

python_script_worker | [2026-11-18 09:25:30.123456] 服务 TelemetryCollector 启动成功,检查间隔: 3秒
python_script_worker | [2026-11-18 09:25:30.124102] 正在执行第 1 次批处理任务...
python_script_worker | [2026-11-18 09:25:33.125890] 正在执行第 2 次批处理任务...
python_script_worker | [2026-11-18 09:25:36.127412] 正在执行第 3 次批处理任务...

4. 平滑停止与注销服务

docker compose stop

Docker 会向容器内进程发送 SIGTERM 信号。由于我们在代码中注册了 handle_exit,Python 脚本会在完成当前这一秒的睡眠后安全退出,控制台通常会在 1 到 2 秒内优雅停止,而不是等待 10 秒超时。如果需要连同虚拟网络一并销毁,可执行 docker compose down。

DockerCompose怎么执行python脚本服务
图3:Python 容器化运行的三大核心底层机制解析

四、关键细节与三个高频陷阱排查

在实际使用 Docker Compose 执行 Python 脚本时,大部分读者遇到“服务不工作”的情况并非 Compose 软件本身损坏,而是以下三个具体机制导致的异常:

陷阱 1:docker compose logs 看不到任何输出,界面一片空白
根本原因:Python 在检测到输出流不是交互式 TTY 终端(即重定向到 Docker 的标准流管道)时,会自动开启块缓冲(Block Buffering,默认 4KB)。只有当缓冲区满或者进程结束时才会一次性冲刷出来。
解决方法:在 Dockerfile 中声明 ENV PYTHONUNBUFFERED=1,或者在 docker-compose.yml 的 environment 节点下显式添加 PYTHONUNBUFFERED: 1。也可以在 command 中指定 python -u app.py。
陷阱 2:容器启动后几秒内自动退出,状态为 Exited (0)
根本原因:脚本只是一段单次执行的过程性代码,执行到底部后进程自然终结。Docker 发现 PID 1 已经终止,按照容器语义直接退出。
解决方法:如果你期望它是长期运行的服务,必须在代码内部加入阻塞机制(如消息消费、调度循环或网络监听);如果该脚本本身就是一次性任务,则不应使用 restart: unless-stopped,而应结合后文介绍的 docker compose run 来执行。
陷阱 3:停止容器时 Docker 卡住 10 秒,最后提示“Kill”
根本原因:Dockerfile 中使用了 Shell 格式命令:CMD python app.py。此时容器内的 PID 1 实际上是 /bin/sh,而系统 shell 默认不会将 SIGTERM 信号向下转发给子进程 Python。Compose 等待 10 秒超时后,不得不升级为不可捕获的 SIGKILL 强制杀进程。
解决方法:改用 Exec 列表格式:CMD ["python", "app.py"],让 Python 解释器直接作为 PID 1 启动。

五、扩展场景:执行一次性任务与多脚本组合

在同一个工程下,除了常驻的后台 Worker 脚本,往往还会有辅助脚本,例如用于初始化数据结构的 init_db.py、一次性跑批的 export_data.py,或者临时排查用的脚本。

1. 使用 docker compose run 执行临时独立脚本

你可以复用已经构建好的 py-worker 服务镜像与网络环境,无需另外声明新容器:

# 临时执行单次数据迁移脚本,运行完后自动清理临时容器
docker compose run --rm py-worker python init_db.py

该命令会基于 py-worker 镜像启动一个独立的临时容器,挂载相同的卷,但使用 python init_db.py 覆盖默认的 app.py 入口,参数 --rm 确保执行完毕后自动删除该容器,不留下任何垃圾容器。

2. 在同一个 compose 文件中配置多个脚本服务

如果同一个系统包含多个独立的 Python 业务脚本(例如一个负责拉取订单,另一个负责生成汇总),可以直接在 services 下定义多个服务节点,彼此共享镜像或代码卷:

version: '3.8'

services:
  # 服务 A:订单同步脚本
  order-sync:
    build: .
    command: ["python", "order_sync.py"]
    restart: unless-stopped
    volumes:
      - ./:/app
    environment:
      - PYTHONUNBUFFERED=1

  # 服务 B:监控报警脚本
  metrics-watcher:
    build: .
    command: ["python", "metrics_watcher.py"]
    restart: unless-stopped
    volumes:
      - ./:/app
    environment:
      - PYTHONUNBUFFERED=1
DockerCompose怎么执行python脚本服务
图4:Docker Compose 运行 Python 脚本的全场景决策与速查总结

六、常用操作指令与参数速查

下表总结了在日常维护和执行 Python 脚本服务时最常使用的 Compose 指令组合:

操作目标 标准执行命令 典型应用场景
全新构建并后台启动 docker compose up -d --build 更新了 requirements.txt 或 Dockerfile 之后首次或迭代部署
实时查看脚本输出 docker compose logs -f <服务名> 观察当前运行状态、业务打印日志或捕获排查异常报错
执行一次性辅助脚本 docker compose run --rm <服务名> python <脚本.py> 执行数据库迁移、冷启动脚本或一次性数据校验导出
重启服务生效代码 docker compose restart <服务名> 在配置了卷挂载的情况下快速重启 Python 脚本进程
进入容器交互式排查 docker compose exec <服务名> /bin/bash 进入运行中的环境,手动验证文件路径或依赖包可用性
停止并清理资源 docker compose down 下线服务,同时注销默认创建的 Docker 桥接虚拟网络

通过遵循上述配置原则:轻量 slim 基础镜像 + PYTHONUNBUFFERED=1 保证无缓冲输出 + Exec 数组格式 CMD 捕获退出信号 + 结合开发态卷挂载,你便可以兼顾开发阶段的热修改灵活性与生产阶段的高可靠守护,稳定自如地在 Docker Compose 中执行各类 Python 脚本服务。

相关专题:

本站声明

本文内容仅供参考,不代表本站观点。转载或引用请注明出处。如发现内容问题,请通过联系我们页面反馈。

Python 相关产品和应用

全部下载

专题列表