moonbuggy2000/python-alpine-wheels

Python musl wheel镜像

在Docker容器中构建的Python musl wheel，用于导入多阶段构建。

• 基本原理
• Wheel类型
• 使用方法
  • 使用Docker镜像
    • 多阶段构建示例
• 构建wheel镜像
  • 默认构建
  • 构建环境
  • 构建示例
  • 添加新wheel
• 链接

基本原理

许多Python模块目前没有预构建的musl wheel，特别是非x64架构的。这会导致Docker中的Python构建缓慢，因为当镜像构建时，没有可用wheel的模块需要从源码编译。

本项目生成的Docker镜像包含wheel文件，镜像标签指定了模块和Python版本（旧镜像标签中还包含架构）。这些镜像旨在作为Docker多阶段构建的一部分，为Python阶段提供预构建的wheel。镜像包含标签中指定模块及其所有依赖的wheel。

注意：这些镜像主要用于我自己的Docker镜像，以避免每次对Python镜像进行破坏缓存的更改时都必须编译模块。本项目不会是全面的wheel集合。

Wheel类型

提供两种不同类型的wheel：

• 包含共享库的wheel

  这些wheel由https://github.com/pypa/auditwheel%E5%A4%84%E7%90%86%EF%BC%8C%E5%BA%94%E7%AC%A6%E5%90%88%E7%9B%B8%E5%85%B3PEP 656规范，具有最高可移植性。

  包含这些wheel的Docker镜像推送到https://hub.docker.com/r/moonbuggy2000/python-musl-wheels%EF%BC%8Cwheel%E6%96%87%E4%BB%B6%E5%90%8D%E4%B8%AD%E5%8C%85%E5%90%AB%60-musllinux%60%E3%80%82

• 不包含共享库的wheel

  这些wheel通过依赖系统库来减小最终Docker镜像大小，因此可移植性较低。相关系统库必须存在且与wheel构建时依赖的库兼容。

  包含这些wheel的Docker镜像推送到https://hub.docker.com/r/moonbuggy2000/python-alpine-wheels%EF%BC%8Cwheel%E6%96%87%E4%BB%B6%E5%90%8D%E4%B8%AD%E5%8C%85%E5%90%AB%60-linux%60%E3%80%82

当前wheel镜像基于Alpine 3.19和musl 1.2构建，wheels/目录中也提供一些musl 1.1的wheel。

注意：如果PyPi上已有某架构的预构建wheel，“无共享库”类型的镜像可能会使用这些现有wheel而非自行构建。因此，特别是对于amd64和arm64架构，部分“python-alpine-wheels”镜像中的wheel可能实际包含共享库。

本项目的目的是填补空白，随着PyPi上更多架构的预构建wheel变得可用，这一空白会逐渐缩小。构建不需要的wheel会扩大这一空白，没有意义。省略共享库并不会节省大量磁盘空间，因此难以证明构建时间的合理性。

使用方法

本项目的wheels/目录中包含大量可直接使用的wheel文件。此外，Docker镜像可作为其他镜像构建过程的一部分拉取使用。

对于使用SSL库的模块，wheels/目录中的wheel文件默认应为OpenSSL构建版本。Docker镜像中通常提供LibreSSL构建版本。

使用Docker镜像

较新的构建仅为每个wheel推送一个多平台标签，格式如下：

moonbuggy2000/python-musl-wheels:<module><module_version>-py<python_version>

示例：

moonbuggy2000/python-musl-wheels:cryptography45.0.1-py3.8

旧版本构建为每个架构推送独立镜像，格式如下：

moonbuggy2000/python-musl-wheels:<module><module_version>-py<python_version>-<arch>

示例：

moonbuggy2000/python-musl-wheels:cryptography3.4.8-py3.8-armv7

多阶段构建示例

dockerfile
ARG PYTHON_VERSION="3.8"

# 从多平台镜像获取cryptography模块
FROM --platform="${TARGETPLATFORM}" \
  "moonbuggy2000/python-musl-wheels:cryptography45.0.1-py${PYTHON_VERSION}" \
  AS mod_cryptography

# 或从旧版单架构镜像获取
FROM "moonbuggy2000/python-musl-wheels:cryptography3.4.8-py${PYTHON_VERSION}-armv7" \
  AS mod_cryptography

# 获取其他模块
FROM --platform="${TARGETPLATFORM}" \
  "moonbuggy2000/python-musl-wheels:some-other-module1.0.0-py${PYTHON_VERSION}" \
  AS mod_some_other

