Python 与 Docker 结合：从入门到实践，容器化部署 Python 应用全攻略

1次阅读

共计 8193 个字符，预计需要花费 21 分钟才能阅读完成。

在当今快节奏的软件开发领域，如何确保应用在不同环境中的一致性、可移植性和高效部署，是每一位开发者和运维工程师面临的重要挑战。传统的部署方式常常伴随着“在我的机器上能跑”的尴尬局面，而依赖问题、环境配置差异更是家常便饭。幸运的是，容器化技术——尤其是 Docker 的出现，彻底改变了这一现状。当强大的 Python 编程语言与 Docker 的容器魔力相结合时，我们便拥有了一个能够彻底解决这些痛点的强大工具链。

本文将作为一份详尽的教程，带领您深入探索 Python 与 Docker 的融合之道。我们将从基础概念讲起，手把手教您如何将一个 Python 应用容器化，并通过 Docker Compose 管理多服务应用，最终触及一些高级技巧和最佳实践，让您的 Python 应用部署变得前所未甲的简单、高效和可靠。

在深入实践之前，我们先来理解为什么 Python 与 Docker 的结合如此具有吸引力：

环境一致性与隔离性：Docker 容器为 Python 应用提供了一个独立、隔离的运行环境。这意味着无论您的开发机、测试服务器还是生产环境，Python 应用及其所有依赖（如特定版本的库、操作系统级别的包）都将运行在完全相同的环境中，彻底解决了“works on my machine”的问题。
依赖管理简化：Python 项目的依赖管理有时会很复杂，特别是当不同项目需要不同版本的库时。Docker 通过将所有依赖打包到镜像中，简化了这一过程，避免了系统级别的依赖冲突。
快速部署与扩展：Docker 镜像一旦构建完成，就可以在任何安装了 Docker 的机器上快速部署。这大大缩短了部署时间，并且利用 Docker 的编排工具（如 Docker Compose、Kubernetes），可以轻松实现应用的水平扩展。
开发与运维协作：容器化为开发和运维团队提供了一个统一的交付物——Docker 镜像。开发者构建镜像，运维团队部署镜像，促进了 DevOps 流程的实施。
资源利用率提升：相比于虚拟机，Docker 容器更加轻量级，启动速度更快，占用的系统资源更少，从而提高了服务器的资源利用率。
微服务架构支持：Docker 是实现微服务架构的理想选择。Python 编写的各个微服务可以独立地打包成 Docker 容器，独立部署、独立扩展，增强了系统的灵活性和可维护性。

在开始本教程之前，请确保您已具备以下条件：

Python 基础知识：了解 Python 编程和包管理（如 pip）。
命令行基础：熟悉基本的终端操作。
Docker Desktop 或 Docker Engine：请访问 Docker 官方网站 (https://www.docker.com/get-started) 下载并安装适用于您操作系统的 Docker 版本。安装完成后，运行 docker --version 和 docker compose version（如果安装了 Docker Compose）检查是否安装成功。

在深入实践之前，我们先快速回顾几个 Docker 的核心概念：

镜像 (Image)：一个只读的模板，包含了运行容器所需的所有文件系统、代码、库、环境变量和配置。可以理解为容器的“蓝图”。
容器 (Container)：镜像的运行实例。每个容器都是一个独立的、隔离的进程，拥有自己的文件系统、网络接口和进程空间。
Dockerfile：一个文本文件，包含了一系列指令，用于自动化构建 Docker 镜像。
Docker Hub：一个官方的 Docker 镜像仓库，您可以在其中找到各种官方和社区维护的镜像，也可以上传自己的镜像。
Docker Compose：一个用于定义和运行多容器 Docker 应用的工具。通过一个 YAML 文件配置应用的服务，然后通过一个命令启动所有服务。

我们将以一个简单的 Flask Web 应用为例，演示如何将其容器化。

首先，创建一个简单的 Flask 应用。

创建一个名为 python-docker-app 的新目录：
```
mkdir python-docker-app
cd python-docker-app
```

在该目录下创建 app.py 文件：

# app.py
from flask import Flask

app = Flask(__name__)

@app.route('/')
def hello_world():
    return 'Hello from Dockerized Python App!'

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=5000)

