构建Python项目的简单方法

!logo

本仓库提供并演示了一种将Python包打包为紧凑Docker镜像的方法，基于现代的Ubuntu Jammy操作系统。

可用镜像

本项目同时在官方Docker仓库和GitHub Container Registry（ghcr.io）提供。

镜像描述

根据用途和特性，镜像分类如下：

核心概念

该方法的核心思想是：使用功能齐全的重型镜像（如ghcr.io/snakepacker/python:all，包含所有必要的头文件、库、编译器等）为你的包构建virtualenv，然后将其复制到具有合适Python版本的轻量级基础镜像中。

采用原因

为何需要如此复杂的流程？你可能会认为直接将Python项目目录COPY到Docker容器中更简单，乍一看似乎合理，但直接复制会导致以下问题：

• 在不同操作系统上生成的.pyc文件可能会意外打包到Docker镜像中，导致Python每次启动镜像时尝试重写正确的.pyc文件。如果以只读模式运行镜像，应用会崩溃。

• 很可能会打包垃圾文件：pytest和tox缓存、开发者的virtualenv等，这些文件只会增加最终镜像的大小。

• 缺少明确的入口点。最终用户难以确定可以运行哪些命令（尽管你可能实现了-h或--help参数）。

• 默认情况下，tox将你的包解释为Python模块，例如在准备环境时尝试运行pip install .。

当然，你可以通过hack、特定设置、.dockerignore文件等解决这些问题，但这对用户来说不直观且难以理解。因此，建议花少量时间仔细打包你的包，让用户能够愉快地使用。

使用示例

例如，你可以构建jupyter notebook。只需创建包含以下内容的Dockerfile：

#################################################################
####################### 构建阶段 #############################
#################################################################
# 该镜像包含：
# 1. 所有Python版本
# 2. 所需的Python头文件
# 3. C编译器和开发工具
FROM ghcr.io/snakepacker/python:all as builder

# 在Python 3.10上创建virtualenv
# 目标文件夹在构建阶段和目标阶段应保持一致
RUN python3.10 -m venv /usr/share/python3/app

# 安装目标包
RUN /usr/share/python3/app/bin/pip install -U pip 'ipython[notebook]'

# 查找所需的系统库及其包
RUN find-libdeps /usr/share/python3/app > /usr/share/python3/app/pkgdeps.txt

#################################################################
####################### 目标阶段 ############################
#################################################################
# 使用与构建阶段相同版本的镜像
FROM ghcr.io/snakepacker/python:3.10

# 将virtualenv复制到目标镜像
COPY --from=builder /usr/share/python3/app /usr/share/python3/app

# 安装所需的库包
RUN xargs -ra /usr/share/python3/app/pkgdeps.txt apt-install

# 创建指向目标二进制文件的符号链接（仅为方便）
RUN ln -snf /usr/share/python3/app/bin/ipython /usr/bin/

CMD ["ipython"]

然后构建镜像：

docker build -t ipython .

实用工具

所有镜像都包含易于使用的包装器，便于镜像构建。

apt-install

简单的bash脚本，主要用途是在通过apt-get install安装软件后自动清理apt缓存和临时文件。通常你需要编写：

apt-get update && \
apt-get install -y tcpdump && \
rm -fr /var/lib/apt/lists /var/lib/cache/* /var/log/*

使用apt-install可简化为：

apt-install tcpdump

wait-for-port

等待一个或多个TCP端口可用的Python脚本，非常适用于测试和docker-compose环境。

wait-for-port --period=0.5 --timeout=600 postgres:5432 pgbouncer:6432 && python myscript.py

或更简洁的写法（使用上述示例中的默认值）：

wait-for-port postgres:5432 pgbouncer:6432 && python myscript.py

该脚本会尝试连接指定的端点，直到超时或端点可连接为止。

find-libdeps

查找二进制*.so文件并解析所需系统包以安装库依赖的shell脚本。

保存所需包：

find-libdeps /usr