Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Serve

alias: s

运行 HTTP 服务器。

参数

参数别名环境变量说明
--address-aADDRESS监听地址；未指定时使用配置 setting.address（默认 0.0.0.0）
--port-pPORT监听端口；未指定时使用配置 setting.port（默认 10100）。端口为 0 时使用随机端口
--dev-dDEV开发模式：每次渲染前重新加载模板
--idle-iIDLE空闲模式：IDLE_TIMEOUT（默认 30s）内无请求则退出程序（配合 systemd Restart=always 按需拉起）
--evict-eEVICT空闲时清空数据缓存（默认开启；--evict=false 关闭）：EVICT_TIMEOUT（默认 10s）无请求先清缓存，进程继续存活
--tls-only-sTLS_ONLY仅提供 HTTPS（必须同时提供证书与私钥，否则报错）
--tls-port-tTLS_PORTTLS 端口，默认等于 --port
--tls-cert-cTLS_CERTTLS 证书文件
--tls-cert-key-kTLS_CERT_KEYTLS 私钥文件
--open-OOPEN启动时用 xdg-open 打开浏览器

提供证书与私钥时，TLS 服务器与明文服务器可并行启动（--tls-only 则只启动 TLS）。同时提供明文与 HTTPS 时必须用 --tls-port 指定与 --port 不同的端口。

若配置文件来自本地文件，serve 会监听该配置文件本身（无防抖）：thurgio.yaml 变更时全量重载配置并链式触发重建（成功才重建，失败保留旧配置仅记日志）。模板与 sibling YAML 的变更不在 serve 的监听范围内——需要模板热更新请用 --dev 模式（每次渲染前重载模板）或 thurgio build --watch。

app（公开端点）

  • /: Hello world!
  • /v: 版本字符串（get_version()：NAME VERSION (GIT_BUILD)）
  • /health: JSON 健康状态
  • /ready: 就绪探针
  • /metrics: Prometheus 指标
  • /favicon.svg: 编译期嵌入的站点图标，亮色方案（assets/favicon.svg，image/svg+xml）
  • /favicon-dark.svg: 站点图标，暗色方案（image/svg+xml）
  • /icon-app.svg: 渐变 App 图标（Dashboard 头部 brand 标记，image/svg+xml）
  • /app/login: 登录页（GET）与令牌校验（POST JSON {"token": ...}）

app_th（受保护端点）

令牌通过 ?token= 查询参数或 Authorization: Bearer 请求头传递，按作用域分组（Read/Admin）。

Read 作用域：

  • /app/read/l?name=: 更新数据后渲染 provider（name 为必填查询参数；支持请求级规则覆盖与 tpl=auto UA 自适应，见 API 参考）。
  • /app/read/r?name=: 更新数据后渲染 snippet（name 为必填查询参数）。
  • /app/read/ui: 后台更新，渲染 ui.tpl（上下文含当前令牌 scope）。
  • /app/read/c: 渲染完整 Tera 上下文为 JSON（含 scope，剔除 config 内 proxies/content）。
  • /app/read/events: SSE 构建通知（build_complete，15s keep-alive）。
  • /app/read/health: 订阅健康度聚合（熔断器状态/失败计数/最后更新时间，只读）。
  • /app/read/subs: 订阅商店聚合清单（provider 带解析后节点数与流量元数据，snippet 在后）。
  • /app/read/meta?name=: 单个 provider 的流量元数据（解析 subscription-userinfo 头）。
  • /app/read/history?name=&limit=: provider 快照时间序列（节点数 + 流量元数据）。
  • /app/read/history/diff?name=&from=&to=: 对比时间序列中两个快照。
  • /app/read/latency?name=: 逐代理 TCP 连接延迟测试（按需、不缓存）。
  • /app/read/udp?name=: 逐代理 UDP 生效标志（静态能力报告）。
  • /app/read/geo?name=: 入口落地检测（DNS 解析 + GeoIP 查询）。
  • /app/read/unlock?services=: 流媒体解锁探测（netflix/youtube/disney）。

Admin 作用域：

  • /app/admin/s: 通过 prov/url 请求头更新提供者来源并强制刷新。
  • /app/admin/p: params，请求携带的 queries 会深度合并覆盖当前内存中的 params。
  • /app/admin/adhoc: 创建临时 provider/snippet（不写入配置，缓存持久化到 DB）。
  • /app/admin/write: 执行完整构建（更新 + 渲染 + 写盘）。
  • /app/admin/refresh: 无视缓存强制更新 providers/snippets（不写盘）。
  • /app/admin/reload: 重载所有 templates。
  • /app/admin/save: 持久化所有响应到数据库。
  • /app/admin/dev?value=: 设置 dev 状态（true/false）。
  • /app/admin/gist: 把配置声明文件备份为 GitHub 私密 Gist。
  • /app/admin/shorten?url=: 经配置的短链接服务缩短 URL。

query

当携带参数请求接口时，比如 example.com/app/read/l?name=example&udp=true&port=9090，除 token 与 name 外的 queries 会被转换为 YAML 值（true → 布尔、9090 → 数字），作为 hp 注入模板——请求参数与配置参数分离：p 仅来自配置（params.yaml + /app/admin/p 热更新），hp 携带本次请求的查询参数。点分键（如 dns.enabled）在 hp 中写入嵌套结构（hp.dns.enabled）。单次请求参数超过 100 个会被拒绝。配置中的 params 可在模板中用 config.params 访问。

headers

访问 l / r 时：

  • 转发提供者响应中的 subscription-userinfo 头（snippet 转发请求头中的同名头）。
  • 携带 d=config.yaml 查询参数时，返回 Content-Disposition: attachment; filename="config.yaml" 下载头。