eBPF map 完全指南：内核态与用户态的数据共享与选型实战

我第一次被 eBPF 映射（eBPF map）教做人，是在一个很朴素的场景：想统计每个进程在单位时间内打开了多少次文件。按照普通 C 编程的惯性，我一开始直接在 BPF 程序里声明了一个全局数组，结果加载时直接被 verifier 拒绝。后来把代码改成 map，用lookup/update把逻辑理顺，问题才真正解决。这篇文章我就把对 eBPF map 的理解整理出来：它到底是什么、内核里怎么存、常用类型怎么选、用户态和内核态的读写路径有什么不同，最后给一个能直接跑起来看的 demo。不管你是刚接触 eBPF 的新手，还是已经写过几个探针但没深究过 map 原理的开发者，这份内容应该都能帮到你。

1. eBPF 映射是什么：内核与用户态之间的“共享黑板”

很多人把 eBPF map 当成一个简单的 key-value store，用起来也确实像。但我更愿意把它比喻成一块“内核黑板”：BPF 程序运行在内核态，往黑板上写字；用户态程序通过系统调用读取、修改同一块黑板上的内容。这块黑板由内核统一管理，有明确的大小、类型和访问权限，不是谁都能乱摸的。

1.1 为什么 BPF 程序里不能随便写全局变量

BPF 程序不是普通用户态进程，它被加载进内核之后，以一组受限指令的形式附加到某个事件上。verifier 会检查程序里的每一次内存访问，普通全局变量意味着可读写的地址范围无法被精确追踪，这在内核安全模型下是不可接受的。同时，BPF 程序的栈空间被限制在 512 字节，执行完一次回调之后，任何“局部”状态都随栈帧消失。要做跨事件、跨上下文的累计和缓存，就必须有一个显式的、内核统一分配的数据结构，也就是 map。

这里多说一句：即使你写出了“全局变量”，底层也逃不开 map。现代编译器和加载器会把.data/.bss/.rodata段映射成一个隐藏的数组 map，你的“全局变量”实际上是这个 map 的 value。所以理解 map，其实是理解整个 BPF 程序内存模型的基础。

1.2 映射的三个核心能力

第一个能力是双向数据共享。内核态 BPF 程序可以查询、更新 map；用户态程序也可以用 fd 访问同一个 map，传入规则、读取统计、删除过期数据。第二个能力是类型多样性。map 不是只有 hash 和 array 两种，它还包括 per-CPU 计数器、队列、栈、程序数组、事件环形缓冲等，基本覆盖了各种访问场景。第三个能力是安全边界。所有对 map 的访问都要经过类型和大小检查，BPF 程序侧由 verifier 把关，用户态侧由系统调用参数校验把关，越界和类型混淆在一开始就会被拦下来。除此之外，map 还支持 pin 到 bpffs 文件系统，让两个独立进程可以共享同一份数据，这个特性在长期运行的监控 agent 里尤其有用。

2. 映射的内核实现：从 fd 到哈希桶

2.1 bpf_map 结构体与文件描述符

在内核里，每个 map 都有自己的struct bpf_map。用户态拿到的 fd 不是一个 bpf_map 的句柄，而是一个 file 对象，file 的private_data指向对应的bpf_map。bpf_map的头部字段包括引用计数、map 类型、key 大小、value 大小、最大条目数、map 名称，以及一个最关键的东西：ops函数指针表。每种 map 类型都实现自己的ops，里面放着map_alloc、map_free、map_lookup_elem、map_update_elem、map_delete_elem、map_get_next_key等函数。

这套设计让用户态可以用同一套bpf()系统调用操作所有类型的 map，而不需要关心内部布局。你创建一个 hash map 和一个 array map，拿到的 fd 都是整数，但对应的内核对象和操作函数完全两样。创建 map 的底层代码长这样：

union bpf_attr attr; memset(&attr, 0, sizeof(attr)); attr.map_type = BPF_MAP_TYPE_HASH; attr.key_size = sizeof(__u32); attr.value_size = sizeof(__u64); attr.max_entries = 1024; int fd = syscall(__NR_bpf, BPF_MAP_CREATE, &attr, sizeof(attr));

