gNMI Collector 配置指南:完整看懂 target.proto 配置文件与 grpctunnel 隧道支持
gNMI Collector 配置指南:完整看懂 target.proto 配置文件与 grpctunnel 隧道支持
gNMI(gRPC Network Management Interface)Collector 是 gnmi 仓库提供的缓存式数据采集器:它连接多个 gNMI 目标设备,将数据缓存后通过单一 Subscribe RPC 对外提供。本文将带你完整看懂它的核心配置文件 target.proto,以及如何启用 grpctunnel 隧道支持,让你快速上手配置。
📦 认识 gNMI Collector
gNMI Collector(二进制入口为 gnmi_collector.go)启动后做三件事:
- 读取配置文件:解析 protobuf 文本格式(textproto)的 target.proto 配置;
- 连接目标设备:按配置逐个建立 gNMI 订阅连接,把通知数据写入缓存;
- 对外提供服务:在同一端口提供 gNMI Subscribe RPC(代理订阅)、Collector Reconnect RPC(强制重连目标),以及 grpctunnel 隧道服务。
启动时必须指定四个参数,缺一不可(见 gnmi_collector.go):
| 参数 | 说明 |
|---|---|
-config_file |
target.proto 配置文件路径 |
-cert_file |
TLS 证书文件 |
-key_file |
TLS 密钥文件 |
-port |
服务监听端口 |
另有可选参数:-dial_timeout(拨号超时,默认 1 分钟)、-metadata_update_period 和 -size_update_period(周期性元数据/缓存大小更新,0 表示关闭)。
📄 target.proto 配置文件结构
配置文件的格式由 proto/target/target.proto 定义,顶层是一个 Configuration 消息,包含 5 个字段:
1. request:订阅请求表
一个以字符串为 key 的 SubscribeRequest 映射表。每个订阅至少包含带 origin 的 prefix 和一条或多条 subscription,仅支持 STREAM 模式。
request: <
key: "interfaces"
value: <
subscribe: <
prefix: < origin: "openconfig" >
subscription: <
path: < elem: < name: "interfaces" > >
>
>
>
>
多个 target 可以共享同一个 key 对应的订阅,实现"配置复用"。
2. target:目标设备表
以目标名称为 key 的 Target 映射表,每个 Target 包含:
| 字段 | 必填 | 说明 |
|---|---|---|
addresses |
✅ | 地址:端口列表(或可解析名称) |
credentials |
❌ | 鉴权信息:username、password、password_id |
request |
✅ | 引用 request 表中的 key,决定订阅什么数据 |
meta |
❌ | 附加目标元数据(字符串键值对) |
dialer |
❌ | 拨号方式;留空用默认直连,填 tunnel 走隧道(下文详述) |
3. instance_id / meta / revision
instance_id:Collector 实例标识;meta:配置级附加元数据;revision:版本号。动态更新配置时,新 revision 必须严格递增,否则被拒绝(见 target.go 的校验逻辑)。
配置示例对照
仓库提供了可直接参考的示例:
- 普通直连示例:testdata/good.cfg
- 隧道示例:testdata/good_tunnel.cfg
- Docker 部署示例:docker/config/example.cfg
直连配置的 target 部分只需填真实地址:
target: <
key: "target1"
value: <
addresses: "127.0.0.1:9998"
request: "interfaces"
credentials: <
username: "username"
password: "password"
>
>
>
⚠️ 常见配置错误与校验规则
Collector 启动时会调用 Validate 校验配置,以下问题会直接导致启动失败:
| 错误场景 | 报错信息 |
|---|---|
| 目标名为空 | target with empty name |
| 目标缺少地址 | target "xxx" missing address |
| 目标未指定 request | target "xxx" missing request |
| request key 在表中不存在 | missing request "protocols" for target "target1" |
最后一条最典型:testdata/bad.cfg 中 target 引用了 "protocols",但 request 表里只有 "interfaces",因此校验不通过。记住口诀:target.request 必须能在 request 表中找到对应 key。
配置文件本身若不符合 protobuf 文本语法,则会报 Could not parse configuration 错误。
🚀 最快启动方法
本地二进制方式:
gnmi_collector -config_file example.cfg -cert_file cert.pem -key_file key.pem -port 8888
Docker 方式(仓库自带镜像构建文件):执行 docker/run.sh,它会挂载 config 目录并以 tcp/8888 端口运行,详见 docker/README.md。
启动后可用 gnmi_cli 命令行工具连接 8888 端口验证订阅数据。
🌐 grpctunnel 隧道支持
为什么需要隧道?
某些目标设备(如网络节点)无法被 Collector 主动访问——处于 NAT 之后、无公网 IP 等。grpctunnel 的思路是反转连接方向:由目标主动向 Collector 发起隧道连接,Collector 再通过这条隧道"回拨"目标的 gNMI 服务。
该项目通过依赖 github.com/openconfig/grpctunnel(见 go.mod)实现,核心逻辑在 gnmi_collector.go:Collector 启动时创建 tunnel server 并注册 gRPC 服务,同时为连接管理器注册名为 tunnel 的自定义拨号器。
启用隧道的 3 个配置要点
- target 必须存在于配置中:隧道连接到达时,Collector 会检查 target ID 是否在配置表里,且类型必须是
GNMI_GNOI,否则拒绝(白名单机制,见 gnmi_collector.go); - dialer 必须显式设置:未设置
dialer的 target 会报tunnel dialer not specified错误; - addresses 字段占位即可:隧道按目标名称解析,地址无实际意义。示例中填
"use_tunnel:0"只是满足"地址非空"的校验。
完整隧道配置对照 good_tunnel.cfg:
target: <
key: "target1"
value: <
addresses: "use_tunnel:0"
dialer: "tunnel"
request: "interfaces"
credentials: <
username: "username"
password: "password"
>
>
>
当 dialer 为 tunnel 时,Collector 会自动把地址替换为目标名称(见 gnmi_collector.go),确保隧道内按名称寻址。
直连与隧道可混合使用
两种连接方式可以共存于同一份配置:dialer 留空走默认 TCP 直连,dialer: "tunnel" 走隧道。连接管理器按 target 的 dialer 字段分发拨号器(见 connection.go),互不干扰。
📝 小结
- target.proto 是 gNMI Collector 的唯一配置来源,核心是
request表和target表两张映射表,target 通过request字段引用订阅定义; - 启动时严格校验:目标必须有地址、有 request,且 request key 必须存在;
- grpctunnel 通过
dialer: "tunnel"一键启用,适合目标设备无法被直连的场景,Collector 以白名单方式控制哪些目标可以经隧道接入; - 生产环境请更换 Docker 示例中的测试证书(
cert.pem/key.pem)。
按本文对照示例配置文件逐步调整,即可完成 gNMI Collector 的完整部署。