技术 · 思考 · 实践 · 成长

首页/Docker/正文

Docker 部署 Python 开发环境完全指南:Dockerfile、Compose 与远程调试

Docker12 次阅读

用 Docker 搭 Python 开发环境,核心目标只有三个:依赖一致、环境可重建、和宿主机隔离。本章从零开始,覆盖镜像选型、Dockerfile、Compose、依赖管理、远程调试、数据库依赖和常见坑,最后给一份可直接套用的完整配置。参考:Docker Python 指南。

一、为什么用 Docker 做 Python 开发

  • 依赖一致:Python 版本、系统库、pip 包全部锁在镜像里,不会出现「我这能跑」;
  • 环境可重建:删掉容器重来一遍即可,不污染宿主机;
  • 多版本并存:3.9、3.11、3.12 各跑一个容器,互不干扰;
  • 依赖服务一键起:PostgreSQL、Redis、RabbitMQ 用 Compose 一起拉起;
  • 贴近生产:开发用的镜像和线上镜像可以共用同一份 Dockerfile。

二、三种方案怎么选

方案做法适合
官方镜像 + 挂载代码docker run -v $PWD:/app python:3.12临时脚本、快速验证
自建 Dockerfile写依赖、系统包、用户,docker build正式项目、团队协作
Dev ContainersVS Code 连接容器开发需要 IDE 补全、调试、终端一体化

实际项目推荐「自建 Dockerfile + Compose 编排 + Dev Containers 接入」组合。

三、项目结构

myproject/
├─ app/
│  ├─ __init__.py
│  ├─ main.py
│  └─ settings.py
├─ tests/
│  └─ test_main.py
├─ requirements.txt
├─ Dockerfile
├─ docker-compose.yml
├─ .dockerignore
└─ .devcontainer/
   └─ devcontainer.json

四、编写开发用 Dockerfile

FROM python:3.12-slim

# 基础环境变量
ENV PYTHONDONTWRITEBYTECODE=1 \
    PYTHONUNBUFFERED=1 \
    PIP_NO_CACHE_DIR=1 \
    TZ=Asia/Shanghai

WORKDIR /app

