企业官网建设流程全解析

第 6 章：内核探针逐行拆解——fd 跟踪与字节搬运

6.1 探针的三块职责

整个探针bpf/kvs_repl_probe.bpf.c只做三件事，对应三个区块：声明 Map、跟踪 fd 的出生/迁移/死亡、盯住 recvfrom/read 搬运字节。内核里不解析 RESP、不做任何业务判断——那是用户态的事（第 7 章）。

6.2 六张 Map 各司其职

struct { __uint(type, BPF_MAP_TYPE_ARRAY); __uint(max_entries, 1); ... } probe_cfg SEC(".maps"); struct { __uint(type, BPF_MAP_TYPE_HASH); __uint(max_entries, 4096); ... } tracked_fds SEC(".maps"); struct { __uint(type, BPF_MAP_TYPE_RINGBUF);__uint(max_entries, 1 << 22); } events SEC(".maps"); struct { ... key=pid_tgid, value=pending_rd } pending_rd SEC(".maps"); // fd + 用户缓冲指针 struct { ... key=pid_tgid, value=__u8 } pending_accept SEC(".maps"); // 打"正在 accept"标记 struct { ... key=pid_tgid, value=pending_dup } pending_dup SEC(".maps"); // dup 暂存

• probe_cfg（ARRAY）：写死master_pid。每个探针函数第一步都调is_master_pid()过滤——不是主库进程的事件，一律当场返回。这是全局开关。
• tracked_fds（HASH，fd→1 字节）：这套探针的心脏。只有 key 在里面的 fd，探针才采集数据。它回答"这条连接我要不要偷听"。
• events（RINGBUF，4MiB）：唯一输出通道，字节流从这里流到用户态。
• 三张pending_*（HASH，key 都是 pid_tgid）：都是enter/exit 接力棒——enter 存参数，exit 读结果，靠 pid_tgid 唯一标识"同一次系统调用的两个事件"。为什么要 pid_tgid 而不是进程号？因为协程/多线程下同一时刻可能有多个线程同时在 recv，用 PID 会串台，必须用"进程号+线程号"合成的一个值。

6.3 第一条流：fd 的出生、迁移与死亡

出生。客户端连接是被accept出来的。探针在sys_enter_accept4往pending_accept打个标记，在sys_exit_accept4读返回值（新 fd 号）把它塞进tracked_fds：

