Diagnostics

🩺 请求诊断

SubConverter-Extended 提供 X-Request-ID、explain=true、/inspect 和结构化日志事件，用于定位请求路径，同时减少敏感信息泄露。

X-Request-ID

进入应用路由生命周期的 HTTP 响应会包含服务端生成的：

X-Request-ID: ...

同一 ID 会写入该请求同步处理期间的日志。客户端传入的同名请求头不会被信任或复用。

HTTP 解析器在进入应用路由前直接拒绝的畸形或超限请求，不保证具有该 ID。CDN 直接命中缓存时，响应 ID 也不能证明源站处理了一次新请求。

explain=true

在原 /sub 请求后增加：

&explain=true

示例：

https://api.asailor.org/sub?target=clash&url=...&explain=true

响应改为 JSON 诊断，不再返回目标配置。可用于检查：

• target=auto 最终选择；
• Mihomo、兼容解析器（诊断字段可能显示 Legacy）或客户端原生远程资源路径；
• 请求参数是否识别、应用、覆盖或忽略；
• Provider、远程资源和直接节点数量；
• 外部配置、规则集和基础模板状态；
• 最终安全档位和出站策略摘要；
• 输出大小和错误原因。

诊断响应不会返回完整订阅 URL、节点正文、原始敏感参数或稳定短哈希。若请求包含上传参数，诊断模式会抑制上传。

/inspect 诊断台

访问：

https://api.asailor.org/inspect

自行部署：

http://localhost:25500/inspect

可以粘贴：

• 完整 /sub?... URL；
• 只有查询参数的字符串；
• 当前站点下的请求路径。

诊断台自动增加 explain=true，并显示摘要、参数状态、Provider、远程资源和原始脱敏 JSON。它不会改变转换逻辑。

日志关联顺序

对同一 request_id 按以下顺序检查：

1. AUTO_TARGET_RESOLVED：自动目标和 UA 家族；
2. SUB_ROUTE_RESULT：解析器或远程资源路径、调用和失败数量；
3. 具体错误事件，例如节点解析、外部抓取或未预期异常；
4. HTTP_RESPONSE_PREPARED：最终状态、耗时和可确定的响应大小。

如果首先看到 SUB_REQUEST_COALESCED，当前请求是等待者。使用事件中的 owner_request_id 查找真正执行转换的请求。

常见 HTTP 状态

状态	常见含义	下一步
200	已生成目标内容或诊断报告	检查正文语义和客户端加载结果
400	缺少/无效参数、扩展语法不适用、没有有效节点或配置内容校验失败	检查双语错误正文和 explain=true
401	Dashboard Basic Auth 缺失或失败	检查认证配置和锁定状态
403	安全档位拒绝请求方可控访问或上传	检查目标 URL、档位和上传策略
404	路由不存在或可选功能未启用	检查路径；Dashboard 需要启用统计
429	Dashboard 当前客户端的认证失败次数达到锁定阈值	等待 Retry-After 指定的时间，并检查客户端地址识别和认证信息
503	Dashboard 已启用认证，但用户名或密码为空	补全认证配置并重启服务
5xx	后端依赖、默认配置、规则转换或未预期错误	使用请求 ID 检查源站日志和依赖状态

状态码表是分类入口，不替代响应正文中的具体原因。

日志级别

[advanced]
log_level = "info"
print_debug_info = false

print_debug_info=true 会覆盖普通级别并启用 verbose。只在受控排障期间使用；不要在生产环境长期保留高详细度日志。

日志文件

原生进程支持：

-l <path>
--log <path>

日志以追加方式打开，不会清空已有文件。程序不负责进程内日志轮转：

• Docker 使用日志驱动和大小限制；
• systemd 使用 journald；
• 原生文件应由服务管理器或外部轮转工具管理。

进程运行期间重命名日志文件并创建同名新文件，不会让进程自动重新打开日志。SIGHUP 表示优雅停机，不用于重新打开日志。

向维护者提供信息

可以提供：

• 客户端和版本；
• target；
• HTTP 状态码；
• X-Request-ID；
• 脱敏诊断报告；
• 可公开复现的最小输入。

不要提供：

• 真实订阅 URL；
• 节点、密码、token、Cookie；
• 完整未脱敏访问日志；
• 包含秘密的截图或浏览器地址栏。