实际工程里很少直接写syscall，一般用 libbpf 的bpf_map_create或者 BCC 的上层 API，但最终都会走到这个系统调用。key_size和value_size的单位是字节，而且 key/value 都是“哑字节”，内核不去理解你存的是整数、结构体还是字符串。这正是后面容易踩坑的地方。

2.2 哈希表与数组的底层差异

哈希表在内核里的实现集中在kernel/bpf/hashtab.c，对象名一般叫htab。它维护一个 bucket 数组，每个 bucket 是一条链表的头。bucket 的数量并不直接等于max_entries，而是从较小值开始动态扩容，当元素数量超过容量的 75% 时会翻倍并 rehash。所以哈希 map 的内存占用不是创建时就固定的，会根据实际插入量增长。查找时，内核用哈希函数（例如 jhash）把 key 变成一个哈希值，再用哈希值定位桶，然后沿着链表逐个对比 key。碰撞多的时候会退化成线性扫描，吞吐会下来，所以max_entries不能随意设得太小。

数组 map 则完全不同。它在创建时一次性分配max_entries * value_size的连续内存，key 必须是0到max_entries-1的整数索引。查找直接用key * value_size计算内存偏移，连哈希都不用算，速度是几类 map 里最快的。数组 map 基本不支持 delete，因为删除一个槽位会让“数组”语义变得很奇怪；更新某个 key，本质就是覆盖掉对应槽位的 value。如果你的需求是做快速索引和查表，比如网络规则表、CPU 编号统计表，优先考虑数组。

2.3 并发访问与同步机制

BPF 程序允许在多个 CPU 上并发执行，同一个 key 可能被同时更新，这就需要同步机制。哈希表在更新和删除时需要拿到对应 bucket 的锁，查找尽量走 RCU 或无锁路径，避免在 BPF 程序里产生阻塞。BPF 程序不允许睡眠，拿一个短暂的 spinlock 可以，但长时间持锁是致命伤。很多 map 类型都针对这个场景做了优化：per-CPU 哈希和 per-CPU 数组给每个 CPU 一份独立的 value 槽位，程序更新自己的槽位，完全不需要跨 CPU 加锁；用户态读取时再把所有 CPU 的值求和。

如果用的是普通 hash map 做计数器，多个 CPU 同时更新同一个 key，就会出现“读出来小、实际调用多”的问题。解决方案是在 BPF 代码里用原子指令__sync_fetch_and_add，或者干脆换 per-CPU map。我一直建议，高频计数场景优先考虑 per-CPU 结构，别为了写法简单就猛怼普通 hash，后面排查数据不准非常头疼。

2.4 map 的生命周期管理

map 创建之后，引用计数至少为 1。用户态每持有一个 fd，用户引用加一；BPF 程序在加载时，relocation 会把 map fd 转换成内核 map 对象的指针，同时增加内核引用。引用计数归零之后，内核才回收 map 的内存。如果开了 pin，map 会挂在/sys/fs/bpf下，只要 pin 文件还在，即使没有任何 fd 和程序引用，map 也不会被释放。这个机制让 map 可以跨进程共享，也方便你用命令行工具bpftool直接查看一个正在运行的 map 里到底存了什么。

3. 映射类型速查与选型思路

3.1 一张表看清常见映射类型

我平时查资料时最喜欢先看速查表，这里直接给出一版常用类型对照：

表格里“无 key”的意思，不是说 key_size 是 0 就行那么简单，而是 STACK/QUEUE/RINGBUF 在操作接口上根本没有 key 参数，使用的辅助函数也完全不同。

3.2 哈希还是数组：两个典型场景的选择

选型时先问自己一个问题：key 是稀疏的还是连续的，需要删除还是只更新？

比如要统计进程打开文件次数，key 是 PID。理论上 PID 范围可能到几百万，但同时活跃的进程可能只有几百。用数组就得按最大 PID 上限预分配，内存浪费严重；用哈希则只保存活跃 PID 的条目，内存随实际数量增长，但每次 lookup 都有哈希计算，比数组慢。反过来，如果 key 是 CPU 编号、网卡队列编号，或者一段连续的枚举值，用数组最快，没有任何哈希开销。

再比如你需要在 BPF 程序里维护一个“来源 IP 是否允许”的规则表。IP 是 32 位整数，但还是一个稀疏集合，适合哈希。而且规则表会不断增删，哈希的 delete 语义很自然。数组的 delete 基本不可用，只能通过更新成特殊值来模拟“删除”，所以动态增删场景首选哈希。

