Moby NetworkDB 抓包分析实战：用 Wireshark Lua 插件解码 memberlist 与 NetworkDB Gossip 协议

本文围绕 Moby 仓库 contrib/wireshark 目录下随源码提供的两个 Wireshark Lua 插件（memberlist.lua 与 moby-networkdb.lua）及配套说明文档，完整讲解如何配置 Wireshark 解码 Docker/Moby 底层网络库 NetworkDB 的节点间 gossip 通信：包括插件安装、ProtoBuf IDL 搜索路径配置、memberlist 用户数据子分析器挂载、加密密钥日志（NETWORKDBKEYLOGFILE）解密分析，以及已知问题与局限性的处理办法。读完后你将能够把 dockerd 产生的抓包文件解码为可读的 NetworkDB 消息层次结构。

1. 背景：NetworkDB 报文为什么"裸眼"不可读

NetworkDB 是 Moby 网络库（libnetwork）的分布式键值存储层，负责在集群节点间同步网络附着、overlay 端点记录等状态。其节点间通信分两层：

• 底层传输：基于 hashicorp/memberlist 的 gossip 协议，报文经 msgpack 序列化，通过 TCP/UDP 收发；
• 上层载荷：memberlist 的 "User" 消息（opcode 8）中携带 NetworkDB 的 GossipMessage，该消息以 protobuf 序列化。

三层编码（msgpack 外壳 + protobuf 内壳 + memberlist 可选 AES-GCM 加密）意味着直接抓包看到的只是二进制乱码。contrib/wireshark 目录下的插件正是为此而生，配合仓库内随源码发布的 .proto IDL 文件（daemon/libnetwork/networkdb/networkdb.proto、daemon/libnetwork/drivers/overlay/overlay.proto），可让 Wireshark 完整还原报文结构。

2. 两个 Lua 插件的分工

2.1 memberlist.lua：通用 memberlist 协议分析器

contrib/wireshark/memberlist.lua 注册了名为 memberlist 的协议，可解码 memberlist 的 TCP 和 UDP 报文。从源码看，它定义了完整的字段集（memberlist.message_type、memberlist.crc、memberlist.encryption.*、memberlist.userdata 等，见 memberlist.lua 第 22-55 行），支持的消息类型枚举与 memberlist 协议一致：Ping(0)、IndirectPing(1)、ACKResp(2)、Suspect(3)、Alive(4)、Dead(5)、PushPull(6)、Compound(7)、User(8)、Compress(9)、Encrypt(10)、NACKResp(11)、HasCRC(12)、Err(13)、HasLabel(244)。

该分析器在运行时按 opcode 分派处理逻辑（memberlist.lua 第 122-232 行）：

• User 消息（opcode 8）：这是 NetworkDB 报文的载体。TCP 流上会先解出 msgpack 头（含 UserMsgLen），再把消息体交给"用户数据子分析器"（dissect_userdata 函数，第 67-84 行）；UDP 上则直接将整个剩余缓冲交给子分析器。
• Encrypt 消息（opcode 10）：解析 4 字节密文长度，尝试用密钥日志中的密钥解密后递归分析内层报文；
• Compound（opcode 7）/ PushPull（opcode 6）/ HasLabel（opcode 244）/ HasCRC（opcode 12）/ Compress（opcode 9）：分别处理组合报文拆分、push/pull 头中的节点表与用户状态段、标签剥除、CRC32 校验（内置了纯 Lua 实现的 CRC32 与 Go 标准库 compress/lzw 的移植版解压器，见文件末尾的 Library definitions 段）。

它对外暴露三个 Wireshark 偏好项（preferences）：

偏好项	名称	默认值	说明
memberlist.userdata_dissector	User Data Dissector	（空）	应用到 User 消息体上的分析器名称
memberlist.ports	Memberlist TCP+UDP Port(s)	7946	分析器挂载的 TCP/UDP 端口范围，可设多值如 7946,10000-10999
memberlist.keylog	Encryption Key Logfile Path	（空）	十六进制密钥文件路径，每行一个密钥

端口偏好在变更时会自动从 tcp.port/udp.port 分析器表中注销旧端口并注册新端口（prefs_changed 回调，第 236-244 行）。

2.2 moby-networkdb.lua：NetworkDB gossip 子分析器

contrib/wireshark/moby-networkdb.lua 注册名为 networkdbgossip 的协议，负责解码 NetworkDB gossip 消息。由于 NetworkDB 的节点间通信是封装在 memberlist 的 User 消息里的，因此必须让 memberlist 分析器把用户数据委托给 networkdbgossip（下文第 4.4 节配置）。

