配置指南

Thurgio 常见用例的实际配置模式。

最小工作配置

每个 Thurgio 设置至少需要一个 provider（提供者），在 provider.yaml 中定义获取、处理与渲染所需的一切：

# thurgio.yaml
setting:
  tokens:
    admin:
      - "your-api-token"          # 至少配置一个令牌
  output:
    provider:
      "clash_list.tpl":
        - "output/proxies.yaml"   # 默认输出路径（按模板名映射，详见配置参考）

# provider.yaml
example:
  name: example
  type: clash
  source: "https://example.com/clash-config"
  template: clash_list.tpl
  filename:
    - output/proxies.yaml

管道流程为：Provider → 获取 → 解析代理 → pre_rename → filter → rename → 使用模板渲染 → 写入输出。

添加多个提供者

你可以从多个来源聚合代理：

# provider.yaml
vps_provider:
  name: vps_provider
  type: clash
  source: "https://example.com/clash-config"
  template: clash.tpl
  filename:
    - output/vps.yaml
  rename:
    - "add_vps_prefix"

free_provider:
  name: free_provider
  type: sip002
  source: "https://example.com/sip002.txt"
  template: sip002.tpl
  filename:
    - output/free.txt

local_backup:
  name: local_backup
  type: v2rayn
  source: "backup/v2rayn.json"
  template: v2rayn.tpl
  filename:
    - output/backup.txt

支持的提供者类型（provider.type）：

每个 provider 独立渲染自己的输出；同一个提供者可以通过 outputs 定义多个具名输出，用不同模板渲染同一份代理列表：

# provider.yaml
all_proxies:
  name: all_proxies
  type: clash
  source: "https://example.com/clash-config"
  template: clash.tpl
  filename:
    - output/clash.yaml
  rename:
    - "clean_names"
  outputs:
    v2rayn:
      template: v2rayn.tpl
      filename:
        - output/v2rayn.txt

过滤代理

过滤规则按名称保留或剔除代理。在 filter.yaml 中定义过滤规则（声明式语法，详见配置参考）：

filter:
  # 简写：包含任一关键字的代理（忽略大小写）
  only_uk_us: "英国|美国|UK|US|London|New York"

  # 仅保留 ss 类型
  ss_only:
    - type: ss

  # 正则
  hk:
    - regex: '\W+(US|us|United States)\W+'

在提供者中引用过滤规则：

# provider.yaml
my_list:
  name: my_list
  type: clash
  source: "https://example.com/proxy-config"
  template: clash.tpl
  filter:
    - "only_uk_us"
    - "ss_only"                  # 多个过滤规则依次应用

匹配器

共享选项：ignore_case（缺省 true）、negate（缺省 false，命中则剔除）。列表（AND）仅支持 contain/start/end。

重命名代理

重命名规则使用正则替换（支持反向引用）清理或标准化代理名称：

rename:
  add_vps_prefix:
    - "^(.*)$"
    - "VPS-$1"

  clean_names:
    - "（美国）"
    - "🇺🇸 US"
    - "（日本）"
    - "🇯🇵 JP"
    - "带宽.*"
    - "Standard"

  room_number:
    - "(\\d+)-(\\d+)"
    - "$1-$2"               # 支持正则反向引用

在提供者中应用（pre_rename 在过滤前、rename 在过滤后）：

# provider.yaml
my_provider:
  name: my_provider
  type: clash
  source: "https://..."
  template: clash.tpl
  pre_rename:                     # 在过滤前应用（解析后立即执行）
    - "add_vps_prefix"
  rename:                         # 在过滤后应用
    - "clean_names"
    - "room_number"

每条规则是 [正则, 替换串] 列表，对代理名称执行 replace_all。

使用 Emoji 模式

Emoji 模式根据检测到的国家/地区自动在代理名称前添加旗帜 emoji。

全局设置

setting:
  mode: Enable          # 全局启用 emoji（默认值）

其他可选值：

按提供者覆盖

为特定提供者覆盖全局设置：

# provider.yaml
my_provider:
  name: my_provider
  type: clash
  source: "https://..."
  template: clash.tpl
  emoji: false         # 仅对此提供者禁用 emoji（默认 true）

模板示例

模板使用 Tera 引擎（语法类似 Jinja2/Django）。

上下文变量

自定义过滤器（30+，register_all 统一注册）

示例：带测试部分的 Clash 输出

