docs: rework kernel_event_support spec (zh_cn) to connection-level stack selection (drop KNI)

Author: jfb8856606

docs/kernel_event_support_spec/zh_cn/00-overview.md

@@ -1,51 +1,52 @@
-# F-Stack 本地 socket/fd/event 访问能力 —— 项目总览与文档导航（00-overview.md）
+# 00 总览：F-Stack 连接级选栈增强（本机直访 F-Stack 服务）
 
 > **文档编号**：SPEC-KE-00
-> **版本**：v0.1 草稿
+> **版本**：v2（全量重做）
 > **日期**：2026-06-15
 > **状态**：编写中
-> **作用域**：`/data/workspace/f-stack/`（本阶段仅产出中文 spec 文档）
+> **作用域**：本目录中文 spec 的导航、术语与范围声明
 
 ---
 
 ## 1. 一句话目标
 
-让 DPDK 接管网卡后的 F-Stack 主机，**业务流量走用户态 FreeBSD 协议栈、本机/管理面流量（ping、本地 curl 等）仍可走内核协议栈**，并将该能力以 lib 库形式沉淀。
+为 F-Stack 提供一个 lib，使应用进程能在 **F-Stack 用户态栈**与**宿主机 Linux 内核栈**上**同时**创建/监听 socket，并以**统一的 fd / event 抽象**在单事件循环中服务两栈；从而即使 DPDK 接管了网卡，本机的 `ping` / `curl` 等工具也能**直接访问该应用在内核栈侧暴露的服务**。
 
-## 2. 阅读路径
+## 2. 范围声明（重要）
 
-```
-plan.md                       ← 总体规划 / 团队拓扑 / 门禁规约（先读）
-00-overview.md                ← 本文：导航
-01-requirements-spec.md       ← 为什么做、做到什么程度（需求/边界）
-02-current-state-analysis.md  ← 现状：F-Stack 已有的两个参考机制（代码级、文件:行号）
-03-external-research.md       ← 业界怎么做：KNI/TAP/exception path/virtio-user（附 URL）
-04-architecture-design.md     ← 我们怎么做：目标 lib 架构与分流模型
-05-interface-design.md        ← 对外 API / 编译宏 / 数据结构
-06-milestones.md              ← 分几步落地 + 编码工作清单
-07-test-spec.md               ← 怎么验证：单测/集成/性能基线
-08-review-gate.md             ← 审核门禁结论 + bounce 记录
-```
+- **本特性 = 连接级选栈增强（Connection-level Stack Selection）**。
+- **首要参考**：nginx 的 `kernel_network_stack` 开关（`belong_to_host` 1-bit 选栈 + 双事件后端）。
+- **次要参考**：`adapter/syscall` 的 `FF_KERNEL_EVENT` 编译宏（`fstack_kernel_fd_map` + 双栈 epoll 合并）。
+- **明确排除（非目标）**：KNI / `rte_kni` / virtio-user / TAP / AF_XDP 等"报文回灌内核"方案——它们解决的是"未被应用接管的报文回到内核"，与本特性"应用主动在内核栈侧暴露服务"是不同问题，仅在方案对比中用于澄清边界。
 
-## 3. 关键术语
+## 3. 阅读路径
 
-| 术语 | 含义 |
-|---|---|
-| **用户态栈 / F-Stack 栈** | F-Stack 移植的 FreeBSD TCP/IP 协议栈，运行在 DPDK polling 线程内 |
-| **内核栈** | Linux 内核原生 TCP/IP 协议栈 |
-| **分流（dispatch）** | 按某种判定（fd、地址、配置开关）决定一个 socket/事件走用户态栈还是内核栈 |
-| **机制 A** | nginx `kernel_network_stack` per-server 开关（应用配置粒度） |
-| **机制 B** | `adapter/syscall` 的 `FF_KERNEL_EVENT` 宏（fd/syscall 粒度，含 `fstack_kernel_fd_map`） |
-| **KNI / TAP / exception path / virtio-user** | DPDK 生态中将报文送回内核的几类典型路径（详见 `03-external-research.md`） |
-
-## 4. 现状参考的依据来源（待 02 文档实测精确化）
+| 顺序 | 文档 | 用途 |
+|---|---|---|
+| 1 | `plan.md` | 计划、团队、门禁、范围修正 |
+| 2 | `01-requirements-spec.md` | 需求与目标/非目标 |
+| 3 | `02-current-state-analysis.md` | 机制 A/B 代码级现状（以代码为准） |
+| 4 | `03-external-research.md` | 外部方案调研（附 URL） |
+| 5 | `04-architecture-design.md` | 双栈选栈架构与事件模型 |
+| 6 | `05-interface-design.md` | lib 对外接口契约 |
+| 7 | `06-milestones.md` | 里程碑与编码工作清单 |
+| 8 | `07-test-spec.md` | 测试与性能基线方案 |
+| 9 | `08-review-gate.md` | 审核门禁结论 |
 
