Telegraf inputs.teamspeak 插件：通过 ServerQuery 协议监控 Teamspeak 3 语音服务器

Telegraf inputs.teamspeak 插件：通过 ServerQuery 协议监控 Teamspeak 3 语音服务器

【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegraf

本文以 plugins/inputs/teamspeak/README.md 为主体，结合 teamspeak.go 的源码实现与 teamspeak_test.go 的测试用例，完整讲解 Telegrafinputs.teamspeak插件的接入前提、配置参数、指标清单与底层采集链路，帮助运维人员把 Teamspeak 3 语音服务器纳入统一的指标监控体系。

一、插件定位：只支持 Teamspeak 3 的 ServerQuery 采集

teamspeak是一个输入插件，用于通过ServerQuery接口采集一个或多个虚拟 Teamspeak 服务器的统计数据。根据插件 README 的明确说明：

• 目前仅支持 Teamspeak 3服务器；
• 插件自 Telegraf v1.5.0 引入，归类于server类插件，支持所有平台；
• 在插件注册文件 plugins/inputs/all/teamspeak.go 中通过_ "github.com/influxdata/telegraf/plugins/inputs/teamspeak"匿名导入完成注册，默认随标准构建编译。

ServerQuery 是 Teamspeak 3 提供的文本命令接口（通常监听10011端口），客户端登录后可发送serverinfo、serverrequestconnectioninfo等命令获取服务器状态。本插件正是基于该协议工作。

二、接入前提：ServerQuery 账户与 IP 白名单

在配置 Telegraf 之前，有两项 Teamspeak 服务端侧的准备工作（这一点是生产环境最常见的坑）：

1. 创建 ServerQuery 专用账户：Teamspeak 的常规用户不能直接执行 ServerQuery 命令，需要在服务器管理端创建一个具备 ServerQuery 权限的账户（如示例中的serverqueryuser），并记录其用户名与密码，供下文username/password使用。具体如何创建与授权，可参考官方的Teamspeak 3 Server Query Manual。
2. 配置 IP 白名单：README 中特别强调了一条注意事项——如果 Telegraf 从外部主机查询 Teamspeak 服务器，必须把 Telegraf 所在主机加入 Teamspeak Server 安装目录下的query_ip_allowlist.txt文件，否则 ServerQuery 连接会被服务器直接拒绝。

三、完整配置说明

以下是插件的完整示例配置（源自 sample.conf）：

# Reads metrics from a Teamspeak 3 Server via ServerQuery [[inputs.teamspeak]] ## Server address for Teamspeak 3 ServerQuery # server = "127.0.0.1:10011" ## Username for ServerQuery username = "serverqueryuser" ## Password for ServerQuery password = "secret" ## Nickname of the ServerQuery client nickname = "telegraf" ## Array of virtual servers # virtual_servers = [1]

各配置项的详细说明如下。其中“代码默认值”一列来自 teamspeak.go 中init()函数注册插件时的初始值：

此外，插件支持 Telegraf 全部插件通用的全局配置项（如过滤 tags/fields、别名、插件排序等），详见 docs/CONFIGURATION.md。

两点使用提示：

• 一台 Teamspeak 物理服务器上可以运行多个虚拟服务器（vServer），通过virtual_servers = [1, 2, 3]即可在同一插件实例中批量采集；
• nickname设置后，该 ServerQuery 客户端会以指定昵称短暂出现在每个虚拟服务器中，便于在服务端识别这是采集器而非普通用户。

四、采集指标与标签

插件以teamspeak为 metric 名称输出以下字段：

每条指标携带两个标签：

• virtual_server：虚拟服务器 ID（数值转为字符串）；
• name：虚拟服务器名称。

五、输出示例

插件 README 给出的真实输出示例（InfluxDB line protocol 格式）：