3.3 扩展类型：LRU、队列/栈、程序数组与环形缓冲

LRU_HASH 适合做缓存，比如有限的 per-host 限流表。当条目超过max_entries，它会按近似 LRU 淘汰最久没访问的 key，防止 map 无限膨胀。队列和栈则提供了 FIFO/LIFO 语义，操作接口是bpf_map_push_elem、bpf_map_pop_elem、bpf_map_peek_elem，适合在内核里传递短暂生命周期的事件对象。

PROG_ARRAY 是我个人觉得最特别的一种 map。它的 value 存的是另一个 BPF 程序的 fd，在 BPF 程序里通过bpf_tail_call按 key 跳转到对应程序。更新 PROG_ARRAY 的内容，相当于动态替换了主程序的“子逻辑”，但又不必重新加载整个主程序。很多可编程包处理方案就是靠 prog array 把流量分类到不同的处理程序里。

RINGBUF 是现在新项目里首选的用户态数据导出方式。BPF 程序通过bpf_ringbuf_reserve申请一块记录内存，填充完数据后bpf_ringbuf_submit提交；用户态侧 mmap 同一块环形缓冲区，直接消费记录。它支持可变长记录，多个 CPU 可以共用，批量吞吐比老式的 PERF_EVENT_ARRAY 更平滑。

3.4 map-in-map：用映射索引映射

map-in-map 指的是外层 map 的 value 不是普通数据，而是另一个 map 的 fd。BPF 程序先从外层 map 里lookup，拿到内层 map 指针，再对内层 map 做第二次lookup。这个结构能让程序根据运行时条件切换不同的统计表，或者按 CPU 选择隔离的数据集。

创建外层 map 时有个细节：必须先创建一个 inner map template，把它的 fd 通过 attr 传给内核，否则 verifier 无法确定内层 map 的类型、key 大小和 value 大小。之后向内外 map 写入内层 fd 时，内核会检查 fd 指向的 map 是否和 template 兼容，不兼容会直接报错。虽然 map-in-map 首次接触会觉得绕，但在复杂监控和策略引擎里，它几乎是必需品。

4. 从用户态到内核态的读写路径

4.1 bpf 系统调用与 union bpf_attr

用户态对 map 的所有操作，最终都落到bpf()系统调用的不同命令字上。创建用BPF_MAP_CREATE，读取用BPF_MAP_LOOKUP_ELEM，更新用BPF_MAP_UPDATE_ELEM，删除用BPF_MAP_DELETE_ELEM，遍历用BPF_MAP_GET_NEXT_KEY。这些命令的参数全部塞进union bpf_attr。libbpf 的bpf_map_lookup_elem(fd, key, value)，本质上就是 syscall 的一层轻封装，不允许绕过。

一个容易被忽略的点是BPF_MAP_UPDATE_ELEM的 flags。BPF_ANY表示存在就更新、不存在就插入，BPF_NOEXIST只有不存在时才插入，BPF_EXIST只有存在时才更新。自己写工具时如果不小心用了BPF_NOEXIST去更新一个已经存在的 key，内核会返回EEXIST，容易让人误以为 map 出 bug 了。

4.2 lookup/update/delete 背后发生了什么

用户态 lookup 的完整链路是：先把 key 从用户空间复制到内核缓冲区，调用对应 map 的ops->map_lookup_elem，找到 value 后再复制回用户空间。如果 key 不存在，返回ENOENT。这个链路包含两次数据拷贝加一次系统调用，成本在微秒级。如果你在高频循环里一条条 lookup 用户态数据，吞吐会非常难看。

BPF 程序侧的 lookup 路径则完全不同。加载时，map fd 已经被改写成内核 map 对象的指针，辅助函数是直接对内存地址操作，没有系统调用。单次 lookup 的开销通常在几十纳秒量级，比用户态快一个数量级以上。所以设计原则很清楚：能放进 BPF 里做的计数和过滤，就放进 BPF；用户态只负责低频汇总、配置下发和故障排查。verifier 会检查 key/value 大小和类型，一旦程序里定义的 struct 和 map 本身定义不符，加载就会报invalid argument，这是安全模型的一部分，不是 bug。

4.3 遍历与批量操作要注意的细节