-- `app/nginx-1.28.0/`：`kernel_network_stack` 指令链路（`NGX_HAVE_FSTACK`）。
-- `adapter/syscall/`：`FF_KERNEL_EVENT` 宏（`ff_hook_syscall.c`、`Makefile`、`README.md`），含 `helloworld_stack_epoll_kernel` demo。
-- `docs/`：三层架构文档（`01/02/03-LAYER*.md`、`F-Stack_Architecture_Layer1/2/3_*.md`）与知识图谱（`KNOWLEDGE_GRAPH_WIKI.md`、`F-Stack_Knowledge_Base_Summary.md`）。
+## 4. 术语表
 
-## 5. 文档纪律
-
-- 现状描述一律带 `文件:行号` 实测证据；与文档/README 冲突以**实际代码**为准。
-- 外部方案一律附**可访问 URL**。
-- 本阶段不改源码、不写实现。
+| 术语 | 含义 |
+|---|---|
+| F-Stack 栈 | DPDK PMD + 用户态 FreeBSD 协议栈（业务高速路径） |
+| 内核栈 | 宿主机 Linux 内核网络协议栈（本机/管理/异常路径） |
+| 连接级选栈 | 在 socket/listen/connect 粒度上决定该连接走 F-Stack 还是内核栈 |
+| `belong_to_host` | nginx 中标记某连接/监听走内核栈的 1-bit 标志 |
+| `SOCK_FSTACK` | F-Stack 适配层在 `socket()` type 上附加的标志，表示走 F-Stack |
+| `FF_KERNEL_EVENT` | LD_PRELOAD 适配层的编译宏，使事件循环同时处理内核 fd |
+| `fstack_kernel_fd_map` | "F-Stack fd → 内核 fd"映射表，用于双栈事件合并 |
+
+## 5. 依据来源
+
+- F-Stack 实际代码（`app/nginx-1.28.0/`、`adapter/syscall/`、`lib/`）——**最高优先级，冲突以代码为准**。
+- F-Stack 三层架构文档与知识图谱（`docs/`）。
+- 外网公开资料（GitHub issue/wiki、技术博客等），均在 `03` 附可访问 URL。

docs/kernel_event_support_spec/zh_cn/01-requirements-spec.md

@@ -1,82 +1,81 @@
-# 需求与问题域规格（01-requirements-spec.md）
+# 01 需求规格：F-Stack 连接级选栈增强 lib
 
 > **文档编号**：SPEC-KE-01
-> **版本**：v0.1 草稿
+> **版本**：v2（全量重做）
 > **日期**：2026-06-15
 > **状态**：编写中
-> **作用域**：F-Stack 本地 socket/fd/event 访问能力的需求边界
+> **作用域**：定义"连接级选栈增强 lib"的问题域、目标/非目标、功能与非功能需求、成功标准。
 
 ---
 
 ## 1. 问题域
 
-### 1.1 根因
-F-Stack 启动后，DPDK 通过 UIO/VFIO 将物理网卡从内核驱动解绑并独占（PMD 轮询），内核协议栈**不再能看到该网卡**。因此本机基于内核栈的工具——`ping`、`curl`、`ssh`、`ntpdate`、监控 agent 等——**无法经该网卡收发**，运维/管理面受阻。
+F-Stack 通过 DPDK 接管网卡后，该网卡流量绕过 Linux 内核协议栈，导致**本机工具（`ping`/`curl`/`ssh` 等）无法访问运行在 F-Stack 用户态栈上的服务**。
 
-### 1.2 现状（详见 `02-current-state-analysis.md`，以代码为准）
-F-Stack 已存在三类"流量回内核"机制：
-- **机制 A** nginx `kernel_network_stack`：仅服务 nginx，per-server/upstream 选栈，强耦合 nginx 源码。
-- **机制 B** `FF_KERNEL_EVENT`：LD_PRELOAD 层，仅镜像 epoll 事件，不覆盖数据 socket。
-- **机制 C** KNI（已迁移为 **virtio-user + vhost-net** exception path）：报文级分流、可运行时调控，**已能支撑本机 ping/curl**，但缺少面向通用应用的统一编程接口与易用封装。
+现有解法分两类：
 
