跳到主要内容
版本：1.6.0

可观测、健康与运维操作

本文说明 Beacon v2 的日常观测闭环：先看全局健康，再定位服务器、命令、审计或告警，最后采取受审计的操作。不要把面板中的历史数据当作实时控制指令；玩家链路由数据面和 Agent 本地快照保障。

1. 日常巡检顺序​

  1. 打开「运维总览」（/dashboard），按 namespace 一屏看全局：顶部 KPI（可调度服务器、代理 / 子服在线、在线玩家、平均 TPS / CPU、不健康实例与健康等级分布）、服务器状态墙、玩家流 / 连接流、告警概览与调度概览。它是只读总览，异常从这里下钻。
  2. 打开「服务器」，筛选异常服务器，查看身份、角色、归属、心跳、健康原因、端点事实和配置时间线。
  3. 在「拓扑」确认 BC、LobbyCluster、Region、Zone 与后端关系；归属变化应使用受控的 placement/改派流程。
  4. 有变更或异常时，依次检查「审批中心」「命令观测」「审计」「告警事件」；不要只凭单个卡片作结论。

从总览下钻的三条常用路径：玩家流 / 连接流的「明细」→「连接明细」；告警概览的「查看告警事件」→「告警事件」；调度概览的失败原因 Top 与「前往服务分析」→「服务分析」。下钻会带上当前 namespace 与时间窗，不必重新筛一遍。

NOC 场景可使用只读 Wallboard；它不提供下线、排空、改派或配置发布入口。

1.1 服务分析：单服趋势、多服对比与健康快照​

「服务分析」回答的是「这台（或这几台）最近怎么样」——比总览细，也比告警早。

  1. 先选服务器。左侧可多选，支持按服务器 ID 搜索；只有在线子服可选。被记住的旧选择若已下线或不在当前环境，会以「已选但不在当前在线列表」提示，点掉或一键清除即可，不影响新选择。
  2. 右侧四个板块按问题切换：
    • 指标时序：CPU % / TPS / 内存 / 在线人数曲线，可切聚合步长（1 分钟 / 5 分钟），卡片带最新 / 均值 / 峰值与在线快照。
    • 数据对比：多台并排对比健康分、等级、不可调度原因、角色、大区 / 小区、摘流、默认入口与各健康因子；差异维度会被标出，最优 / 最差一眼可见。
    • 调度决策：按时间窗（近 1 小时到近 30 天）检索决策，点行看逐台排除原因、traceId、权重版本与决策耗时。
    • 健康快照：回放所选服务器健康分与等级的走势，给出最新 / 最低 / 最高分和「最新不可调度原因」。
  3. 页面不会替你放宽时间窗：所选窗口内没有采样点时它会直说「无采样点」。先放宽窗口或确认这台服确实在跑，不要当成采集故障。
  4. 曲线与快照是历史事实，不驱动调度。要解释「这次为什么没选它」，走调度决策板块或按 traceId 追溯，不要只看曲线猜。

2. 健康与调度​

每台已确认服务器会得到 score、健康等级、是否可调度、原因列表与因子分解。健康分用于候选排序，不代替业务插件的玩家容量或玩法规则。

  • healthy：正常候选，按健康分优先；同分时优先容量占用较低者，再随机。
  • degraded：应尽快检查，但通常仍可作为靠后的候选，避免高峰期突然摘除大量服务器。
  • unhealthy、未确认、被主动下线、排空中或达到容量限制：不可调度。

需要维护一台服时，先在服务器页启用 drain，等待玩家自然离开并验证在线人数为零，再改派、重启或下线。不要直接修改数据库，也不要把 drain 当作强制踢人。

健康权重的变更应先在测试 namespace 验证，再经「设置」更新。记录变更时间、原因和预期效果；历史快照中的权重版本可用于解释当时的评分。

3. 调度决策与 fail-static​

调度记录的 trace ID 用于回答「为什么选择或排除了某台服」。查看时重点核对目标 Zone、候选数、排除原因、选择结果、耗时和 source。

控制面短时不可用时，Agent 使用最近候选快照做本地决策并在恢复后补报；这会显示为本地降级来源。此时优先修复控制面连通性，不要因单次降级记录就关闭玩家入口。快照长期未更新会被标记为陈旧，仍应尽快排查。

4. 命令、审计与告警​