# 构建Python应用镜像
FROM "arm32v7/python:${PYTHON_VERSION}"

WORKDIR "/wheels"

COPY --from=mod_cryptography / ./
COPY --from=mod_some_other / ./

WORKDIR "/app"

# .. 设置虚拟环境等 ..

RUN python3 -m pip install /wheels/*
# 或
RUN python3 -m pip install --find-links /wheels/ cryptography some_other_module

# .. 其他步骤 ..

构建wheel镜像

sh
./build.sh <module><module_version>-py<python_version>-<arch>

除./build.sh <module>外，其余参数均为可选。<module>可包含-openssl或-libressl后缀（如适用）。

目前，-libressl构建不支持s390x架构，因为Alpine软件仓库中没有libressl-dev包。

若未提供<module_version>，将构建PyPi上的最新版本。若省略<python_version>，将使用Docker Hubhttps://hub.docker.com/_/python的最新版本。若未指定<arch>，将构建所有可能的架构。

要为所有默认Python版本（在_build.sh_中定义）构建模块，可使用pyall作为py<python_version>。

可一次性构建多个模块，作为_build.sh_的 separate参数。

默认构建

_build.sh_中内置了一些默认模块和Python版本，可通过特殊构建参数使用：

• all - 为所有默认Python版本构建所有默认模块
• core - 为所有默认Python版本构建核心默认模块（最适合其他模块常用的依赖项，确保在all构建时可用）
• check - 检查PyPi上是否有默认模块的新版本，然后退出，不开始构建
• update - 与check类似，但会继续为所有默认Python版本构建

这些构建应作为_build.sh_的唯一参数独立执行。它们会同时构建包含和不包含共享库的两种wheel。

远程仓库的数据在本地缓存24小时，因此在构建和推送模块后，check的输出不会立即变化。必要时可使用CLEAN_CACHE（见下文）清除缓存。

构建环境

构建脚本使用环境变量确定某些行为，特别是关于推送到Docker Hub和从Docker Hub拉取的操作。

最常用的环境变量如下：

这些变量的命名目前不够清晰一致，未来可能会修改（如果有时间整理的话）。

默认行为是构建包含共享库的wheel，将wheel输出到主机的wheels/目录，且不推送任何镜像到Docker Hub。

构建示例

sh
# 最新cryptography（OpenSSL）、最新Python、所有架构
./build.sh cryptography
# 或
./build.sh cryptography-openssl

# 最新cryptography（LibreSSL）、最新Python、amd64架构
# 推送到Docker仓库
DO_PUSH=1 ./build.sh cryptography-libreSSL-amd64

# cryptography 36.0.1（OpenSSL）、所有默认Python版本、amd64架构
# 不包含共享库
NO_SHARED=1 ./build.sh cryptography-openssl36.0.1-pyall-amd64

# 同时构建多个模块
./build.sh cryptography-openssl-py3.9 cffi1.15.1-armv7 pycparser toml-pyall

# 一次性构建所有默认模块、所有默认Python版本、所有架构
# 从源码构建，同时构建两种类型的wheel，并推送到Docker仓库
DO_PUSH=1 ./build.sh all

添加新wheel

构建系统通常能够使用格式正确的镜像标签构建任何请求的wheel。

默认情况下，wheel在Docker容器中通过以下命令构建：python3 -m pip wheel -w "${WHEELS_DIR}" "${MODULE_NAME}==${MODULE_VERSION}"

scripts/<module_name>.sh

对于特定wheel，若需要超出默认构建设置的配置，可通过可选的scripts/<module_name>.sh文件（与镜像标签中的<module_name>匹配）处理。这是安装Python/pip不会自动安装的构建依赖项的适当位置（如通过apk、make或wget）。

若此文件存在，mod_build函数将在Dockerfile中的pip wheel命令前立即调用。

可通过在scripts/<module_name>.sh文件中放置自定义命令并设置WHEEL_BUILT_IN_SCRIPT来覆盖Dockerfile中的pip wheel命令，以阻止默认命令执行。

mod_depends函数在构建系统检出后调用，用于从本项目获取任何所需模块（若未找到则回退到PyPi），这些依赖项将在Dockerfile开始构建模块前安装。

示例参见scripts/paramiko.sh。

链接

GitHub: https://github.com/moonbuggy/docker-python-musl-wheels

Docker Hub:

• https://hub.docker.com/r/moonbuggy2000/python-alpine-wheels
• https://hub.docker.com/r/moonbuggy2000/python-musl-wheels

相关项目:

• https://github.com/moonbuggy/python-dependency-groups