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 全绿。
This commit is contained in:
admin committed 2026-11-13 12:42:08 +08:00
1 parent e95b37ca51
commit 019945385e
5 files changed
+646 -44

No files matched your search

+125
View File
@@ -246,6 +246,131 @@ docker run --rm --platform linux/arm/v7 \
> 把 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. 发布