升级与迁移

升级 Thurgio 二进制的标准流程，以及各版本破坏性变更的迁移说明。首次安装与 systemd/Docker 部署细节见部署指南。

升级前准备

备份配置声明文件：
```
thurgio config backup
```
该命令把 thurgio.yaml、5 个 sibling YAML 与 tpls/ 模板目录复制到 <root>/backups/<YYYYMMDD-HHMMSS>；它不加载配置、不访问网络、不碰数据库——即使当前配置已经改坏也能运行。详见 config backup/restore/list 与备份与回滚。
检查 CHANGELOG：对照下方版本间迁移说明，确认目标版本是否有需要手动处理的破坏性变更。没有对应条目时，按标准流程直接升级即可。
记录当前版本，便于回滚时选择旧 tag：
```
thurgio version
```

数据面无需额外备份：SQLite 数据库与渲染输出都位于数据根目录（systemd 部署默认 /var/lib/thurgio），替换二进制不影响数据；/etc/thurgio 配置目录也不随升级变动。

标准升级步骤

流程：下载新版本 → 校验 sha256 → 替换二进制 → 重启服务 → 健康验证。

Docker 部署

拉取新镜像并重建容器（卷挂载保持不变，/data 数据卷自动保留）：

docker pull ghcr.io/xylylab/thurgio:v<新版本>
docker rm -f thurgio
# 以与原先相同的参数重新 docker run，参见部署指南「使用 Docker」

私有镜像的一次性登录见部署指南 · 使用 Docker。

thurgio upgrade 只检查 GitHub 是否有新版本并打印下载地址，不会自动安装。

版本间迁移说明

以下内容均提取自 CHANGELOG 原文，只列真实存在的破坏性变更或需要用户动作的条目；无对应条目的版本按标准流程升级即可。

版本	变更	用户需要做什么
Unreleased	HTTP 参数绑定拆分（ADR-081）：`p` 只承载配置参数，请求级覆盖移入新的 `hp` 绑定	模板与调用方改用 `hp` 传请求级参数
0.18.0	Token 作用域路由前缀（ADR-063）：read 路由移至 `/app/read/...`，admin 路由移至 `/app/admin/...`（breaking URLs）	更新客户端、脚本与监控中的端点路径
0.18.0	无路径 item 路由（ADR-062）：`/app/read/l`、`/app/read/r` 经 `?name=` 取名，`/app/admin/dev` 经 `value=true\|false` 取值	把原路径中的参数改为查询参数
0.18.0	`Source` 改为 untagged（ADR-065）：反序列化为纯字符串，http(s) 前缀即 URL 源（breaking：`!Url`/`!File` 配置语法不再解析）	删除 `source:` 字段的 YAML 标签写法
0.18.0	Provider/NodeList 合并（ADR-058）：`Provider` 成为唯一代理解析实体，`nodelist.yaml` 与 `provider:` 引用键删除	将 nodelist 配置迁入 `provider.yaml`
0.17.0	配置校验收紧：`concurrency_limit >= 1`、`token >= 4 字符`、`interval` 最小值；client URL 格式改为配置解析期校验	升级前核对新约束，避免旧配置解析失败

Unreleased：`hp` 参数绑定（ADR-081）

p 不再接收本次 HTTP 请求的查询参数覆盖；请求级参数落在新的 hp 绑定中（dot 展开合并，无请求参数时为 {}）。模板中原本依赖“用查询参数临时覆盖某个 p.key“的地方，改为读取 {{ hp.key }}。上下文变量说明见配置指南。

从 0.17.x 迁移到 0.18.0

按影响范围逐项检查：

1. 端点路径调整（ADR-063 / ADR-062）

所有受保护的 read 路由移到 /app/read/... 下，admin 路由移到 /app/admin/... 下，认证中间件显式作用于各子路由。item 类路由不再从路径取参：/app/read/l 与 /app/read/r 用 ?name= 指定资源名，/app/admin/dev 用 value=true|false 指定开关；缺失或非法参数现在返回显式 400（而非 404 或被忽略的路径段）。当前完整端点列表见 API 参考，逐一核对客户端与反向代理规则。

2. source 字段去掉标签（ADR-065）

Source 序列化为纯字符串，http(s):// 开头解析为 URL 源，其余解析为文件源。旧配置中的显式 YAML 标签会导致解析失败：

# 旧（不再解析）：
source: !Url "https://example.com/clash-config"

# 新：
source: "https://example.com/clash-config"

3. nodelist 并入 provider（ADR-058）

nodelist.yaml 与 provider 内的 provider: 引用键已删除。把原 nodelist 条目作为普通 provider 写入 provider.yaml（补上 type、template、filename 等字段）。当前 provider 结构见配置参考。

4. 行为变化：解析锚点改为配置文件目录（ADR-066，非破坏性标记）

sibling YAML 与模板目录现在相对配置文件所在目录解析，而不是进程工作目录（这修复了 systemd 场景下的文件源定位问题）。升级后确认 tpls/ 与相对路径输出仍指向预期位置。

更早版本

0.16.0 及之前没有标记面向用户的破坏性变更；除上表 0.17.0 的校验收紧外，按标准流程升级即可。

回滚

配置回滚：restore 会先把当前状态自动备份一份再覆盖写回，只恢复备份中包含的内容，不删除 root 里的其他文件：

thurgio config list
thurgio config restore <备份名>

二进制回滚：用升级前记录的旧版本 tag 重新走一遍下载、校验、替换流程（见标准升级步骤），然后重启：

sudo systemctl restart thurgio
curl -fsS http://127.0.0.1:10100/ready

数据库与输出文件位于数据根目录，替换二进制不影响其中数据（见部署指南 · 升级）；若回滚同时涉及配置，先执行上面的 config restore 再重启。

升级后验证清单

thurgio version 输出为目标版本
curl -fsS http://127.0.0.1:10100/ready 返回 200 与 {"status":"ready",...}
GET /health 显示新版本号且 "database": "connected"
journalctl -u thurgio -n 200 无错误日志
触发一次构建或刷新，确认输出文件正常生成
本次版本涉及迁移项的（见版本间迁移说明），逐项确认已应用：端点路径、hp 绑定、source 写法、provider 合并等
已接入 Prometheus 的实例确认 GET /metrics 抓取正常

Keyboard shortcuts

Thurgio Documentation