{# tpls/clash.tpl #}
{%- set format = "json" -%}
{%- set pretty = false -%}

# {{ l.name }}
# 生成时间 {{ now() | date(format="%Y-%m-%d %H:%M:%S") }}

test: &test
  url: {{ p.test.url }}
  interval: {{ p.test.interval }}

proxies:
{% filter indent(width=2) %}{% if format == "json" %}
{%- for i in l.proxies %}
- {{ i | json_str(pretty=pretty) }}
{%- endfor %}{% elif format == "yaml" %}
{{ l.proxies | yaml_str() }}{% endif %}{% endfilter %}

示例：V2RayN 输出

{# tpls/v2rayn.tpl #}
{{ l.proxies | v2rayn() }}

示例：模板内动态应用过滤/重命名规则

模板可在 l.proxies 基础上按需应用 filter.yaml / rename.yaml 中的规则，多个过滤器可链式组合（顺序即应用顺序）：

{# 只保留美国节点，去掉名称中的 "US-" 前缀，再输出 V2RayN 格式 #}
{{ l.proxies | filter(rules="us") | rename(rules="us_prefix") | v2rayn() }}

rules 参数接受逗号分隔的规则名字符串或名字数组；未定义的规则名会被静默忽略（与配置解析行为一致）。

示例：SIP002 输出

{# tpls/sip002.tpl #}
{{ l.proxies | sip002() }}

使用自定义参数

在配置中定义参数：

params:
  test:
    url: "http://www.gstatic.com/generate_204"
    interval: 600
  region: "asia"

然后在模板中使用：

test-url: {{ p.test.url }}
test-interval: {{ p.test.interval }}
region: {{ p.region }}

使用 config.snippet

片段可以为模板提供额外数据：

snippet:
  ruleset:
    source:
      url: "https://example.com/rules.yaml"
    p:
      clash_url: "https://example.com/clash-rules.yaml"

在模板中：

{%- for k, v in config.snippet %}
rule-provider {{ k }}:
  url: {{ v.p.clash_url }}
{%- endfor %}

TLS 设置

通过 TLS 提供 HTTPS 代理服务。

使用 CLI 标志

thurgio serve \
  --tls-only \                       # 仅提供 HTTPS（无明文 HTTP）
  --tls-port 8443 \                  # TLS 端口
  --tls-cert /etc/ssl/cert.pem \     # 证书文件（-c）
  --tls-cert-key /etc/ssl/key.pem    # 私钥文件（-k）

TLS + 明文在不同端口上

thurgio serve \
  --port 10100 \                     # 明文 HTTP
  --tls-port 8443 \                  # 同时提供 HTTPS
  --tls-cert /etc/ssl/cert.pem \
  --tls-cert-key /etc/ssl/key.pem

注意：--tls-port 默认等于 --port。同时提供明文与 HTTPS 时必须显式指定不同的 TLS 端口，否则两个服务会绑定同一地址导致启动失败。

使用环境变量

export TLS_CERT=/etc/ssl/cert.pem
export TLS_CERT_KEY=/etc/ssl/key.pem
export TLS_PORT=8443
export TLS_ONLY=true
thurgio serve

拆分配置为多个文件

Thurgio 解析 thurgio.yaml 后，会自动读取配置文件所在目录下的配套 YAML 文件并合并（模板目录同样相对该目录解析，ADR-066）：

这对于组织大型配置很有用：

~/.config/thurgio/
├── thurgio.yaml        # 主配置（setting）
├── provider.yaml       # 所有提供者
├── filter.yaml         # 所有过滤规则
├── rename.yaml         # 所有重命名规则
├── snippet.yaml        # 所有片段
└── tpls/               # 模板目录（THURGIO_TPL_DIR，默认 "tpls"）
    ├── clash.tpl
    ├── surge.tpl
    └── v2rayn.tpl

所有被引用的模板文件必须在模板目录中存在，否则配置解析失败。

命名规则集（ruleset.yaml）

可选 sibling 文件 ruleset.yaml 按名称定义命名规则集（本地行列表或 http(s):// 远程 URL），生成 _rules.ruleset 上下文面供 ruleset 过滤器消费（{{ l.proxies | ruleset(name="ads") }}）。远程条目由更新管线定时拉取并物化，本地声明优先于同名远程。

# ruleset.yaml
ads:
  - DOMAIN-SUFFIX,ads.example.com
  - DOMAIN-KEYWORD,tracker
cnlist: https://example.com/cn.list

过滤器调用：{{ l.proxies | ruleset(name="ads", format="clash") }} / surge；内联 text 参数优先于命名表，命名表优先于内置 assets/rulesets/*.list。

备份与回滚

编辑配置前可以用 config backup 把当前声明文件（thurgio.yaml、5 个 sibling YAML 与 tpls/ 模板目录，清单与配置热重载的监听一致；ruleset.yaml 不在清单内）整体复制到备份目录：

thurgio config backup
# ✔ Backup created: <root>/backups/20260814-153000

thurgio config list
# Available backups in <root>/backups:
#   20260814-153000  2026-08-14 15:30:00

默认备份到 <root>/backups/<YYYYMMDD-HHMMSS>/，可用 -d/--dir 指定其他位置；只复制实际存在的文件。

配置改坏后，用 list 找到备份名并恢复：

thurgio config restore 20260814-153000

restore 接受备份名（backups/ 下的子目录名）或备份目录路径（绝对路径，或相对 root 的路径）。恢复前会把当前状态自动再备份一份到 backups/（保险），然后覆盖写回声明文件与 tpls/；仅恢复备份中包含的内容，不会删除 root 中的其他文件。

数据库

Thurgio 使用嵌入式 SQLite 数据库（WAL 模式）进行持久化，无需外部数据库服务器。数据库文件（默认 thurgio.db，可用 DATABASE_URL 环境变量覆盖；兼容 sqlite:// 前缀写法）会在首次使用时自动创建于工作目录。持久化以下数据：

• Provider 响应 — 缓存的响应，避免每次构建时重新获取。
• Snippet 数据 — 获取的片段内容。
• 熔断器快照 — 重启后保持打开状态的熔断器。
• KV 存储 — 通用键值数据（kv_store 表）。

环境变量参考