把码本编码放进网络路径：AtomBeam 公开专利机制的 Docker AF_XDP 工程验证

我们要做一件具体的事：在两个普通 IP 网络之间放置一对透明网关，让重复、结构化的二进制报文以更短的表示穿过中间链路，到达另一端后再逐字节恢复。 应用仍然使用原来的 TCP 或 UDP socket，端点也不需要集成专用压缩库。

AtomBeam 公开专利给出了码本、Huffman 和差分编码等核心机制。我们的工作重点，是把这些离线编码机制变成一个真正进入网络路径的流式系统，并回答三个工程问题：

1. 编码后的报文能否通过真实 TCP/UDP 通信闭环，而不是只在文件上压缩再解压；
2. 加上隧道头、外层网络头和 codebook 后，实际传输字节是否仍然减少；
3. 当数据偏离训练分布、码本未命中或两端版本不一致时，网络是否仍有明确行为。

本文按照“任务—目标—编码原理—系统方案—验证结果”的顺序展开。公开专利和编码原理的完整调研见《AtomBeam 技术全景：从码本编码到性能指标验证》。

一、我们要构造什么系统

系统的输入不是文件，而是端点发出的完整 IP 报文；系统的输出也不是压缩包，而是对端网络栈能够继续处理的原始 IP 报文。中间链路承载项目自定义的 NCT1 datagram。

flowchart TB
    app_tx["普通 TCP / UDP 应用"]
    ip_tx["发送端 Linux IP 协议栈"]
    gateway_tx["发送侧网关<br/>识别 profile · 选择 codebook"]
    choose{"APC1 是否严格更短？"}
    apc["APC1 压缩 item"]
    raw["RAW 旁路 item"]
    transport["NCT1 datagram<br/>穿过中间链路"]
    gateway_rx["接收侧网关<br/>校验 · 解码 · 恢复"]
    ip_rx["接收端 Linux IP 协议栈"]
    app_rx["对端 TCP / UDP 应用"]

    app_tx --> ip_tx --> gateway_tx --> choose
    choose -->|是| apc --> transport
    choose -->|否| raw --> transport
    transport --> gateway_rx --> ip_rx --> app_rx

这不是在端点重写 TCP，也不是让 AF_XDP socket 与应用 socket 直接相连。TCP 的连接、ACK、重传和拥塞控制仍由端点 Linux 内核负责；两端网关只处理进入隧道的完整 IP 报文。由此，码本编码成为网络路径中的一个透明流式算子。

当前原型已经形成一条完整闭环：为四种自定义固定格式二进制协议分别训练 codebook，使用公开专利中可明确复现的 Huffman、二级 Huffman、原词和无损差分机制进行编码，通过 Docker bridge/veth 上的 XDP 与 AF_XDP 传输，再把报文逐字节交还给对端 TCP/UDP 栈。

二、目标、验收标准与研究边界

工程目标需要能够被实验直接判断。当前项目采用以下六项验收标准。

研究边界同样明确：

• 四种训练协议是项目自定义的固定格式二进制协议，用于控制变量和验证分布变化；
• 本项目独立复现公开专利中能够明确实现的机制，不代表 Neurpac 私有实现；
• NCT1、按 byte 对齐、规范 Huffman、选择位和差分参考集合属于 COMPIN 的工程设计；
• 当前结果是端到端字节缩减，不直接等同于物理链路带宽提升；
• 当前 Docker veth 原型验证功能路径，物理 NIC native XDP、zero-copy 和 line-rate 属于后续性能阶段。

三、码本编码在这里解决什么问题

这类系统利用的是协议数据的重复结构。固定格式遥测、状态、事件和轨迹记录中，一部分字段长期重复，另一部分字段只在相邻取值之间小幅变化。发送每个完整原值会反复携带相同信息，码本编码则把常见模式换成更短的 codeword。

训练阶段把记录按固定长度切成 source word，统计训练集中的出现频率，并为每种协议建立独立 codebook。运行阶段逐个处理 source word：

1. source word 命中主字典时，发送对应的短 Huffman codeword；
2. 未命中时，比较原词、逐 byte 二级 Huffman 和相对参考词的差分编码；
3. 选择 bit cost 最低的无损表示；
4. 对完整 IP 报文再次比较 APC1 与 RAW 的实际 byte 数，压缩结果严格更短才进入隧道。