-### 1.3 缺口
-机制 C 提供了数据面通路，但：
-- 配置分散（`config.ini [kni]` + 运行时 `FF_KNICTL` IPC），无统一 lib API；
-- 缺少面向"本地 socket/fd/event"的应用编程模型（应用难以显式声明"这条连接走内核栈"）；
-- 缺少独立可复用的 lib 形态（当前能力散落在 `lib/ff_dpdk_if.c`、`lib/ff_dpdk_kni.c`、`adapter/syscall/`、nginx 补丁中）。
+- **报文回灌（KNI/virtio-user/TAP）**：把裸报文送回内核——**本特性不采用**（见非目标）。
+- **连接级选栈**：应用**主动**在内核栈侧也创建/监听 socket，按连接/监听粒度选栈，并在统一事件循环中服务两栈——**本特性采用**。
 
-## 2. 目标
+F-Stack 自身已有两处"连接级选栈"实现（`02` 机制 A/B），但分别**内嵌**在 nginx 适配与 LD_PRELOAD syscall 适配中，**无法被任意 F-Stack 应用直接复用**。本特性即将其抽象为**应用无关的通用 lib**。
 
-提供一个**lib 库**，使**任意本机应用**（不限 nginx）在 DPDK 接管网卡的前提下，仍可：
-1. 通过内核协议栈完成本机/管理面网络操作（ping、本地 curl 等）；
-2. 以统一、显式的接口声明某个 socket/fd/事件走"内核栈"或"F-Stack 用户态栈"；
-3. 复用 F-Stack 既有 virtio-user exception path 数据面（机制 C），不重造轮子。
+---
+
+## 2. 目标与非目标
 
-## 3. 范围
+### 2.1 目标（In Scope）
+- G1：提供一个 lib，使 F-Stack 应用能在**内核栈侧创建/监听 socket**，本机 `ping`/`curl` 等可直接访问该服务。
+- G2：提供**连接/监听级选栈**能力（某监听走内核栈、某监听走 F-Stack），范式借鉴机制 A 的 `belong_to_host`。
+- G3：提供**统一 fd/event 抽象**，使一个事件循环可同时服务内核栈 fd 与 F-Stack fd（合并事件），范式借鉴机制 B 的 `fstack_kernel_fd_map` + 双栈 epoll。
+- G4：对应用**低侵入**（编译开关 + 少量 API），不强制改造业务逻辑；不绑定 nginx 或 LD_PRELOAD。
 
-### 3.1 本阶段（spec 文档）
-- **仅产出中文 spec 文档**，不写实现代码、不改源码。
-- 交付：需求/现状/外部调研/架构/接口/里程碑/测试/门禁 共 9 篇（见 `plan.md`）。
+### 2.2 非目标（Out of Scope）
+- N1：**不**采用 KNI / `rte_kni` / virtio-user / TAP / AF_XDP 等报文回灌方案（`rte_kni` 已于 DPDK 23.11 移除；gazelle KNI 亦衰退）。
+- N2：本阶段**不写实现代码、不改 f-stack 源码**，仅产出中文 spec。
+- N3：本阶段**不生成英文文档**。
+- N4：不实现内核栈与 F-Stack 之间的 socket 自动迁移/透明代理（连接归属在创建时确定）。
 
-### 3.2 后续实现阶段（本 spec 规划，非本阶段交付）
-- 在 mechanism C 之上抽象统一 lib（暂名 `libff_local` / `ff_local_*`）。
-- 提供编译开关与运行时控制对齐。
-- 单测/集成/性能基线。
+---
 
-### 3.3 不在范围
-- 不改变 F-Stack 业务快路径性能模型；
-- 不引入新的自研内核模块（KNI 内核模块已被 DPDK 23.11 移除，禁止回退）；
-- 本阶段不产出英文文档。
+## 3. 功能需求（FR）
 
-## 4. 功能性需求（FR）
+| 编号 | 需求 | 验收要点 | 代码依据 |
+|---|---|---|---|
+| FR-1 | 应用可在内核栈侧创建监听 socket，本机 `curl`/`ssh` 可访问 | 本机访问内核栈监听成功 | 机制 A `ngx_event_connect.c:46-50` |
+| FR-2 | 本机 `ping`（ICMP）对内核栈侧地址可达 | ping 通 | 内核栈原生处理 ICMP |
+| FR-3 | 连接/监听级选栈：可声明某监听走内核栈或 F-Stack | 两类监听并存且各自可达 | 机制 A `belong_to_host` `ngx_http.c:1890` |
+| FR-4 | 统一事件循环：单循环同时收 F-Stack 与内核栈事件 | 两栈事件均被正确投递 | 机制 B `ff_hook_syscall.c:2329-2338` |
+| FR-5 | fd 归属判定：lib 能区分 fd 属内核栈还是 F-Stack | API 行为按归属正确分流 | 机制 B `is_fstack_fd` `:309` |
+| FR-6 | 资源联动：关闭/异常时两栈 fd 一致释放 | 无 fd 泄漏 | 机制 B close 联动 `:1874-1883` |
+| FR-7 | 编译开关：本能力可编译期开/关，默认关闭零开销 | 关闭时与原 F-Stack 行为一致 | 机制 B `Makefile -DFF_KERNEL_EVENT` |
 
