# sub-provider 一个可部署的订阅聚合后端模板，目标是同时支持两种输出方式： - **薄壳模式**：客户端拉取 `/clients/*.yaml`，配置内继续引用远程 `proxy-providers` / `rule-providers` - **打包模式**：客户端拉取 `/bundle/*.yaml`，服务端把节点、策略组、规则全部铺开成单文件 YAML 这一版已经补上： - 多机场源选择：`?sources=airport-a,airport-b,airport-c` - 单机场或多机场时，**始终取第一个源**的 `Subscription-Userinfo` 返回给客户端 - `GET` 和 `HEAD` 都支持 - provider 单源输出、merged provider 输出、thin client 输出、bundle 输出 - 服务端内部继续解耦：抓取、配额头解析、provider 构建、规则加载、profile 组装分层处理 > 当前版本会自动识别上游输入格式，支持： > 1. 已经能返回 Clash/Mihomo YAML `proxies:` 文件的地址 > 2. base64 编码的 URI 订阅 > 3. 明文 URI 订阅 > > 对 URI 订阅还额外兼容了常见变种：外层 base64 解开后仍是 base64、以及整段 URI 文本再次经过 URL encode。 > > 当前已兼容常见的 `anytls://`、`vless://`、`trojan://`、`ss://`、`vmess://`。 --- ## 目录结构 ```text sub-provider/ app/ config.py main.py models.py services/ cache.py headers.py loader.py profiles.py rules.py subscriptions.py config/ conf/ base.conf profiles/ default.conf lite.conf sources.yaml rules/ reject.yaml direct.yaml proxy.yaml cn-ip.yaml data/ cache/ sources/ .env.example Dockerfile docker-compose.yaml requirements.txt ``` --- ## 快速开始 1. 复制环境变量文件： ```bash cp .env.example .env ``` 2. 编辑 `.env`： - `PUBLIC_PATH` 改成足够长的随机字符串 - `PUBLIC_BASE_URL` 建议填写你反代后的最终访问地址，例如 `https://sub.example.com` - 如果上游订阅地址对默认 UA 返回 `406`，可在 `.env` 里设置 `UPSTREAM_USER_AGENT`，填成你客户端实际使用的 UA，例如 Clash Party 抓包出来的值 - `AIRPORT_A_URL` / `AIRPORT_B_URL` / `AIRPORT_C_URL` 都可以直接填订阅地址，项目会自动判断是 YAML 还是 URI 订阅 - 也可以直接填本地文件路径，例如 `/app/data/sources/airport-b.txt` 或 `file:///app/data/sources/airport-b.txt` - 允许把其中一个留空；留空时这个机场会自动跳过 3. 启动： ```bash docker compose up -d --build ``` 4. 访问检查： - 健康检查：`http://YOUR_HOST:18080/healthz` - 单 provider： `https://YOUR_DOMAIN//providers/airport-a.yaml` - merged provider： `https://YOUR_DOMAIN//providers/merged.yaml?sources=airport-a,airport-b,airport-c` - Mihomo/OpenClash 薄壳入口： `https://YOUR_DOMAIN//clients/mihomo.yaml?sources=airport-a,airport-b,airport-c` - Stash 薄壳入口： `https://YOUR_DOMAIN//clients/stash.yaml?sources=airport-a,airport-b,airport-c` - Conf 薄壳入口： `https://YOUR_DOMAIN//conf/clients/mihomo/default.yaml` - Mihomo/OpenClash bundle： `https://YOUR_DOMAIN//bundle/mihomo.yaml?sources=airport-a,airport-b,airport-c` - Stash bundle： `https://YOUR_DOMAIN//bundle/stash.yaml?sources=airport-a,airport-b,airport-c` - Conf bundle： `https://YOUR_DOMAIN//conf/bundle/mihomo/default.yaml` --- ## 接口说明 ### 1. 单 provider ```text GET //providers/{name}.yaml HEAD //providers/{name}.yaml ``` 返回指定机场源的 provider 文件，并携带这个源的 `Subscription-Userinfo`（如果上游有）。 ### 2. merged provider ```text GET //providers/merged.yaml?sources=airport-a,airport-b,airport-c HEAD //providers/merged.yaml?sources=airport-a,airport-b,airport-c ``` 把多个 provider 合并成一个 `proxies:` 文件返回。响应头只取 `sources` 参数里**第一个源**的配额信息。 ### 3. 薄壳客户端配置 ```text GET //clients/mihomo.yaml?sources=airport-a,airport-b,airport-c GET //clients/stash.yaml?sources=airport-a,airport-b,airport-c HEAD //clients/mihomo.yaml?sources=airport-a,airport-b,airport-c HEAD //clients/stash.yaml?sources=airport-a,airport-b,airport-c ``` 特点： - 客户端收到的是轻量入口配置 - 节点更新依赖远程 `proxy-providers` - 规则更新依赖远程 `rule-providers` - 响应头同样只取第一个源的 `Subscription-Userinfo` ### 4. bundle 单文件配置 ```text GET //bundle/mihomo.yaml?sources=airport-a,airport-b,airport-c GET //bundle/stash.yaml?sources=airport-a,airport-b,airport-c HEAD //bundle/mihomo.yaml?sources=airport-a,airport-b,airport-c HEAD //bundle/stash.yaml?sources=airport-a,airport-b,airport-c ``` 特点： - 服务端把节点、策略组、规则全部展开到一个 YAML 里 - 适合想直接给 Mihomo Party / Clash Party / Stash 一个最终链接的场景 - 响应头同样只取第一个源的 `Subscription-Userinfo` - 生成后的完整 YAML 会缓存到 `output/bundle-cache/`，默认 600 秒内直接返回缓存 - 可用 `force_refresh=true` 强制跳过缓存并覆盖旧缓存文件 - 上游订阅原始内容也会按 TTL 落盘缓存到 `data/fetch-cache/`，默认 900 秒 - 如果你想固定使用本地文件订阅，可以把文件放到 `data/sources/`，再把 `AIRPORT_*_URL` 指向 `/app/data/sources/xxx.txt` ### 5. Conf 配置入口 ```text GET //conf/clients/{client_type}/{profile_key}.yaml GET //conf/bundle/{client_type}/{profile_key}.yaml GET //conf/providers/{profile_key}/{name}.yaml GET //conf/rules/{profile_key}/{name}.yaml ``` 特点： - 旧 `sources.yaml` 路由保持不变，conf 路由独立存在 - 新链路读取 `config/conf/base.conf` 和 `config/conf/profiles/*.conf` - 可以并行对比旧输出和 conf 输出，不影响日常使用 - conf 路由按请求懒加载配置；conf 写坏时不会影响旧接口启动 --- ## Conf 配置说明 当前已落地一套 ACL4SSR-like 的 `.conf` 配置链路： - `config/conf/base.conf` 负责 `source`、`selector`、`group`、`module`、`builtin` 等全局定义 - `config/conf/profiles/*.conf` 负责 `sources`、`include_modules`、`include_builtins` 以及 `override_policy`、`prepend_rule`、`append_rule` 这条链路目前的目标不是替换旧接口，而是： - 保持旧 YAML 配置和旧路由继续可用 - 用新 conf 路由做并行验证 - 逐步把输出收敛到和旧链路一致 ### 示例 `base.conf` 里一条规则模块： ```ini module = apple,../rules/acl4ssr/Apple.yaml,🍎 苹果服务,80,true ``` `default.conf` 里启用模块： ```ini include_modules = apple,openai include_builtins = geoip_cn,final ``` --- ## 对比脚本 项目内置了一个本地对比脚本： ```bash python scripts/compare_conf_outputs.py ``` 它会： - 启动本地 `TestClient` - 同时请求旧路由和 conf 路由 - 输出 `proxy-providers`、`rule-providers`、`proxy-groups`、`rules` 的差异摘要 如果要指定样例源文件： ```bash python scripts/compare_conf_outputs.py --sample-source C:\path\to\sample.yaml ``` --- ## 默认策略结构 当前默认生成的策略组是一个基础版： - `☁️ 机场选择` - `♻️ 自动选择` - `🚀 手动切换` - `🇭🇰 香港自动` - `🇸🇬 新加坡自动` - `🇯🇵 日本自动` - `🇺🇸 美国自动` - `节点选择` 其中： - `☁️ 机场选择` 允许在“混合自动”和各机场单独自动组之间切换 - `节点选择` 是最终主策略组 - bundle 模式会把节点名全部展开 - thin 模式会保留 provider 引用关系 你后面要继续进阶的话，最值得加的是： - `policies.yaml`：把 Telegram / AI / YouTube / Netflix 这类业务组模板化 - `regions.yaml`：把更多地区从 `sources.yaml` 独立出去 - URI/base64 原始订阅解析 - 鉴权层（例如前置 Caddy/Nginx Basic Auth 或仅 Tailscale 可访问） --- ## 配额头策略 为了避免聚合多个机场后“总流量怎么显示”语义混乱，这个版本统一采用： - `sources` 只填一个机场源：返回这个机场源的配额信息 - `sources` 填多个机场源：**只取第一个**机场源的 `Subscription-Userinfo` 这样 Stash、Clash Party 这类客户端读取配置订阅头时，行为是稳定可预期的。 --- ## 上游 `406` 处理 上游订阅抓取默认使用 `sub-provider/0.2` 作为 `User-Agent`。如果机场对这个 UA 返回 `406 Not Acceptable`，可以直接在 `.env` 里覆盖： ```env UPSTREAM_USER_AGENT=Clash Party/<你的版本号或抓包值> ``` 代码里也兼容旧变量名 `DEFAULT_USER_AGENT`，但建议后续统一用 `UPSTREAM_USER_AGENT`。