# 换国内 apt 源并安装系统依赖(编译型包需要 build-essential)
RUN sed -i 's@deb.debian.org@mirrors.aliyun.com@g' /etc/apt/sources.list.d/debian.sources \
    && apt-get update \
    && apt-get install -y --no-install-recommends \
       build-essential libpq-dev curl git tzdata \
    && rm -rf /var/lib/apt/lists/*

# 先拷依赖清单,利用层缓存
COPY requirements.txt .
RUN pip install -i https://pypi.tuna.tsinghua.edu.cn/simple -r requirements.txt

# 再拷源码
COPY . .

# 非 root 用户运行
RUN useradd -m -u 1000 dev && chown -R dev:dev /app
USER dev

CMD ["python", "-m", "app"]

几个关键点:

  • PYTHONUNBUFFERED=1 让日志实时输出,不会卡在缓冲区;
  • PYTHONDONTWRITEBYTECODE=1 避免容器里到处是 __pycache__;
  • 先 COPY requirements.txt 再安装依赖,改代码不会触发重装;
  • 用非 root 用户运行,挂载目录权限也更可控。

五、docker-compose 开发编排

services:
  app:
    build: .
    command: python -m app
    volumes:
      - .:/app
    ports:
      - "8000:8000"
      - "5678:5678"        # debugpy
    environment:
      - DATABASE_URL=postgresql://app:app@db:5432/app
      - REDIS_URL=redis://redis:6379/0
      - PYTHONPATH=/app
    depends_on:
      - db
      - redis
    tty: true

  db:
    image: postgres:16
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: app
      POSTGRES_DB: app
    volumes:
      - pgdata:/var/lib/postgresql/data
    ports:
      - "5432:5432"

  redis:
    image: redis:7
    ports:
      - "6379:6379"

volumes:
  pgdata:
docker compose up -d --build
docker compose exec app bash
docker compose logs -f app
docker compose down

volumes: .:/app 让宿主机改代码立即生效;depends_on 只保证启动顺序,不保证服务就绪,应用里最好加重试。

六、依赖管理

1. requirements.txt

fastapi==0.115.0
uvicorn[standard]==0.30.6
psycopg[binary]==3.2.3
redis==5.2.0
pytest==8.3.4
debugpy==1.8.8

2. pyproject.toml + uv

COPY pyproject.toml uv.lock ./
RUN pip install uv \
    && uv sync --frozen

3. 分层缓存技巧

依赖文件不变就不重装;可以用「先装基础依赖,再装开发依赖」拆成两个文件:

requirements.txt        # 运行时依赖
requirements-dev.txt    # 测试、调试、格式化工具

七、常用开发工具

1. 交互式 Shell

docker compose exec app python
docker compose exec app ipython

2. 测试与格式化

docker compose exec app pytest -q
docker compose exec app ruff check .
docker compose exec app black .

3. 远程调试(debugpy)

RUN pip install debugpy
docker compose exec app \
  python -m debugpy --listen 0.0.0.0:5678 --wait-for-client -m app

VS Code 的 launch.json 配置:

{
  "name": "Attach to Docker",
  "type": "debugpy",
  "request": "attach",
  "connect": { "host": "127.0.0.1", "port": 5678 },
  "pathMappings": [
    { "localRoot": "${workspaceFolder}", "remoteRoot": "/app" }
  ]
}

八、Dev Containers(VS Code)

{
  "name": "python-dev",
  "dockerComposeFile": "../docker-compose.yml",
  "service": "app",
  "workspaceFolder": "/app",
  "customizations": {
    "vscode": {
      "extensions": [
        "ms-python.python",
        "ms-python.vscode-pylance",
        "charliermarsh.ruff"
      ]
    }
  }
}

用 VS Code 的「Reopen in Container」打开项目,终端、调试、补全全部在容器里,宿主机不需要装 Python。

PyCharm 则可以在「Interpreter → Docker Compose」里指定 service,自动识别容器内的解释器。

九、数据库与缓存的初始化

# initdb/001-init.sql
CREATE TABLE IF NOT EXISTS users (
  id SERIAL PRIMARY KEY,
  name TEXT NOT NULL
);
  db:
    image: postgres:16
    volumes:
      - pgdata:/var/lib/postgresql/data
      - ./initdb:/docker-entrypoint-initdb.d:ro

放在 /docker-entrypoint-initdb.d 下的 .sql、.sh 会在数据库首次初始化时执行。

十、Jupyter Notebook 场景

docker run -d --name jupyter \
  -p 8888:8888 \
  -v $PWD:/home/jovyan/work \
  jupyter/scipy-notebook:latest
docker logs jupyter | grep token

需要固定密码时,用 jupyter server password 生成配置后挂载到容器。

十一、生产与开发的差异

维度开发生产
启动命令python -m app / debugpygunicorn / uvicorn --workers
代码挂载宿主机目录打进镜像
调试工具包含 pytest、debugpy不安装
用户root 或 dev 均可非 root
镜像体积不敏感多阶段构建、slim/alpine
# 生产阶段示例
FROM python:3.12-slim AS runtime
WORKDIR /app
COPY --from=builder /usr/local/lib/python3.12/site-packages /usr/local/lib/python3.12/site-packages
COPY --from=builder /usr/local/bin /usr/local/bin
COPY . .
USER 1000
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

十二、常见问题

  • pip 安装慢:在 Dockerfile 里指定清华/阿里源,或配置全局 pip.conf;
  • 时区不对:设置 TZ=Asia/Shanghai 并安装 tzdata;
  • 挂载目录权限:容器内 UID 与宿主机不一致,用 useradd -u 1000 对齐,或构建时传 --build-arg UID=$(id -u);
  • 改代码不生效:确认 volumes 挂的是源码目录,且应用支持热重载;
  • 文件监听失效:挂载卷上的 inotify 可能不工作,改用 polling 模式(如 uvicorn --reload 配合 watchdog);
  • Apple Silicon 拉 amd64 镜像:加 --platform linux/amd64,或改用 arm64 版本;
  • 容器访问宿主机服务:Linux 用宿主 IP 或 host-gateway,Docker Desktop 用 host.docker.internal;
  • 端口被占用:改宿主机端口,如 8001:8000;
  • 镜像越来越大:清理 apt 缓存、用 --no-install-recommends、多阶段构建、.dockerignore 排除无关文件。

十三、完整可运行的最小配置

# .dockerignore
.git
__pycache__
*.pyc
.venv
.env
node_modules
docker compose up -d --build
docker compose exec app python -c "import sys; print(sys.version)"
curl -I http://127.0.0.1:8000

到这里,一个「代码热更新 + 依赖固定 + 数据库/Redis 就绪 + 可远程调试」的 Python 开发环境就跑起来了。

十四、总结

用 python:3.12-slim 做基础镜像,先装系统依赖、再装 pip 依赖、最后拷源码;Compose 挂载代码并编排数据库与缓存;用 debugpy 或 Dev Containers 接入 IDE;开发与生产分离,生产用多阶段构建和非 root 运行。

无论人生上到哪一层台阶,阶下有人在仰望你,阶上亦有人在俯视你,你抬头自卑,低头自得,唯有平视,才能看见真实的自己。

评论交流

0 条评论 · 支持多级回复
验证码
暂无评论,来说说你的想法吧

相关文章

继续阅读