7DTD 服主管理

简体中文

English

简体中文

English

Appearance

故障排查 ​

面向调查工作流失败的管理员。先执行通用前置检查，再进入与现象匹配的分支。每个分支都会给出可观察的验证信号或升级边界。

通用判断流程 ​

  1. 可达性： 打开前端，并请求 <SERVERADMIN_API_BASE_URL>/swagger/v1/swagger.json。可达后端应返回 HTTP 200 和非空 JSON。
  2. 身份认证： 重新登录并确认账号没有过期或被禁用。401 是身份/会话问题，不是功能失败。
  3. 功能模块状态： 打开功能模块，确认相关模块已启用并完成初始化。模块关闭时隐藏设置或拒绝请求可能是预期行为。
  4. 权限： 对照账号角色和当前动作所需权限。403 应通过访问控制修复，不要反复重试同一个请求。
  5. 配置： 重新读取已保存值，包括 CronExpression、TimeZoneId、目标根目录、保留天数和集成端点。不要用浏览器标签推断服务器设置。
  6. 历史或审计证据： 在相同的 UTC/本地时间窗口检查对应运行历史、审计日志、游戏事件日志和后端日志。
  7. 线上服务器验证： 确认游戏进程、网络连接、玩家可见结果或生成的文件。HTTP 成功只证明后端接受了请求。

某一步失败时，记录状态、时间、脱敏后的请求标识和下一责任人，再进行升级。工单中不要包含真实令牌、密码、IP、Discord 密钥、玩家标识或服务器路径。

重启时间或仪表盘时间异常 ​

现象： 设置了 Cron: 0 5 * * *，重启实际发生时间正确，但仪表盘显示为 13:00 等不同时间。

  1. 在重启设置中读取已保存的 CronExpression 和 TimeZoneId。Cron 表达式本身不包含时区。
  2. 如果 TimeZoneId 为空，确认后端服务器的本地时区。如果使用 UTC，而浏览器使用 Asia/Shanghai，显示可能相差八小时；不要通过修改表达式来补偿。
  3. 重新加载页面，将显示值与 NextRunAt、最近一条 Cron 历史记录和游戏进程日志对比。NextRunAt 是计算出的显示提示，不是计划的权威来源。
  4. 按已配置时区确认下一次运行，并核对 TriggerSource，再比较实际重新连接时间。

验证或升级： 已保存的表达式与显式时区、历史记录和服务器日志一致。如果实际触发正确但只有显示偏移，记录配置值和浏览器时区，作为前端日期格式化问题升级。如果运行时触发与保存的组合不一致，升级给后端计划任务/运行时负责人。

计划任务失败 ​

现象： 计划任务不运行、时间错误或出现失败历史记录。

  1. 确认计划任务模块和任务本身已启用，Cron 表达式可以解析，任务的 TimeZoneId 已明确填写。
  2. 检查任务下一次运行值、历史状态、错误信息，以及计划时刻附近的后端日志。
  3. 验证动作所需功能模块和权限可用。任务可能已被计划任务接受，但在动作边界失败。
  4. 在维护窗口内手动执行同一个动作，并比较它的审计或历史记录。

验证或升级： 手动运行成功，下一次计划运行产生一条相符的历史记录。如果重载后没有注册任务，或手动动作也失败，带上任务 ID、脱敏后的参数、历史行和后端日志时间升级。

备份失败或文件缺失 ​

现象： 备份运行失败、完成后没有可用文件，或没有历史记录。

  1. 确认备份已启用，并读取 TimeZoneId、保留天数和各目标设置。讨论路径时使用 <7DTD_SERVER_ROOT> 等占位符。
  2. 验证后端服务身份能在目标位置创建和写入文件，磁盘有足够空间，且游戏进程处于预期状态。
  3. 手动运行一次备份任务。检查返回状态、BackupHistory 行、文件大小、时间戳，以及校验和或压缩包打开结果。
  4. 确认保留清理是否删除了文件；不要把按策略清理误判为写入失败。

验证或升级： 手动运行生成非空、可打开的文件，并有匹配的历史记录。如果任务在写入前失败，或成功状态对应损坏文件，带上目标类型、运行 ID、错误文本和存储负责人结果升级，但不要暴露真实路径。

Discord 连接或投递失败 ​