用户态遍历一个哈希 map，用的是GET_NEXT_KEY，从key=NULL拿到第一个有效 key，然后一路拿 next。哈希表的遍历顺序不保证稳定，而且遍历过程中如果有并发增删，可能出现跳过、重复或者短暂的不一致。对于监控场景，最好先把数据一次性拉到用户态，再在用户态排序和过滤。

较新内核里还提供了批量接口，如BPF_MAP_LOOKUP_BATCH、BPF_MAP_UPDATE_BATCH、BPF_MAP_DELETE_BATCH，一次系统调用处理多条记录，能明显减少用户态频繁操作时的 syscall 开销。批量 lookup 要求用户态提前准备足够大的 value buffer，否则返回ENOSPC。我个人处理大 map 时，一般都会走 batch 而不是GET_NEXT_KEY循环，省时间也省 CPU。

5. 实操：用 eBPF map 统计进程打开文件数

5.1 先想清楚 key 和 value 怎么设计

这个 demo 的目标是统计每个进程用openat打开文件的次数。key 用进程 ID（严格说是 tgid，即线程组 ID），因为用户态看到的是进程 ID；value 用u64计数，避免统计时间稍长就溢出。为什么不用数组？同时活跃的进程数量远比 PID 范围小，哈希 map 只保存活跃进程的条目，内存使用更合理。这里为了演示 insert 和 update 的差异，故意选择普通 hash map；如果是生产环境长期采集，建议换 per-CPU 结构。

5.2 内核侧 BPF 代码：查找与原子累加

下面是完整的 BCC 脚本，内核侧用TRACEPOINT_PROBE宏挂到sys_enter_openat探针上：

from bcc import BPF import time bpf_text = """ #include <uapi/linux/ptrace.h> BPF_HASH(counts, u32, u64); TRACEPOINT_PROBE(syscalls, sys_enter_openat) { u32 pid = bpf_get_current_pid_tgid() >> 32; u64 *val = counts.lookup(&pid); if (val) { __sync_fetch_and_add(val, 1); } else { u64 one = 1; counts.update(&pid, &one); } return 0; } """ b = BPF(text=bpf_text) print("Monitoring openat syscalls, sleep 5 seconds...") time.sleep(5) counts = b["counts"] result = [] for k, v in counts.items(): result.append((k.value, v.value)) for pid, cnt in sorted(result, key=lambda x: x[1], reverse=True)[:20]: print(f"pid={pid:<6} opens={cnt}")

这里的关键是bpf_get_current_pid_tgid() >> 32。这个 helper 返回一个u64，高 32 位是 tgid，低 32 位是当前线程的 pid。我们按用户态习惯统计进程 ID，所以要取高 32 位。counts.lookup(&pid)返回一个指向 value 的指针，首次调用某 PID 时返回 NULL，于是走update把初始值 1 写进去；以后每次进来都用原子指令自增，避免多 CPU 并发更新导致丢计数。

5.3 用户态读取 map 数据

用户态侧，BCC 把 map 暴露成b["counts"]，你可以直接调用.items()遍历所有 KV。这里我把结果存成列表，再按打开次数降序打印前 20 个进程。注意用户态拿到的 value 是u64，但 BCC 会包装成带.value属性的对象，所以打印时要用v.value。这个脚本在 root 权限下运行 5 秒就能看到结果，不需要自己管理 fd，BCC 已经在背后帮你完成了 map 的创建、加载和 hook。

如果你不想写 Python，只想快速验证 map 里的数据长什么样，可以改用 bpftool。

5.4 用 bpftool 现场验证 map 的变化

bpftool 是排查 map 问题最直接的工具。先把上面的脚本跑起来，然后在另一个终端执行：

sudo bpftool prog show sudo bpftool map show sudo bpftool map dump name counts

prog show能看到加载的 BPF 程序，map show能看到当前内核里注册的所有 map，包括名字、类型、key/value 大小、max_entries 和当前条目数。map dump name counts会把 map 里的所有 KV 打印出来，每次执行看到的值都在增长时，说明内核侧的 update 逻辑生效了。如果没有挂载 bpffs，bpftool可能找不到/sys/fs/bpf，可以手动挂载：

sudo mount -t bpf bpf /sys/fs/bpf