Huffman 在这里负责让高频模式使用更短表示；二级 Huffman 为主字典未命中的长词提供逐 byte 退路；差分编码用“参考词 + XOR 变化位置”描述相近但未见过的词；RAW 则保证随机数据或明显分布漂移时仍能传输。四条路径共同构成系统，而不是单独依赖某一种编码算法。

四、从目标推导系统方案

上述目标对应到工程设计，可以形成一条清晰的推导链。

由此得到两端压缩隧道：内侧边界是三层 TUN，外侧承载是项目定义的 NCT1 over UDP/IPv4/Ethernet。

flowchart TB
    endpoint_a["端点 A<br/>应用 socket · Linux TCP / UDP / IP"]
    gateway_a_inner["网关 A · 内侧<br/>TUN nct0 · Python gateway<br/>APC1 / RAW · codebook · NCT1"]
    gateway_a_outer["网关 A · 外侧<br/>SOCK_SEQPACKET · C AF_XDP worker<br/>UMEM · RX/TX ring"]
    wan["Docker WAN veth<br/>NCT1 over UDP / IPv4 / Ethernet"]
    gateway_b_outer["网关 B · 外侧<br/>C AF_XDP worker · SOCK_SEQPACKET<br/>UMEM · RX/TX ring"]
    gateway_b_inner["网关 B · 内侧<br/>NCT1 · codebook · APC1 / RAW<br/>Python gateway · TUN nct0"]
    endpoint_b["端点 B<br/>Linux TCP / UDP / IP · 应用 socket"]

    endpoint_a --> gateway_a_inner --> gateway_a_outer --> wan
    wan --> gateway_b_outer --> gateway_b_inner --> endpoint_b

图中按 A → B 展示一次完整发送路径；B → A 使用同一组组件执行对称流程。

4.1 一条 TCP 数据怎样到达 AF_XDP worker

这里需要先区分应用看到的 byte stream 与网关处理的 IP packet。应用把 byte stream 交给 TCP socket；端点 Linux 内核完成分段，加入 TCP sequence、ACK 和 IP header，再把生成的完整 IP packet 发向本侧网关。网关的接口位于 IP 层，通过 Linux 路由和 TUN 接住这些 packet。

在当前 Docker 拓扑中，端点把对端测试网段路由到本侧网关，网关再把该网段路由到 nct0。nct0 是 Linux 提供的三层 TUN 虚拟接口，网关进程通过 /dev/net/tun 打开它。当内核把 packet 路由到 nct0 时，Python 可以从 TUN file descriptor 读到一条完整记录：IP header + TCP header + TCP payload。TUN 位于三层，所以这条记录不带 Ethernet header。

当前单侧发送路径如下。

sequenceDiagram
    participant App as 端点 TCP 应用
    participant EP as 端点 Linux TCP/IP
    participant GW as 网关 Linux 路由
    participant TUN as TUN nct0
    participant PY as Python codec/gateway
    participant IPC as Unix SOCK_SEQPACKET
    participant C as C AF_XDP worker
    participant WAN as WAN veth/NIC

    App->>EP: send(TCP byte stream)
    EP->>GW: TCP/IP 封装后的内层 IP packet
    GW->>TUN: 按对端网段路由到 nct0
    TUN->>PY: read(tun_fd) 返回完整 IP packet
    PY->>PY: 微批、APC1/RAW、NCT1
    PY->>IPC: sendmsg(一条 NCT1 datagram)
    IPC->>C: recvmsg(保留 datagram 边界)
    C->>WAN: AF_XDP TX 外层 Ethernet frame

接收方向执行相反的层次转换：XDP 把外层 frame redirect 到 AF_XDP socket，C worker 取出 NCT1 datagram，Python 解码出原始 IP packet 并写入 TUN；网关内核随后把它路由到对端 LAN，目的端 Linux TCP 栈再把连续 byte stream 交给应用。

这条路径里有三种名字都含有 “socket” 的接口，但它们处理的对象和所在边界不同。

