故障排查与常见问题

TPS 降低或卡顿

• 检查 ray-trace-threads、pipelineThreads 是否超过物理核心数，必要时减半并观察 top 或 Spark 报告。
• 确保服务器运行最新 Paper/Folia 构建，启用异步区块补丁避免主线程阻塞。
• Algo/AI 造成的尖峰可通过提高 trace_remove、缩短 max_path_length 或减少 rare-ores 数量来缓和。

误判过多

• 调整 commands 中的处罚阈值，优先使用告警或记录级别，待人工复核后再封禁。
• 在 check.AlgoAntiXray.decay 段启用 use_factor 并降低 vl-multiplier，让违规值更平滑。
• 打开 natural-detection.cave.air-monitor、提高 air-ratio-threshold 可减少自然洞穴触发。
• 对施工玩家提前发放 /nax internalbypass grant 或启用 mass-excavation，避免大型工程触发。

模式互斥或误配置

• Algo 与传统模式互斥：若同时启用，请确认 enable 取值并检查控制台警告。
• AI 检测需 model.onnx / feature_stats.json，缺失时会在日志中提示；不要在缺模型情况下启用处罚。
• 修改 YAML 后务必使用 :%s 等方式检查Tab字符，必要时通过 yamllint 验证。

种子仍被泄露

• 确认玩家是否持有 fakeseed.viewreal 权限。
• 运行 /nax secureseed status，确保安全种子系统处于 ENABLED 状态。
• 若安装了其他 /seed 覆盖插件，请调整加载顺序或在其配置中放行 NekoAntiXray。

大规模挖掘频繁误报

• 提升 block-count-threshold、min-volume-threshold 或延长 detection-time-window。
• 为施工玩家发放临时豁免：/nax internalbypass grant Player 3600 建筑施工。
• 在告警信息中加入提醒，要求玩家提前报备大型挖掘活动。

回放/记录异常

• /nax record 未写入：确认磁盘剩余空间，并检查 plugins/NekoAntiXray/logs/ 是否只读。
• /nax replay tp 无效：确保录像坐标仍存在且世界已加载，可先 tppos 或手动加载区块。
• 盔甲架残留：执行 /nax cleanup（控制台执行为全服），或缩短 replay.record-duration、调低采样频率。

深度学习模块无输出

• 检查 plugins/NekoAntiXray/ 下是否存在 model.onnx、feature_stats.json，确保与训练脚本版本一致。
• 确认 deeplearn.enable=true 且 cooldown_ms、sequence_length 与训练参数匹配。
• 将 deeplearn.debug=true 开启以在控制台查看推理日志；若仍无数据，检查服务器是否使用兼容的 ONNX Runtime。
• 暂停处罚：将 violations.enable-punishment=false 只记录评分，待验证模型准确率后再开启。

常用排障命令

命令	作用
/nax status	查看模块开关、线程与缓存信息
/nax togglemassexcavation status	快速确认大规模挖掘检测是否开启
/nax cleanup	清除回放盔甲架，处理崩溃后的实体残留
/nax orestats <player>	观察可疑玩家矿脉命中率以评估误报
/nax alerts	为巡查成员开启/关闭实时告警

如何兼容Liteban？

• 在配置文件当中把封禁命令改为liteban:ban 然后在配置文件中把NAX内部封禁系统的封禁天数设置为0 即可

日志与支持

• 生产环境下建议将日志级别保持 WARN，在排障时切换到 DEBUG。
• 收集 plugins/NekoAntiXray/logs/、latest.log、config.yml，在提交工单或反馈前一并附上，有助于官方快速定位问题。
• 重大配置改动前备份 config.yml，可利用 Git 或版本化存储，以便回滚。

若按照以上步骤仍无法解决问题，请在官方支持渠道（QQ 群/论坛/GitHub 讨论区）描述现象、服务器版本、近期变更以及相关日志片段。*** End Patch