这里我们将 host 设置为 0.0.0.0，这是为了让容器外部能够访问到应用。

创建 requirements.txt 文件，列出应用所需的所有 Python 依赖：
```
# requirements.txt
Flask==2.2.2
```
注意：指定明确的版本号是一个好习惯，可以避免未来依赖更新带来的兼容性问题。

Dockerfile 是构建 Docker 镜像的“食谱”。在 python-docker-app 目录下创建 Dockerfile 文件（没有文件后缀名）：

# Dockerfile

# 使用官方 Python 运行时作为父镜像
# 我们选择一个较小的版本，如 python:3.9-slim-buster，以减小镜像大小
FROM python:3.9-slim-buster

# 将工作目录设置为 /app
WORKDIR /app

# 将当前目录下的 requirements.txt 复制到容器的 /app 目录
COPY requirements.txt .

# 在容器中安装 Python 依赖
RUN pip install --no-cache-dir -r requirements.txt

# 将当前目录下的所有文件（包括 app.py）复制到容器的 /app 目录
COPY . .

# 暴露端口 5000，这是 Flask 应用运行的端口
EXPOSE 5000

# 定义容器启动时要执行的命令
# 这里我们使用 gunicorn 来运行 Flask 应用，因为它更适合生产环境
# 如果是简单的开发测试，也可以直接用 python app.py
CMD ["flask", "run", "--host=0.0.0.0", "--port=5000"]
# 或者使用 Gunicorn (更推荐生产环境):
# RUN pip install gunicorn
# CMD ["gunicorn", "-w", "4", "-b", "0.0.0.0:5000", "app:app"]

Dockerfile 详解：

FROM python:3.9-slim-buster：基于 python:3.9-slim-buster 镜像构建。slim-buster 版本比完整版更小，包含了运行 Python 应用所需的最少组件。
WORKDIR /app：设置容器内的工作目录为 /app。后续所有相对路径的命令都将在此目录下执行。
COPY requirements.txt .：将宿主机当前目录下的 requirements.txt 文件复制到容器的 /app 目录。
RUN pip install --no-cache-dir -r requirements.txt：在容器内执行 pip install 命令安装所有依赖。--no-cache-dir 选项可以避免 pip 缓存安装包，进一步减小镜像体积。
COPY . .：将宿主机当前目录下的所有文件（包括 app.py）复制到容器的 /app 目录。
EXPOSE 5000：声明容器的 5000 端口将被暴露。这只是一个文档声明，并不会实际发布端口，端口映射在 docker run 命令中进行。
CMD ["flask", "run", "--host=0.0.0.0", "--port=5000"]：定义容器启动时执行的默认命令。这里启动 Flask 应用。

在 python-docker-app 目录下执行以下命令来构建镜像：

docker build -t python-flask-app .

docker build：构建 Docker 镜像的命令。
-t python-flask-app：为镜像指定一个标签（tag），这里是 python-flask-app:latest（默认 latest）。这个标签可以方便我们识别和引用镜像。
.：表示 Dockerfile 所在的上下文路径，即当前目录。

构建过程可能需要一些时间，取决于您的网络速度和机器性能。成功后，您可以使用 docker images 命令查看已构建的镜像。

docker images

您应该会看到 python-flask-app 镜像在列表中。

现在，我们可以从构建好的镜像启动一个容器：

docker run -p 8000:5000 python-flask-app

docker run：运行 Docker 容器的命令。
-p 8000:5000：这是端口映射。它将宿主机的 8000 端口映射到容器的 5000 端口。这样，当您访问宿主机的 8000 端口时，请求会被转发到容器内部的 Flask 应用。
python-flask-app：指定要运行的镜像名称。