这个验证方式特别适合 debug：你先在程序里插入你怀疑没被更新的 key，再用bpftool map dump看那一个 key 是否存在，比自己在用户态打日志快得多。

6. 常见问题与排查记录

6.1 create 时报 “cannot allocate memory”

这是创建 map 最常见的报错之一，但真实原因往往不是物理内存不够。一种是max_entries设得太大，尤其用哈希时还要考虑桶扩容、per-CPU 数组要按 CPU 数倍增内存；另一种是旧内核上的 RLIMIT_MEMLOCK 限制，导致进程虽然内存充足，但内核不允许 BPF 对象占用更多锁页内存。

排查思路：先看内核日志，dmesg | tail通常会有 bpf 相关提示。如果是 memlock 限制，可以临时调大ulimit -l，或者用现代内核里的 cgroup 内存统计看是否被 cgroup 限额挡住。创建 map 时也要注意max_entries只是上限，不是预分配，对于哈希 map，实际内存会随着条目增长逐步增加，不要一看 map 创建成功就觉得内存已经占满。

6.2 key/value 大小不一致：见鬼的 0 和 invalid argument

这个问题我踩过不止一次。BPF 的 map 把 key 和 value 都当作字节数组，结构体大小必须和key_size/value_size严格一致。C 语言存在对齐，比如一个结构体：

struct value { __u32 a; __u64 b; };

如果直接填sizeof(struct value)，实际大小可能是 16 而不是 12，因为b要 8 字节对齐。用户态如果另一个定义没有相同对齐，就会出现 key 能查到但 value 内容“错位”的诡异现象。

解决办法其实很粗暴：在代码里加一段printf("sizeof=%zu offsetof=%zu\n", sizeof(...), offsetof(...))，然后对照填到 map 定义里。如果确实要压缩布局，就用__attribute__((packed))，但必须保证 BPF 侧和用户态侧都使用同一个头文件，避免两边定义漂移。

6.3 计数不准确：原子性、并发和 per-CPU

普通 hash map 在多个 CPU 上同时更新同一个 key 时，如果只是“读出来 +1 写回去”，在并发下会丢失更新。我在文章里给的 demo 使用了__sync_fetch_and_add，这是为了规避这个问题。更稳妥的长线方案是换PERCPU_HASH或PERCPU_ARRAY：每个 CPU 写自己的 value，用户态汇总求和。但要注意，per-CPU map 的 value 是一个数组，数组长度等于 CPU 数量，用户态读取时不能只取一个元素，否则你看到的只是某个 CPU 的局部计数。

另外，用户态如果直接bpf_map_update_elem覆盖同一个 key，也可能把 BPF 程序正在自增的值整体覆盖掉。建议用户态只读和清零，不要在内核程序运行期间用整值覆盖的方式“修改”统计字段。

6.4 ringbuf 还是 perfbuf：数据导出的选型

如果你要把 BPF 程序里的事件一条条发给用户态，老接口是PERF_EVENT_ARRAY，新接口是RINGBUF。PERF_EVENT_ARRAY 按 per-CPU 环形缓冲组织，用户态需要绑定到固定 CPU 才能消费；RINGBUF 是单缓冲多生产者，支持可变长记录和 reserve/commit，性能通常更好，已经成为新项目的默认选择。

选型时也不用纠结很久：新项目无脑用 RINGBUF，除非你维护的旧代码已经基于 perf event。RINGBUF 一条记录最大能到多少，取决于max_entries和内核页大小，理解成一块共享内存就行。用户态读取时注意处理BPF_RINGBUF_BUSY和BPF_RINGBUF_DISCARD的标签，前者说明记录还没写完，后者说明程序主动丢弃了这条记录，不要当成数据错误。

写在最后的一点经验

我以前调试一个 map 程序，用户态拿到的 key 一直是对的，value 却全是 0，后来发现是用户态结构体定义多了 4 字节 padding。这种问题不亲眼见一次，很难第一时间想到。现在我的习惯是：写任何涉及 map 的代码，都先用一个小工具打印一遍sizeof(key)、sizeof(value)和offsetof，再填key_size/value_size。另一个教训是：能用 per-CPU 就别用普通 hash 做高频计数器；能一次批量读取就别在用户态循环单条 lookup。eBPF map 本身不复杂，复杂的是你常常忘了自己正站在内核态和用户态的交界处。