命令观测​

命令观测展示控制面到 Agent 的命令生命周期：待领取、已领取、完成、失败或过期。它只显示元数据与结果摘要，不应展示配置正文、日志正文或凭据。

  • 发布、重同步、文件读取、日志请求等操作卡住时，按服务器和命令类型过滤。
  • 先确认 Agent 是否在线且身份 active，再看命令年龄和结果摘要。
  • 重复下发前先确认旧命令是否仍在途，避免造成并发交付或误判。

审计​

审计记录谁在何时对哪个 namespace/对象执行了写操作及结果。对改派、排空、密钥、配置、变更单和更新等高风险动作，必须先从审计记录回溯再继续操作。导出时遵守数据分级，避免把敏感字段带出受控环境。

告警事件​

告警事件既是历史线索，也是一个要收口的待办队列。闭环是：异常触发 → 在告警事件里筛选定位 → 下钻到服务器 / 命令 / 审计找根因 → 修好 → 关闭事件。确认或关闭只改变事件的处理状态，不会自动修复服务器健康。

  • 筛选：按级别（严重 / 警告 / 提示）、类型、处理状态与时间窗筛选。常见类型是健康流转、发布失败、子服失联与身份冲突。
  • 标记已读：表示已知悉、仍在跟进。后续同类触发会继续合并进该条、不再刷出新行，并立即停止计入健康分罚分。适合「已经有人在处理、但还没修好」。
  • 标记处理：关闭事件，必须填写处理备注说明怎么消除的。同类异常再次发生时会另开一条新记录。适合「根因已排除」。
  • 分不清就按这个判据选：还没修好 → 标记已读；已经修好 → 标记处理。
  • 批量收口：可勾选多条一起处理（仅「待处理」行可选），也可对当前筛选命中的全部待处理告警跨页「一键已读 / 一键处理」，不必上千条逐条点。
  • 自动消解：实例被外部删除且不在受管目录时，超过失联阈值会由控制面自动关闭该事件，处理人显示为系统。看到这种记录不是人工漏处理。
  • 详情里能看到该服近期状态与该服告警时间线，也可直接跳到服务器或在审计中追溯；级别可人工升降，用于压制噪音或升级真正要紧的故障。

5. 监控接入​

控制面在独立监听端口上暴露 Prometheus 指标（Prometheus 文本格式），由 config.yml 顶层配置段 metrics-endpoint 控制。出厂值只绑本机回环，外部与公网默认抓不到；该端点属于运维网络面，应仅在受信任网络或反向代理访问控制之内开放，不要直接公开到互联网。指标适合告警和趋势，不取代管理台的详细审计和诊断。

5.1 抓取地址（1.5.0 起变更）​

⚠️ 升级必读：主端口（默认 :8848）不再提供 /metrics。升级后若继续抓旧地址，up{job="beacon"} 会立即归零——控制面并没有挂，是抓取地址变了。

  • 同机抓取：指向 http://127.0.0.1:8849/metrics。
  • 跨机抓取：先把 metrics-endpoint.listen-addr 放开到内网地址（或用环境变量 BEACON_METRICS_ENDPOINT_LISTEN_ADDR 覆盖，env 优先），改后重启生效。
  • 容器形态：必须额外映射 8849 端口。容器内回环与宿主回环不是同一个网络命名空间，只改 listen-addr 而不映射，宿主侧依旧抓不到。
  • 为什么独立端口：主端口默认绑所有网卡且承载管理台与 agent 数据面，抓取挂在上面等于「主端口可达即能匿名读到实例拓扑与容量画像」，无法单独收敛暴露面。
  • 抓取端点不经过主路由中间件，因此每次 scrape 不会再记入 beacon_http_requests_total（旧版那条 route="/metrics" 的自记 series 已消失）。算业务 QPS 时可忽略抓取流量，但不要把该 series 归零误读成业务流量骤降。

抓取配置片段、Bearer 鉴权（可选）与完整降级说明见 OPERATIONS §3.2。

5.2 可抓取的指标分组​

前缀含义
beacon_instances_*被管实例：注册量、健康等级、在线/可调度状态、发布与推送计数
beacon_self_*控制面自身：连接池等待与在用、长轮询挂起数、命令队列深度、指标写入丢弃
beacon_http_*接口 RED：请求数、耗时直方图（可按路由模板算 p95 / p99）、错误计数
go_* / process_*Go 运行时与进程：goroutine、堆、GC、RSS、CPU（约 40 条 series）

