Kener 游戏服务器监控指南：使用 GameDig 协议实现游戏状态页监控

• 可观测性
• 后端
• 前端
• 运维

导读

Kener 内置的GAMEDIG监控类型通过 gamedig 查询协议，向 Minecraft、CS、Valve 系等主流游戏服务器发送查询请求，并依据响应评估其可用性与延迟，从而把"游戏服务器是否在线、玩家能否进入"这类问题纳入统一的状态页监控体系。读完本文，你将掌握 GAMEDIG 监控的完整配置字段、默认判定规则、自定义 eval 函数的编写契约，以及排障手段，并能直接将其落地到自己的 Kener 监控配置中。

GAMEDIG 是 Kener 中与 API、PING、TCP 等并列的 13 种监控类型之一（见 MONITOR_TYPES 定义）。它适合那些无法用 HTTP 探活、只能用专用查询协议探测的游戏服务场景，例如 Minecraft 服务器、Source 引擎服务器等。

一、最小配置：从零启用一个 GameDig 监控

GameDig 监控通过查询游戏服务器的状态端口来工作，而不是简单地 ping 一个 IP。Kener 中创建 GAMEDIG 监控时，必须设置以下字段：

在管理界面中，GAMEDIG 表单还预置了两个默认值：

• guessPort默认false：不允许探测备用查询端口；
• requestRules默认false：不请求额外的规则数据。

对应的type_data配置示例：

{ "monitor_type": "GAMEDIG", "type_data": { "gameId": "minecraft", "host": "mc.example.com", "port": 25565, "timeout": 10000, "guessPort": false, "requestRules": false } }

注意：gameId不是随意填写的字符串，它必须是 gamedig 支持的游戏类型标识（例如minecraft、valve、csgo等）。Kener 管理界面的"Game"下拉框从 all-games-list.json 加载游戏列表，默认展示前 50 个，并支持按名称搜索（见 monitor-gamedig.svelte 的实现/manage/app/monitors/[tag]/types/monitor-gamedig.svelte#L29-L34)）。gameId最终会原样传给 gamedig 的query({ type })，因此选错游戏标识会导致查询直接失败。

二、配置字段全解

下表是 GAMEDIG 监控type_data的完整字段说明（与 GamedigMonitorTypeData 类型定义 一一对应）：

字段细节与源码依据

timeout（超时）

执行时，gamedigCall.ts 会做一次兜底：如果type_data.timeout未设置，则回退到常量GAMEDIG_TIMEOUT，其值为10 * 1000（10 秒），定义在 anywhere.ts。此外 gamedig 调用还固定传入socketTimeout: GAMEDIG_SOCKET_TIMEOUT（2 秒，见 anywhere.ts），用于控制底层 socket 的读写超时，避免个别包丢失导致长时间挂起。

在管理表单的校验逻辑中，GAMEDIG 分支要求data.timeout >= GAMEDIG_SOCKET_TIMEOUT（即不得小于 2000ms），否则校验失败（见 MonitorTypeCard.svelte 的 GAMEDIG 校验分支/manage/app/monitors/[tag]/components/MonitorTypeCard.svelte#L232-L239)）。

guessPort（猜测端口）

对应 gamedig 查询参数givenPortOnly取反：guessPort: false时givenPortOnly: true，即只查询你指定的端口；开启guessPort后，gamedig 会根据游戏类型尝试额外的查询端口。管理界面的提示文案是："Used port can be different from client port, depending on queried game. Try this if you have unsuccessful responses"（不同游戏的查询端口可能与客户端端口不一致，若查询失败可尝试开启此选项）。适用场景：某些游戏的客户端端口与查询端口不同，固定端口查询无响应时。

requestRules（请求规则数据）

开启后会在查询中请求额外的规则（rules）数据。管理界面提示：Valve 游戏可以提供额外规则给 Gamedig 监控，开启后这些数据会出现在responseRaw.raw中，但会增加查询耗时。如果你的自定义 eval 需要依赖规则数据做判定，再开启它。

eval（自定义判定函数）

这是 GAMEDIG 监控最有威力的扩展点，下文单独讲解。

三、默认 eval 行为：查询成功与失败的判定

如果不配置eval，Kener 使用内置默认函数，其定义在 anywhere.ts：

async function (responseTime, responseRaw) { return { status: 'UP', latency: responseTime, } }

判定规则非常直接：

• 查询成功 → 状态UP，latency取查询响应的responseTime（即 gamedig 返回的ping字段）；
• 查询失败（超时、端口拒绝、协议不匹配等）→ 返回DOWN，latency为 0，同时记录type: ERROR与截断后的错误信息；
• 若 eval 执行过程抛出异常，同样返回DOWN（错误信息会被截断到 200 字符并写入日志，见 gamedigCall.ts）。

从源码结构看，execute()的流程分为三步（gamedigCall.ts）：

1. Query：调用GameDig.query()，成功后取出response.ping作为responseTime、response.raw作为responseRaw；
2. Eval：将eval函数与入参一起构造为new Function("responseTime", "responseRaw", ...)并执行；
3. Result：组装{ status, latency, type: REALTIME }作为最终的 MonitoringResult 返回。

其中结果type为GC.REALTIME，表示这是一次实时探测得到的真实数据。这个结果最终会写入监控数据表，供状态页、延迟趋势图与告警系统消费。

四、自定义 eval 契约：编写自己的判定逻辑