从源码看，它的解码策略是"两级 protobuf 解码 + 类型分派"：

1. 先把整个缓冲区当作 networkdb.GossipMessage 交给 Wireshark 内置的 ProtoBuf 分析器（第 22-24 行），拿到 pbf.networkdb.GossipMessage.type 和 pbf.networkdb.GossipMessage.data 两个字段；
2. 按 type 字段值查表得到具体消息类型（第 7-14 行）：

type 值	解码为
1	networkdb.NetworkEvent
2	networkdb.TableEvent
3	networkdb.NetworkPushPull
4	networkdb.BulkSyncMessage
5	networkdb.CompoundMessage
6	networkdb.NodeEvent

这与 networkdb.proto 中 MessageType 枚举定义（NETWORK_EVENT = 1 … NODE_EVENT = 6）一一对应；

3. 把 data 字段的字节范围按上表重新交给 ProtoBuf 分析器解码（decodeas 机制，第 31-35 行），解码失败时以 PI_DISSECTOR_BUG 专家信息报错；
4. TableEvent 还需二次分派：按 pbf.networkdb.TableEvent.table_name 值把 value 字段解码为 overlay.PeerRecord（overlay_peer_table 表）或 libnetwork.EndpointRecord（endpoint_table 表），对应 moby-networkdb.lua 第 38-53 行；
5. 最后通过 protobuf_field 分析器表，把嵌套位置也挂上子分析器：networkdb.CompoundMessage.SimpleMessage.Payload 与 networkdb.BulkSyncMessage.payload → gossip_proto；networkdb.TableEvent.value → tableevent_proto（第 56-59 行）。

这些消息结构均可在 IDL 中找到定义，如 GossipMessage（type + data，networkdb.proto 第 50-54 行）、TableEvent（含 table_name、key、value、residual_reap_time 等字段，第 126-159 行）、CompoundMessage（第 177-187 行），以及 overlay 驱动同步的 PeerRecord（endpoint_ip、endpoint_mac、tunnel_endpoint_ip，overlay.proto 第 16-27 行）。

3. 安装与前置条件

3.1 安装 Wireshark 4.5 或更新版本

Wireshark 4.4 的 msgpack 协议分析器不完整，无法正确解码 memberlist 消息，因此必须使用 4.5 或更新版本。文档写作时（2025-06-30）4.5 尚未正式发布，可能需要使用 Wireshark 官方 nightly 构建。这一依赖的原因是：memberlist 分析器中多处直接调用 Dissector.get("msgpack") 解析 push/pull 头和 user 消息头（memberlist.lua 第 155 行、第 191 行），内置 msgpack 分析器不可用时这些路径全部失效。

3.2 安装插件

将 contrib/wireshark/memberlist.lua 与 contrib/wireshark/moby-networkdb.lua 两个文件复制到 Wireshark/Tshark 的 Lua 插件目录（例如用户主目录下的 ~/.config/wireshark/plugins，或在 Wireshark 首选项的 Lua Plugins 中追加路径），使两者都随启动加载。

4. Wireshark 配置步骤

4.1 配置 ProtoBuf 协议搜索路径

NetworkDB 消息序列化为 protobuf，而 protobuf 不是自描述格式，Wireshark 的 ProtoBuf 分析器必须拿到 .proto IDL 定义才能解码。步骤：

1. 获取 Moby 仓库源码（含 NetworkDB IDL 定义）；
2. 获取 protocolbuffers/protobuf 仓库源码（protobuf 的"标准库" IDL）；
3. 在 Wireshark Preferences → Protocols → ProtoBuf 中：
   • 勾选 Load .proto files on startup（protobuf.reload_protos）；
   • 勾选 Dissect Protobuf fields as Wireshark fields（protobuf.pbf_as_hf）；
   • 在 Protobuf Search Paths 表（uat:protobuf.search_paths）中依次添加：
     • path/to/protocolbuffers/protobuf/src
     • path/to/moby/moby/vendor（gogo/protobuf 等第三方 proto 依赖）
     • path/to/moby/moby
     • path/to/moby/moby/libnetwork/networkdb（勾选 "Load all files"）
     • path/to/moby/moby/libnetwork/drivers/overlay（勾选 "Load all files"）

注意：文档特别强调，只把 .proto 文件单独拷出来是不够的，必须保留目录结构，否则 IDL 无法正确加载。这一点从 IDL 自身的 import 语句可得到印证：networkdb.proto 第 3 行 是 import "github.com/gogo/protobuf/gogoproto/gogo.proto";，该文件位于 Moby 仓库 vendor/github.com/gogo/protobuf/ 目录下，所以必须把仓库根（或 vendor 目录）作为搜索路径。

