Files
admin 019945385e fix(boot): fd 1 非管道导致内嵌 PG exit 100,改管道 + 转发
修复 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 全绿。
2026-11-13 12:42:08 +08:00

18 KiB
Raw Permalink Blame History

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 <原件> vs nm -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.tar
  • native/relocate-runtime.sh → 给 runtime 打 RPATH + 打包 libpq

第一版交叉脚本只做了前者。relocate-runtime.sh 在 Linux 下做三件事:

  1. patchelf --set-rpath '$ORIGIN/../lib:$ORIGIN/..' → initdb / postgres / libpqwalreceiver.so
  2. 把 lib/libpq.so* 打进 runtime tar
  3. 把 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 字节

根因链条

  1. pglite 的 initDummyPort()(src/backend/tcop/postgres.c)设 s.sock = 1 ⇒ 把 fd 1 当成「名义客户端 socket」;
  2. pq_init()(src/backend/libpq/pqcomm.c)随即把它注册进 WaitEventSet:
    socket_pos = AddWaitEventToSet(FeBeWaitSet, WL_SOCKET_WRITEABLE,
                                   port->sock, NULL, NULL);   /* port->sock == 1 */
    
  3. 等待事件的后端按平台分(src/backend/storage/ipc/latch.c): Linux ⇒ HAVE_SYS_EPOLL_H ⇒ epoll;macOS ⇒ kqueue;
  4. 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
    
  5. ⇒ 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 线程:

  1. pipe() 造一对 fd;
  2. dup 原始 stdout ⇒ 平台的 println!(「已启动」「导入完成」…)仍落到 用户真正要的 stdout;
  3. dup2(pipe_w, 1) ⇒ fd 1 变成管道写端(epoll 合法);
  4. 起 drain 线程读管道读端 → 转发到原始 stdout;
  5. 原始 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 —— 这是 pglite shutdown() 的已知现象 (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 已内嵌),引擎包只给需要自己链接引擎的二次开发者。