快速开始
从零开始运行 Thurgio 的教程。
前提条件
- 选项 A — 预编译二进制：从 GitHub Releases 页面下载适用于你平台的最新版本。
- 选项 B — 从源码构建：Rust 1.85+（2024 edition）。
安装
从源码安装（cargo）
从本地仓库安装（开发构建）：
cargo install --path crates/thurgio-cli
或从 crates.io 安装最新发布版本：
cargo install thurgio
两种命令都会编译 thurgio 二进制文件并将其放置到 ~/.cargo/bin/。
从预编译二进制安装
- 从 Releases 页面下载适用于你操作系统/架构的压缩包。
- 解压并将
thurgio二进制文件放到$PATH中的某个目录（例如/usr/local/bin）。
验证
thurgio --version
快速初始化
使用一条命令生成最小可用配置：
thurgio init
这会在当前目录创建以下文件：
thurgio.yaml— 主配置（setting）provider.yaml/filter.yaml/rename.yaml/params.yaml/snippet.yaml— 各配置节（均可留空，按需填充）tpls/base.tpl与tpls/ui.tpl— 示例模板与 UI 模板
也可以指定目标目录或强制覆盖：
thurgio init --dir /path/to/dir
thurgio init --force # 覆盖已存在的文件
验证生成的配置：
thurgio check
你会看到配置是否有效、提供者/片段的数量、令牌总数、监听地址/端口、TTL，以及每个提供者来源（URL 格式、本地文件是否存在）和输出目录的检查结果。
你的第一个配置文件
创建工作目录和一个最小化的 thurgio.yaml：
mkdir ~/my-thurgio && cd ~/my-thurgio
# thurgio.yaml
setting:
tokens:
admin:
- "my-secret-token"
output:
provider:
"proxies.tpl":
- "output/proxies.yaml"
# provider.yaml
my_provider:
name: my_provider
type: clash
source: "https://example.com/proxy-config"
template: proxies.tpl
filename:
- output/proxies.yaml
该配置：
- 从 Clash 兼容的 URL 加载代理数据。
- 使用模板
tpls/proxies.tpl渲染结果。 - 将最终输出写入
output/proxies.yaml。
注意：
setting使用tokens配置（按作用域分组，至少配置一个）。旧的单值token字段已移除。
创建模板
mkdir tpls
{# tpls/proxies.tpl #}
# Generated by Thurgio — {{ now() | date(format="%Y-%m-%d %H:%M:%S") }}
proxies:
{%- for proxy in l.proxies %}
- {{ proxy | json_str(pretty=false) }}
{%- endfor %}
模板上下文提供以下变量：
l.proxies— provider 的代理对象列表。l.name— provider 名称。content— 片段内容（仅在 snippet 模板中）。p.*— 自定义参数（参见配置指南）。config— 完整配置对象（config.snippet、config.params等）。headers— 请求头映射（HTTP API 渲染时）。version— 版本字符串。now()— 当前时间戳（Tera 自定义函数）。get_env(name="VAR", default="...")— 读取环境变量（Tera 自定义函数）。
可用过滤器和模板变量的完整列表请参阅配置指南。
构建
获取订阅源数据并渲染产物：
thurgio build
成功后，输出文件 output/proxies.yaml 将包含渲染后的代理配置。
Thurgio 会自动在工作目录中创建 SQLite 数据库（thurgio.db，可用 DATABASE_URL 环境变量覆盖路径）来缓存订阅源响应。无需外部数据库服务器。
强制更新所有订阅源（忽略缓存状态）：
thurgio build --force
构建完成时发送系统通知（Linux 桌面，依赖 notify-send）：
thurgio build --notify
监听模式
当源文件变更时自动重新构建：
thurgio build --watch
进程将持续运行，在当前目录（递归）发生任何修改时触发新的构建。按 Ctrl+C 停止。
启动服务
启动 HTTP 服务器按需提供配置：
thurgio serve
服务器默认监听 0.0.0.0:10100。所有需要认证的端点位于 /app/ 命名空间下，令牌通过 ?token= 查询参数或 Authorization: Bearer 请求头传递。
测试 API
# 健康检查
curl http://localhost:10100/health
# 获取渲染后的 provider 配置（需要令牌）
curl "http://localhost:10100/app/read/l?name=my_provider&token=my-secret-token"
# 通过 Server-Sent Events 实时获取构建通知
curl -N "http://localhost:10100/app/read/events?token=my-secret-token"
SSE 在每次构建完成时推送
build_complete事件，支持实时更新的仪表盘或代理配置。
使用自定义设置启动服务
# 自定义地址和端口
thurgio serve --address 127.0.0.1 --port 8080
# 开发模式（每次请求重新加载模板）
thurgio serve --dev
# 空闲模式（30 秒无请求后自动退出，配合 systemd Restart=always 按需拉起）
thurgio serve --idle
# 空闲时清空数据缓存（默认开启；可显式关闭：--evict=false）
thurgio serve --evict
# 启用 TLS（同时提供明文 HTTP 时需指定不同端口）
thurgio serve --tls-port 8443 --tls-cert cert.pem --tls-cert-key key.pem
# 仅提供 HTTPS
thurgio serve --tls-only --tls-port 8443 --tls-cert cert.pem --tls-cert-key key.pem
# 启动时打开浏览器
thurgio serve --open
检查更新
thurgio upgrade
查询 GitHub Releases 检查是否有新版本（仅提示，不会自动安装）。
Shell 自动补全
为 bash、zsh 或 fish 生成 shell 自动补全脚本：
# Bash
thurgio generate --shell bash > /etc/bash_completion.d/thurgio
# Zsh
thurgio generate --shell zsh > /usr/local/share/zsh/site-functions/_thurgio
# Fish
thurgio generate --shell fish > ~/.config/fish/completions/thurgio.fish
也可以使用 -o/--output 直接写入文件。