排障手册

先保护玩家，再收集证据，最后做最小的可逆操作。不要为排障直接改数据库、复制 identity 文件、泄露令牌，或在生产环境反复重启全部 BC/子服。

版本边界：以下以 v2 控制面和 Agent 行为为准。遇到旧 /admin/v1、v1 Agent 接口或 Redis 消息字段时，仅按兼容路径查阅旧文档；新问题不要回退设计到 Redis 或业务插件直连 HTTP。

内容读取口径已变更：日志、目录浏览、文件资产正文与差异、消息 payload 已改为按 management.read 直读并强审计，不再走审批与一次性授权；仅敏感配置明文、反向抓取冲突与拓印差异仍保留审批。

1. 首先收集什么

1. 记录发生时间、namespace、服务器 ID、角色、用户影响和最近变更单/改派/更新。
2. 查看 Dashboard 与 Servers：健康等级、原因、最后心跳、是否 drain/offline、身份状态。
3. 查看命令观测：命令类型、状态、年龄和结果摘要。
4. 查看审计和告警事件，建立“谁做了什么—何时出现异常”的时间线。
5. 在受影响节点执行 /beacon status；BC 还可执行 /beacon servers [page] 和 /beacon server <serverId> 查看受管目录。

收集时对 token、口令、API Key、数据库 DSN、玩家隐私和完整公网地址脱敏。

2. 症状速查

症状	可能原因	首选处理
Agent 一直 pending	token/endpoint 错、身份未审批、控制面不可达	核对最小引导配置和网络；在待确认列表核对角色/端点后分配 serverId 并批准。
Agent active 但不健康	心跳/指标未上报、时钟或资源异常	看健康原因和 Agent 日志；先恢复服务资源与网络，再考虑重连。
玩家不能首次进服	BC listener、LobbyCluster 候选或目录异常	确认 BC listener，检查大厅成员在线/可调度和 BC /beacon servers；不要把玩家静默导向普通游戏服。
调度无候选	Zone 错、全部 drain/offline/unhealthy/满载	由 trace 查看排除原因；修复归属或容量，必要时有序取消维护状态。
调度显示本地降级	控制面短暂不可达或候选快照陈旧	玩家可继续使用快照；排查控制面连通性、DNS/反向代理和服务健康。
配置未生效	作用域覆盖、版本未入变更单、命令未回执	看有效预览、变更单目标与命令状态；不要在目标机手改文件掩盖问题。
交付卡住/失败	Agent 离线、命令过期、下载或重载失败	暂停后续批次，查看错误摘要和 /beacon status，修复后对失败目标重试或回滚。
文件资产找不到/过期	Agent 扫描关闭、扫描尚未完成或权限不足	查看扫描状态；在允许范围内请求重扫并核对本地路径权限。
API 返回 401/403	凭据失效或 readonly 越权	区分认证失败(401)和权限不足(403)；轮换/申请正确角色，勿共享管理员凭据。
危险写入返回 202 或长期 pending	已创建审批申请、尚未被 human 决定或 worker 尚未执行	到审批中心核对原因、冻结快照、审批人和执行 timeline；不要重试同一写入来绕过审批。202 票据带 orderId 与 impactSummary 时可直接核对它申请的是哪张单。
大量 503 + DB_WAIT_TIMEOUT	等 DB 连接超时：连接池被长事务占满，或并发超过池容量	不是控制面崩了。查 beacon_self_db_pool_wait_*（等待时长）与慢事务，而不是重启。详见下方「DB 等待上限」。
所有需 DB 的端点挂起、healthz 却 200	锁序互等（永久挂起、不可自愈）	重启前先取 goroutine 栈，重启会毁掉唯一证据。见 §3。
Agent 在较新 BungeeCord 上启动即失败	BungeeCord 的 maven-resolver 升到 2，旧 TabooLib 抛 NoSuchMethodError	症状为加载阶段抛 NoSuchMethodError: MavenRepositorySystemUtils.newServiceLocator()。用本版本附带的新版 agent jar 替换；旧版 BungeeCord 不受影响。
敏感正文读不到（403 / 404 / 410）	正文读取已改为 content.read 直执：403 是缺 management.read 能力；404 COMMAND_NOT_FOUND 是命令不存在或不属于该 serverId；410（sensitive_access_consumed）是浏览结果已被读过一次或已过期清理	补齐能力后重试；目录浏览结果读过即清、有效期 5 分钟，需要再读就重新发起一次浏览命令（POST /browse）。仍在审批范畴的敏感配置明文、反向抓取冲突与拓印差异返回 409 operation_requires_approval，由原申请 human 通过对应授权消费端点领取；任何情况都不要把正文复制到审计或工单。
namespace / server 显示 archived 或 tombstoned	生命周期操作已执行或正在等待审批	已归档资源只读且不能参与运行面；恢复或永久删除必须重新走影响预览、原因和审批流程。
告警持续出现	根因未恢复或事件未处理	从告警跳到服务器、命令和审计；确认修复后再「标记处理」关闭事件（「标记已读」仅表示已知悉、事件仍在跟进）。实例被外部删除且不在受管目录时，超过失联阈值会由控制面自动消解（handled_by=system）。