teamspeak,virtual_server=1,name=LeopoldsServer,host=vm01 bytes_received_total=29638202639i,uptime=13567846i,total_ping=26.89,total_packet_loss=0,packets_sent_total=415821252i,packets_received_total=237069900i,bytes_sent_total=55309568252i,clients_online=11i,query_clients_online=1i 1507406561000000000

可以看到：整数型计数器带i后缀（uint64 类型），total_ping、total_packet_loss为浮点；host标签来自 Telegraf agent 全局配置，非本插件产生。

六、源码级实现分析

采集主流程（Gather）

核心逻辑位于 teamspeak.go 的Gather方法，每个采集周期执行：

1. 惰性连接：插件用connected布尔标志维护连接状态。首次Gather时调用connect()建立连接；若某次采集中途出错（如服务器重启导致连接断开），代码会执行ts.connected = false使标志复位，下个周期自动重连，而不是让插件永久失效。
2. 逐虚拟服务器查询：遍历VirtualServers数组，对每个 vServer 依次执行三步：
   • ts.client.Use(vserver)——切换到目标虚拟服务器上下文；
   • ts.client.Server.Info()——执行serverinfo命令，获得uptime、clients_online、total_ping、total_packet_loss、query_clients_online；
   • ts.client.Server.ServerConnectionInfo()——执行serverrequestconnectioninfo命令，获得四个累计包/字节计数。
3. 组装指标：以virtual_server（vServer ID）和name（服务器名）为 tags，通过acc.AddFields("teamspeak", fields, tags)提交指标。

连接与登录（connect）

connect() 的实现：

• 通过第三方 Go 客户端库github.com/multiplay/go-ts3（go.mod 中固定为 v1.2.0）的ts3.NewClient(ts.Server)打开 TCP 连接并读取欢迎语；
• 调用ts.client.Login(ts.Username, ts.Password)完成认证；
• 若配置了nickname，则对每个虚拟服务器执行Use+SetNick，把 ServerQuery 客户端的显示昵称设为指定值。

从源码结构看，该插件把协议解析完全委托给 go-ts3 库，自身只负责“连接生命周期管理 + 命令编排 + 指标映射”，代码量很小且逻辑清晰。

测试如何模拟 ServerQuery 协议

teamspeak_test.go 的做法值得参考：测试在127.0.0.1:0上启动一个临时 TCP Listener，在handleRequest中手工实现了 ServerQuery 协议的最小服务端——先发送TS3标记与欢迎语，然后按命令前缀返回预设响应：

• login、use→ 返回error id=0 msg=ok；
• serverinfo→ 返回包含virtualserver_clientsonline=2、virtualserver_uptime=148、virtualserver_total_ping=1.0000、virtualserver_queryclientsonline=1等字段的完整serverinfo报文；
• serverrequestconnectioninfo→ 返回含connection_packets_sent_total=369、connection_bytes_received_total=17468等的连接信息报文。

随后TestGather断言插件产出的字段与这些报文数值一一对应（uptime=148、clients_online=2、total_ping=1.0、packets_sent_total=369等）。这既验证了字段映射的正确性，也间接说明了各指标在 ServerQuery 协议报文中的确切来源字段，是排查“指标值不符合预期”问题时的最佳对照资料。

七、适用场景与限制小结

• 适用：自托管 Teamspeak 3 服务器的可用性监控（clients_online、uptime）、网络质量观察（total_ping、total_packet_loss）以及 ServerQuery 通道自身的流量统计（四个*_total累计字段）。
• 限制：仅支持 TS3，不支持 TS2/TS5；插件通过 ServerQuery 通道获取的是该连接维度的累计计数（packets_*/bytes_*来自serverrequestconnectioninfo），并非全服所有用户流量的直接求和，用于趋势观察而非精确容量核算——从测试用例与源码字段来源可以确认这一语义。
• 部署检查清单：创建 ServerQuery 账户 → 将 Telegraf 主机 IP 加入query_ip_allowlist.txt→ 确认10011端口可达 → 按第三节填写配置并确认virtual_servers覆盖全部 vServer ID。

【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegraf