Skip to content

Commit b0888d9

Browse files
author
fengbojiang
committed
Apply the cross-audit corrections to the nginx graceful-reload spec (00-09).
Re-anchors the documents against the current code, records the R-01/R-02/R-15/R-16 fixes and the new generation-directory material, and keeps the falsified and unexecuted items explicit. One commit for all nine documents so their cross-references stay consistent.
1 parent c7b3924 commit b0888d9

9 files changed

Lines changed: 194 additions & 106 deletions

‎docs/nginx_reload_spec/zh_cn/00-overview.md‎

Lines changed: 12 additions & 11 deletions
Large diffs are not rendered by default.

‎docs/nginx_reload_spec/zh_cn/01-vpp-vcl-research.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -4,11 +4,11 @@
44
|---|---|
55
| 文档编号 | 01 |
66
| 标题 | VPP VCL 支撑 Nginx 无损 reload 的机制、工程问题与启示 |
7-
| 版本 | v1.1 |
8-
| 日期 | 2026-08-18 |
7+
| 版本 | v1.4(v1.3 基础上:**终门禁 G-D 返工 F-01 的跨篇回扫**——R-01 代码修复(`lib/ff_dpdk_if.c:669-673` 代际池 `cache_size=0`)已落地,本篇经全篇回扫**无「代际池未归零 / 仍带 256」类表述需改写**(本篇不涉及代际 mempool 论述),仅版本头同步。v1.2 =**按 `plan_cross_audit` G-A 裁决 R-11 订正**——§6.1 对照表两处失效锚点:`ff_init`/`ff_run` 的 `ngx_process_cycle.c L397/L924` 改为 `ngx_ff_module.c:317` 与 `ngx_process_cycle.c:681/1962/2732`(并注明以符号为准);`ngx_ff_worker_sem` 的 `L459-L509` 改为 `:2024-2037` 创建 / `:2063-2064` 15s `sem_timedwait` / `:2090-2099` 销毁+置 NULL / `:2952-2953` worker0 `sem_post`,并补注 M6 已坐实的 F2 根因与修复) |
8+
| 日期 | 2026-08-18(v1.1~v1.2 增补:2026-09-17) |
99
| 状态 | 待人工审计 |
1010
| 来源产物 | work/research-vpp-vcl.md(调研员 researcher-vpp-vcl,2026-08-18 落盘)。本篇为正式化改写:删除过程性叙述,保留全部事实证据(文件:行号、URL、commit hash、issue 编号)、未坐实标注与单来源声明;「实际执行的操作清单」保留为第 1 节以体现证据可追溯 |
11-
| 修订说明 | v1.1(2026-09-17):本轮 spec×代码交叉审核(plan_audit)订正——§6.4 对 VPP issue #3547 的时效表述由「连环 crash 三年未修」更正为依据 `gh` 元数据的事实(created 2025-02-02,未修复即关闭,至今近两年) |
11+
| 修订说明 | v1.1(2026-09-17):本轮 spec×代码交叉审核(plan_audit)订正——§6.4 对 VPP issue #3547 的时效表述由「连环 crash 三年未修」更正为依据 `gh` 元数据的事实(created 2025-02-02,未修复即关闭,至今近两年)。**v1.2(2026-09-17):按 `plan_cross_audit` G-A 裁决 R-11 订正**——§6.1 对照表两处失效锚点订正(`ff_init`/`ff_run` 与 `ngx_ff_worker_sem`),详见「版本」行。**v1.3(2026-09-18):终门禁 G-D 返工 F-01 跨篇回扫**——R-01 代码修复已落地,本篇回扫无 R-01 相关表述需改写,仅版本头同步。**v1.4(2026-09-18):R-01 机理错误收尾(G-D「提交前必补」)**——本篇经回扫无该机理错误落点(本篇不涉及代际 mempool 论述),仅版本头同步 |
1212

1313
相关篇章:[00-总览](00-overview.md) | [02-其他项目调研](02-other-projects-research.md) | [06-方案设计](06-solution-design.md)
1414

@@ -223,10 +223,10 @@ https://github.com/FDio/vpp/issues/3645
223223

