gNMI Collector 配置指南:完整看懂 target.proto 配置文件与 grpctunnel 隧道支持

原创2026-11-15 10:51:031,651 阅读

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)启动后做三件事:

  1. 读取配置文件:解析 protobuf 文本格式(textproto)的 target.proto 配置;
  2. 连接目标设备:按配置逐个建立 gNMI 订阅连接,把通知数据写入缓存;
  3. 对外提供服务:在同一端口提供 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 的校验逻辑)。

配置示例对照

仓库提供了可直接参考的示例:

直连配置的 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 个配置要点

  1. target 必须存在于配置中:隧道连接到达时,Collector 会检查 target ID 是否在配置表里,且类型必须是 GNMI_GNOI,否则拒绝(白名单机制,见 gnmi_collector.go);
  2. dialer 必须显式设置:未设置 dialer 的 target 会报 tunnel dialer not specified 错误;
  3. 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 的完整部署。

登录后查看全文
gnmi