容器启动后，您会在终端看到 Flask 应用的输出信息。现在打开浏览器或使用 curl 访问 http://localhost:8000：

curl http://localhost:8000

您应该会看到输出 Hello from Dockerized Python App!。恭喜您，您的第一个 Python 应用已经成功容器化并运行起来了！

要停止容器，您可以在运行 docker run 的终端按下 Ctrl+C。如果希望在后台运行容器，可以使用 -d 参数（docker run -d -p 8000:5000 python-flask-app），然后通过 docker stop <container-id> 来停止。

在实际开发中，我们的应用通常不止一个服务，可能还会依赖数据库、缓存等。Docker Compose 是一个强大的工具，可以帮助我们定义和运行多容器 Docker 应用。

假设我们的 Flask 应用需要一个 Redis 缓存。

在 python-docker-app 目录下创建 docker-compose.yml 文件：

# docker-compose.yml
version: '3.8' # Docker Compose 文件格式版本

services:
  web: # 定义一个名为 web 的服务
    build: . # web 服务从当前目录的 Dockerfile 构建镜像
    ports:
      - "8000:5000" # 将宿主机的 8000 端口映射到 web 容器的 5000 端口
    volumes:
      - .:/app # 将当前目录（宿主机）挂载到容器的 /app 目录，方便开发时实时更新代码
    depends_on:
      - redis # web 服务依赖于 redis 服务，redis 会在 web 启动前启动

  redis: # 定义一个名为 redis 的服务
    image: "redis:latest" # 使用官方 redis 镜像
    ports:
      - "6379:6379" # 暴露 Redis 默认端口
    volumes:
      - redis-data:/data # 持久化 Redis 数据

volumes:
  redis-data: # 定义一个名为 redis-data 的 Docker 卷用于数据持久化

修改 app.py，使其连接并使用 Redis：

# app.py
from flask import Flask
import redis
import os

app = Flask(__name__)

# 从环境变量获取 Redis 主机名，如果未设置则默认为 'redis'
# 在 Docker Compose 网络中，服务名称可以直接作为主机名使用
redis_host = os.environ.get('REDIS_HOST', 'redis')
r = redis.Redis(host=redis_host, port=6379, decode_responses=True)

@app.route('/')
def hello_world():
    # 尝试增加访问计数
    try:
        visits = r.incr('counter')
        return f'Hello from Dockerized Python App! This page has been visited {visits} times.'
    except Exception as e:
        return f'Error connecting to Redis: {e}'

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=5000)

更新 requirements.txt，添加 redis 库：

# requirements.txt
Flask==2.2.2
redis==4.3.4

现在，使用 Docker Compose 启动整个应用栈：
```
docker compose up -d
```
- docker compose up：启动 docker-compose.yml 中定义的所有服务。
- -d：在后台运行容器。
首次运行 docker compose up 会自动构建 web 服务的镜像并拉取 redis 镜像。
访问 http://localhost:8000，您会看到页面访问次数每次都在增加。这证明您的 Flask 应用成功连接并使用了 Redis 容器。

要停止和移除 Compose 定义的所有服务，可以使用：

docker compose down

多阶段构建允许您在同一个 Dockerfile 中使用多个 FROM 语句。每个 FROM 语句都会开始一个新阶段，并且可以从前一个阶段复制文件。这对于构建环境和运行环境有显著差异的应用非常有用，可以极大地减小最终镜像的大小。

例如，您的 Python 应用可能在构建时需要一些编译工具，但运行生产环境时并不需要。

# Dockerfile (多阶段构建示例)

# 阶段 1: 构建阶段
FROM python:3.9-slim-buster as builder

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# 阶段 2: 运行时阶段
FROM python:3.9-slim-buster

WORKDIR /app