自定义eval是一个 JavaScript 函数（string形式存储），它接收两个参数：

函数必须返回如下结构的对象：

{ status: "UP" | "DEGRADED" | "DOWN" | "MAINTENANCE", latency: number }

status 支持四种取值：UP、DEGRADED、DOWN、MAINTENANCE，这与 Kener 通用的监控状态模型一致（见 MonitorStatus 类型）。latency为数字，用于延迟图表展示。

一个典型的自定义 eval 示例——比如当服务器满员时标记为 DEGRADED：

async function (responseTime, responseRaw) { // responseRaw 包含 players / maxplayers 等字段（具体取决于游戏协议） if (responseRaw.players >= responseRaw.maxplayers) { return { status: 'DEGRADED', latency: responseTime }; } return { status: 'UP', latency: responseTime }; }

从执行机制上看（gamedigCall.ts），eval 通过new Function动态构造并异步执行；若 eval 抛错，监控会直接判为 DOWN 并记录Error in gamedigEval for <tag>日志。因此编写 eval 时需要注意：

• 函数体必须是异步函数或返回 Promise（示例均为async function，与内置默认一致）；
• 不要依赖外部作用域变量——它是被new Function单独构造的；
• 返回对象缺失status或latency时，源码会用||兜底为DOWN与0（见 gamedigCall.ts），所以宁可显式返回完整对象。

管理界面的"Custom Eval Function"区域使用 CodeMirror 编辑器（JavaScript 语法高亮，随主题切换明暗配色），并在下方提示："Function receives (responseTime, responseRaw) and should return { status, latency }"（见 monitor-gamedig.svelte/manage/app/monitors/[tag]/types/monitor-gamedig.svelte#L112-L130)）。

五、运行链路：GAMEDIG 监控如何被调度与执行

了解 GAMEDIG 监控在整个 Kener 运行链路中的位置，有助于你理解其行为边界：

1. 调度触发：Kener 的监控调度器按 cron 周期将每个监控打包为队列任务（monitorExecuteQueue.ts）；
2. 服务分派：队列 Worker 通过new Service(monitor)按monitor_type实例化对应的探测服务；当类型为GAMEDIG时，分派到GamedigCall（service.ts）；
3. 执行探测：serviceClient.execute(ts)调用 GamedigCall.execute()，完成查询 → eval → 组装结果；
4. 结果落库：探测结果（含raw_status原始状态）写入监控数据，再叠加事故/维护等人工覆盖数据（见 monitorExecuteQueue.ts）；
5. 确认阈值：如果监控配置了confirmation_threshold > 1，连续 N 次探测结果一致后状态才会翻转，避免单次抖动误报（见 monitorExecuteQueue.ts）。

由此可见，GAMEDIG 探测结果会被当作普通实时监控数据参与延迟计算、确认阈值与覆盖逻辑，行为与其他监控类型保持一致。

六、排障指南：常见问题与解决方向

Always DOWN（始终不可用）

• gameId错误：检查是否选择了正确的游戏类型标识。不同游戏的查询协议（Valve 的 Source Query、Minecraft 的 Server List Ping 等）各不相同，选错会导致查询协议不匹配；
• 查询端口错误：游戏客户端端口 ≠ 查询端口是常态。尝试开启guessPort，让 gamedig 探测备用查询端口；
• UDP/TCP 查询流量被防火墙拦截：多数游戏使用 UDP 查询（如 Valve），少数使用 TCP。请确认 Kener 所在服务器到目标主机对应协议端口的网络可达性。

延迟偏高（High latency）

• 增加timeout：网络抖动或对端响应慢时，适当调高超时（表单校验要求 ≥ 2000ms）；
• 检查服务器地域与网络路径：跨地域查询、跨境网络链路波动都会显著影响探测延迟，可通过监控的延迟趋势图观察规律。

细节缺失（Missing details）

• 开启requestRules：对支持的（尤其是 Valve）游戏，开启后可获得额外规则数据，供自定义 eval 使用，但注意这会增加查询耗时；
• 若你依赖玩家数、地图等字段做状态判定，先确认responseRaw中确实包含这些数据（不同游戏协议返回的字段差异很大）。

七、适用边界与建议

• 适用场景：需要探测游戏服务器真实可用性的场景，例如 Minecraft 服务器、Source 引擎游戏服务器、以及任何 gamedig 协议库支持的游戏类型；
• 不适用场景：纯 HTTP 服务探测应使用 API 监控；仅验证端口连通性可使用 TCP 监控。GAMEDIG 的查询协议开销明显高于简单端口探测，不需要游戏级信息时不必使用它；
• 依赖说明：Kener 依赖 npm 包gamedig（当前版本^5.3.2，见 package.json）完成实际查询，gameId的合法取值集合以该库支持的游戏列表为准；本文中的all-games-list.json是 Kener 管理界面下拉框的数据源。

结语

GameDig 监控把"游戏服务器是否可玩"这一看似小众的探活需求，无缝纳入 Kener 通用监控体系：既能实时反映服务器在线状态与延迟，也能通过自定义 eval 表达满员降级、维护窗口等复杂语义，还能与事故管理、确认阈值等机制协同工作。结合本文给出的字段说明、默认/自定义 eval 契约与排障清单，你可以在 Kener 中快速建立一套可靠的游戏服务器状态页监控。

• 可观测性
• 后端
• 前端
• 运维