blackdex/rust-musl

rust-musl

该项目提供用于通过Rust语言构建静态musl二进制文件的Docker镜像。它包含多个预编译的C/C++库，以加快Rust项目的编译速度，或使某些项目（如使用MySQL的Diesel）能够成功构建。

这些容器镜像基于Ubuntu 24.04，使用GCC v14.2.0构建工具链和库。自2024年3月15日起，所有镜像均使用musl v1.2.5（通过https://github.com/richfelker/musl-cross-make%E6%9E%84%E5%BB%BA%EF%BC%89%E3%80%82%E8%87%AA2025%E5%B9%B42%E6%9C%8815%E6%97%A5%E8%B5%B7%EF%BC%8C%E6%89%80%E6%9C%89%E9%95%9C%E5%83%8F%E6%94%AF%E6%8C%81amd64%E5%92%8Carm64%E5%B9%B3%E5%8F%B0%E3%80%82

以下库已预编译并通过ENV变量标记为STATIC，Rust Crates可识别这些静态库：

• OpenSSL (v3.5.x)
• cURL (v8.x.x)
• ZLib (v1.3.1)
• PostgreSQL库 (v16.x、v17.x 和 v15.x)
• SQLite (v3.x.x)
• MariaDB Connector/C (v3.x.x)（兼容MySQL）
• libxml2 (v2.x.x)

[!提示] 有关当前版本详情，请查看GitHub仓库：https://github.com/BlackDex/rust-musl/

可用架构

提供stable和nightly两种构建版本。最新nightly版本标签后缀为-nightly，若需特定日期版本，可使用-nightly-YYYY-MM-DD标签。Nightly版本每天约UTC 9:30构建。

Stable版本可直接使用下方列出的标签，或添加-stable后缀。若需固定特定stable版本，可使用-X.Y.Z或-stable-X.Y.Z标签。Stable版本会在有新版本时自动触发构建。

[!提示] 2025-02-15: 创建了aarch64（arm64）基础镜像！
从此日期起，可在aarch64（arm64）架构（如Raspberry Pi 4或5）上构建。
也可使用GitHub arm64运行器（本项目镜像构建亦使用该运行器）。
这意味着可在aarch64（arm64）主机上构建x86_64（amd64）二进制文件。
OCI镜像是多平台容器，在两种架构上功能一致。

OpenSSL v3.5

[!注意] 2024-03-15: 停止在标签中添加-openssl3后缀。

[!注意] 2023-09-29: 停止构建OpenSSL v1.1.1（已停止支持）。
现在仅构建OpenSSL v3.0。

PostgreSQL v16、v17和v15

默认使用PostgreSQL v16库。
若需使用v17或v15，需覆盖环境变量，使PostgreSQL crate指向正确目录。

在命令行添加-e PQ_LIB_DIR="/usr/local/musl/pq17/lib"，或在自定义构建镜像中添加ENV PQ_LIB_DIR="/usr/local/musl/pq17/lib"，将触发使用v17版本进行构建。

[!注意] 2025-02-18: 新增构建libpq v17（同时支持v15和v16）。

[!注意] 2024-11-26: 停止构建libpq v11（已废弃）。

[!注意] 2024-08-08: libpq v16现为默认版本。v15仍继续构建并可用。

[!注意] 2024-08-02: 某些情况下可能仍使用libpq v11，这取决于编译时其他crate是否在pq-sys之后添加主库路径作为搜索路径，导致rustc使用不同的libpq.a。
现已通过将v11库文件移至单独目录解决此问题。默认目录已更改，除非手动将PQ_LIB_DIR设置为v15目录外的路径，否则不应出现问题。

使用方法

[!警告] 2023-04-23: 停止构建arm-unknown-linux-musleabihf和armv5te-unknown-linux-musleabi。
这些目标似乎未被使用。如有用户使用，请提交issue告知。

使用这些镜像的方式有两种：作为Dockerfile中的基础镜像，或通过命令行直接使用。

容器仓库

镜像推送到多个容器仓库：

使用Dockerfile

dockerfile
FROM docker.io/blackdex/rust-musl:aarch64-musl as build