-| 编号 | 需求 | 验收线索 |
-|---|---|---|
-| FR-1 | 本机可经内核栈 `ping` F-Stack 主机网卡 IP | 启用方案后 `ping <nic_ip>` 通 |
-| FR-2 | 本机可经内核栈 `curl` 本机/外部地址 | `curl` 成功，走 veth/virtio-user |
-| FR-3 | 提供统一开关：全部走内核 / 全部走 F-Stack / 默认按规则 | 对齐 `FF_KNICTL_ACTION_*`（`lib/ff_msg.h:118-123`） |
-| FR-4 | 支持按 tcp/udp 端口、协议（ICMP/ARP/OSPF）分流 | 对齐 `config.ini [kni] method/tcp_port/udp_port` |
-| FR-5 | 提供运行时动态调整分流策略的接口 | 对齐 `handle_knictl_msg`（`lib/ff_dpdk_if.c:1960-1977`） |
-| FR-6 | 提供本地 socket/fd/event 编程接口（供应用显式选栈） | 借鉴机制 A 的 1-bit 选栈与机制 B 的 fd 映射 |
+---
 
-## 5. 非功能性需求（NFR）
+## 4. 非功能需求（NFR）
 
 | 编号 | 需求 |
 |---|---|
-| NFR-1 | 关闭本能力时对业务快路径**零额外开销**（默认 KNI 关闭，见官方提示） |
-| NFR-2 | 开启时分流检查开销可控、可限速（对齐 `console_packets_ratelimit`/`general_packets_ratelimit`/`kernel_packets_ratelimit`） |
-| NFR-3 | 不依赖已移除的 `rte_kni`；仅用 upstream 能力（virtio-user/vhost-net） |
-| NFR-4 | 与现有 `config.ini`、`FF_KNICTL` 语义兼容，不破坏既有部署 |
-| NFR-5 | 多进程（primary/secondary）模型下行为明确 |
+| NFR-1 | **默认零开销**：未开启本能力时不引入任何额外分支/内存开销 |
+| NFR-2 | **业务快路径无回归**：F-Stack 高速路径性能不受影响（性能基线见 `07`） |
+| NFR-3 | **可移植**：兼容本工作区 DPDK 23.11.5 / 24.11.6 与移植后的 FreeBSD 栈 |
+| NFR-4 | **可观测**：提供两栈 fd 数、事件数等基本统计 |
+| NFR-5 | **接口稳定**：lib API 语义贴合 POSIX/`ff_api.h`，降低学习成本 |
 
-## 6. 边界与异常场景
+---
+
+## 5. 边界与异常场景
 
-- 内核 `vhost-net` 模块缺失 / 无权限 / hugepage 不足 → 明确报错路径。
-- `method=accept` vs `reject` 语义边界（见 `config.ini:250-253`）。
-- 单网卡场景：管理流量与业务流量共网卡时的端口规划。
-- secondary 进程不创建 virtio_user 口（`lib/ff_dpdk_if.c:609-611` 仅 primary 翻倍端口）。
+- 内核栈侧地址/端口与 F-Stack 侧冲突时的行为约定（应报错而非静默）。
+- `maxevents` 过小（机制 B 要求 `>=2`）时的处理。
+- 内核栈 fd 与 F-Stack fd 在同一 epoll/kqueue 中混用时的事件合并正确性。
+- 本能力关闭（编译期/运行期）时，所有 API 退化为纯 F-Stack 行为。
+- 系统前提缺失（参考 gazelle `rp_filter=1`）时的检测与提示。
+
+---
 
-## 7. 成功标准
+## 6. 成功标准
 
-1. 文档层面：架构/接口/里程碑/测试方案完整、与代码交叉验证一致、外部方案附 URL，通过 `08-review-gate.md` 门禁。
-2. （后续实现阶段）功能层面：FR-1~FR-6 可演示；NFR 满足；性能基线达标（详见 `07-test-spec.md`）。
+1. DPDK 接管网卡后，本机 `ping <内核栈侧IP>` 通、`curl <内核栈侧服务>` 成功（FR-1/FR-2）。
+2. 同一应用进程内"内核栈监听"与"F-Stack 监听"并存，单事件循环均正确收发（FR-3/FR-4）。
+3. 本能力关闭时，F-Stack 业务性能与功能**零回归**（NFR-1/NFR-2）。
+4. spec 全集过 `08-review-gate.md` 门禁。