TUN 本身是一种可读写的三层虚拟网卡 file descriptor，与上面的三类 socket 位于不同接口层。由此可以准确理解“TCP 数据进入 AF_XDP”：TCP 始终运行在端点内核；网关依次完成 IP packet 截取、码本表示转换、NCT1 封装和外层 frame 收发，各层通过路由、TUN 记录、NCT1 消息和 frame descriptor 衔接。

当前实现由六个工程组件组成。

Python codec 与 C worker 之间使用 Unix SOCK_SEQPACKET。该接口一次发送一个完整 NCT1 datagram，既保留边界，也让普通 kernel UDP 与 AF_XDP 成为可替换的外侧后端。

五、Docker 网络拓扑

功能验证采用四个容器和三张独立 bridge/veth 网络。

flowchart LR
    client["client<br/>10.10.9.2"]
    gateway_a["gateway-a<br/>LAN: 10.10.9.1<br/>WAN: 172.30.9.2<br/>TUN nct0<br/>XDP / AF_XDP on WAN eth1"]
    gateway_b["gateway-b<br/>WAN: 172.30.9.3<br/>LAN: 10.20.9.1<br/>TUN nct0<br/>XDP / AF_XDP on WAN eth1"]
    server["server<br/>10.20.9.2"]

    client <-->|"lan_a · bridge/veth"| gateway_a
    gateway_a <-->|"wan · bridge/veth"| gateway_b
    gateway_b <-->|"lan_b · bridge/veth"| server

• lan_a 只连接 client 与 gateway-a；
• wan 只连接两个 gateway；
• lan_b 只连接 gateway-b 与 server；
• client 与 server 分别把对端测试网段路由到本侧 gateway；
• gateway 在自己的 network namespace 内创建 nct0；
• XDP 只附着在两个 gateway 的 WAN eth1 veth。

Compose 为 WAN 两端配置确定性 IPv4 和 MAC 地址，C worker 因而可以直接构造完整 Ethernet frame。gateway 获得 BPF、PERFMON、NET_ADMIN、NET_RAW、IPC_LOCK 和 /dev/net/tun；容器使用独立 network namespace、普通 bridge 网络和 no-new-privileges，不使用 host networking 或 privileged 模式。

这一拓扑把实验状态限制在固定 Compose project 中。运行脚本结束后，只删除该 project 的四个容器和三张网络，宿主物理网卡、路由、防火墙及其他 Docker 工作负载保持原状。

六、发送与接收热路径

6.1 发送方向

1. Linux 根据远端测试网段路由，把内层 IPv4 报文交给 nct0。
2. DatagramTunnelGateway 从 TUN 读取完整报文，加入当前微批。
3. 微批在 item 数量、200 微秒等待预算或 1,200-byte NCT1 上限首先满足时 flush。
4. PacketCompactor 在一次 flush 开始时捕获一个不可变 codebook snapshot，确保该批全部 item 使用同一版本。
5. codec 编码每个 item，并用实际 body byte 数比较 APC1 与 RAW。
6. 网关生成一个或多个 NCT1 datagram，通过 SOCK_SEQPACKET 交给 C worker。
7. C worker 从独立 TX frame 池取得 UMEM 地址，构造 Ethernet/IPv4/UDP header 与 NCT1 payload。
8. worker 填写 TX descriptor、提交 TX ring，并按 XDP_USE_NEED_WAKEUP 状态唤醒内核。

当前 TUN MTU 为 1,140 byte，满足：

1140-byte inner packet
+ 8-byte item header
+ 52-byte NCT1 header
= 1200-byte NCT1 datagram

NCT1 上限 1,200 byte，再加入 20-byte IPv4 与 8-byte UDP 后仍位于常见 1,500-byte path MTU 内。当前版本不依赖外层 IP 分片。

6.2 接收方向

1. XDP 解析 Ethernet、固定 20-byte IPv4 header 和 UDP header。
2. 目的 UDP 端口匹配配置 map 时，以 rx_queue_index 查询 XSKMAP 并 redirect；其他流量返回 XDP_PASS。
3. AF_XDP worker 从 RX ring 取得 descriptor 和 UMEM frame。
4. worker 验证源/目的 MAC、源/目的 IPv4、UDP 双端口、IPv4 checksum、长度和分片状态。
5. NCT1 payload 通过本地 SOCK_SEQPACKET 交给 Python 网关。
6. 网关验证 NCT1 magic、版本、flags、长度、CRC、tunnel/lane/profile、sequence、codebook ID、item mode、bit length 和 padding。
7. codec 逐 item 恢复原始内层 IP 报文，并核对原始长度。
8. 网关把完整报文写回 TUN，由 Linux 继续路由到端点 TCP/UDP socket。