# 从 builder 阶段复制安装好的依赖
COPY --from=builder /usr/local/lib/python3.9/site-packages /usr/local/lib/python3.9/site-packages
COPY . .

EXPOSE 5000
CMD ["flask", "run", "--host=0.0.0.0", "--port=5000"]

在这个例子中，虽然看起来没有明显减小体积，但对于复杂应用（如需要 C 扩展的 Python 库），多阶段构建可以先在第一个阶段安装所有编译工具和依赖，然后只将编译好的结果复制到第二个轻量级镜像中，从而大大减小最终镜像体积。

2. 使用 `.dockerignore`

dockerignore 文件类似于 .gitignore，它告诉 Docker 构建引擎在构建镜像时忽略哪些文件和目录。这有助于避免将不必要的文件（如 .git 目录、.env 文件、本地开发文件等）复制到镜像中，从而减小镜像体积并提高构建速度。

在 python-docker-app 目录下创建 .dockerignore 文件：

.git
.venv
__pycache__
*.pyc
*.log
.DS_Store
Dockerfile
docker-compose.yml

对于数据库等需要持久化存储数据的服务，容器默认的文件系统是非持久化的。一旦容器被删除，数据也会丢失。通过 Docker 的 卷 (Volumes) 可以解决这个问题。在 Docker Compose 示例中，我们已经使用了命名卷 redis-data 来持久化 Redis 数据。

敏感信息（如数据库密码、API 密钥）不应直接硬编码在 Dockerfile 或应用代码中。应通过环境变量传递。

Docker run: 使用 -e KEY=VALUE 参数。

docker run -e MY_VAR=my_value -p 8000:5000 python-flask-app

Docker Compose: 在 docker-compose.yml 中使用 environment 字段。
```
services:
  web:
    environment:
      MY_VAR: "my_value"
      DATABASE_URL: "postgres://user:password@db:5432/mydb"
```
您还可以使用 .env 文件来管理环境变量，并在 docker-compose.yml 中引用它们。

容器内的应用日志应输出到标准输出 (stdout) 或标准错误 (stderr)。Docker 引擎会捕获这些输出，您可以通过 docker logs <container-id> 命令查看。这使得日志收集和集中管理变得非常方便。

在生产环境中，确保容器内的应用确实处于健康状态非常重要。Docker 支持健康检查 (HEALTHCHECK) 指令，可以定期检查容器内服务的健康状况。

# Dockerfile 中添加健康检查示例
HEALTHCHECK --interval=30s --timeout=10s --retries=3 
  CMD curl --fail http://localhost:5000 || exit 1

这会每 30 秒向应用的 5000 端口发送一个 HTTP 请求，如果 10 秒内没有响应或返回非 2xx 状态码，则认为检查失败。连续失败 3 次后，Docker 会将容器标记为不健康。

根据应用需求选择合适的 Python 基础镜像至关重要：

python:3.9：完整版镜像，包含许多开发工具和库，体积较大，适合开发环境。
python:3.9-slim-buster：基于 Debian Buster Slim 版，移除了一些不常用的包，体积中等，适合生产环境。
python:3.9-alpine：基于 Alpine Linux，体积最小，但可能存在一些 C 扩展库兼容性问题，因为 Alpine 使用 musl libc 而非 glibc。如果追求极致小体积，可以尝试，但需测试兼容性。

ModuleNotFoundError：
- 原因：requirements.txt 未包含所有依赖，或者 pip install 命令未正确执行。
- 解决方案：仔细检查 requirements.txt，确保所有依赖都已列出。确保 Dockerfile 中的 RUN pip install 命令在 COPY . . 之前，以利用 Docker 层的缓存。
端口冲突：
- 原因：宿主机上要映射的端口已被其他进程占用。
- 解决方案：更换宿主机映射端口（如 8000:5000 改为 8080:5000），或停止占用端口的进程。
容器内网络问题：
- 原因：应用尝试连接的外部服务或数据库地址不正确。
- 解决方案：在 Docker Compose 网络中，服务名可以直接作为 DNS 名称使用（如 redis 作为 redis 服务的 hostname）。确保 Python 应用使用正确的服务名。
镜像体积过大：
- 原因：使用了不精简的基础镜像、未利用 .dockerignore、未进行多阶段构建。
- 解决方案：使用 slim 或 alpine 基础镜像，配置 .dockerignore，考虑多阶段构建。