COPY . /home/rust/src

# 如需使用PostgreSQL v15，取消以下ENV注释
# ENV PQ_LIB_DIR="/usr/local/musl/pq15/lib"

RUN cargo build --release

FROM scratch

WORKDIR /
COPY --from=build /home/rust/src/target/aarch64-unknown-linux-musl/release/my-application-name .

CMD ["/my-application-name"]

使用命令行

如需使用PostgreSQL v17客户端库，在-v "$(pwd)"参数前添加-e PQ_LIB_DIR="/usr/local/musl/pq17/lib"。

bash
# 首先拉取镜像：
docker pull docker.io/blackdex/rust-musl:aarch64-musl

# 创建别名
alias rust-musl-builder='docker run --rm -it -v "$(pwd)":/home/rust/src docker.io/blackdex/rust-musl:aarch64-musl'
rust-musl-builder cargo build --release

# 或直接使用
docker run --rm -it -v "$(pwd)":/home/rust/src docker.io/blackdex/rust-musl:aarch64-musl cargo build --release

作为GitHub Actions容器

也可将这些镜像用作GitHub Actions容器。
以下是构建aarch64二进制文件的简单示例：

yaml
name: "构建容器"

on:
  push:
    branches:
     - main

jobs:
  build_container:
    runs-on: ubuntu-latest
    container: ghcr.io/blackdex/rust-musl:aarch64-musl-stable
    steps:
      - uses: actions/checkout@v4
      - name: 构建
        run: |
          cargo build --release

提示

验证容器镜像

自2025年2月15日起，可使用gh客户端验证所有镜像。

例如，验证aarch64 v1.84.1镜像：

bash
gh attestation verify --owner BlackDex oci://ghcr.io/blackdex/rust-musl:aarch64-musl-stable-1.84.1

使用不同的内存分配器

有时musl-based二进制文件比glibc-based慢，主要原因是内存分配器（malloc）性能差异。
提升性能的一种方法是在Rust项目中使用其他内存分配器。
例如，Vaultwarden通过https://github.com/purpleprotocol/mimalloc_rust%E4%BD%BF%E7%94%A8https://github.com/microsoft/mimalloc%E3%80%82
也有其他内存分配器可供选择，选择最适合应用的即可。
构建后的测试会验证MiMalloc crate。

测试

在自动构建工作流中，镜像首先通过Rust项目进行测试，该项目使用Diesel测试所有预编译的C/C++库（数据库库），以及OpenSSL、ZLib和cURL等其他库。

若测试失败，镜像将不会推送到Docker Hub。

链接问题（atomic）

由于一些特殊bug/特性，某些平台可能报告缺少__atomic*库。奇怪的是，这些库实际存在，但链接器或rustc可能忽略它们（如有解决方案，请分享）。

因此，某些平台可能需要额外的RUSTFLAGS以指定C归档文件（.a）的正确位置。

历史

我启动该项目是为了使https://github.com/dani-garcia/vaultwarden%E8%83%BD%E5%A4%9F%E9%9D%99%E6%80%81%E6%9E%84%E5%BB%BA%E5%B9%B6%E6%94%AF%E6%8C%81%E6%89%80%E6%9C%89%E6%95%B0%E6%8D%AE%E5%BA%93%E3%80%82SQLite%E5%9B%A0%E6%9C%89%E6%8D%86%E7%BB%91%E9%80%89%E9%A1%B9%E9%97%AE%E9%A2%98%E4%B8%8D%E5%A4%A7%EF%BC%8C%E4%BD%86PostgreSQL%E5%92%8CMariaDB/MySQL%E6%B2%A1%E6%9C%89%E6%8D%86%E7%BB%91/ vendored特性。

同时，我也希望更好地理解musl工具链和GitHub Actions，目前已达成目标。

参考

启发本项目的部分项目：

• https://github.com/messense/rust-musl-cross
• https://github.com/clux/muslrust
• https://github.com/emk/rust-musl-builder

实现过程中使用的项目：

• https://github.com/richfelker/musl-cross-make
• https://github.com/rust-embedded/cross