返回方向执行同一条对称路径。TCP 分段、ACK 和重传始终留在 endpoint 内核；NCT1 sequence 用于观察 lane 内丢失与乱序，不承担隧道级可靠重传。

七、公开专利机制与工程选择

公开机制与项目自定义格式在实现中分开记录。

主字典 miss 后，codec 对候选路径计算精确 bit cost；整项封装层随后再执行 APC1/RAW byte cost 比较。两层选择分别解决 source-word 表示和网络 item 净收益问题。

八、NCT1 v1 线格式

NCT1 是压缩网关之间的自定义数据面合同。所有整数使用网络字节序，固定 frame header 为 52 byte。

每个 item 使用 8-byte header：

RAW item 要求 bit_length = original_length × 8；APC1 item 的末尾未使用 bit 必须为零。parser 同时拒绝未知模式、未知 flags、长度不一致、非零 padding、尾随数据和 CRC 错误。

同一 frame 只关联一个 profile 和 codebook，同时允许 RAW 与 APC1 item 混合。全 RAW frame 使用全零 codebook ID，可以在尚未激活 codebook 时保持数据面连通。

九、Codebook 生命周期

CodebookRegistry 以完整 APC1 blob 为安装单位：

1. 从 blob 恢复 codec 并验证格式；
2. 计算完整 SHA-256；
3. 取前 128 bit 作为 NCT1 codebook_id；
4. 检查同一 128-bit ID 是否对应完全相同的摘要和 blob；
5. 安装为 inactive snapshot；
6. 按 profile 显式 activate；
7. 保留上一 snapshot 用于 rollback 和过渡期解码。

registry 的读路径只返回不可变 snapshot，激活操作采用 copy-on-write 语义。一次微批持有同一 snapshot，即使控制面在 flush 期间切换 profile，新版本也只影响后续批次。

当前 Docker 功能实验在启动时为两端生成并安装同一个确定性 demo codebook。生产控制面还需要实现双端 stage、完整摘要确认、激活 epoch、健康回报和自动回滚，这部分已确定协议需求，尚未进入当前单队列数据面。

十、XDP 与 AF_XDP 实现参数

10.1 XDP 分类器

当前 eBPF 对象包含两个 map：

• nct_config：单元素 ARRAY，保存 NCT1 UDP 目的端口；
• xsks_map：单元素 XSKMAP，保存 queue 0 的 AF_XDP socket。

分类器只接受 Ethernet + IPv4 + UDP，并要求 IPv4 IHL 为 5。端口匹配后执行 bpf_redirect_map()；map 中不存在对应 queue 时以 XDP_PASS 作为 fallback。当前 map 容量明确对应单队列原型，多队列阶段会同步扩展 map、socket 与 lane 配置。

10.2 AF_XDP worker

当前 worker 使用以下固定资源参数：

RX 与 TX 使用不重叠的 UMEM 地址池。RX frame 处理后回填 FILL ring；TX completion 返回的地址进入 worker 自有 free stack。该所有权划分避免同一 frame 同时被 RX、TX 或用户态重复占用。

发送 frame 使用固定 14-byte Ethernet、20-byte IPv4 与 8-byte UDP header。IPv4 设置 DF，UDP checksum 在 IPv4 下取零；接收方向严格核验 IPv4 checksum 与双端身份。worker 定期原子更新 JSON 状态文件，报告 RX/TX frame、NCT1 byte、invalid、local error、oversize、ring busy 和 wakeup 次数。

10.3 Python/C 进程边界

当前 Python 进程既承担 packet 搬移，也承担编码计算和有状态协议处理。只有 TUN read/write 可以概括为搬移；完整热路径还包括以下工作。

这种拆分首先固定了可测试语义：Python 参考实现覆盖公开专利 codec、codebook 与 NCT1，较小的 C worker 独立验证 AF_XDP 内存所有权和 frame 生命周期。它已经适合功能闭环，也明确暴露出高速版本需要迁移的边界。