通过本文的详细教程，您已经掌握了 Python 应用容器化部署的核心技能。从编写 Dockerfile 到使用 Docker Compose 管理多服务应用，再到探索高级优化技巧，Python 与 Docker 的结合无疑为现代应用开发和部署带来了革命性的变革。

容器化不仅解决了环境依赖的“老大难”问题，还为应用的快速迭代、弹性伸缩和高效运维奠定了坚实基础。现在，您可以自信地将您的 Python 项目打包成轻便、可移植的容器，在任何支持 Docker 的环境中轻松运行。

容器化之旅远不止于此，您可以继续探索 Docker Swarm、Kubernetes 等容器编排工具，将您的容器化应用推向更广阔的生产环境。希望这篇教程能成为您容器化实践的有力起点！

正文完

发表至： Python

近一天内

0

Python基础入门 Day95 正则表达式入门

Playwright：现代 Web 自动化测试的终极方案

Python 高效爬虫实战：requests+BeautifulSoup 避坑与优化全攻略

用 Python 处理 JSON/XML 数据：高效解析与格式转换

Python爬虫进阶：requests与BeautifulSoup高效实践及避坑宝典

Python 与 Docker 结合：从入门到实践，容器化部署 Python 应用全攻略

为什么选择 Python 与 Docker 结合？

前置准备

核心概念速览

容器化部署 Python 应用：一步步实践

步骤 1：准备 Python 应用

步骤 2：编写 Dockerfile

步骤 3：构建 Docker 镜像

步骤 4：运行 Docker 容器

步骤 5：使用 Docker Compose 管理多服务应用

高级技巧与最佳实践

1. 优化 Dockerfile：多阶段构建 (Multi-stage Builds)

2. 使用 `.dockerignore`

3. 持久化数据

4. 环境变量管理

5. 容器日志

6. 健康检查

7. 选择合适的 Python 基础镜像

常见问题与解决方案

总结

Playwright page.goto(url) 详解：深入解析网页导航的最佳实践

如何在安卓 Termux 上安装 qBittorrent

深度解析：基于 PyTorch 实现图像分类——从数据集构建到模型训练部署全攻略

如何在Mac上高效使用Terminal：5个实用命令

如何用 Python 批量重命名文件：一步一步的教程

如何用Python爬虫自动化下载网页数据：从入门到精通

Mac 文件管理技巧：如何利用 Spotlight 快速查找文件

Python 性能优化：提升代码执行效率的五个技巧

如何在 Mac 下使用 Ollama 本地部署 DeepSeek

DeepSeek 系列硬件要求与应用场景：为不同需求选择合适的模型

Python 与 Docker 结合：从入门到实践，容器化部署 Python 应用全攻略

为什么选择 Python 与 Docker 结合？

前置准备

核心概念速览

容器化部署 Python 应用：一步步实践

步骤 1：准备 Python 应用

步骤 2：编写 Dockerfile

步骤 3：构建 Docker 镜像

步骤 4：运行 Docker 容器

步骤 5：使用 Docker Compose 管理多服务应用

高级技巧与最佳实践

1. 优化 Dockerfile：多阶段构建 (Multi-stage Builds)

2. 使用 .dockerignore

3. 持久化数据

4. 环境变量管理

5. 容器日志

6. 健康检查

7. 选择合适的 Python 基础镜像

常见问题与解决方案

总结

2. 使用 `.dockerignore`