现象： Discord 状态断开、通知没有到达或命令没有响应。

  1. 确认 Discord 模块已启用，机器人配置存在且已脱敏，并绑定到预期服务器/频道。
  2. 检查后端到 Discord 的网络/DNS，并查看后端日志中的 HTTP 状态、限流、网关或权限错误。
  3. 向专用测试频道发送测试通知，验证机器人角色能按需要查看、发送和嵌入消息。
  4. 对入站命令，确认命令前缀、账号绑定和管理员权限；测试或工单中不要使用真实令牌。

验证或升级： 测试消息以正确语言到达，没有重复投递，健康状态仍显示已连接。如果完成角色和网络检查后仍返回授权或网关错误，只带状态码、时间、服务器/频道占位符和关联 ID，升级给 Discord 集成负责人。

GeoIP 查询或访问决策异常 ​

现象： 客户端被意外允许/阻止，或最近决策没有国家/地区信息。

  1. 确认 GeoIP 访问控制及其设置已启用，包括查询提供方/数据库和失败时放行或拒绝策略。
  2. 确认后端实际收到的客户端地址。反向代理可能需要可信转发配置；不要发布真实地址。
  3. 查询最近决策，并与允许/拒绝规则、缓存时间和查询错误对比。
  4. 使用专用的脱敏客户端或提供方测试结果验证，不要在事故处理中直接修改生产规则。

验证或升级： 决策行显示预期策略、来源分类和查询状态。如果提供方无数据或代理地址错误，带脱敏后的决策 ID 和配置版本升级给 GeoIP 提供方或网络负责人。

事件自动化运行失败或没有历史 ​

现象： 规则没有运行、动作失败或运行历史没有记录。

  1. 确认模块和规则已启用，触发器属于当前 MVP 支持的 PlayerJoined、PlayerLeft、ChatMessage 或 Cron。
  2. 检查条件、目标范围、动作配置、权限以及适用时的规则时区。
  3. 同时检查运行历史、审计日志、聊天/Discord 输出和后端日志。冷却或首次加入抑制可能刻意不创建 RunLog；Cron 并发抑制也可能静默发生。
  4. 使用测试数据触发一次事件，并等待配置的冷却时间后再重试。

验证或升级： 预期动作可观察到；如果有运行记录，其状态和详情与测试相符。如果确认权限和抑制条件后，支持的事件仍被接收却没有动作，带规则 ID、触发时间、脱敏后的条件/动作和模块状态升级。

玩家物品追踪数据缺失 ​

现象： 玩家背包物品没有获得记录、来源坐标或预期容器条目。

  1. 确认玩家追踪已启用，并在玩家档案的追踪标签中加载正确玩家和时间范围。
  2. 查找支持的来源类型：实体掉落容器或地面拾取。只有来源事件提供坐标时才会记录坐标。
  3. 将堆叠合并、转移、制作和不支持的模组流程视为身份边界。这些流程可能不会产生永久物品身份或新的获得记录。
  4. 将记录与游戏事件日志、物品发放/审计记录和玩家快照对照。缺少记录只能作为调查线索，不能单独证明开挂。

验证或升级： 支持的掉落或拾取应显示物品、数量、来源类型、时间，并在可用时显示坐标。如果支持的事件持续缺失，带脱敏的玩家引用、物品键、事件时间、模块版本和日志关联信息升级；不要仅凭缺口认定作弊。

Swagger 或生成的 API 客户端不匹配 ​

现象： Swagger 空白或不可达，生成的请求结构错误，或发布后前端收到 404、401、403、5xx。

  1. 请求 <SERVERADMIN_API_BASE_URL>/swagger/v1/swagger.json，记录 HTTP 状态和响应是否为非空 JSON。
  2. 确认后端发布目标、反向代理基础路径、CORS/认证设置和前端 SERVERADMIN_API_BASE_URL 一致。浏览器页面可打开不代表 API 基础地址正确。
  3. 后端契约可访问后，在前端仓库运行 pnpm api:gen，然后运行 pnpm typecheck 和 pnpm locale:check。
  4. 在 Swagger 中重新打开生成的操作，执行一个非破坏性的带认证请求。凭据放在环境变量中，并从输出中脱敏。

验证或升级： Swagger 返回非空的当前契约，生成类型与响应一致，且只读请求返回预期 2xx。如果后端契约本身为空或代理仍然改写路径，带状态、路径和构建版本升级给发布/代理负责人。

相关页面 ​