Troubleshooting

🧯 故障排查

排障时先保留状态码、X-Request-ID 和脱敏诊断。不要反复修改多个参数，也不要公开真实订阅。

通用排查顺序

1. 访问 /version，确认服务和版本身份。
2. 使用相同请求增加 explain=true。
3. 记录 HTTP 状态码和 X-Request-ID。
4. 判断请求走客户端原生远程资源还是后端解析。
5. 检查外部配置、规则、订阅和出站策略。
6. 获取真实配置并用目标客户端加载。
7. 区分生成失败、客户端导入失败和节点连通失败。

/version 无法访问

检查：

• 进程或容器是否运行；
• 监听地址和端口；
• Docker 端口映射；
• 宿主防火墙、云安全组和 NAT；
• 反向代理上游地址；
• 域名解析和 TLS 证书。

如果 127.0.0.1:25500/version 可访问而外部域名不可访问，问题通常位于端口暴露、反向代理或网络入口，不在转换器。

/healthz 成功，但转换失败

/healthz 只检查 HTTP 进程。继续检查：

• target 和 url 是否存在；
• 参数值是否正确 URL 编码；
• 外部配置和规则是否可访问；
• 安全档位是否拒绝目标；
• 订阅是否由后端下载；
• 目标格式是否能表示输入节点。

使用 explain=true 查看实际路径。

返回 HTTP 400

常见原因：

• 缺少 target 或 url；
• target 不存在；
• interval:、proxy_direct: 用于不支持的目标或节点链接；
• provider_headers 选择了缺失、保留或无效请求头；
• 正则表达式或外部配置内容无效；
• 所有节点都被过滤；
• 没有任何目标格式能够表示的节点或远程资源；
• ruleprepend / ruleappend 内容校验失败。

先阅读双语响应正文，不要把所有 400 都归因于订阅失效。

返回 HTTP 403

通常表示安全策略拒绝请求方可控目标或上传。检查：

• 是否在 public / strict 下请求回环、私网或 fake-ip 字面量；
• 外部配置是否包含受限 import / fetch；
• upload=true 是否被当前档位禁止；
• 是否误把内部资源暴露给公网请求者。

不要为了消除 403 直接切回 lan。如果业务必须访问内网资源，应把服务放回可信网络，而不是公开放宽 SSRF 边界。

外部配置加载失败

检查：

1. URL 是否完成编码。
2. 直接访问是否返回配置正文，而不是登录页或 HTML 错误页。
3. TLS 证书是否有效。
4. proxy_config 是否符合部署网络。
5. 安全档位是否拒绝目标地址。
6. INI/YAML/TOML 语法和导入路径。
7. 是否超过下载大小或资源数量限制。

显式配置失败时，不要假设默认配置回退一定开启。查看 fallback_to_default_external_config 和诊断报告。

规则加载或顺序异常

检查：

• ruleset 类型和内容格式是否匹配；
• clash-domain、clash-ipcidr、clash-classic 是否选对；
• .txt 内容究竟是纯文本还是 YAML；
• ruleprepend / ruleappend 是否包含 MATCH / FINAL；
• no-resolve 是否只用于 clash-ipcidr；
• OpenClash LuCI 是否在下载后再次覆写。

Provider 在客户端更新失败

先确认生成配置中的 Provider URL 正确，再在客户端检查：

• 客户端网络能否直连订阅；
• Mihomo Provider 是否写入 proxy: DIRECT；
• 是否需要 proxy_direct:false；
• 服务商是否要求特定 User-Agent 或请求头；
• Stash Provider 内容是否符合 Stash 可读取格式；
• 订阅是否过期或限制客户端类型。

Provider 由客户端更新时，修改后端 proxy_subscription 不会生效。

后端无法下载订阅

仅适用于服务端解析路径。检查：

• proxy_subscription；
• proxy_bypass；
• DNS 和 TLS；
• 后端出口 IP、地区和 User-Agent；
• 安全档位；
• 订阅响应状态和大小限制。

若客户端可以访问而后端不能访问，可改用客户端原生远程资源目标，前提是目标客户端和格式支持。

配置已生成，但所有节点不可用

检查顺序：

1. 客户端是否成功加载最新配置。
2. Provider 是否成功更新。
3. DNS 是否配置；除 Stash 独立模板外，默认输出通常不含完整 DNS。
4. 客户端版本是否支持节点协议和字段。
5. 节点是否过期或网络不可达。
6. 生成器是否因目标能力过滤或省略关键字段。

转换后端不会验证每个代理节点的实际连通性。

managed_config_prefix 指向错误地址

症状：客户端收到的更新链接指向 127.0.0.1:25500 或旧域名。

修复：

[managed_config]
managed_config_prefix = "https://sub.example.com"

检查是否有 MANAGED_CONFIG_PREFIX 环境变量覆盖文件，然后重启并重新生成配置。

Dashboard 404、401 或锁定

• 404：确认 statistics.enabled=true 并已重启；
• 401：检查 Basic Auth 用户名和密码；
• 多个真实用户被当成一个来源：默认看到反向代理 socket peer；
• 错误信任客户端头：重新检查 header 和 trusted_proxy_cidrs；
• 锁定持续异常：检查代理是否覆盖请求头，以及应用端口是否可被绕过。

日志中找不到请求

可能原因：

• 请求被 CDN 缓存直接响应；
• 反向代理没有转发到源站；
• HTTP 解析器在进入应用路由前拒绝请求；
• 搜索了客户端传入而非服务端生成的请求 ID；
• 请求被合并，需要改查 owner_request_id。

提交问题前

准备：

• 正式 Release 版本号和修订；
• 部署方式；
• 客户端和版本；
• target；
• HTTP 状态码；
• X-Request-ID；
• 脱敏 explain 报告；
• 可公开复现的最小输入。

删除订阅 URL、节点、token、Cookie、设备 ID 和上传路径。