上游 pglite-rs 只有 aarch64/x86_64 四架构引擎,没有 armv7 ⇒ 自建。 上游认 PGLITE_LIB_DIR,用它喂自建的 libpglite.a + pglite-runtime.tar。 构建链(amd64 容器 + arm-linux-gnueabihf 交叉工具链 + zig cc 链接): - build-pglite-engine.sh / build-libpglite-cross.sh / relocate-runtime-cross.sh - zig-cc-armv7.sh(改写 -Wl,/abs/path + 注入 armhf sysroot) - build-armv7.sh(一键:引擎 → Rust 交叉编译 → arm/v7 容器冒烟) 三个坑(详见 docs/armv7-build.md): - strip="symbols" 让 rustc 重建 native 静态库时破坏全局符号 ⇒ 交叉构建强制 strip=none - PG configure 在 cross_compiling 时假定不支持 --export-dynamic ⇒ 强制 cache 变量 - 上游把 runtime 可移植化拆成独立脚本(RPATH + libpq + libz)⇒ 新增交叉版 release.sh 支持 --target <triple>:跳过宿主消费方编译自检改验架构, rlib 走隔离目录,解包目录名带 target 后缀(多平台互不覆盖)。 实测(linux/arm/v7 容器):initdb、单用户模式、pglite 读写探针、 sspf-admin 启动 + 14255 条示例数据、登录接口、CurrentUser 菜单树全部通过; 从发布包 tar 解出的二进制端到端复测同样通过。
11 KiB
armv7(32 位 ARM hard-float)交叉编译与发布
面向 Linux 32 位 ARM(
armv7-unknown-linux-gnueabihf)的 sspf-admin 构建链。 2026-11-12 建立。
1. 为什么需要自建引擎
平台后端把 PostgreSQL 引擎(libpglite.a)静态链进二进制。上游
Midwess/pglite-rs 的预编译引擎只发布 4 个架构:
| asset | 架构 |
|---|---|
pglite-aarch64-apple-darwin.tar.gz |
aarch64 macOS |
pglite-aarch64-unknown-linux-gnu.tar.gz |
aarch64 Linux |
pglite-x86_64-apple-darwin.tar.gz |
x86_64 macOS |
pglite-x86_64-unknown-linux-gnu.tar.gz |
x86_64 Linux |
没有 armv7 ⇒ pglite-rs-sys 的 build.rs 下载 pglite-armv7-unknown-linux-gnueabihf.tar.gz 会 404。
出路是官方给的 PGLITE_LIB_DIR 环境变量:build.rs 检测到它就不下载,直接用本机目录里的
libpglite.a + pglite-runtime.tar + pglite_native.h。所以要自己交叉编译出这引擎。
引擎版本必须与 crate 匹配:pglite-rs-sys 0.2.7 的 build.rs 里写死了
ENGINE_TAG = "engine-06c837c6a303-p3",对应
electric-sql/postgres-pglite 的 commit 06c837c6a30335169df786c610ed224bc51d81c0
(分支 REL_17_5-pglite,PostgreSQL 17.5)。
2. 路线选择(都实测过)
| 路线 | 结论 |
|---|---|
A. docker run --platform linux/arm/v7 里原生编译 |
❌ qemu 模拟,apt 装依赖就跑了 9 分钟没完;PostgreSQL 全量 make 要数小时 |
B. amd64 容器 + gcc-arm-linux-gnueabihf 交叉工具链 |
✅ 采用。容器是原生 x86_64,编译速度正常 |
Rust 侧用 zig cc 当链接器(zig 0.14.1 自带 lld 与 armv7 libc,免装交叉 libc)。
3. 三个必须记住的坑
这三个坑每一个都花了整轮编译周期才定位,且报错都发生在离原因很远的地方。
坑 1:strip = "symbols" 会破坏静态库的全局符号
现象
ld.lld: error: undefined symbol: ProcessStartupPacket
ld.lld: error: undefined symbol: pgl_shmem_reset
ld.lld: error: undefined symbol: pgl_fd_reset
ld.lld: error: undefined symbol: pgl_xlog_fd_reset
根因:仓库根 Cargo.toml 的 [profile.release] strip = "symbols" 会让 rustc 在链接前
重建 native 静态库(落到 target/<triple>/release/deps/rustcXXXX/libpglite.a)。
重建时全局符号被破坏:
| 符号 | 原件 | rustc 重建后 |
|---|---|---|
ProcessStartupPacket(backend_startup.o) |
T 全局 |
t 局部 |
pgl_shmem_reset(shmem.o) |
T 全局 |
符号消失 |
量化证据:重建后的归档比原件小 3228 字节 —— 恰好 4 个 ARM 符号 × 24 字节符号表条目。
规避:交叉构建时覆盖 CARGO_PROFILE_RELEASE_STRIP=none。
(宿主机 x86_64 构建不受影响,仓库默认 profile 不动。)
排查提示:报错里出现
deps/rustcXXXX/libpglite.a而不是你PGLITE_LIB_DIR指向的那个, 就是这个坑。对比办法:nm -g --defined-only <原件>vsnm -g --defined-only <deps 下的副本>。
坑 2:交叉编译时 PostgreSQL configure 跳过 --export-dynamic 探测
现象(在 arm/v7 容器里起服务时)
FATAL: could not load library ".../lib/postgresql/dict_snowball.so":
undefined symbol: CurrentMemoryContext
根因:PostgreSQL 的 configure 里有这么一段:
if test "$cross_compiling" = yes; then
pgac_cv_prog_cc_LDFLAGS_EX_BE__Wl___export_dynamic="assuming no"
交叉编译时它直接假定不支持,于是 LDFLAGS_EX_BE 里没有 -Wl,--export-dynamic
⇒ postgres 不导出 backend 符号 ⇒ 扩展模块 dlopen 时解析不到。
量化证据:
| 动态导出符号数 | 含 CurrentMemoryContext |
|
|---|---|---|
官方 x86_64 postgres |
10802 | 是 |
自建 armv7 postgres |
0 | 否 |
官方是本机编译,探测能真跑一次所以通过。
规避:configure 时强制 cache 变量
ac_cv_prog_cc_LDFLAGS_EX_BE__Wl___export_dynamic=yes
(已实测 arm-linux-gnueabihf-gcc 支持 -Wl,--export-dynamic,且确实导出符号。)
坑 3:runtime tar 缺 libpq + 缺 RPATH
现象
[启动失败] 打开数据库失败: boot failed: initdb failed:
/tmp/pglite-rs-runtime-*/bin/initdb: error while loading shared libraries:
libpq.so.5: cannot open shared object file: No such file or directory
根因:上游把引擎构建和 runtime 可移植化拆成两个脚本:
native/build-libpglite.sh→ 产出libpglite.a+pglite-runtime.tarnative/relocate-runtime.sh→ 给 runtime 打 RPATH + 打包 libpq
第一版交叉脚本只做了前者。relocate-runtime.sh 在 Linux 下做三件事:
patchelf --set-rpath '$ORIGIN/../lib:$ORIGIN/..'→initdb/postgres/libpqwalreceiver.so- 把
lib/libpq.so*打进 runtime tar - 把 libpq 显式列进 tar 的文件参数
另外 armv7 目标机未必有 libz.so.1(官方 x86_64 包靠宿主系统提供),所以 libz 也要打包进去。
规避:scripts/relocate-runtime-cross.sh(本仓库新增,交叉版)。
排查提示:对比官方 runtime tar 的内容差异最快 ——
tar xf pglite-runtime.tar后看lib/下有没有libpq.so.5, 再strings -a bin/initdb | grep '\$ORIGIN'看有没有 RPATH。
4. 脚本清单
| 脚本 | 作用 |
|---|---|
scripts/build-pglite-engine.sh |
编排:下载源码 → 拉上游 native 脚本与补丁 → 容器内交叉编译 → 导出产物 |
scripts/build-libpglite-cross.sh |
上游 build-libpglite.sh 的交叉变体(打补丁用 patch -p1,强制 export-dynamic) |
scripts/relocate-runtime-cross.sh |
上游 relocate-runtime.sh 的交叉变体(RPATH + libpq + libz) |
scripts/zig-cc-armv7.sh |
cargo 交叉链接器包装器(改写 -Wl,/abs/path → 裸路径;注入 armhf sysroot) |
scripts/build-armv7.sh |
一键入口:引擎 → Rust 交叉编译 → arm/v7 容器冒烟 |
工具链镜像
FROM debian:bookworm-slim
ENV DEBIAN_FRONTEND=noninteractive
RUN dpkg --add-architecture armhf \
&& sed -i 's|^deb |deb [arch=amd64,armhf] |' /etc/apt/sources.list.d/debian.sources \
&& apt-get update -qq \
&& apt-get install -y -qq --no-install-recommends clang llvm make bison flex \
perl pkg-config ca-certificates file patchelf patch \
gcc-arm-linux-gnueabihf libc6-dev-armhf-cross zlib1g-dev:armhf \
&& rm -rf /var/lib/apt/lists/*
镜像名 pglite-armhf-toolchain:latest。
⚠️ multiarch 是必须的:只有
dpkg --add-architecture armhf+ sources 里加[arch=amd64,armhf],才能装zlib1g-dev:armhf(否则Unable to locate package)。
5. 一键构建
bash scripts/build-armv7.sh # 全流程
bash scripts/build-armv7.sh --engine-only # 只建引擎
bash scripts/build-armv7.sh --skip-engine # 只编二进制(复用已有引擎)
产物:
target/armv7-unknown-linux-gnueabihf/release/sspf-admin # ARM EABI5 可执行
dist/pglite-engine-armv7/ # 引擎三件套
├── libpglite.a
├── pglite-runtime.tar
├── pglite_native.h
└── sysroot/ # armhf 交叉 libc + zlib(供 zig cc 链接)
sysroot 的由来
zig 自带 armv7 libc 但不带 zlib(pglite-rs-sys 会链 -lz),
所以从交叉工具链镜像里抽出 armhf 的 libz.so.1 与 libc 系列放本地:
sysroot/lib/ libz.so→libz.so.1, libc.so.6, libm.so.6, libdl.so.2,
libpthread.so.0, librt.so.1, libgcc_s.so.1, ld-linux-armhf.so.3
sysroot/include/ zlib.h, zconf.h, arm-linux-gnueabihf/
6. 验证
# 架构
file target/armv7-unknown-linux-gnueabihf/release/sspf-admin
# → ELF 32-bit LSB pie executable, ARM, EABI5 version 1 (SYSV), dynamically linked,
# interpreter /lib/ld-linux-armhf.so.3
# 真跑(armhf 基础镜像,别用 amd64 的 debian:bookworm-slim)
docker run --rm --platform linux/arm/v7 \
-v "$PWD/target/armv7-unknown-linux-gnueabihf/release/sspf-admin:/sspf-admin:ro" \
-v /tmp/pgdata:/data arm32v7/debian:bookworm-slim \
sh -c 'PGLITE_DIR=/data/pg PORT=30099 /sspf-admin'
2026-11-12 实测结果(全部在 linux/arm/v7 容器内)
| 项 | 结果 |
|---|---|
initdb |
✅ Success |
postgres 单用户模式 |
✅ 退出码 0,输出两个 backend>(与官方 x86_64 一致) |
pglite 探针(open→SELECT 1→CREATE→INSERT→SELECT) |
✅ 全通过,读回 id=1 name=armv7 |
| sspf-admin 首次启动 | ✅ sspf 0.5.0 已启动:http://127.0.0.1:30099 |
| 示例数据导入 | ✅ 14255 条语句,数据目录 1709 个文件 |
POST /api/oauth/Login(admin/123456) |
✅ {"code":200,...,"token":"lite-…"} |
GET /api/oauth/CurrentUser(带 token) |
✅ 85 KB 响应:99 个菜单节点 / 6 条路由 / userInfo 全字段 |
| 复用已有数据目录再启动 | ✅ 正常(WAL 恢复 automatic recovery in progress 后起服务) |
🔴 别把「被 kill -9 后的残留
postmaster.pid」当成 armv7 的 bug: 下次启动会报FATAL: lock file "postmaster.pid" already exists⇒boot failed: backend main returned 1, expected 99。这是强杀进程留下的状态,x86_64 同样如此。 排查时先rm -f <datadir>/postmaster.pid。
端到端(从发布包 tar 解出来的二进制)
tar -xzf dist/sspf-v0.5.0-armv7-unknown-linux-gnueabihf.tar.gz -C /tmp/v
docker run --rm --platform linux/arm/v7 \
-v /tmp/v:/app -v /tmp/d:/data arm32v7/debian:bookworm-slim \
sh -c 'PGLITE_DIR=/data/pg PORT=30099 /app/sspf-v0.5.0-armv7-unknown-linux-gnueabihf/bin/sspf-admin'
实测:启动成功 + 示例数据导入完成 + 登录接口返回 token。
🔴 runtime 是内嵌进二进制的:
pglite-rs用include_bytes!(OUT_DIR/pglite-runtime.tar)把 runtime tar 烤进二进制 ⇒ 目标机不需要额外的引擎文件,发布包自包含。 (dist/pglite-engine-armv7/只是给「想自己链接引擎的二次开发者」用的独立 asset。)
7. 发布
scripts/release.sh 支持 --target <triple>:
bash scripts/release.sh --target armv7-unknown-linux-gnueabihf
与宿主机构建的区别:
- 二进制取自
target/<triple>/release/sspf-admin - 跳过宿主机消费方编译自检(消费方是 x86_64 的,链不上 armv7 库),改为架构校验
(
file结果必须含ARM/EABI) - rlib 用独立隔离目录
target/rlibbuild-<triple>,避免和宿主机的 rlib 互相覆盖 - 解包目录名带 target 后缀:
dist/sspf-vX.Y.Z-<triple>/⇒ 同版本多平台互不覆盖 - 包名
sspf-v${VERSION}-${triple}.tar.gz - README 头部标注目标平台
发布物
| asset | 内容 |
|---|---|
sspf-v0.5.0-armv7-unknown-linux-gnueabihf.tar.gz |
平台包(预编译二进制 + rlib 闭包 + crate 源码) |
pglite-armv7-unknown-linux-gnueabihf.tar.gz |
armv7 引擎(libpglite.a + pglite-runtime.tar + pglite_native.h),命名与上游一致 |
*.sha256 |
校验和(sha256sum -c 可直接用) |
平台包是自包含的(runtime 已内嵌),引擎包只给需要自己链接引擎的二次开发者。