# 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//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 `。 ### 坑 2:交叉编译时 PostgreSQL configure 跳过 `--export-dynamic` 探测 **现象**(在 arm/v7 容器里起服务时) ``` FATAL: could not load library ".../lib/postgresql/dict_snowball.so": undefined symbol: CurrentMemoryContext ``` **根因**:PostgreSQL 的 `configure` 里有这么一段: ```sh 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 变量 ```sh 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 容器冒烟 | ### 工具链镜像 ```dockerfile 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 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. 验证 ```bash # 架构 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 /postmaster.pid`。 ### 端到端(从发布包 tar 解出来的二进制) ```bash 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: ```c 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 容器内实测: ```text 普通文件 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-`,而 `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-<版本>--<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 `: ```bash bash scripts/release.sh --target armv7-unknown-linux-gnueabihf ``` 与宿主机构建的区别: - 二进制取自 `target//release/sspf-admin` - **跳过**宿主机消费方编译自检(消费方是 x86_64 的,链不上 armv7 库),改为**架构校验** (`file` 结果必须含 `ARM`/`EABI`) - rlib 用独立隔离目录 `target/rlibbuild-`,避免和宿主机的 rlib 互相覆盖 - **解包目录名带 target 后缀**:`dist/sspf-vX.Y.Z-/` ⇒ 同版本多平台**互不覆盖** - 包名 `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 已内嵌),引擎包只给需要自己链接引擎的二次开发者。