224224
| 维度 | VPP + VCL | F-Stack app/nginx(源码集成) | F-Stack adapter/syscall(LD_PRELOAD) |
225225
|------|-----------|------------------------------|----------------------------------------|
226-
| 协议栈位置 | 独立 VPP 进程,中心化单实例 | 每 worker 进程内嵌一个 FreeBSD 栈实例(`ff_init` + `ff_run`,ngx_process_cycle.c L397/L924 核实) | 独立 fstack 实例进程(`ff_handle_each_context` 循环),app 进程经 libff_syscall.so 以 sc 上下文对接 |
226+
| 协议栈位置 | 独立 VPP 进程,中心化单实例 | 每 worker 进程内嵌一个 FreeBSD 栈实例(`ff_init` + `ff_run`)。**【2026-09-17 订正·R-11】原引 `ngx_process_cycle.c L397/L924` 已失效**:`ff_init()` 的唯一调用点在 **`app/nginx-1.28.0/src/event/modules/ngx_ff_module.c:317`**;`ff_run` 在 **`ngx_process_cycle.c:681`/`:1962`/`:2732`**(M1~M6 实现使行号系统性漂移)。**建议改引符号名而非行号** | 独立 fstack 实例进程(`ff_handle_each_context` 循环),app 进程经 libff_syscall.so 以 sc 上下文对接 |
227227
| listen 归属 | VPP 侧 app_listener 单点持有,app worker 经 bitmap 共享 | 各 worker 的栈实例各自 bind/listen(reuseport 类语义) | fstack 实例持有,fd 经 hook 映射(FF_MULTI_SC:master 为每 worker 预建 fd + sc 绑定,README 核实) |
228228
| app↔栈通道 | 共享内存 svm fifo(数据)+ svm_msg_q(事件/控制),每 worker 独立 mq | 进程内直调 ff_api(无 IPC) | Hugepage 共享内存 sc 上下文 + sem 或 DPDK SPSC rte_ring IPC(FF_USE_RING_IPC,ld_preload_ring_spec) |
229-
| fork 语义 | pthread_atfork 三阶段:注册新 app worker + 复制 session 池 + 显式共享;SIGCHLD 延迟清理 | master fork worker 后靠 POSIX shm 信号量同步启动(ngx_ff_worker_sem,15s 超时,ngx_process_cycle.c L459-L509 核实);新 worker 全新栈实例 | 2023 年起支持 fork(PR #887:每个 fork 进程拥有自己的 FreeBSD struct thread);FF_MULTI_SC 用静态 scs 数组按 current_worker_id 选 sc |
229+
| fork 语义 | pthread_atfork 三阶段:注册新 app worker + 复制 session 池 + 显式共享;SIGCHLD 延迟清理 | master fork worker 后靠 POSIX shm 信号量同步启动(ngx_ff_worker_sem,15s 超时)。**【2026-09-17 订正·R-11】原引 `ngx_process_cycle.c L459-L509` 已失效**,实测落点为:**创建 `:2024-2037`** / **15s `sem_timedwait` `:2063-2064`** / **销毁 + 置 NULL `:2090-2099`** / **worker0 `sem_post`(带判空)`:2952-2953`**。另注:M6 已坐实该信号量生命周期错配为 F2(respawn 风暴)根因,修复为销毁后置 NULL + post 前判空(见 [07](07-milestones.md) §2.7(3));新 worker 全新栈实例 | 2023 年起支持 fork(PR #887:每个 fork 进程拥有自己的 FreeBSD struct thread);FF_MULTI_SC 用静态 scs 数组按 current_worker_id 选 sc |
230230
| reload 时 listen 连续性 | 机制性保证(listen 与进程解耦 + worker 注册/注销) | 无保证:新 worker 新实例重新建立 listen,存在窗口 → 丢包/断连接(团队已知问题,本篇给出现状对照) | 结构上更接近 VPP(栈进程中心化),但 sc→实例映射是静态预分配的,reload 换 worker 集合需重配 |
231231

232232
### 6.2 关键层面区分:网卡队列归属 vs 监听 fd 归属(与 #1036 根因对照)

‎docs/nginx_reload_spec/zh_cn/02-other-projects-research.md‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,10 @@
44
|---|---|
55
| 文档编号 | 02 |
66
| 标题 | 内核基线三种机制 / eBPF 线 / 其他用户态协议栈 / 通用模式归纳与适用性初判 |
7-
| 版本 | v1.0 |
8-
| 日期 | 2026-08-18 |
7+
| 版本 | v1.3(v1.2 基础上:**终门禁 G-D 返工 F-01 的跨篇回扫**——R-01 代码修复(`lib/ff_dpdk_if.c:669-673` 代际池 `cache_size=0`)已落地,本篇经全篇回扫**无「代际池未归零 / 仍带 256」类表述需改写**(本篇不涉及代际 mempool 论述),仅版本头同步。v1.1 =**按 `plan_cross_audit` G-A 裁决 R-07 同源项订正**——§5.1-1 第 1 条「USR2 式二进制升级在 F-Stack 现架构下不可行」就地加注:该结论仅针对 M5 之前的主线架构,M5 已通过「常驻 slim primary + 世代目录仲裁」实现 USR2(`ngx_process_cycle.c:495` `ngx_exec_new_binary`,C-NR-501~504,[08](08-testing.md) RT-04/RT-04b 实机 PASS);历史结论**保留不删**以维持审计可追溯性) |
8+
| 日期 | 2026-08-18(v1.1 增补:2026-09-17) |
99
| 状态 | 待人工审计 |
10+
| 修订说明 | v1.1(2026-09-17):按 `plan_cross_audit` G-A 裁决 R-07 同源项订正——§5.1-1 第 1 条 USR2 结论就地加注 M5 已实现的事实,历史结论保留不删。v1.2(2026-09-18):终门禁 G-D 返工 F-01 跨篇回扫——R-01 代码修复已落地,本篇回扫无 R-01 相关表述需改写,仅版本头同步。**v1.3(2026-09-18):R-01 机理错误收尾(G-D「提交前必补」)**——本篇经回扫无该机理错误落点(本篇不涉及代际 mempool 论述),仅版本头同步 |
1011
| 来源产物 | work/research-other-projects.md(调研员 researcher-others,2026-08-18 落盘)。本篇为正式化改写:删除过程性叙述,保留全部事实证据(URL、原句、issue/PR 编号)、未坐实标注与单来源声明;「实际执行的操作清单」保留为第 1 节以体现证据可追溯 |
1112

1213
相关篇章:[00-总览](00-overview.md) | [01-VPP/VCL 调研](01-vpp-vcl-research.md) | [06-方案设计](06-solution-design.md)
@@ -202,7 +203,7 @@ reload 行为:官方文档对「reuseport 模式下 HUP/USR2 的具体行为
202203

203204
结合本地档案(3.7)与上节模式:
204205

205-
1. USR2 式二进制升级(P1 的 exec 变体)在 F-Stack 现架构下不可行:DPDK 资源不能跨 exec 存活(档案 #12 结论),且旧 master/exec 新 master 均需重新 ff_init 绑定队列。除非把「栈实例」与「nginx 进程」解耦(见第 4 节)。
206+
1. USR2 式二进制升级(P1 的 exec 变体)在 F-Stack 现架构下不可行:DPDK 资源不能跨 exec 存活(档案 #12 结论),且旧 master/exec 新 master 均需重新 ff_init 绑定队列。除非把「栈实例」与「nginx 进程」解耦(见第 4 节)。**【2026-09-17 就地加注·R-07 同源】** 该结论针对 **M5 之前** 的主线架构(无常驻 primary)。**M5 已通过「常驻 slim primary + 世代目录仲裁」实现 USR2 二进制升级**(`ngx_process_cycle.c:495` `ngx_exec_new_binary`,C-NR-501~504,[08](08-testing.md) RT-04 / RT-04b 实机 PASS):exec 仍然发生,但 DPDK 资源归常驻 primary 所有、不随 master exec 消失。**保留本条历史结论以维持审计可追溯性,不要删除**(未删除本条正是为了让读者看到结论如何被后续里程碑推翻)。
206207
2. HUP 式 reload 的丢包根因不是监听 fd(用户态栈里 fd 只是句柄),而是 RSS 硬件队列所有权的空窗期(档案 #1036 根因)。因此照搬 P1(fd 传递/SCM_RIGHTS)不解决问题;照搬 P2 的收益也有限——F-Stack 每 worker 本来就是独立 listen 的栈实例,「reuseport 等价物」天然存在(新连接按 RSS 哈希进各队列),真正缺的是「切换期间队列始终有人收」。
207208
【2026-08-18 增补:与 VPP/VCL 线交叉收敛】本判断与 [01-VPP/VCL 调研](01-vpp-vcl-research.md) 6.2 节独立得出同构结论:**网卡队列/收包所有权与业务进程生命周期的解耦,是用户态栈无损 reload 的结构性前提;监听 fd 是第二位问题**。VPP/VCL 模式两层天然解耦(数据面:队列归独立 VPP 进程,主窗口问题结构性不存在,#3645 反面印证包持续进 VPP、仅事件同步卡死;控制面:listen 归 VPP 侧 app 级单点)。佐证(据 researcher-vpp-vcl 报告转述,本报告未独立核实):#1078 primary_slim PoC 杀 primary 后 12/12 存量连接零中断、adapter/syscall 中心化设计。下述方向 A/B/C 的共同前置条件即此结构性前提;方向 C 与 VCL 的 atfork + app_listener workers bitmap(新 worker 注册进 bitmap 前 accept 事件不分发给它,与 Facebook "ready 前不切流"同构)属同族设计。
208209
3. 初判最可行的方向(供 spec 阶段论证,非结论;最终分档见 [06-方案设计](06-solution-design.md) §4):

‎docs/nginx_reload_spec/zh_cn/04-fstack-current-analysis.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -4,12 +4,12 @@
44
|---|---|
55
| 文档编号 | 04 |
66
| 标题 | F-Stack nginx 适配层与 lib 层现状代码探测(无损 reload 前置事实 + 8 项代码级障碍) |
7-
| 版本 | v1.2 |
8-
| 日期 | 2026-08-18 |
7+
| 版本 | v1.5(v1.4 基础上:**终门禁 G-D 返工 F-01 的跨篇回扫**——R-01 代码修复(`lib/ff_dpdk_if.c:669-673` 代际池 `cache_size=0`)已落地,本篇经全篇回扫**无「代际池未归零 / 仍带 256」类表述需改写**(§5-2 的 F2「脏 EAL」证伪条目与 R-01 无关,维持原样),仅版本头同步。v1.3 =**按 `plan_cross_audit` G-A 裁决 R-25 订正**——§3.5 末条「dispatch 回调 nginx 未使用」已过时:M0 期未使用,**M3 起 nginx 已注册 flow_map dispatcher**(`ngx_ff_module.c:492`)) |
8+
| 日期 | 2026-08-18(v1.1~v1.3 增补:2026-09-17) |
99
| 状态 | 待人工审计 |
1010
| 来源产物 | work/probe-fstack-current.md(探测员 probe-fstack,2026-08-18 落盘,只读探测,未改任何代码)。本篇为正式化改写:保留全部事实证据(文件:行号)、未坐实标注;「探测方法与读过文件清单」保留为第 1 节以体现证据可追溯 |
1111
| 行号复核 | 本现行号锚点已于 2026-09-17 按 HEAD `28e751259` 复核订正 |
12-
| 修订说明 | v1.1(2026-09-17):本轮 spec×代码交叉审核(plan_audit)订正——按 HEAD `28e751259` 复核重写 nginx 适配层与 lib 层行号锚点(M1~M6 实现导致 `lib/ff_dpdk_if.c`/`lib/ff_api.h`/`lib/ff_config.c`/`ngx_ff_module.c`/`ngx_process_cycle.c` 系统性漂移),订正已被实现推翻的 2 条事实描述(worker QUIT 分支的 `ngx_set_shutdown_timer` 已由 M4 补回;worker 0 硬编码 primary 在 `graceful_reload=1` 下已由 M1 消解),并将 F2「脏 EAL」机理标注为已证伪。**v1.2(2026-09-17):据 audit-anchor 独立复核(`work/audit-G1-fix-review-anchor.md`,bounce-1)订正**——§3.2 收发模型多进程路径锚点改 `ff_dpdk_if.c:562-601`(取 lcore `:572`、lcore_list 下标→queue id `:584-596`,§4 障碍 7 同步);§3.1 `ff_stop_run` 置 stop_loop 锚点改 `:3830`;§5-6 KNI 锚点改 `:3658-3676` 且配置键订正为 `[kni] enable`;§2.1 `ngx_ff_graceful_reload` 锚点改 `:49`;§3.3 消息类型补 `FF_RELOAD`(共 10 类);§1 读文件清单加「M0 基线」注 |
12+
| 修订说明 | v1.1(2026-09-17):本轮 spec×代码交叉审核(plan_audit)订正——按 HEAD `28e751259` 复核重写 nginx 适配层与 lib 层行号锚点(M1~M6 实现导致 `lib/ff_dpdk_if.c`/`lib/ff_api.h`/`lib/ff_config.c`/`ngx_ff_module.c`/`ngx_process_cycle.c` 系统性漂移),订正已被实现推翻的 2 条事实描述(worker QUIT 分支的 `ngx_set_shutdown_timer` 已由 M4 补回;worker 0 硬编码 primary 在 `graceful_reload=1` 下已由 M1 消解),并将 F2「脏 EAL」机理标注为已证伪。**v1.2(2026-09-17):据 audit-anchor 独立复核(`work/audit-G1-fix-review-anchor.md`,bounce-1)订正**——§3.2 收发模型多进程路径锚点改 `ff_dpdk_if.c:562-601`(取 lcore `:572`、lcore_list 下标→queue id `:584-596`,§4 障碍 7 同步);§3.1 `ff_stop_run` 置 stop_loop 锚点改 `:3830`;§5-6 KNI 锚点改 `:3658-3676` 且配置键订正为 `[kni] enable`;§2.1 `ngx_ff_graceful_reload` 锚点改 `:49`;§3.3 消息类型补 `FF_RELOAD`(共 10 类);§1 读文件清单加「M0 基线」注。**v1.3(2026-09-17):按 `plan_cross_audit` G-A 裁决 R-25 订正**——① §3.5 末条「dispatch 回调 … nginx 未使用」就地加注:该表述仅对 M0~M2 成立,M3 起 nginx 已注册 flow_map dispatcher(`app/nginx-1.28.0/src/event/modules/ngx_ff_module.c:492`);② 经复核 §3.2 三个锚点(含取 lcore `:572`)无需订正;③ 篇头声明随 R-11 收敛为逐条可核验口径(本篇无整篇兜底声明,无需改写)。**v1.4(2026-09-18):终门禁 G-D 返工 F-01 跨篇回扫**——R-01 代码修复已落地,本篇回扫无 R-01 相关表述需改写,仅版本头同步。**v1.5(2026-09-18):R-01 机理错误收尾(G-D「提交前必补」)**——本篇经回扫无该机理错误落点(§5-2 的 F2「脏 EAL」证伪条目与 R-01 无关,维持原样),仅版本头同步 |
1313

1414
探测范围:/data/workspace/f-stack(DPDK 24.11.6 + FreeBSD 15.0),nginx 适配 `app/nginx-1.28.0/`,核心库 `lib/`。
1515

@@ -158,7 +158,7 @@ F-Stack 对 `ngx_master_process_cycle` 的 ngx_reconfigure 分支改成了【两
158158
- SO_REUSEPORT:仅作为 setsockopt 的 Linux→FreeBSD 常量透传(lib/ff_syscall_wrapper.c:82, 561-562)。F-Stack nginx 多 worker 不是内核 reuseport 语义,而是【每 worker 一个完全隔离的 FreeBSD 协议栈实例,各自 socket/bind/listen 同一 IP:port 互不冲突(栈隔离),流量由 NIC RSS queue↔proc 静态映射分流,每条 TCP 连接只存在于一个进程的栈内】。
159159
- 每进程独立协议栈实例:`ff_freebsd_init()`(lib/ff_freebsd_init.c:269-370)在每进程内跑完整 FreeBSD 内核初始化(kern_setenv、mp_ncpus、UMA、mi_startup、fd_reserve),thread_mode=0 时 nb_cpus=1(:298-301)。
160160
- thread_mode=1(进程内多线程 native-mt)与 proc_type=secondary 显式互斥(lib/ff_config.c:1601-1608 报错;:1610-1611 强制 primary)。nginx 多进程模式用的是 thread_mode=0。
161-
- dispatch 回调:`ff_regist_packet_dispatcher(_context)` 允许 app 重定向包到指定 queue/进程(ff_api.h:247 / :316-319;ff_dpdk_if.c:2589-2604),nginx 未使用。
161+
- dispatch 回调:`ff_regist_packet_dispatcher(_context)` 允许 app 重定向包到指定 queue/进程(ff_api.h:247 / :316-319;ff_dpdk_if.c:2589-2604)。~~nginx 未使用~~ **【2026-09-17 订正·R-25】该表述已过时**:**M0 期未使用;M3 起 nginx 已注册 flow_map dispatcher**(`app/nginx-1.28.0/src/event/modules/ngx_ff_module.c:492` `ff_regist_packet_dispatcher_context(ngx_ff_flow_map_dispatcher)`),本条仅对 M0~M2 时点成立。
162162

163163
## 4. 无损 reload 的代码级障碍清单
164164

0 commit comments

Comments
 (0)