高速版本将 packet 热路径整体放入 C：启用 IFF_MULTI_QUEUE 的 TUN 为并行 lane 提供完整内层 packet；每个 lane 在本地完成查表、差分、APC1/RAW 选择和 NCT1 微批；相同 lane 再使用独立 XSK、UMEM 与 AF_XDP queue 发送。inner flow 到 lane 的映射保持稳定，以维持单流顺序和每队列局部状态。

flowchart LR
    tun["多队列 TUN<br/>完整内层 IP packet"]
    steer["按 inner flow<br/>稳定映射到 lane"]
    codec["每 lane C 热路径<br/>codebook 查找 · 差分<br/>APC1/RAW · NCT1 微批"]
    xsk["每 lane 独立<br/>XSK · UMEM · AF_XDP queue"]
    wan["WAN NIC / veth"]
    python["Python 控制面与参考实现<br/>训练 · 验证集选参 · codebook 生成<br/>golden vector · 配置与观测"]

    tun --> steer --> codec --> xsk --> wan
    python -. "发布不可变 codebook snapshot" .-> codec
    codec -. "统计与健康状态" .-> python

完成迁移后，Python 转到离线训练、验证集选参、codebook 生成、控制面编排、统计分析和参考解码，逐 packet 热路径由 C 承担。若 codec 与 AF_XDP worker 合并为同一 C 进程，当前 SOCK_SEQPACKET 可以变成进程内队列；若继续隔离进程，则可以用预分配共享内存 ring 降低复制和 syscall 成本。两种实现都维持 NCT1 线格式和逐字节解码结果不变。

TUN 与 AF_XDP 在这里互补：TUN 把 Linux TCP/IP 产生的三层 packet 交给用户态流式计算，AF_XDP 加速外侧二层 frame I/O。AF_XDP 只覆盖外侧收发，因此端到端性能仍取决于 TUN syscall、codec 计算、微批策略和进程间传递。把这些因素纳入同一份 profile，才能判断下一步应优先优化差分搜索、复制次数还是队列并行度。

十一、故障与降级语义

NCT1 CRC 提供随机损坏检测，不承担来源认证、抗篡改或抗重放。需要安全隧道时，应在压缩后对完整 NCT1 frame 增加独立认证加密层，并把 nonce、tag 与密钥轮换成本纳入字节和 CPU 账本。

十二、验证方法与运行结果

12.1 静态与单元验证

当前工程分支完成：

• eBPF 对象由 Clang 14 以 -Wall -Werror 编译；
• C worker 以 GNU C11、-Wall -Wextra -Werror 编译并链接 libbpf；
• Docker Compose 配置严格解析；
• 全仓库 76 项 unittest 通过；
• NCT1 golden vector、损坏拒绝、codebook 切换和随机批次逐字节恢复通过；
• TUN 模拟、IPv4 loopback UDP、Unix datagram 与 SOCK_SEQPACKET EOF 行为通过；
• git diff --check 通过。

12.2 Docker 端到端验证

测试端点使用真实 Linux TCP/UDP socket：

• 100 条 UDP 请求与回显，共 16,000 应用 byte；
• 65,536-byte TCP 流发送与完整回显；
• 两类负载分别计算 SHA-256；
• 最终 byte_exact=true。

严格外层校验版本的一次完整运行如下。

两个 TunnelEndpoint 的 rejected frame、sequence gap、late-or-duplicate 均为 0。确定性 demo codebook 为 1,831 byte，SHA-256 为 abfec8d9fa6d63a802f95cfc32dd04e4d23e3e011f08531f0f70f79e5d720125。

Linux TCP 分段与 ACK 时序会让不同运行的内层 packet 数和 NCT1 byte 小幅变化；应用输入、回显 byte、codebook 与逐字节正确性保持稳定。因此，该运行用于功能闭环和成本示例，后续吞吐实验将固定流量发生器、预热区间、采样窗口和重复次数。

十三、完整字节账本

当前功能报告使用以下成本定义：

outer_frame_bytes = NCT1_bytes + 42 × NCT1_frames
complete_bytes    = outer_frame_bytes + one_serialized_codebook
reduction         = 1 - complete_bytes / inner_IP_bytes

42 byte 包含 Ethernet 14、IPv4 20 和 UDP 8。按上述口径：