3. 控制面不可用

1. 确认进程监督状态、监听端口、数据库连接和反向代理健康。
2. 检查近期在线更新、配置变更和系统告警；保留日志与版本信息。
3. 不要急于重启所有 Agent。已有本地快照的 Agent 应继续 fail-static；新审批、拓扑变更和交付暂缓。
4. 控制面恢复后验证 Agent 自动重连、身份 active、候选刷新和本地降级决策补报，再恢复管理操作。

3.1 「需 DB 的端点全挂、healthz 却 200」

这是锁序互等的典型形态：某条路径持着 DB 连接等一把进程内锁，另一条持锁等连接，池内没有第三条连接可破环——双方永久互等、不可自愈，只能重启恢复。healthz 与 metrics 不查库，所以始终 200，容易让人误判「控制面正常」。

⚠️ 务必在重启前取证。重启会销毁现场，而 goroutine 栈是定位互等的唯一直接证据。

取证入口：/debug/pprof/*（1.5.0 起已真正注册）。

• 走管理面鉴权 + full 角色：只读密钥与 readonly 角色一律 403，需先登录换令牌。
• 完整命令、读栈要点见 OPERATIONS §6。
• 堆转储可能含内存中的配置明文与凭据——只在排障时使用，绝不要在反向代理上放开为匿名可访问。

旧版本注意：/debug/pprof/* 此前从未注册，请求会落到单页应用回退，返回 200 + 前端 index.html——曾被误读成「已拿到转储」。若你的版本出现「200 但内容像网页」，就是没真正取到。

3.2 DB 等待上限（503 DB_WAIT_TIMEOUT）

控制面现在对等 DB 连接与事务寿命各有预算，超时回 503 + 业务码 DB_WAIT_TIMEOUT + 可读原因（「等 DB 连接超时（可能是连接池耗尽或有长事务占用）」）。

配置项	默认	管什么
database.call-timeout-ms	5000	取连接 + 单条语句
database.tx-timeout-ms	60000	事务寿命

• 看到这类 503 不是控制面崩溃，而是池枯竭或长事务——去查 beacon_self_*（连接池等待）与慢事务，不要重启。
• 两者必须满足 call-timeout-ms < tx-timeout-ms，错序会在启动校验时被直接拒绝。
• 启动期建表 / 存量回填已单独放宽（约 30 分钟），因此把日常值调小不会卡住升级。
• 归档长查询另有豁免（约 30 分钟）：不要为归档任务调大这两个值。

4. Agent、BC 与大厅

Agent 的本地配置只应含 endpoint 和 bootstrap token 等出生信息；namespace、serverId、Zone、地址和大厅归属由控制面权威分配。不要从另一台服复制 Agent 状态目录。

BC 问题按以下顺序检查：原生 Bungee listener 是否存在并可达；Agent 是否上报全部 listener；BC 所属 BCCluster 是否正确；全局大厅成员是否属于唯一 LobbyCluster、在线且可调度；受管目录是否成功同步。业务切服、管理员强制切服和普通 fallback 不应被“首次大厅落脚”逻辑错误拦截。

4.1 已经撞上了身份冲突（同 identityId 双实例）

「别复制目录」是预防，不是处置。如果两台实例带着同一个 identityId 交替上线——最典型的成因是有人把整服目录（含 plugins/BeaconAgent/identity.yml 或 plugins/BeaconAgentProxy/identity.yml）复制成第二份并启动——控制面会在冲突窗口内判为并发身份冲突：身份转 conflict，两台都不可调度，数据面请求一律返回 409 identity_conflict，侧栏「集群 → 身份冲突」出现红点计数，并产生一条身份冲突类型的告警。

先确认是不是真冲突：故障换机、正常重启、旧机拖尾上报都只是单向切换，不会被判冲突；只有启动标识往复（A → B → A）才算。冲突窗口默认 600 秒，由运维设置项 identity.conflict-window-sec 调整。

处置步骤：

1. 打开侧栏「集群 → 身份冲突」。每张卡片是一组冲突：卡头是 serverId 与冲突原因，卡体左右并排列出双方各自的启动标识（bootId）、来源地址、最后活跃时间与工作目录。先用来源地址和工作目录判断哪台是副本——通常是新复制出来的那台。
2. 二选一处置：
   • 保留实例 A / B：把要留在集群里的那台保留并恢复接入，另一台被判为副本。这是高风险操作，需要填写原因并二次确认。
   • 解绑此身份：释放该 serverId，两台都要重新接入。适合两台都不想要、或想借机重排归属时。
3. 保留之后必须处理落败实例：它不会自己恢复，后续请求会持续 409 并提示「本实例身份已被判为副本」。到那台机器上删掉它目录下的 identity.yml，让它按新身份重新注册（再到「服务器 → 待确认」分配 serverId 并确认），或者直接下线这台实例。控制面不会远程删除你机器上的文件。
4. 解绑之后两台都要重走接入：回到「服务器 → 待确认」重新分配 serverId 并确认，不要指望身份自己变回 active。
5. 处置完复核：冲突卡片消失、两侧服务器回到可调度、审计里能看到冲突检测与处置两条记录（identity.conflict_detected / identity.conflict_resolved）。

不要为了「快点恢复」直接改数据库、把 identity.yml 从另一台复制回来覆盖，或反复重启两台实例——那只会让启动标识继续往复，冲突很快重新出现。

4.2 下发配置拉取异常（拿到的是 HTML 而不是 JSON）

Agent 日志出现这一类，含义很确定：

[BeaconAgent] 下发配置拉取异常（保持当前配置）：Unexpected JSON token at offset 11 ... JSON input: <!doctype html>

解析位置读到 <!doctype html> 说明 GET /beacon/v2/agent/settings 返回的是内嵌前端的 index 页：当前控制面没有这条路由，请求落到了单页应用兜底。因为兜底返回的是 200，所以不会表现为 401/403/404，也不像网络故障——这类「200 但内容是网页」最容易误判成已经通了。

处置：

1. 核对控制面版本（beacon --version，或源码仓库根目录的 VERSION）与 Agent 版本是否匹配。
2. 把控制面升级到包含 GET /beacon/v2/agent/settings 的版本，再请求同一路径确认返回 JSON 而非 HTML，即为恢复。
3. 不要为此改 Agent 的 config.yml、删 pushed-config.json 或重装 Agent：问题在服务端缺路由，本地改动只会丢掉已有的下发值。

此时 Agent 处于「保持当前配置」的降级态：缓存里的下发值继续生效（无缓存则用 config.yml），只是暂时收不到 Web 上新下发的值。心跳、指标、文件资产、发现与调度候选、跨服消息走各自端点，不受影响，服务器照常在线可调度。所以这属于功能降级而非接入故障，按版本对齐处理即可，不要为此重启全部 Agent 或大范围回滚交付。

5. 何时回滚或升级处理

以下情况优先停止推广或回滚：配置影响面错误、批量交付持续失败、升级后健康持续恶化、首次落脚错误或出现数据/权限风险。回滚前保存变更单、命令、审计和健康快照证据；仅回滚明确受影响的版本或批次。

若怀疑版本缺陷，确认正在使用 GA 还是 RC/开发构建、核验资产 SHA-256，并按受控升级流程恢复到上一个已验证 GA。不要清空数据库或 Agent 快照来获得“干净状态”。

6. 升级支持时应附上的材料

• 脱敏后的时间线、namespace、serverId、Agent/控制面版本和部署方式；
• 健康原因、调度 trace ID、命令 ID、变更单 ID、相关审计和告警 ID；
• 最小复现步骤，以及是否在控制面断开时仍可复现；
• 已做的可逆操作及其结果。

更多部署、真实 Agent 验收和版本回滚流程见 运维手册；全局大厅专项见 全局大厅与 BC 接入操作手册。