# Zenith（齐天）— L2→L7 全栈网络安全数据面框架
## 🎯 定位
Zenith 是一个用 Rust 编写的**从内核旁路到应用层的全栈网络安全数据面框架**。在单一代码库中实现完整的网络栈——AF_XDP/eBPF 零拷贝数据面 → L3/L4 包过滤与转发 → TLS 1.3 → HTTP/1.1/2/3 → 路由/中间件/WAF/代理/缓存。既能构建系统级网络防火墙，也能构建 CDN 边缘节点和 API 网关。
## 📊 工程规模
- **20 个 crate**（19 子 crate + 1 顶层 facade）
- **3235 项测试全通过（53 套件，0 失败）**，`cargo audit` 零告警
- **Rust 1.97.1+ Stable**（禁止 Nightly），edition 2024，全 workspace `#![deny(unsafe_code)]`
- 所有 unsafe 严格隔离在 `zenith-linux`/`zenith-ebpf` 的 FFI 封装内部，上层零 unsafe
- 严格 Lint：clippy `correctness/suspicious/perf = deny`，`missing_docs` 为 warn
- Release 极致优化：`opt-level=3`、`lto="fat"`、`codegen-units=1`、`panic="abort"`、`strip="symbols"`、`incremental=false`
- 安全审计修复（多轮闭环）：
- **v1**：9 项代码缺陷 + 4 项文档修正
- **v2 综合审计**：31 个任务，约 100 个子任务（2 CRITICAL + 4 HIGH + 9 P1 MEDIUM + 9 P2 + 8 LOW）；真实进程级内存泄漏检测通过（FDs 恒定、RSS 空闲回收、进程退出零残留）
- **v3 22 维度审计**：4 High + 21 Medium + 18 Low（BPF redirect flags、RLIMIT_MEMLOCK、ct_compare black_box、指纹评分白名单/黑名单、指纹向量槽位冲突、DecisionAction 映射、ForwardEngine fail-closed、LRU BTreeMap O(log n)、Histogram Prometheus 格式、PermissionSet u16、QoS 继承、TCP ACK 一致性、审计 log() 默认脱敏）
- **v4 22 维度系统级再审计**：6 P0 安全关键 + 12 P1 高优先级 + 20 P2 低优先级（ct_compare 全函数 black_box、ChunkedSig 槽位拆分、Blacklist FxHashSet O(1)、TCP 簿记修正、ExpectationConfig 布局对齐、/metrics Bearer 认证、QPACK 总字节上限接线、ForwardEngine 三态语义、Histogram 双花括号修复、UDP timer_wheel 死重移除、UMEM incref TOCTOU、smuggling 去重、escape_json 去重）
- **v5-v7 深度再审计（多轮闭环）**：QUIC Initial 保留位 Fixed Bit(0x40) 校验（RFC 9000 §17.2，fail-closed）；BPF `queue_map` 跨 crate 缺失（Rust `BpfMaps` 移除已从 BPF 源码删除的 map，杜绝 `from_object` 恒失败）；BPF 分片策略首分片逃逸修复（`frag_off & 0x3FFF`，已重编 .o 并过完整性校验）；WAF NULL 字节 SQLi fail-open 绕过修复（"截断到首个 NULL"改为"就地压缩删除"，保留 NULL 后载荷）；runtime `assign_domain` 单节点累计 CPU/内存容量防超卖 + `extreme_planner` 单策略失败容错；指纹评分 RTT 维度覆盖；`XdpPolicyWriter` 恒 Err 陷阱移除；`ensure_bpffs`/跨平台回退 cfg 门控死代码清理（workspace 0 警告）
- **v8 全链路修复与加固（`zenith-fix-hardening`，246 项审计可落地项）**：恒定时间比较（CORE-001/002，5 函数移除提前返回）；FramePool/Ledger 一致性（CORE-004/006/007/008/009/011/012/013/023/024/031）；L4 转发半开回收（APP-010/030）；HTTP/1-2-3 解析（HTTP-002/004/015/016/020/023/027/035，含 hpack `decode_integer` 步长 bug 修复）；0-RTT 重放/降级（TLS-003/004/011）；eBPF/XDP 过滤链（NET-016/011/010/013/014，WSL2 静态修复 + C 编译验证）；WAF 误报收敛（APP-014/015/017）；系统/运行时/代理（SYS/APP/NET 14 项）；TCP 状态机（NET-020/021 SYN 非监听丢弃 + FIN/RST 窗口校验）；错误分层（ENG-006/007/012/013/015）；H3 coalesced 1-RTT 竞态（quic_server 三守卫）。验证：h2spec 146/146、h3spec 49/49、四协议 curl.exe 200、wrk 55,847/79,006 req/s、hping3 洪水存活、威胁 403/良性 200、JA3/JA4 阻断、IPv6 200、L2/L3/L4、热更新
## 🏗️ 架构分层（L2→L7 全栈）
```
┌─────────────────────────────────────────────────────────────────┐
│ L7 应用层 zenith-web Router / Middleware / StaticFile / │
│ SecurityPipeline（8 步安全管道） │
│ zenith-waf WAF（6 检测器 + 规则 IR，50ms 预算） │
│ zenith-cache CDN 缓存（16 分片 + 条件请求） │
│ zenith-proxy 反向代理（6 负载均衡 + 熔断 + 连接池） │
│ zenith-forward L4 转发（splice/copy + 协议转换） │
│ L3-L7 指纹 zenith-fingerprint 34 采集器 + 决策引擎 + 三级阻断 │
├─────────────────────────────────────────────────────────────────┤
│ L6 加密层 zenith-tls TLS 1.3（rustls+ring + JA3/JA4） │
├─────────────────────────────────────────────────────────────────┤
│ L5 会话层 zenith-http1 HTTP/1.1（RFC 7230，请求走私防护） │
│ zenith-http2 HTTP/2（RFC 7540，HPACK + 流控） │
│ zenith-http3 HTTP/3（RFC 9114，QPACK） │
│ zenith-net QUIC 传输（RFC 9000，真实 QuicServer） │
├─────────────────────────────────────────────────────────────────┤
│ L4 传输层 zenith-net TCP 状态机 / UDP 会话表 / 端口过滤 │
│ zenith-forward TcpRelay 跨平台中继 / 协议转换 │
├─────────────────────────────────────────────────────────────────┤
│ L3 网络层 zenith-net IPv4/IPv6 解析 / IP 黑名单/白名单 │
│ zenith-forward AddressWhitelist CIDR 子网过滤 │
├─────────────────────────────────────────────────────────────────┤
│ L2 数据面 zenith-linux AF_XDP / io_uring / splice 零拷贝 │
│ zenith-ebpf 预编译 BPF 字节码 + 双 Bank 热更新 │
│ zenith-core FramePool 帧池 + 恒定时间比较 │
├─────────────────────────────────────────────────────────────────┤
│ 运行时 zenith-runtime 三级 Supervisor / ChangeSet / Auto │
│ zenith-capability 环境探测 / PermissionSet / 降级 │
│ zenith-observability 指标 / 审计 / 故障快照 │
└─────────────────────────────────────────────────────────────────┘
```
## 📦 Crate 一览
| Crate | 层级 | 职责（核心能力） |
|-------|------|------|
| zenith-api | L7 | 三协议收敛到 `CanonicalRequest`/`CanonicalResponse`（固定容量数组、零堆分配）；`Protocol`/`Transport`/`Method`（RFC 9110 strict）/`CanonicalHeader`/`BodyStream`；CRLF 注入拒绝、超长 fail-closed；治理字段 generation/deadline_ms/cancelled/resource_lease |
| zenith-core | L2+ | 统一错误类型；`FramePool` 帧池 + `FrameToken` 所有权令牌；分层资源账本 `ResourceLedger`（5 级配额）；恒定时间比较 `ct_compare`（eq/contains/starts_with，全函数 black_box）；Huffman、varint、指数退避、CSPRNG 随机源 |
| zenith-linux | L2 | AF_XDP Socket + UMEM + 四环（Fill/RX/TX/Completion）、描述符安全校验引擎与事务化所有权迁移；io_uring 批量 IO（`io_uring` feature）；splice/sendfile 零拷贝系统调用封装；CPU 亲和；`XskConfig` 全参数可配（含 socket 收发缓冲 `so_rcvbuf`/`so_sndbuf` 与 Fill Ring 预填分块 `prefill_chunk`） |
| zenith-ebpf | L2 | eBPF 预编译字节码嵌入（`include_bytes!`，SHA-256 校验）、libbpf-rs 高性能加载、bpf_link 原子挂载、**双 Bank 热更新**（DualBankManager）、XSKMAP 更新 |
| zenith-net | L2-L4 | L2/L3/L4 协议解析（Eth/IPv4/IPv6/TCP/UDP/VLAN）；TCP 状态机（RFC 9293）、UDP 会话表、QUIC 传输（RFC 9000，含真实 `QuicServer`）；`SourceAdmissionEngine`（64 规则五元组 O(1)）、`ProtocolExpectation` 非预期包丢弃、单队列 `Worker` 数据面循环（Phase 0-5）；每包解析步数预算可配（`parse_packet_with_budget`），传输表容量经 `new(capacity)` 注入 |
| zenith-tls | L6 | TLS 1.3（rustls+ring，唯一密码学后端）、证书代际管理（CertManager 双 Bank）、SNI/ALPN 路由、身份一致性校验；JA3/JA4/JA4S/JA4O/JA4H 指纹；0-RTT、fail-closed 无证书绝不回退明文 |
| zenith-http1 | L7 | HTTP/1.1（RFC 7230）解析、热路径零堆分配、流式解析、CRLF 防注入、Content-Length/Transfer-Encoding 二选一、请求走私防护（CL.TE/TE.CL/TE.TE）、强制 Host |
| zenith-http2 | L7 | HTTP/2（RFC 7540）帧解析、流多路复用、HPACK 头部压缩、流量控制（窗口管理）、Rapid Reset 攻击检测、连接级状态机 |
| zenith-http3 | L7 | HTTP/3（RFC 9114）帧、QPACK 头部压缩、流管理、SETTINGS 协商、GOAWAY 关闭流程、控制流/请求流帧类型严格校验、优先级 |
| zenith-web | L7 | 编译期 Trie 路由、类型化 Extractor、中间件 DAG（5 个内置）、静态文件服务（Range/条件请求）、`ProtocolServer`（H1/H2/H3 多协议）、**SecurityPipeline 8 步安全管道**、AF_XDP 桥（`afxdp` feature）；`RuntimeConfig` **无锁原子热更新**（WAF/指纹/监听地址/缓存容量/HTTP 各协议参数等全旋钮运行时热更新） |
| zenith-proxy | L7 | 反向代理：6 种负载均衡（RR/P2C/Rendezvous/EWMA/WeightedRR/IpHash）+ 熔断器（Closed/Open/HalfOpen 自愈）+ 连接池（普通/TLS）+ H3 真实 QUIC 客户端（quinn-proto）+ Auto 最优路径（ALPN 协商 + 健康感知降级/恢复）；`ProxyConfig` 20+ 旋钮可配并支持 `set_proxy_config`/`update_proxy_config` 运行时热更新 |
| zenith-cache | L7 | 16 分片缓存（独立 Mutex）、规范化 CacheKey（host/查询归一）、条件请求（304/206/416）、stale-while-revalidate/stale-if-error、must-revalidate、LRU 时间索引（BTreeMap O(log n)）、租户隔离 |
| zenith-waf | L7 | 6 检测器（SQLi/XSS/SSRF/命令注入/路径穿越/BotThreat）+ 规则 IR（CompiledRule/RuleEngine）；解码→就地 NULL 压缩→检测→规则四阶段；**50ms 预算** fail-closed；自定义 `Box<dyn Detector>` 扩展 |
| zenith-fingerprint | L3-L7 | 全链路指纹识别与阻断：34 采集器结构体（37 collect 入口）、`FingerprintVector` 256B 固定宽度（Copy、零堆分配）、决策引擎（规则+评分+黑白名单+速率限制+信誉）、XDP/L4/L7 三级阻断 |
| zenith-forward | L4 | L4 TCP/UDP 转发、`TcpRelay` 跨平台统一 API（splice/copy 自动选择）、`ForwardEngine`（会话/背压/带宽配额/双向白名单防 SSRF）、`AddressWhitelist` CIDR；`ForwardConfig`（并发会话上限/单会话带宽）可配并支持 `set_config` 运行时热更新 |
| zenith-runtime | 运行时 | 全局 Tokio 运行时、三级 Supervisor（Node/Domain/Queue，故障隔离+指数退避重启）、ChangeSet 八态热切换、AutoOptimizer（重规划+自适应 QoS+缓存预热）、RuntimeGraph/ExtremePlanner 拓扑规划、CPU 硬绑定 |
| zenith-capability | 运行时 | `EnvironmentDetector` 硬件/内核特性探测、`PermissionSet`（u16 位掩码，8 能力）、Profile/ProfileSelector 多目标评分、运行期 revoke 降级 |
| zenith-observability | 运行时 | `MetricsCollector`（Counter/Gauge/Histogram，低基数零堆分配）、`MetricsSubscriber`（tracing 桥）、`AuditLogger`（默认脱敏）、`FaultRecorder` 故障快照、`TraceContext` 分布式追踪 |
| zenith-testkit | 测试 | `TestHarness`/`MockResponse` 生产导出零依赖；integration/demo/stress 全量闭环验证 | |
## 🛡️ 系统级网络防火墙能力（L2→L4）
Zenith 区别于普通 Web 框架的核心——具备构建**系统级网络防火墙**的全部基础组件：
| 层级 | 组件 | 能力 | 等效系统工具 |
|------|------|------|-------------|
| L2 | AF_XDP + eBPF/XDP | 网卡驱动层线速包过滤（XDP_DROP/XDP_PASS） | xdp-bpf / tc-bpf |
| L2 | Ethernet/VLAN 解析 | 按 MAC 地址/VLAN Tag 过滤 | ebtables |
| L3 | SourceAdmissionEngine | 源 IP/端口/协议三维精确匹配（64 规则五元组） | iptables -s / nft |
| L3 | AddressWhitelist CIDR | 子网级过滤（/8, /16, /24） | iptables -s 10.0.0.0/8 |
| L3 | IPv4/IPv6 解析 | 地址族隔离过滤 | ip6tables |
| L4 | 端口过滤 | 源端口/目标端口精确匹配 | iptables -p tcp --dport |
| L4 | 协议过滤 | TCP(6)/UDP(17)/ICMP(1,58)/Any | iptables -p |
| L4 | TCP 状态机 | 连接状态跟踪（RFC 9293） | conntrack |
| L4 | TcpRelay | 端口转发/协议转换（TCP↔UDP） | iptables DNAT / socat |
| L4 | ForwardEngine | L4 转发 + 双向白名单 SSRF 防护 + 背压 + 带宽配额 | haproxy mode tcp |
### eBPF + SourceAdmissionEngine 协作模型
```
网卡 → XDP hook (eBPF 内核态线速粗过滤)
↓ XDP_PASS
AF_XDP UMEM (零拷贝)
↓
Worker process_cycle (Phase 0-5)
↓
SourceAdmissionEngine (用户态细粒度规则匹配)
↓ Allow
L7 处理 (HTTP/TLS/WAF/Proxy)
```
## 🔐 L7 应用层安全
| 特性 | 实现 |
|------|------|
| WAF | 6 种攻击检测（SQLi/XSS/SSRF/命令注入/路径穿越/BotThreat），**50ms 预算** fail-closed，跨协议一致阻断；解码后就地删除（压缩）NULL 字节防注入绕过（保留 NULL 后载荷，杜绝截断漏检）；SQLi 扩展模式（`if(`/`case when`/`into outfile`/`into dumpfile`/`load_file(`/`information_schema`/`regexp`/`between`/`ifnull(`/`coalesce(`），XSS 扩展模式（`window.location`/`window.open`/`location.href`/`string.fromcharcode`/`unescape(`/`atob(`/`innerhtml`/`outerhtml`/`document.location`），路径穿越扩展 `..;/`（Tomcat/Jetty 绕过），BotThreat（sqlmap/nikto 等 30 特征） |
| TLS 指纹 | JA3/JA4/JA4S/JA4O/JA4H/JA4L 指纹识别 + blocklist 前缀阻断 + 64 分片速率限制（60s/100 次 → 429）；**TCP/TLS 与 HTTP/3(QUIC) 连接均采集阻断** |
| 身份一致性 | SNI ↔ Host ↔ :authority 四元一致，不一致 → 421 |
| 请求走私防护 | HTTP/1.1 CL.TE/TE.CL/TE.TE 检测 |
| 响应拆分防护 | CRLF 注入拒绝 |
| 恒定时间比较 | DCID/Token/密码/模式匹配防时序侧信道，`ct_compare` 使用 `core::hint::black_box` 增强 |
| 私钥零化 | `CertGeneration` 使用 `Zeroizing<PrivateKeyDer>`，drop 时自动擦除私钥材料 |
| CORS 安全默认 | `allow_origin` 默认为空——不发送任何 CORS 头，需显式 `with_origin` 配置 |
| X-Forwarded-For | 反向代理自动追加客户端 IP 到 XFF 头 |
| H3 响应限制 | `drive_h3` 强制 `max_response_bytes`，与 H1 路径对齐 |
| QUIC 帧安全 | STOP_SENDING（0x05）独立解析，CRYPTO 缓冲区限制 65536 字节，stream ID 取模 u64 空间（32 位安全），Initial 保留位 Fixed Bit(0x40) 校验 |
| 连接池安全 | `ForwardLease` 实现 `Drop` + `pool_idx` 跟踪，panic 时防止连接池泄漏；`ConnectionTable` 用 `free_stack` O(1) 槽位分配 |
| 协议加固 | `ChunkedDecoder` trailer_buf 限 8192 字节，`TimerWheel` 长延迟钳位防溢出 |
| 反向代理 | 6 种负载均衡（RoundRobin/P2C/Rendezvous/EWMA/WeightedRoundRobin/IpHash）+ 熔断器 + 连接池 + H3 真实 QUIC 客户端（quinn-proto）+ Auto 最优路径（ALPN 协商 h2 > http/1.1，健康感知降级/恢复） |
| CDN 缓存 | 16 分片、条件请求（304/206/416）、stale-while-revalidate、租户隔离 |
| IP 准入 | L3/L4 三维过滤（IP × 端口 × 协议），O(N) N≤64 无锁 |
## 🛡️ 安全特性（30 项闭环）
1. **WAF** — 6 种攻击检测（SQLi/XSS/SSRF/命令注入/路径穿越/BotThreat），50ms 预算控制 fail-closed，跨协议基于 CanonicalRequest 一致阻断；解码后就地删除（压缩）NULL 字节防注入绕过
2. **IP 准入** — SourceAdmissionEngine 按源 IP/端口/协议三维过滤，O(N) N≤64 无锁
3. **TLS 指纹** — JA3/JA4/JA4S/JA4O/JA4H/JA4L 指纹 blocklist 前缀阻断 + 64 分片速率限制；TCP/TLS 与 HTTP/3(QUIC) 连接均采集阻断（QUIC 经 `from_quic_client_hello` 解析裸 handshake）
4. **TLS 1.3** — rustls+ring，双 Bank 证书热切换，SNI 路由，0-RTT，严格 fail-closed（无证书绝不回退明文）
5. **身份一致性** — SNI ↔ Host ↔ :authority 四元一致，不一致 → 421
6. **请求走私防护** — HTTP/1.1 CL.TE/TE.CL/TE.TE 检测，CRLF 注入拒绝
7. **响应拆分防护** — add_header 拒绝含 \r\n 的值
8. **恒定时间比较** — DCID/Token/密码/模式匹配统一用 ct_compare，`#[inline(never)]` + `core::hint::black_box` 防时序泄漏
9. **能力安全模型** — PermissionSet u16 位掩码，最小权限，运行期紧急降级
10. **L4 SSRF 防护** — ForwardEngine 白名单校验客户端与上游地址
11. **checked arithmetic** — 所有容量/地址/偏移算术 checked_*/saturating_*，溢出 fail-closed
12. **全链路指纹** — 34 采集器结构体覆盖 L3-L7，256 字节固定宽度特征向量（Copy 语义），决策引擎（14 种 FingerprintMatcher + 加权评分模型（白名单/黑名单匹配）+ 64 分片固定窗口计数器 + LRU 信誉库），XDP/L4/L7 三级阻断，非预期协议数据包直接丢弃
13. **私钥零化** — `CertGeneration` 使用 `Zeroizing<PrivateKeyDer>`，作用域结束自动擦除私钥材料，防止内存残留
14. **CORS 安全默认** — `allow_origin` 默认为空，不发送任何 CORS 头，需显式 `with_origin` 配置才放行
15. **X-Forwarded-For** — 反向代理自动追加客户端 IP 到 XFF 头，支持上游获取真实客户端地址
16. **H3 响应大小限制** — `drive_h3` 强制 `max_response_bytes`，与 H1 路径对齐，防止响应过大耗尽内存
17. **QUIC 帧安全** — STOP_SENDING（0x05）独立解析，CRYPTO 缓冲区限制 65536 字节，HTTP/3 stream ID 取模在 u64 空间执行（32 位安全）
18. **连接池 Drop 安全** — `ForwardLease` 实现 `Drop` trait + `pool_idx` 精确跟踪，panic 时防止连接池泄漏
19. **TCP 连接表** — `ConnectionTable` 使用 `free_stack` 实现 O(1) 槽位分配，修正 off-by-one 越界
20. **协议加固** — `ChunkedDecoder` trailer_buf 限制 8192 字节，`TimerWheel` 长延迟钳位防溢出
21. **审计日志默认脱敏** — `log()` 方法默认执行 IP 脱敏与敏感字段脱敏，`log_raw()` 保留原始写入
22. **BPF redirect 安全** — `bpf_redirect_map` 使用 `XDP_PASS` flags，XSKMAP 条目竞态删除时回退到内核协议栈
23. **PermissionSet u16 扩展** — 位掩码从 u8 扩展为 u16，编译期断言防止溢出
24. **QoS 继承** — 新 Worker 扩容后强制重放当前 QoS 设置，确保 Critical 级别准入隔离不遗漏
25. **TCP ACK 校验一致** — SynReceived 状态 ACK 序列号校验客户端/服务端一致（RFC 9293 §3.10）
26. **指纹向量槽位独立** — 每个采集器写入独立 FingerprintField 变体，消除后写覆盖先写的数据丢失
27. **/metrics 认证** — 未配置 `metrics_auth_token` 时端点返回 404，配置时校验 `Authorization: Bearer` 恒定时间比较
28. **QPACK 总字节上限** — `decode_field_lines` 内同步累加 name+value 总字节，超 `MAX_TOTAL_HEADER_SIZE` 拒绝（解压炸弹防护）
29. **ForwardEngine 三态** — None=允许透明转发，Some(empty)=fail-closed 拒绝全部，Some(non-empty)=按白名单过滤
30. **UMEM incref 安全** — `compare_exchange` 循环消除 load-then-fetch_add TOCTOU 窗口，ref_count=0 时 incref 失败
## ⚡ 性能特性
| 特性 | 实现 | 平台 |
|------|------|------|
| AF_XDP 零拷贝 | XSK + UMEM + 四环，网卡驱动层旁路 | Linux only |
| eBPF/XDP 线速过滤 | 预编译 BPF + 双 Bank 热更新 | Linux only |
| io_uring 批量 IO | 32 recv + 64 send slot，每批 ≤2 syscall | Linux only |
| splice(2) 零拷贝 | TcpSpliceRelay 内核态双向中继 | Linux only |
| 热路径零堆分配 | 固定容量数组 + SmallVec + FxHashMap | 全平台 |
| 缓存命中零拷贝 | Arc<[u8]> body O(1) 克隆 | 全平台 |
| 无锁 WAF 并发 | check_request 仅需 &self，原子计数器 | 全平台 |
| 任务卸载通道 | TaskOffloadChannel 无锁 O(1)，WAF 大 body 卸载 | 全平台 |
| 代理锁域分离 | 三阶段 begin/IO/finish，I/O 无锁 | 全平台 |
## 🔄 跨平台自动降级
```
高性能环境 (XDP Native + AF_XDP + 零拷贝 + BTF/CO-RE)
→ Performance (tier=3) score=100
→ splice(2) + io_uring + AF_XDP + eBPF 全启用
中等环境 (XDP Generic + BPF，无 Native/零拷贝)
→ Balanced (tier=2) score=92
→ XDP Generic + BPF，io_uring 可用
低能力环境 (无 XDP/AF_XDP/eBPF，如 Windows/最小容器)
→ Minimal (tier=1) score=67
→ 仅 std::net basic_socket
→ TcpRelay 回退 std::io::copy
→ WAF/代理/缓存/路由 全功能可用
```
EnvironmentDetector 真实探测 → ProfileSelector 多目标评分自动选择 → degrade() 三级降级链 → RuntimeConfig::auto() 按 CPU/NUMA 自动推导 → GlobalRuntime 三路径 fail-closed 构建。
## 🎛️ 运行时治理
- **三级 Supervisor** — Node→Domain→Queue→Worker，故障隔离不向上传播，指数退避重启（SupervisorState 状态机 Running/Degraded/Failed）
- **ChangeSet 八态热切换** — Prepare→Validate→ResourceProof→Shadow→Activate→(StopOldAdmission→Drain→Commit | Rollback)，零丢包 A/B 代际切换
- **AutoOptimizer** — 基于负载趋势自动调整 QoS 与 worker 数量，自适应 QoS（Critical/High/Normal/Low/Background）+ 缓存预热预测
- **健康反馈闭环** — 连续 10 次 5xx 触发 Failed 熔断（503）
- **审计闭环** — 环形缓冲 + JSON Lines 落盘，脱敏敏感字段
## 🔄 运行时热更新（全链路 L2→L7）
作为**依赖库**，除固定协议规范标准外，所有运行参数均支持运行时热更新（无需重建服务器/引擎），以实现最高自由度：
| 层 | 机制 | 热更新内容 |
|---|------|-----------|
| L2 | eBPF `config_map` | MTU、协议白名单、fail-closed、期望策略（`BpfMaps::set_*`/`update_*`） |
| L2 | `XskConfig` 可配 | socket 收发缓冲（`so_rcvbuf`/`so_sndbuf`）、Fill Ring 预填分块（`prefill_chunk`） |
| L3 | 每包解析预算 | `parse_packet_with_budget(data, budget)`；传输表容量经 `new(capacity)` 注入 |
| L4 | 引擎 `set_config` | `ForwardEngine` 并发会话上限/单会话带宽（`ForwardConfig`）；经 `ProtocolServer::set_forward_config` 统一热更新 |
| L7 | 无锁原子热更新 | `ProtocolServer::update_runtime(|r| ...)`：WAF 开关/按 host 黑白名单/规则集、指纹安全/限流/阻断、UDP/L4 转发会话、Supervisor 熔断、HTTP/1.1 请求上限/空闲超时、请求体上限、读/写缓冲、HTTP/2 帧长/并发流、HTTP/3 字段段、/metrics 令牌、监听地址、缓存容量 |
| L7 | 代理热更新 | `ProxyConfig` 20+ 旋钮（`set_proxy_config`/`update_proxy_config`）：转发超时对既有路由立即生效，池/健康阈值对新路由生效 |
> **性能设计**：热路径标量一律 `AtomicU64`/`AtomicBool` 单指令原子加载（零锁零竞争）；host 名单/令牌仅启用时才触碰 `RwLock`；写（热更新）低于微秒级，不触碰读热路径。更新对所有 `clone` 副本立即生效。
> **固定内容**：协议规范常量（头长、帧长、MTU 标准值、QUIC 版本等）与 Worker `MAX_BATCH_SIZE`（固定栈数组，刻意零堆分配热路径优化）不可改。
## ✅ 协议合规验证（真实进程级）
| 协议 | 工具 | 结果 |
|------|------|------|
| HTTP/1.1 Plain | wrk -t4 -c200 -d8s | **60,359 req/s**，p50 5.14ms，0 socket errors（WSL Ubuntu 26.04，`0.0.0.0`） |
| HTTP/1.1 Plain 低并发 | wrk -t2 -c20 -d5s | **90,706 req/s**，p50 249µs |
| HTTP/1.1 Plain POST | wrk -t4 -c200 -d8s -s bench/post.lua | **32,881 req/s** |
| HTTP/1.1 Plain 非保活 | wrk -t4 -c200 -d8s -s bench/close.lua | **26,327 req/s** |
| HTTP/1.1 TLS | curl.exe -k（wrk 4.1.0 不支持 TLS） | 200（TLS 1.3 + ALPN h2/http1.1） |
| HTTP/2 | h2spec | 146/146 通过 |
| HTTP/2 | curl.exe --http2 | 200（TLS ALPN h2 协商成功） |
| HTTP/3 | curl.exe --http3 | 200（QUIC + io_uring 批量收发） |
| HTTP/3 | h3spec | 49/49 通过（IPv4 + IPv6） |
| HTTP/3 互操作 | curl --http3-only | 外部 curl（nghttp3/ngtcp2）真实 QUIC 握手 + HTTP/3 200 + 连接复用，SETTINGS/流控帧兼容 |
| TLS 1.3 | curl -vk | TLS_AES_256_GCM_SHA384 / X25519 / ALPN h2 |
| hping3 TCP | hping3 -S | SYN 全应答，服务存活（2000 包无丢包） |
| WAF | curl 攻击 payload | SQLi/XSS/SSRF/命令注入/路径穿越/NULL 字节注入 全拦截 403；BotThreat UA（sqlmap/nikto 等）403 |
| IPv6 | curl [::1] | 200（Plain + TLS + H3 模式；WSL curl 与 Windows curl.exe 双端验证） |
| 指纹阻断 | curl.exe Ja3/Ja4 | TCP/TLS 与 HTTP/3(QUIC) 黑名单 403 均真实生效 |
| CVE | cargo audit | CVE 漏洞扫描无漏洞 |
| 内存 | 进程级 RSS 观测 | 200 连接负载下稳定于 ~74MB 平台，无泄漏 |
## 🧭 可构建的应用场景
| 场景 | 涉及层级 | 核心组件 |
|------|----------|----------|
| XDP 线速包过滤防火墙 | L2 | eBPF + AF_XDP + SourceAdmissionEngine |
| L3/L4 IP/端口防火墙 | L3/L4 | SourceAdmissionEngine + AddressWhitelist CIDR |
| L4 透明转发/协议转换网关 | L4 | TcpRelay + ForwardEngine + AddressWhitelist |
| L7 Web 应用防火墙 | L7 | WAF + TLS 指纹 + 身份一致性 |
| CDN 边缘节点 | L4-L7 | 缓存 + 负载均衡 + SSL 终止 + 代理 |
| API 网关 | L4-L7 | 路由 + 中间件 + WAF + 代理 + 限流 |
| 反向代理/负载均衡器 | L7 | ProxyEngine（6 种策略 + 熔断器） |
| 指纹阻断防火墙 | L3-L7 | zenith-fingerprint + WAF + SourceAdmissionEngine |
| 非预期包丢弃防火墙 | L2-L4 | ProtocolExpectation + XDP + Worker |
| TLS 终止网关 | L6 | TLS 1.3 + 证书代际 + JA3/JA4/JA4S/JA4O/JA4H/JA4L 指纹 |
## 🧩 Feature 组合
```toml
[features]
default = ["api", "core"] # 最小核心
http = ["http1", "http2", "http3"] # HTTP 协议栈组合
web = ["dep:zenith-web", "core"] # Web 服务器（zenith-web 默认 full：HTTP/TLS/WAF/缓存）
full-stack = ["api", "web", "http", "tls", "proxy", "cache", "waf", "forward",
"runtime", "capability", "observability"]
full = ["full-stack", "testkit"] # 全量（含测试工具）
```
> 注：`runtime` 特性依赖 `net + linux + ebpf`，并把 `zenith-web` 升级到 `full`（AF_XDP 桥接/runtime 治理闭环）。
> `audit` 特性（Linux only）启用 cargo-audit 的 netlink 链路。
> `zenith-net`/`zenith-forward` 在 workspace 层 `default-features=false`，`linux` 数据面由使用方按需开启。
## 🎯 核心设计原则
1. **Fail-Closed** — 探测/构建/解析失败取安全默认值，永不 panic
2. **零成本抽象** — 热路径零堆分配、零锁、编译期分发
3. **单 Owner 数据面** — Worker 无锁单线程循环
4. **协议完备** — HTTP/1.1 + HTTP/2 + HTTP/3 over QUIC，TLS 1.3
5. **跨平台兼容** — Linux 极致性能，Windows/其他平台自动降级仍全功能可用
6. **L2→L7 全栈** — 从网卡驱动层包过滤到应用层 WAF，单一代码库覆盖完整网络安全数据面