只看 NCT1 与内层 IP，两个方向缩减约 31.74% 和 31.81%；加入主要外层 header 和一次完整 codebook 后，本次保留约 21.8%。这一结果说明公开编码机制产生的 byte saving 能够覆盖当前主要工程封装成本。

物理链路口径还需要加入 Ethernet FCS、preamble、inter-frame gap，以及具体链路的帧结构、纠错、调度和重传。同时应为未压缩路径建立相同二层基线。由此才能进一步计算可复用链路资源，而不是把 byte reduction 直接称为物理带宽提升。

十四、当前性能边界与下一阶段

当前版本已经固定功能语义，性能工程集中在四个方向。

14.1 差分参考搜索

PatentWordCodec._delta_choice 是已识别的主要计算热点。每个未命中 source word 会遍历多个参考词，计算 XOR、Hamming weight 和组合数表示长度。下一阶段先通过 profile 给出：

• 每 packet codec 时间；
• miss 数量与候选参考词数量；
• XOR/Hamming/colex 计算占比；
• 候选剪枝前后的 bitstream 一致性；
• RAW、二级与差分路径的收益和 CPU 代价。

优化约束是编码格式、参考集合定义和解码结果保持不变。

14.2 多队列 AF_XDP

当前 XSKMAP 与 worker 对应 queue 0。多队列版本计划为每个 queue 配置独立 XSK、UMEM、worker 和 CPU affinity，并建立多条外层 UDP lane 配合 RSS。内层五元组稳定映射到 lane，保证单流顺序，同时扩展不同流的并行处理能力。

14.3 Codebook 控制闭环

数据面已经具备 install、activate、rollback 与 unknown-codebook 拒绝语义。控制面下一阶段补齐双端 stage、完整摘要确认、激活 epoch、健康检测、漂移告警与自动回滚，并单独核算 codebook 分发频率和过渡期缓存。

14.4 性能与稳定性矩阵

正式性能实验将报告：

• 单核与多核 packet/s、bit/s 和 goodput；
• p50、p95、p99 编码、排队和端到端时延；
• 每 packet、每 input byte 和每 saved byte 的 CPU 成本；
• 微批大小与 200 微秒等待预算的权衡；
• nominal、drift、noisy 下的命中率和旁路比例；
• 丢包、乱序、codebook 不一致和 worker 过载行为；
• kernel UDP、AF_XDP copy mode 与后续 native/zero-copy 路径的同口径对比。

当前 Docker veth 使用 XDP_SKB_MODE + XDP_COPY，验证的是完整功能路径与 ring 所有权。物理 NIC native XDP、zero-copy 与 line-rate 结论属于独立性能阶段。

COMPIN 的工程评价

当前原型已经把公开专利 codec 从离线算法验证推进到可运行的网络系统：端点保留 TCP/UDP，TUN 提供稳定内层 packet 边界，NCT1 固定双端合同，AF_XDP 承担外层 frame I/O，codebook registry 管理版本状态，RAW 路径保证分布外数据仍可传输。

我们认为这条架构适合网络流式计算，原因有三点。

第一，编码状态与传输层状态相互独立。 codebook 的训练、激活和回滚不会进入端点 TCP 实现，应用接入范围因此保持稳定。

第二，算法收益接受完整网络成本检验。 本次 codec/NCT1 层约 31.8% 的缩减，在加入 Ethernet/IPv4/UDP 和一次 codebook 后仍保留约 21.8%。这个数字规模适中，但证据链完整，也比只报告最佳 payload ratio 更有工程决策价值。

第三，性能演进路径明确。 当前 Python 的职责远多于搬移 packet，它同时执行 codec、codebook 与 NCT1 热路径；这些职责可以按已经固定的线格式整体迁入 C，并扩展为多队列 lane。Python 随后保留训练、控制面和参考验证，同时保持端点 TCP 语义与 NCT1 基础格式稳定。

现阶段最准确的结论是：

AtomBeam 公开专利中可明确复现的码本、Huffman 与差分机制，已经组成一条 Docker AF_XDP 两端压缩隧道，并在真实 TCP/UDP 栈上完成无损闭环；本次完整成本口径获得约 21.8% byte reduction。系统下一阶段进入多队列、热路径优化和性能证据建设。