Subscription 配置

当前版本不可用

本页描述的配置在当前版本的 Specola Core 中会被忽略或拒绝，仅作参考保留。当前支持的配置见 完整配置。

Specola 的 Subscription 是“完整配置订阅”：远端文件必须是一份能独立通过校验的 Specola TOML， 可同时包含节点、策略组、Provider、DNS 和规则。它不是 Clash YAML 转换器，也不是只返回节点的 Proxy Provider。

1. 创建订阅

订阅由 Specola Core API 管理，不写在主配置的普通 TOML 字段中。启用 REST 后：

curl -X POST http://127.0.0.1:9090/api/v1/subscriptions \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "remote-team",
    "url": "https://config.example.com/specola/team.toml",
    "interval": 3600
  }'

约束：

项目	约束
name	1–128 字符；首字符为字母或数字，其余可用字母、数字、.、_、-
url	http:// 或 https://
interval	秒；最小 60，默认 86400
下载大小	最大 16 MiB
文件格式	当前 Specola TOML，必须完整通过配置校验

创建操作会立即下载并校验。失败时不会留下一个半成品订阅。

2. 文件位置和更新保证

订阅管理器在 Core 的配置目录保存：

.specola-subscriptions.toml       # 订阅清单
<name>.subscription.toml         # 已校验的配置缓存

缓存路径由经过校验的 name 生成，不信任清单中外部提供的路径。下载先写临时文件，只有新文件完整 通过配置解析和引用校验后才原子替换旧缓存；下载或校验失败时旧缓存保持不变。

后台每 60 秒检查一次到期项，所以实际刷新可能比 interval 最多晚约一个检查周期。

3. 列出、刷新和删除

curl http://127.0.0.1:9090/api/v1/subscriptions

curl -X POST \
  http://127.0.0.1:9090/api/v1/subscriptions/remote-team/refresh

curl -X DELETE \
  http://127.0.0.1:9090/api/v1/subscriptions/remote-team

列表返回 name、url、cache_path、interval 和 last_updated。当前没有原地修改 URL 或 interval 的接口；需要改变时删除并重新创建。

删除会移除清单项和缓存文件。若它正是当前运行配置，先切换到本地配置再删除，避免运行态与磁盘 状态不一致。

4. 激活订阅配置

创建或刷新订阅只更新缓存，不会自动切换当前配置，也不会热重载一个已经激活的订阅。先从订阅列表 取得 cache_path，再显式加载：

curl -X PUT http://127.0.0.1:9090/api/v1/config \
  -H 'Content-Type: application/json' \
  -d '{
    "format": "toml",
    "path": "/absolute/path/to/remote-team.subscription.toml"
  }'

每次需要应用刚刷新的内容，都执行一次加载/切换。切换前现有连接如何结束取决于 Core 的配置重载 生命周期；重要业务应在低流量窗口切换并检查运行状态。

订阅缓存通过配置文档 API按只读配置展示。要长期编辑其中内容，应复制为本地 profile，而不是直接 改缓存；下一次刷新会替换缓存。

5. 与 Provider 的区别

能力	Subscription	Proxy Provider	Rule Provider
内容	完整 Specola 配置	[[proxy]] TOML	逐行规则文本/inline
引用方式	作为当前配置加载	策略组 use	RULE-SET
更新后自动生效	否，需重新加载	是，成功后重载配置	是，热替换规则 snapshot
格式转换	不提供	不提供	不提供

如果只是复用节点列表，用 Proxy Provider；只更新规则，用 Rule Provider；需要由服务端托管整份配置 才使用 Subscription。

6. 安全建议

• 使用 HTTPS，并只订阅可信发布者；订阅可改变全部流量出口和 DNS；
• 当前下载不提供额外的内容签名校验，HTTPS 之外的真实性需由发布流程保证；
• 订阅下载当前使用直连，不支持通过配置中的代理节点获取；
• 不要把 API secret、节点密码或私钥放在可公开访问的订阅地址；
• 加载新版本前先查看返回的更新时间，必要时在独立环境运行 specola-core -t --config <cache_path>。