修复 Gitea issue #1(armv7 包只在 stdout 为管道时能启动)。 根因:pglite 的 initDummyPort() 设 s.sock = 1,把 fd 1 当「名义客户端 socket」;pq_init() 把它注册进 WaitEventSet。Linux 走 epoll,而 epoll 不接受 普通文件与字符设备(实测 EPERM)⇒ ereport(ERROR) ⇒ longjmp ⇒ exit(100)。 macOS 走 kqueue(接受普通文件/字符设备)⇒ 同样形态正常,故此前未暴露。 - 重写 ensure_stdout_for_pglite():pipe + dup 原始 stdout + dup2 让 fd 1 成为管道写端 + drain 线程把内容转发回原 stdout。drain 是必需的: pgl_fcntl 是 dummy ⇒ pg_set_noblock(fd 1) 无效 ⇒ fd 1 始终阻塞 ⇒ 管道写满 64KB 会永久阻塞。macOS 分支保留空实现(kqueue 无需替换)。 - 开库前固化 PGLITE_RUNTIME_DIR 为带 arch + 构建指纹(路径/大小/mtime 的 FNV-1a)的路径,消除 x86_64/armv7 共用 runtime 目录的抢占;用户显式设置时不覆盖。 - 失败路径改为打印「启动诊断」,不再静默 dup2。 门禁:scripts/build-armv7.sh 冒烟改为三 case(A 管道 / B 普通文件 / C /dev/null) × 各自干净数据目录,断言 HTTP 通 + 进程常驻;B/C 另断言出现「启动诊断」 (证明替换路径真的走到)。探活改用 bash 内建 /dev/tcp(armhf 镜像无 wget/curl)。 验证:旧二进制 case B = EXIT 100 + 46 字节 banner;新二进制 = HTTP 200、 14255 条示例数据、登录返 200、优雅关闭。三 case 全绿。
18 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。)
🔴 第四个坑:fd 1 必须是「能被 epoll 注册」的类型(2026-11-13,Gitea issue #1)
这是发布后才暴露的坑,也是最狠的一个:所有标准部署形态全部挂。
现象
armv7 包只有 stdout 是管道时能起来。stdout 重定向到普通文件或 /dev/null
⇒ 进程在 initdb 之后以 exit 100 直接退出,stderr 常常是空的。
| case | stdout (fd 1) | inner_rc |
结果 |
|---|---|---|---|
| A | 继承 docker pipe | 124 | ✅ 正常常驻 |
| B | 普通文件 > /tmp/srv.log 2>&1 |
100 | ❌ 只剩 banner |
| C | /dev/null 字符设备 |
100 | ❌ stderr 0 字节 |
根因链条
- pglite 的
initDummyPort()(src/backend/tcop/postgres.c)设s.sock = 1⇒ 把 fd 1 当成「名义客户端 socket」; pq_init()(src/backend/libpq/pqcomm.c)随即把它注册进 WaitEventSet:socket_pos = AddWaitEventToSet(FeBeWaitSet, WL_SOCKET_WRITEABLE, port->sock, NULL, NULL); /* port->sock == 1 */- 等待事件的后端按平台分(
src/backend/storage/ipc/latch.c): Linux ⇒HAVE_SYS_EPOLL_H⇒ epoll;macOS ⇒ kqueue; - epoll 只接受 poll-able 的 fd(管道 / socket / eventfd …),
普通文件(
S_IFREG)与字符设备(S_IFCHR)一律EPERM。 armv7 容器内实测:普通文件 epoll_ctl=-1 Operation not permitted /dev/null epoll_ctl=-1 Operation not permitted 管道写端 epoll_ctl=0 OK 管道读端 epoll_ctl=0 OK - ⇒
ereport(ERROR, "epoll_ctl() failed: %m")→ longjmp →exit(100)。
💡 macOS 走 kqueue(允许把普通文件/字符设备注册为
EVFILT_WRITE)⇒ 同样形态正常。 ⇒ 这是 Linux 专属问题,x86_64 macOS 上从未暴露。
为什么旧修复是错的
boot.rs::ensure_stdout_for_pglite() 原来把 fd 1 dup2 到一个普通临时文件
⇒ 只是把「字符设备失败」换成「普通文件失败」,同样 EPERM、同样 exit 100。
且它只判 S_IFCHR,普通文件(最主要的部署形态)根本不覆盖;
注释里的「kqueue 读事件 / kevent() 失败」是 macOS 语义,Linux 上有害无益。
本仓的修法(boot.rs::ensure_stdout_for_pglite())
管道 + 原始 stdout 转发 + drain 线程:
pipe()造一对 fd;dup原始 stdout ⇒ 平台的println!(「已启动」「导入完成」…)仍落到 用户真正要的 stdout;dup2(pipe_w, 1)⇒ fd 1 变成管道写端(epoll 合法);- 起 drain 线程读管道读端 → 转发到原始 stdout;
- 原始 stdout 与管道读端泄漏保活(进程级)。
🔴 drain 线程是必需的,不是保险: pglite 的
pgl_fcntl是 dummy(pglitec.c:int pgl_fcntl(...) { return 0; }) ⇒pq_init()里的pg_set_noblock(port->sock)完全无效 ⇒ fd 1 始终阻塞 ⇒ 管道缓冲(Linux 64KB)写满后write()永久阻塞 ⇒ 内嵌 PG 直接卡死 ⇒ 必须有活线程持续消费。
macOS 分支用 #[cfg(target_os = "macos")] 限定为空实现(kqueue 本就接受普通文件)。
回归门禁
scripts/build-armv7.sh 的冒烟现在跑三个 case(每个都是全新容器 + 全新数据目录):
| case | stdout (fd 1) | 走替换? | 断言 |
|---|---|---|---|
| A | 继承 docker pipe | ❌ 已是管道 ⇒ 提前返回 | HTTP 通 + 常驻 + stdout 含「已启动」 |
| B | 普通文件 > /tmp/srv.log 2>&1 |
✅ | HTTP 通 + 常驻 + 日志含「已启动」+ 含「启动诊断」 |
| C | /dev/null |
✅ | HTTP 通 + 常驻 + 含「启动诊断」 |
🔴 B 才是 issue 报的失败形态(
nohup … > app.log 2>&1 &的标准部署写法), 也是最容易漏测的那个。C 的「已启动」进了/dev/null⇒ 只能靠「HTTP 通 + 常驻」判定。
🔴 「启动诊断」这条断言的价值:它证明替换路径真的走到了。 只断言「没 exit 100」是不够的 —— 万一将来有人把替换逻辑删掉、而恰好测试机上 fd 1 是管道,用例依然会绿 ⇒ 用「必须打出诊断行」把这条路径钉死。
🔴 探活用 bash 内建
/dev/tcp,不用wget/curl——arm32v7/debian:bookworm-slim里没有 wget/curl(只有 coreutils)。 且整套探活要包在子 shell 里、2>/dev/null放最外层:bash 连接失败会自己往 stderr 打connect: Connection refused,只重定向exec那行压不住,日志会被刷屏。
🔴
PGLITE_DIR/PORT必须用-e传进容器(2026-11-13 实测踩坑): 它们若只写在bash -c '...'的内联命令行里,会在外层展开成宿主变量、 容器内拿不到 ⇒ 服务起在默认端口 30010 + 默认数据目录 ⇒ 探活一直Connection refused⇒ 被误判成「修复没生效」。
⚠️ 停机时 stderr 会有大量
FATAL: terminating connection because protocol synchronization was lost—— 这是 pgliteshutdown()的已知现象 (postmaster 循环拉起后端,见boot.rs::shutdown_pg注释),不是启动缺陷。 门禁日志里已过滤掉它。
🔴 第五个坑:runtime 目录跨架构抢占(issue #1 关联问题 1)
pglite-rs 0.2.7 的 runtime_dir()(engine.rs)默认取
$TMPDIR/pglite-rs-runtime-0.2.7-<fingerprint>,而 runtime_fingerprint()
只哈希 runtime tar 的内容 ⇒ x86_64 与 armv7 共用同一个目录名。
⇒ 同一台机器上先后跑两种架构的二进制时,后者撞上前者残留目录 ⇒
Error::Boot("runtime extraction race lost and target invalid")。
修法:boot.rs::ensure_runtime_dir_isolated() 在开库前把 PGLITE_RUNTIME_DIR
固化成一个带目标架构与二进制指纹的路径(engine.rs 确实支持该环境变量覆盖):
$TMPDIR/pglite-rs-runtime-<版本>-<arch>-<16 位十六进制指纹>
例:pglite-rs-runtime-0.1.0-x86_64-72b6cc1782da05b7
pglite-rs-runtime-0.1.0-arm-<另一串>
指纹 = FNV-1a( 可执行文件绝对路径 + 文件大小 + 修改时间 ):
- 含路径 ⇒ 同一台机上两个部署(不同安装位置)互不踩;
- 含大小 + mtime ⇒ 换引擎/改代码重编后必然变化 ⇒ 不会复用上一次解出来的 runtime(那正是跨架构/跨版本抢占的真实来源);
- 只
stat不读内容 —— 70 MB 二进制算内容哈希要几百毫秒,启动期不值。
⚠️ 只在用户没显式设置 PGLITE_RUNTIME_DIR 时覆盖 —— 用户显式指定就该尊重。
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 已内嵌),引擎包只给需要自己链接引擎的二次开发者。