另外注意：本文引用的 IDL 路径为 libnetwork/...，而 README 原文写的是仓库顶层 libnetwork/...；在当前仓库中，这些 .proto 文件实际位于 daemon/libnetwork/networkdb/networkdb.proto 与 daemon/libnetwork/drivers/overlay/overlay.proto，请据此调整搜索路径指向对应目录。

4.2 配置 Memberlist 用户数据子分析器

在 Preferences → Protocols → MEMBERLIST 中：

• 将 User Data Dissector（memberlist.userdata_dissector）设为 networkdbgossip；
• （可选）按需设置 Memberlist TCP+UDP Port(s)（memberlist.ports），例如 7946,10000-10999 这类取值对分析 NetworkDB 单元测试产生的抓包很有用（单元测试通常在 7946 之外的高位端口上并行拉起多个 memberlist 实例）。

配置生效后，memberlist 分析器在遇到 User 消息时会通过 Dissector.get("networkdbgossip") 取出该分析器并作用于消息体；若指定的分析器名不存在或调用失败，则回退为把消息体作为裸 memberlist.userdata 字节显示，并（在失败时）写入专家信息（memberlist.lua 第 67-84 行）。

5. 解密加密报文：Encryption Key Logfile

memberlist 协议分析器支持在提供密钥文件的情况下解密加密的 memberlist 消息：

• 在 Preferences → Protocols → MEMBERLIST 中设置 Encryption Key Logfile Path（memberlist.keylog）为包含加密密钥的文件；
• 文件中每行一个密钥，以十六进制字符串编码。

dockerd 可通过设置环境变量 NETWORKDBKEYLOGFILE 为文件路径，让守护进程把 NetworkDB 使用的加密密钥追加写入该文件。这一行为在源码中的实现见 daemon/libnetwork/networkdb/debug.go 第 13-47 行：logEncKeys 函数读取 NETWORKDBKEYLOGFILE 环境变量，非空时以 O_CREATE|O_WRONLY|O_APPEND、权限 0600 打开该文件，用 hex.Encoder 把每把密钥按"一行一个十六进制串"追加写入——与插件侧 io.lines(path) 逐行尝试解密的读取格式（memberlist.lua 第 103-118 行）严格对应。

解密路径在分析器中的行为：try_decrypt 只处理加密版本号为 1 的报文，按"1 字节版本 + 12 字节 nonce + 密文 + 16 字节 AEAD tag"布局拆包，依次用文件中的每个密钥执行 AES-GCM 解密并校验 tag，成功即以 Encrypted Memberlist 子树呈现各字段并返回解密后的缓冲区（memberlist.lua 第 86-120 行）。

6. 已知问题与局限性

6.1 首次启动时 NetworkDB 协议加载失败

Wireshark 首次启动时，moby-networkdb.lua 可能报错：

moby-networkdb.lua:4: bad argument #1 to 'new'
(Field_new: a field with this name must exist)

原因是 Wireshark 自身的已知问题：插件文件顶层的 Field.new("pbf.networkdb.GossipMessage.type")（moby-networkdb.lua 第 4-5 行）在 ProtoBuf 字段尚未注册时执行会失败。

规避方法：等 Wireshark 初始化完成后重新加载 Lua 插件——

• 菜单：Analyze → Reload Lua Plugins；
• 快捷键：Ctrl-Shift-L（Windows/Linux）、⇧⌘L（macOS）。

6.2 功能局限

• 仅支持 memberlist 加密版本 1（AES-GCM 128，无填充），不支持版本 0（AES-GCM 128 + PKCS#7 填充）——与 try_decrypt 中 cryptoversion:uint() ~= 1 then return buffer 的短路逻辑一致；
• 带标签（HasLabel）的加密消息目前无法解密。

7. 小结

contrib/wireshark 提供的这套插件把 Moby NetworkDB 的抓包分析变成了可复现的流程：Wireshark 4.5+ → 加载两个 Lua 插件 → 配置 protobuf 搜索路径（保留仓库目录结构）→ memberlist.userdata_dissector 指向 networkdbgossip →（可选）NETWORKDBKEYLOGFILE 导出密钥文件并配置 memberlist.keylog。配置完成后，memberlist 层的 PushPull/Compound/User 消息、加密层、msgpack 头，直到 NetworkDB 层的 GossipMessage 及其 TableEvent/PeerRecord 等具体载荷，都会在 Wireshark 的协议树中以结构化字段呈现，为排查 overlay 网络状态同步、节点发现等问题提供了协议级的观测手段。