SEC("tracepoint/syscalls/sys_exit_accept4") int tp_exit_accept4(struct tp_sys_exit *ctx) { // 若此线程确实调过 accept（pending_accept 有标记）且 ret>=0： bpf_map_update_elem(&tracked_fds, &(u32)ctx->ret, &one, BPF_ANY); bpf_map_delete_elem(&pending_accept, &id); // 用完清掉 }

迁移。主库握手会把 accept 出的 fddup成控制面 fd 再 close 原 fd。探针在sys_enter_dup/dup2/dup3里判断"旧 fd 在 tracked_fds 里吗？在的话把新 fd 也登记进去"。否则控制面上后续的SYNC FINISHED信号会完全听不到（第 4 章提过）。

死亡。sys_enter_close做两件事：把 fd 从tracked_fds删掉，同时往 ringbuf 发一个len=0的特殊事件：

if (tr) { // 被跟踪的 fd 正在被 close e = bpf_ringbuf_reserve(&events, sizeof(*e), 0); e->fd = ctx->fd; e->len = 0; // len=0 语义：该 fd 已关闭 bpf_ringbuf_submit(e, 0); } bpf_map_delete_elem(&tracked_fds, &fdk);

这个len=0事件意义很大：fd 号会复用。如果用户态不清掉这个 fd 的半包缓冲，下次一个完全不相干的连接复用同一个 fd 号，会拼上上一段脏半包，组帧全乱。close 通知就是"你该把这个 fd 的组帧状态清掉了"。

6.4 第二条流：recvfrom/read 的字节搬运

enter：sys_enter_recvfrom拿到 fd 和用户缓冲区指针ubuf，但此刻还不知道会读到多少字节。它把两者存进pending_rd（且跳过MSG_PEEK，第 4 章讲过）。

exit：sys_exit_recvfrom的返回值ret就是实际读到的字节数。emit_on_exit做四步：ret>0才继续；按 pid_tgid 取出pending_rd里暂存的指针；确认这个 fd 还在tracked_fds里；然后按 512B 一片，最多 32 片地把用户缓冲区拷进 ringbuf：

total = ret; #pragma unroll for (i = 0; i < 32; i++) { if (off >= total) break; copy_len = min(total - off, 512); e = bpf_ringbuf_reserve(&events, sizeof(*e), 0); if (!e) break; // ringbuf 满：放弃本次，不阻塞 e->fd = p->fd; e->len = copy_len; bpf_probe_read_user(e->data, 512, (void *)(p->ubuf + off)); // 安全拷用户内存 bpf_ringbuf_submit(e, 0); off += copy_len; }

为什么是"32 片 × 512B = 16KiB"？因为主库的读缓冲上限就是 16KiB，一次 recv/read 最多读到这么多，32 片正好全覆盖。#pragma unroll让验证器能静态证明循环 32 次必然结束（第 2 章验证器约束的直接体现）。bpf_probe_read_user是唯一能碰用户态内存的安全 helper，指针越界由它兜底——哪怕用户缓冲非法，也只是拷 0 字节，不会让内核崩。

6.5 探针行为直接决定上层业务正确性

这个"32 片分片"曾经是一个线上事故的根因。早期版本emit_on_exit只拷 ringbuf 里的第一片 512B：一次 recv 若返回好几 KB（比如 LLM 生成的长答案通过 VSET 写入），后面的字节全被丢弃，用户态组帧拿到残缺命令 → 从库收不到向量 → 近似语义检索永不命中。修复就是改成完整 32 片，和 io_uring 路径的emit_user_chunks保持同一上限（第 8 章）。

这个教训值得单独记住：探针在内核里丢一个字节，用户态没有任何办法察觉。探针的采集逻辑必须严格等于"用户态需要什么"，多丢一片就是业务事故。这也是为什么把"组帧、判断、投递"全部放用户态更稳——至少出错时还能打日志、能 debug，而内核里的 bug 是盲区。

第 7 章：用户态旁路进程——组帧、VSET 语义化、会话与容错

7.1 从 ringbuf 字节流到业务命令

探针把主库入站字节按 512B 分片推进 ringbuf。用户态旁路进程kvs_repl_ebpf的主循环就是poll三路 fd：ringbuf 的 epoll fd（客户端写）、控制套接字（主库控制面消息）、增量 TCP 监听口（从库来连）。每次唤醒先把 ringbuf 抽干再处理别的——这个顺序是刻意的：SYNC FINISHED若是抢先触发 drain→LIVE，而 ringbuf 里还堵着未投递的写命令，就会丢数据。所以代码里是"抽干 ringbuf → 处理 TCP accept → 处理控制面 → 再抽一轮 ringbuf → 统一 LIVE"。

ringbuf 回调拿到的是"某个 fd 的一段字节"，先按 fd 拼进对应的半包缓冲g_frames[fd]，再进入组帧循环。

7.2 组帧：半包、粘包与软重置

探针采到的是字节流，不是命令边界。用户态要把它还原成一条条 RESP 命令，于是手写了一个 RESP Array 解析器resp_array_span：从缓冲开头找*、解析数组长度、逐个解析$bulk，直到确认整条命令完整到达，返回该命令占的字节数（span）。

三种情况：

• 缓冲区不够一条完整命令 → 返回"半包"，等更多字节拼进来；
• 解析出完整命令 → 按 span 消费掉；
• 中间出现非法字节 → 不整段清空，而是软重置：从偏移 1 开始找下一个*，跳到下一条可能的命令起点。这防止"一条脏字节毁掉后面整段写命令"。

还有一个特殊信号：len=0的 ringbuf 事件代表某个 fd 被 close（第 6 章）。用户态收到它就把该 fd 的组帧缓冲整个清掉——fd 号会复用，不清就会把旧半包拼给新连接。

7.3 白名单：不是所有命令都复制

组帧出完整命令后，先看命令名是否命中复制白名单cmd_is_replicated_write：SET/RSET/HSET/ZSET、VSET、MOD/RMOD/HMOD/ZMOD、DEL/RDEL/HDEL/ZDEL、PEXPIRE/RPEXPIRE/HPEXPIRE/ZPEXPIRE。命中的才投递给从库；GET 族、PING、ECHO、SAVE、FLUSHALL 一律不复制。

这个名单不是拍脑袋定的，它严格对齐主库dispatch里会进"持久化+复制"通道的写命令——凡是从库需要一致的写操作，才值得复制。而REPL/SYNC这类控制命令不走业务通道，会被直接移出tracked_fds（frame_drop_fd），不再当业务连接偷听。

7.4 VSET 语义化：从"观测"到"业务"

这是本系统最有意思的部分：eBPF 不只是观测，还参与业务转换。主库收到VSET 问题 答案后，普通复制路径只发明文给从库。但从库的职责是"向量→答案"，它需要的不是明文VSET，而是把问题 embed 成向量、再带着答案存进去。于是旁路进程在识别出VSET时调用handle_vset_semantic：

1. 调 embedding 服务（:35303），把问题转成 1024 维 dense 向量 + 可选的 ColBERT 向量；
2. 用floats_to_vec_key把浮点向量打包成 4096 字节的二进制 key；
3. 用vector_codec_encode_value把"问题+答案[+ColBERT]"编码成 v0x02 复合 value；
4. 组一条SET <4096字节向量key> <复合value>，投递给从库——绝不把明文 VSET 转发过去。

如果 embedding 失败，先重试，再退化为"纯 dense 向量 + 只含问题和答案的 value"，最后仍失败就放弃本次语义转发（明文已在主库落库，稍后全量同步会补向量快照）。整个函数末尾有一句自检日志打印长度公式expect=1+4+q+4+a[+4+tc*4096]——编码长度必须在投递前算清楚，错了就丢掉。这条路径把"探针偷字节 → 用户态解析 → 外部服务调用 → 格式转换 → 再投递"串成了闭环，是 eBPF 应用里难得的"旁路即中间件"案例。

7.5 会话管理：从 HOLDING 到 LIVE

从库不是一开始就能实时收增量的。它先做主从全量同步（走独立的全量通道），这段时间如果旁路把增量发过去，会被从库丢弃或打乱。所以旁路给每个从库维护一个状态机：

• HOLDING（积压）：主库通过控制套接字发SLAVE_BEGIN（带从库 id/IP/端口），旁路登记会话、只把命令攒进队列，不发；
• FINISHED（分界）：主库发SLAVE_FINISHED，表示"全量同步已到某个序号 M，此前的增量都在积压队列里，此后的才要实时发"。旁路只打一个want_live标记，不立刻切；
• LIVE（实时）：把积压队列 drain 干净，状态切到 LIVE，之后新命令直接send。

为什么 FINISHED 不立刻切 LIVE？因为SYNC FINISHED信号（探针辅通道 + Unix 控制面双通道，幂等去重）可能比 ringbuf 里仍在排队的写命令先到，若此时 drain，随后入队的写会丢。所以统一"等 ringbuf 抽干后再 drain→LIVE"。

从库的 TCP 增量连接靠IP 匹配绑定到会话：SLAVE_BEGIN 登记了从库 IP，增量口 accept 时取对端 IP 找"同 IP 且未绑定"的会话；还没 BEGIN 就来的连接先进 pending，等 BEGIN 到了再 FIFO 绑定。多从库场景下，这套匹配防止把增量发给 id/IP 不匹配的从库。

7.6 容错：崩了怎么办

旁路进程由主库的一个监督线程管着（repl_ebpf_proc.c）：

• 主库 fork 出旁路，等它的控制套接字出现才算就绪，超时（默认 3s）就杀掉重来；
• 监督线程用waitpid(WNOHANG)盯着旁路，发现它退出，先立即把增量回退成 tcp（不让业务停摆），再尝试重启，最多 3 次，间隔 1s；
• 重启次数耗尽后，固定走 tcp 直到主库重启，不再折腾。

单从库缓冲满也只断该从库的 eBPF 连接，不影响其它从库、不阻塞主库写。这套"软降级 + 监督重启"的容错矩阵是项目自己定义的降级策略（文档里叫 §8 降级矩阵）：任何一步失败，系统的底线是退回传统的 tcp 增量。这也回答了一个核心设计问题——eBPF 是加速器、是优化项，但绝不是唯一路径；主从同步的正确性永远有一份 tcp 兜底。这是生产系统用 eBPF 的正确姿势：永远留退路。

第 8 章：io_uring 的坑与 uprobe 方案

8.1 问题：io_uring 不走经典系统调用

第 6 章探针依赖sys_enter_recvfrom/sys_enter_read这些 tracepoint——它们在内核处理经典系统调用时触发。但主库有个后端叫 io_uring：它把读写请求提交到内核队列，由内核异步完成，根本不经过recvfrom/read的系统调用路径。于是 tracepoint 完全听不到主库读了什么字节，旁路增量直接失效。

这暴露了 eBPF 探针的一个通用局限：探针能看到的，是"目标程序触发了你监听的事件"；目标程序如果换了路径，探针就瞎了。io_uring 就是换了路径。

8.2 解法：主库埋 noinline 钩子 + uprobe

既然 tracepoint 听不到，就换一种程序类型——uprobe（第 2 章提过：挂到用户态程序的某个函数入口）。但 eBPF 无法知道主库的 io_uring 代码里哪个函数是"读入站字节"的。项目的做法是在主库里主动埋两个空钩子：

__attribute__((noinline, used)) void kvs_repl_probe_hook_accept(int fd) {} __attribute__((noinline, used)) void kvs_repl_probe_hook_inbound(int fd, const void *buf, size_t n) {}

• noinline：保证钩子真的有独立函数体、有符号表项，uprobe 才能挂上去；used：防止编译器把没人调用的它优化掉。
• 主库在 io_uring 的 accept 完成、读到入站字节时，显式调用这两个钩子，把 fd、缓冲区指针、长度传进去——钩子本身是空函数，什么都不做，只是给 uprobe 一个"下钩点"。

这样分工很清晰：钩子函数体在主库里，是主库代码的一部分（要随NET=uring编译才有）；但真正读数据的逻辑在旁路的 uprobe 程序里，旁路从函数入口的参数寄存器里取 fd/指针/长度。

8.3 uprobe 如何拿到参数：手搓寄存器布局

uprobe 程序触发时，参数在 CPU 寄存器里（x86_64 下前几个参数在di/si/dx）。探针为此自备了一个struct kvs_pt_regs结构体，字段顺序严格对齐 x86_64 的pt_regs：

struct kvs_pt_regs { __u64 r15, r14, r13, r12, bp, bx; __u64 r11, r10, r9, r8; __u64 ax, cx, dx, si, di; // 用户态 ABI：parm1=di, parm2=si, parm3=dx ... };

两个 uprobe 程序分别对应两个钩子：uprobe_hook_accept从di拿新 fd 号登记进tracked_fds；uprobe_hook_inbound从di/si/dx拿 fd、缓冲指针、长度，直接走emit_user_chunks分片拷进 ringbuf。核心采集逻辑和 tracepoint 路径完全共用，只是入口不一样。

8.4 attach 细节：先解析 ELF 再挂

uprobe 要指定"挂到哪个函数的哪个地址"。旁路进程先读主库的/proc/<pid>/exe得到可执行文件路径，再用 libelf 遍历符号表，找到kvs_repl_probe_hook_accept/_inbound这两个函数的符号偏移，然后：

lk = bpf_program__attach_uprobe(prog, false, master_pid, exe, (size_t)off);

进程号 + 可执行文件 + 函数偏移，三要素齐了才能把 uprobe 精确挂到主库进程里那个钩子上。如果主库不是用NET=uring编译的，符号不存在，attach 直接失败——旁路进程 exit≠0，主库软降级回 tcp。所以这也是一道隐形的"编译期一致性校验"：uprobe 方案天然要求主库二进制和旁路探针的预期匹配。

8.5 三模式对比与降级矩阵

至此三种网络后端的旁路方案就齐了：

• coro / epoll（走经典系统调用）：tracepoint 采集recvfrom/read/accept，纯探针方案；
• uring（异步队列）：tracepoint 只能采 close/dup 这类仍走 syscall 的事件，入站字节靠主库空钩子 + uprobe。

而配置层面始终有三个档位：repl_incr_accel=ebpf（强制 eBPF，失败软降级 tcp）、=auto（能用就用，失败静默回 tcp）、=tcp（根本不拉起旁路）。不论哪个后端、哪档配置，失败的最后归宿都是 tcp。这个"永远有 tcp 兜底"的设计，在 io_uring 这种最特殊的场景下是最后的保险。

8.6 教训

io_uring 案例浓缩成一句话：tracepoint 只覆盖"经典系统调用路径"，异步 IO、用户态库、非标准 IO 都可能绕过它。遇到这种场景，与其在内核里找更多 hook，不如回到"目标程序自己最懂自己"的原则——在主库里埋一个极简的 noinline 空钩子，把"数据到了"这个事实暴露出来，再用 uprobe 在钩子入口接住。钩子没有业务逻辑、不影响性能（空函数）、随编译开关可选，这是"程序可观测性接口"的一种轻量做法，也是 eBPF 用户态探针的标准姿势。

第 9 章：构建、验收、排错与展望

9.1 构建策略：缺依赖不炸主工程

项目对 eBPF 相关依赖采取"缺了也能编过"的构建策略：

• 无 clang：跳过编译kvs_repl_probe.bpf.o，主程序、旁路进程、测试照常编；
• 无 libbpf：旁路进程仍编出来（不带-DKVS_HAVE_LIBBPF），运行时加载那一步失败，主库自动降级 tcp；
• 无 root / CAP_BPF：探针 attach 失败，同样降级 tcp。

所以"eBPF 没装上"绝不会导致整个服务起不来——它只是让旁路功能不可用。这套策略的核心是：eBPF 在项目里是可选加速，不是硬依赖。

9.2 验收：怎么确认旁路真的在工作

项目自带一个降级验收脚本scripts/check_repl_ebpf_degrade_07b.sh，人工触发"无权限、端口占用、缓冲满、旁路口断"等至少 3 项，确认每一项都按预期软降级。常规联调时，主要看日志关键字：

• 主库启动打印增量=ebpf——旁路真正生效（而不是悄悄退回了 tcp）；
• 旁路打印VSET→向量 SET v0x02 …——VSET 语义化路径在走；
• 想验证"从库真的收到了向量"，对从库发一次改写问句的VGET，命中即为整条链路打通。

排错辅助工具：bpftool prog list/bpftool map dump看探针和 Map 是否在；内核报错一般直接出现在旁路 stderr（如EPERM、EADDRINUSE），主库侧只有一句"回退 tcp"。

9.3 常见坑速查（全部出自本项目真实踩坑）

1. 权限：加载需要 root/CAP_BPF；setcap在 nosuid 挂载上无效（本机仓库就这样），改用repl_ebpf_sudo=1让主库 sudo 拉起旁路。
2. tracepoint 参数布局：__syscall_nr在第 8 字节，真参数从第 16 字节起——别把系统调用号当 fd。
3. MSG_PEEK 重复采集：peek 和真实 recv 读到同一份字节，会重复组帧前缀，探针要显式跳过。
4. dup 后 fd 迁移：主库握手 dup 出新 fd 并 close 原 fd，探针要跟 dup/dup2/dup3 才能继续监听控制面。
5. 大包分片：一次 recv 可达 16KiB，只拷第一片 512B 会导致长答案组帧残缺、语义永不命中——必须完整 32 片。
6. fd 复用：close 后要清用户态组帧缓冲，否则新连接拼上旧半包。
7. io_uring：tracepoint 听不到异步读写，需要主库 noinline 钩子 + uprobe。
8. ringbuf 顺序：先抽干 ringbuf 再处理控制面 FINISHED，否则可能丢写命令。

这些坑几乎每一个都对应一次线上事故或联调失败。eBPF 教程不会教你这些，因为它们藏在真实系统的交互细节里——这正是一篇"以真实项目为教材"的博客最有价值的地方。

9.4 展望

这套旁路方案还有几个值得继续深挖的方向：

• CO-RE / BTF 迁移：当前探针手搓结构体布局（tracepoint 参数、pt_regs），是硬编码了当前内核版本；用 BTF + CO-RE 可以做到探针跨内核版本免重编译，代价是引入 CO-RE 的 libbpf 依赖。
• 从"观察"到"介入"：当前方案只在外面看入站字节，属于可观测性。将来若想在内核里直接做响应式处理（比如按命令类型分流），可以借鉴 sockmap 的思路，但要吸取旧方案"在内核里做太多"的教训。
• 把"旁路即中间件"的模式推广：VSET 语义化已经证明，旁路进程可以对接外部服务（embedding）、做格式转换，再反向投递。这套"探针观察 + 用户态中间件"的模式，完全可以复用到数据脱敏、审计、流控等场景。

结语

回头看，这条博客从 eBPF 的理论底座出发（验证器怎么保证安全、程序类型怎么选、Map 怎么传数据），经过一段程序从源码到运行的全流程（clang 编译、libbpf 加载、attach、ringbuf），最终落回到一套真实跑在生产上的旁路复制系统：探针偷听主库入站字节 → 用户态组帧、白名单过滤 → VSET 语义化对接 embedding → 会话状态机投递从库 → 监督重启与 tcp 兜底，外加 io_uring 这种"探针听不到"场景的 uprobe 解法。

这条链路上几乎每一行都踩过真实的坑：验证器的循环展开约束、tracepoint 的偏移布局、MSG_PEEK 的重复采集、dup 的 fd 迁移、512B 分片的长答案截断、fd 复用污染、nosuid 下 setcap 失效、io_uring 绕过系统调用……eBPF 的知识从来不在 API 表里，而在这些"为什么"和"怎么绕"里面。

最后留一句我认为最重要的设计心得：生产环境用 eBPF，一定要留一条不走 eBPF 的退路。本项目里这条退路就是 tcp 增量——旁路崩了、权限没了、内核不兼容了，主从同步依旧正确，只是慢一点。eBPF 是优化项，正确性永远有兜底，这既是工程的务实，也是对新技术的敬畏。