# sub-provider

一个可部署的订阅聚合后端模板，目标是同时支持两种输出方式：

- **薄壳模式**：客户端拉取 `/clients/*.yaml`，配置内继续引用远程 `proxy-providers` / `rule-providers`
- **打包模式**：客户端拉取 `/bundle/*.yaml`，服务端把节点、策略组、规则全部铺开成单文件 YAML

这一版已经补上：

- 多机场源选择：`?sources=airport-a,airport-b`
- 单机场或多机场时，**始终取第一个源**的 `Subscription-Userinfo` 返回给客户端
- `GET` 和 `HEAD` 都支持
- provider 单源输出、merged provider 输出、thin client 输出、bundle 输出
- 服务端内部继续解耦：抓取、配额头解析、provider 构建、规则加载、profile 组装分层处理

> 当前版本会自动识别上游输入格式，支持：
> 1. 已经能返回 Clash/Mihomo YAML `proxies:` 文件的地址
> 2. base64 编码的 URI 订阅
> 3. 明文 URI 订阅
>
> 当前已兼容常见的 `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/
    sources.yaml
    rules/
      reject.yaml
      direct.yaml
      proxy.yaml
      cn-ip.yaml
  data/
    cache/
  .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`
- `AIRPORT_A_URL` / `AIRPORT_B_URL` 都可以直接填订阅地址，项目会自动判断是 YAML 还是 URI 订阅
- 允许把其中一个留空；留空时这个机场会自动跳过

3. 启动：

```bash
docker compose up -d --build
```

4. 访问检查：

- 健康检查：`http://YOUR_HOST:18080/healthz`
- 单 provider：
  `https://YOUR_DOMAIN/<PUBLIC_PATH>/providers/airport-a.yaml`
- merged provider：
  `https://YOUR_DOMAIN/<PUBLIC_PATH>/providers/merged.yaml?sources=airport-a,airport-b`
- Mihomo/OpenClash 薄壳入口：
  `https://YOUR_DOMAIN/<PUBLIC_PATH>/clients/mihomo.yaml?sources=airport-a,airport-b`
- Stash 薄壳入口：
  `https://YOUR_DOMAIN/<PUBLIC_PATH>/clients/stash.yaml?sources=airport-a,airport-b`
- Mihomo/OpenClash bundle：
  `https://YOUR_DOMAIN/<PUBLIC_PATH>/bundle/mihomo.yaml?sources=airport-a,airport-b`
- Stash bundle：
  `https://YOUR_DOMAIN/<PUBLIC_PATH>/bundle/stash.yaml?sources=airport-a,airport-b`

---

## 接口说明

### 1. 单 provider

```text
GET /<PUBLIC_PATH>/providers/{name}.yaml
HEAD /<PUBLIC_PATH>/providers/{name}.yaml
```

返回指定机场源的 provider 文件，并携带这个源的 `Subscription-Userinfo`（如果上游有）。

### 2. merged provider

```text
GET /<PUBLIC_PATH>/providers/merged.yaml?sources=airport-a,airport-b
HEAD /<PUBLIC_PATH>/providers/merged.yaml?sources=airport-a,airport-b
```

把多个 provider 合并成一个 `proxies:` 文件返回。响应头只取 `sources` 参数里**第一个源**的配额信息。

### 3. 薄壳客户端配置

```text
GET /<PUBLIC_PATH>/clients/mihomo.yaml?sources=airport-a,airport-b
GET /<PUBLIC_PATH>/clients/stash.yaml?sources=airport-a,airport-b
HEAD /<PUBLIC_PATH>/clients/mihomo.yaml?sources=airport-a,airport-b
HEAD /<PUBLIC_PATH>/clients/stash.yaml?sources=airport-a,airport-b
```

特点：

- 客户端收到的是轻量入口配置
- 节点更新依赖远程 `proxy-providers`
- 规则更新依赖远程 `rule-providers`
- 响应头同样只取第一个源的 `Subscription-Userinfo`

### 4. bundle 单文件配置

```text
GET /<PUBLIC_PATH>/bundle/mihomo.yaml?sources=airport-a,airport-b
GET /<PUBLIC_PATH>/bundle/stash.yaml?sources=airport-a,airport-b
HEAD /<PUBLIC_PATH>/bundle/mihomo.yaml?sources=airport-a,airport-b
HEAD /<PUBLIC_PATH>/bundle/stash.yaml?sources=airport-a,airport-b
```

特点：

- 服务端把节点、策略组、规则全部展开到一个 YAML 里
- 适合想直接给 Mihomo Party / Clash Party / Stash 一个最终链接的场景
- 响应头同样只取第一个源的 `Subscription-Userinfo`
- 生成后的完整 YAML 会缓存到 `output/bundle-cache/`，默认 600 秒内直接返回缓存
- 可用 `force_refresh=true` 强制跳过缓存并覆盖旧缓存文件

---

## 默认策略结构

当前默认生成的策略组是一个基础版：

- `☁️ 机场选择`
- `♻️ 自动选择`
- `🚀 手动切换`
- `🇭🇰 香港自动`
- `🇸🇬 新加坡自动`
- `🇯🇵 日本自动`
- `🇺🇸 美国自动`
- `节点选择`

其中：

- `☁️ 机场选择` 允许在“混合自动”和各机场单独自动组之间切换
- `节点选择` 是最终主策略组
- 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 这类客户端读取配置订阅头时，行为是稳定可预期的。