常见问题

如何开始？

运行 thurgio init 生成最小配置（含 provider.yaml、filter.yaml 等拆分文件与 tpls/ 模板目录），然后执行 thurgio build。用 thurgio check 验证配置。

如何添加代理提供者？

编辑 provider.yaml，填入你的提供者 URL 和类型（clash/meta/v2rayn/sip002/surge）。本地文件直接用路径字符串 source: "path"，远程 URL 用 source: "https://..."（http(s) 开头自动识别为 URL）。

如何过滤代理？

在 filter.yaml 中定义过滤规则。示例：

# 简写：包含任一关键字的代理（忽略大小写）
jp: "日本|Japan"

# 排除（negate）
rm_jp:
  - contain: [日本, Japan]
    negate: true

contain/start/end/type/regex 五种匹配器，详见配置参考。

如何重命名代理？

在 rename.yaml 中定义正则替换规则（[正则, 替换串]，支持 $1 反向引用）：

us: ["(.*)", "🇺🇸 $1"]

如何启用 TLS？

使用 thurgio serve --tls-cert cert.pem --tls-cert-key key.pem（可加 --tls-port、--tls-only），或用环境变量 TLS_CERT / TLS_CERT_KEY。

如何监控配置变更？

使用 thurgio build --watch 在当前目录文件变更时自动重建；thurgio serve 也会监听配置文件变更并自动重建。模板目录（tpls/）变更会自动重载渲染器。

如何获取实时构建通知？

通过 Server-Sent Events 连接到 /app/read/events（需令牌认证，?token= 或 Authorization: Bearer）。每次构建完成会推送 build_complete 事件。也可设置 THURGIO_WEBHOOK_URL 在构建完成时收到 HTTP 通知。

如何查看渲染后的配置？

启动 thurgio serve 后请求 /app/read/l?name={provider} 或 /app/read/r?name={snippet}，例如：

curl "http://localhost:10100/app/read/l?name=my_provider&token=my-token"

输出文件在哪里？

在 thurgio.yaml 的 setting.output 中配置（按渲染目标 + 模板名分组）：

setting:
  output:
    provider:
      "clash.tpl":
        - "output/proxies.yaml"
    snippet:
      "rule.tpl":
        - "output/rules.yaml"

条目键为模板名，值是要写入该模板默认输出的目录列表。

如何升级？

运行 thurgio upgrade 检查 GitHub Releases 是否有新版本；或 cargo install --path crates/thurgio-cli（开发构建）/ 下载最新发布版本。

故障排查

系统性的排查步骤（日志、启动失败、HTTP 错误码速查、熔断器、数据库问题）见故障排查。

配置改坏了，起不来怎么办？

用 thurgio check 定位解析错误；改坏前做过备份的话直接 thurgio config restore <备份名> 回滚——config 命令不加载配置，坏配置下也能运行。

订阅源挂了构建会失败吗？

不会立即失败。抓取失败时回退数据库中的 last-known-good 缓存；连续失败触发熔断器（open 后跳过该源一段时间），恢复情况看 GET /app/read/health 聚合端点。

过滤/改名规则好像没生效？

规则名拼错会被静默忽略（解析期丢弃未知名字）。跑 thurgio check，悬空引用会以 WARNING 列出。

模板报 rule set 'xxx' not found？

ruleset 过滤器的名字在 ruleset.yaml 与内置资产中都找不到。注意它与 filter/rename 不同：未定义直接报错而非静默忽略。

输出文件没有生成？

检查两点：provider 的 filename 是否写了；若期望默认输出，setting.output 的键是模板名且目录条目要匹配 item 自己的模板。thurgio check 会报告输出父目录缺失。

改了模板但不生效？

• thurgio build --watch 下模板变更直接触发重建。
• serve 默认只监听主配置文件，模板变更不监听——开发时加 --dev（每次渲染前重载模板）或调 GET /app/admin/reload。

渲染结果不对怎么调试？

RUST_LOG=debug,thurgio=trace thurgio build      # 详细日志
RUST_LOG_FORMAT=json thurgio serve               # 结构化日志

另可用 GET /app/read/c 直接查看渲染上下文 JSON，确认变量取值。

401 但 token 明明对？

令牌分 Read/Admin 作用域：Read 令牌访问 /app/admin/* 会被拒。检查用的是哪组令牌、请求的是哪个命名空间。