Files
ssw-platform/docs/armv7-build.md
T
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

404 lines
18 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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` 里有这么一段:
```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 <datadir>/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-<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
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 已内嵌),引擎包只给需要自己链接引擎的二次开发者。