beacon_self_* 尤其值得配告警——它暴露的是故障前兆：连接池等待增长（2026-10-10「所有需 DB 端点挂起」事故的直接前兆）、命令队列积压（429 背压出现前唯一的信号）、指标写入丢弃（非零即代表数据已经丢了）。

beacon_http_* 的耗时直方图按路由模板而非原始路径聚合（避免高基数），可直接用于算接口 p95 / p99 并设延迟告警。

建议最少建立以下告警：控制面不可达、在线实例急剧下降、不可调度实例增加、交付失败/超时、健康等级持续恶化、归档任务失败，以及上面 beacon_self_* 的连接池等待与指标丢弃。

5.3 控制面自身不健康时看哪里​

指标是给 Prometheus 的；管理台另有一页直接看控制面自己——侧栏「系统 → 控制面健康」。它不需要抓取配置，怀疑控制面本身有问题时第一个看这里：

  • 进程运行时：版本、运行时长、数据库是否已连接、在线实例数、负载采样器是否启用、协程数、堆内存、CPU 占用。
  • 子系统健康：数据库连接池（使用中 / 最大连接）、长轮询挂起、实例注册表、命令队列，各带正常 / 注意 / 异常等级。点进单个子系统看明细：连接池给出最大 / 当前连接、使用中、空闲、等待次数与累计等待；长轮询给出配置 / 文件 / 拓扑 / 命令各分类的挂起数与合计。
  • 读法：healthz 返回 200 不等于健康。若连接池等待次数在涨、长轮询挂起堆积或命令队列积压，按 排障手册 §3.2 的 DB_WAIT_TIMEOUT 口径处理，不要直接重启。
  • 需要栈或 profile 时：这一页不提供转储，走 /debug/pprof/*；前提、鉴权与安全边界见 排障手册 §3.1 与 OPERATIONS §6。

6. 操作边界​

  • Agent 只报告事实并执行经命令通道下发的操作；控制面不反向连接 Agent。
  • 控制面不可用不应阻断已具备本地快照的玩家进服路径；但新增审批、拓扑变更和交付应等待控制面恢复。
  • 数据库中的事实、历史指标和归档数据是排障依据，不是绕过管理台约束的操作入口。

7. 数据口径速查​

上文各页面的可核对口径如下，可直接用于判断数据是否正常：

  • 指标按 5 秒一批由 Agent 上报，控制面按日期分表保存并按批次幂等去重。时钟偏移过大的批次会被拒绝并计入丢弃数；断连期间的样本按 Agent 本地缓冲策略补报或丢弃，恢复后以控制面收到的批次为准。
  • 健康分范围为 0–100，与等级、是否可调度、原因列表和因子明细一并给出。调度决策包含 trace ID、候选数、排除原因、选择结果与耗时，来源字段区分控制面决策与本地降级。
  • 连接明细与消息元数据同样按日期分表保存。管理面查询必须给出选择性条件（如 serverId 或玩家标识）加显式时间范围，否则会被拒绝；单次跨度上限为 168 小时，前端默认填最近 24 小时。分页默认 50 条、上限 200 条。需要更长跨度时应先导出或归档，而不是放宽查询范围。
  • 命令观测只返回元数据与结果摘要，支持按类型、状态和服务器过滤并分页，列表项附带命令年龄；配置正文、日志正文和凭据不会出现在这里。
  • 告警事件按级别、类型、namespace 和时间窗筛选。确认或关闭只改变事件的处理状态，不会改变服务器实际健康，也不会自动修复故障。
  • 实例 online 字段的真源是运行态注册表（1.5.0 起）。online 为真表示该实例在控制面的运行时注册表中处于 online 或 degraded（心跳陈旧但未达失联阈值）。它不再依据身份表状态：身份 active 只说明「已接入过」，进程被杀后没有任何写点会把它改回去。
    • 因此若你看到身份 active 但 online=false，那是进程真的不在线，不是显示 bug。
    • 反过来，旧版本在进程停止数分钟后仍可能报 online=true——历史期间的 online=true 不能作为「当时还活着」的证据。运维脚本判断存活请以当前返回值与心跳时间为准。