687 lines
14 KiB
Markdown
687 lines
14 KiB
Markdown
# sub-provider 分阶段重构方案
|
||
|
||
## 1. 文档目标
|
||
|
||
这份文档不是重新定义“最终想做成什么”，而是基于当前 `sub-provider` 已有实现，给出一版可逐步落地、每阶段都能交付可运行结果的重构路径。
|
||
|
||
当前项目已经具备以下基础能力：
|
||
|
||
* 读取 `config/sources.yaml`
|
||
* 拉取和缓存上游订阅
|
||
* 解析 Clash YAML / base64 URI / 明文 URI 订阅
|
||
* 合并节点并生成 bundle YAML
|
||
* 生成 thin client 配置
|
||
* 加载本地规则文件并拼接 `rules`
|
||
* 透传第一个源的 `Subscription-Userinfo`
|
||
|
||
因此重构的目标不是“从零搭系统”，而是把现有静态配置驱动的生成器，逐步改造成：
|
||
|
||
* 内部模块化更清晰
|
||
* 配置存储可演进到数据库
|
||
* 对外仍以完整 YAML 为主
|
||
* 保留现有已验证能力
|
||
* 后续可平滑加管理页和快照系统
|
||
|
||
---
|
||
|
||
## 2. 总体原则
|
||
|
||
### 原则 1：对外接口尽量稳定
|
||
|
||
在重构前几阶段，尽量不打断现有输出能力：
|
||
|
||
* `/bundle/{client}.yaml`
|
||
* `/clients/{client}.yaml`
|
||
* `/providers/{name}.yaml`
|
||
* `/providers/merged.yaml`
|
||
|
||
即使最终主路线偏向 bundle，也不建议在早期重构中直接删除 thin/provider 能力。
|
||
|
||
### 原则 2：先拆“配置来源”，再拆“表现层”
|
||
|
||
当前项目的核心问题不是生成逻辑完全不可用，而是配置全部堆在 `sources.yaml` 里。
|
||
优先级应是：
|
||
|
||
1. 把配置从单一 YAML 拆到更清晰的数据结构
|
||
2. 再引入数据库承载配置
|
||
3. 最后再补管理页面
|
||
|
||
不要一上来把大量时间花在页面上。
|
||
|
||
### 原则 3：规则正文继续文件化
|
||
|
||
规则文件仍然保存在项目目录中，继续使用 Git 管理。
|
||
数据库只存：
|
||
|
||
* 规则模块元数据
|
||
* 规则启用关系
|
||
* 规则顺序
|
||
* 规则绑定到哪个策略组
|
||
|
||
不把 ACL4SSR 规则逐条拆进数据库。
|
||
|
||
### 原则 4：保留动态选源能力
|
||
|
||
当前项目支持通过 `?sources=` 在请求级动态组合源，这个能力实际很有价值。
|
||
重构后不建议退化成只能在 profile 中静态绑定源。
|
||
|
||
建议模型上同时支持：
|
||
|
||
* profile 默认源集合
|
||
* 请求级 `sources` override
|
||
|
||
---
|
||
|
||
## 3. 对现有项目的基线判断
|
||
|
||
### 3.1 现状优点
|
||
|
||
当前代码结构虽然还偏轻量，但核心职责已经初步分开：
|
||
|
||
* `subscriptions.py` 负责源抓取、解析、节点转换
|
||
* `profiles.py` 负责 thin / bundle 配置组装
|
||
* `rules.py` 负责规则文件加载和规则输出
|
||
* `bundle_cache.py` / `fetch_cache.py` 负责磁盘缓存
|
||
|
||
这意味着重构时应该优先“抽象和替换内部数据来源”，而不是推倒服务层。
|
||
|
||
### 3.2 现状主要问题
|
||
|
||
当前主要限制有：
|
||
|
||
* `sources.yaml` 同时承载源配置、地区分组、业务策略组、规则绑定、客户端配置
|
||
* 配置模型偏静态，不利于面板管理
|
||
* bundle 缓存仍是 TTL 模式，不是内容指纹模式
|
||
* 没有配置快照、生成快照、审计能力
|
||
* 当前没有数据库层，也没有迁移体系
|
||
|
||
### 3.3 结论
|
||
|
||
最稳的路线不是“大重写”，而是：
|
||
|
||
1. 保持现有生成骨架
|
||
2. 把配置与渲染逻辑进一步解耦
|
||
3. 再把配置落进数据库
|
||
4. 最后加面板和快照
|
||
|
||
---
|
||
|
||
## 4. 目标架构
|
||
|
||
推荐演进成如下结构：
|
||
|
||
```text
|
||
请求
|
||
-> API 路由
|
||
-> Profile 解析
|
||
-> Source 选择
|
||
-> Source 拉取 / 缓存
|
||
-> 节点解析 / 标准化 / 处理
|
||
-> 策略组装配
|
||
-> 规则模块解析
|
||
-> 完整 YAML 渲染
|
||
-> 结果缓存 / 快照
|
||
-> 返回响应头与 YAML
|
||
```
|
||
|
||
配置来源则逐步从：
|
||
|
||
```text
|
||
sources.yaml
|
||
```
|
||
|
||
演进为：
|
||
|
||
```text
|
||
数据库配置 + 本地规则资产文件 + 少量默认 YAML 模板
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 分阶段路线
|
||
|
||
建议拆成五个阶段，每个阶段结束都能保留一个稳定可运行版本。
|
||
|
||
### 阶段 0：重构准备与基线冻结
|
||
|
||
目标：
|
||
|
||
* 不改行为，先明确现有能力边界
|
||
* 为后续重构建立可回归的基线
|
||
|
||
本阶段任务：
|
||
|
||
1. 盘点当前公开接口、查询参数、响应头语义
|
||
2. 记录当前 `sources.yaml` 中各配置块的职责
|
||
3. 为核心生成路径补最小测试
|
||
4. 输出一份“当前行为基线”文档
|
||
|
||
验收标准：
|
||
|
||
* 至少覆盖以下场景：
|
||
* 单源 provider
|
||
* 多源 merged provider
|
||
* bundle 输出
|
||
* thin 输出
|
||
* 第一个源配额头透传
|
||
* 有一组固定输入可验证当前输出结构不被意外破坏
|
||
|
||
建议产物：
|
||
|
||
* `tests/` 下最小回归测试
|
||
* `docs/当前行为基线.md`
|
||
|
||
说明：
|
||
|
||
这一阶段很重要。没有基线，后面数据库化后很难判断是“重构带来的结构变化”，还是“偷偷改了行为”。
|
||
|
||
---
|
||
|
||
### 阶段 1：配置解耦，但仍以 YAML 为配置源
|
||
|
||
目标：
|
||
|
||
* 先把“一个巨大的 `sources.yaml`”拆成多个清晰模块
|
||
* 暂时不引入数据库
|
||
* 不改变线上运行方式
|
||
|
||
本阶段任务：
|
||
|
||
1. 拆分当前 `sources.yaml`：
|
||
* `config/sources.yaml`
|
||
* `config/clients.yaml`
|
||
* `config/rule-bindings.yaml`
|
||
* `config/policy-groups.yaml`
|
||
* `config/regions.yaml`
|
||
2. 新增统一配置加载层，把多个 YAML 聚合成当前运行所需的内部配置对象
|
||
3. 把当前 `AppConfig` 进一步拆开，减少“大一统模型”
|
||
4. 让 `main.py` 不再直接依赖单个全局 `app_config`
|
||
5. 把“配置加载”和“配置解释”职责从“服务逻辑”中剥离
|
||
|
||
建议目录演进：
|
||
|
||
```text
|
||
app/
|
||
config.py
|
||
main.py
|
||
models/
|
||
source.py
|
||
client.py
|
||
profile.py
|
||
rule.py
|
||
group.py
|
||
services/
|
||
config_loader.py
|
||
subscriptions.py
|
||
profiles.py
|
||
rules.py
|
||
```
|
||
|
||
验收标准：
|
||
|
||
* 对外接口路径和行为保持不变
|
||
* `bundle` 与 `thin` 输出内容结构基本一致
|
||
* 已不再依赖单个巨型 YAML 文件
|
||
|
||
这一阶段收益：
|
||
|
||
* 先把系统结构理顺
|
||
* 后续接数据库时，只需要替换配置仓储层，不需要大改生成器本身
|
||
|
||
---
|
||
|
||
### 阶段 2：引入数据库配置层，保留 YAML 兼容导入
|
||
|
||
目标：
|
||
|
||
* 让配置从静态文件迁移到数据库
|
||
* 但仍支持从 YAML 导入初始数据
|
||
|
||
本阶段任务：
|
||
|
||
1. 引入 SQLAlchemy 与 Alembic
|
||
2. 增加 `DATABASE_URL`
|
||
3. 建立第一批核心表
|
||
4. 实现配置仓储层
|
||
5. 提供 YAML 初始化导入脚本
|
||
|
||
推荐第一批表：
|
||
|
||
* `sources`
|
||
* `profiles`
|
||
* `profile_sources`
|
||
* `rule_modules`
|
||
* `profile_rule_modules`
|
||
* `policy_groups`
|
||
* `profile_overrides`
|
||
|
||
推荐暂不引入的表：
|
||
|
||
* `generated_artifacts`
|
||
* `sync_logs`
|
||
* `rule_module_versions`
|
||
|
||
原因：
|
||
|
||
先把“当前运行配置”迁过去，比一开始就把快照、审计、版本全部做全更稳。
|
||
|
||
#### 推荐字段设计
|
||
|
||
`sources`
|
||
|
||
* `id`
|
||
* `key`
|
||
* `name`
|
||
* `enabled`
|
||
* `kind`
|
||
* `url`
|
||
* `display_name`
|
||
* `headers_json`
|
||
* `include_regex`
|
||
* `exclude_regex`
|
||
* `prefix`
|
||
* `suffix`
|
||
* `cache_ttl_seconds`
|
||
* `created_at`
|
||
* `updated_at`
|
||
|
||
`profiles`
|
||
|
||
* `id`
|
||
* `key`
|
||
* `name`
|
||
* `client_type`
|
||
* `description`
|
||
* `enabled`
|
||
* `allow_lan`
|
||
* `ipv6`
|
||
* `mixed_port`
|
||
* `socks_port`
|
||
* `mode`
|
||
* `log_level`
|
||
* `main_policy`
|
||
* `source_policy`
|
||
* `mixed_auto_policy`
|
||
* `manual_policy`
|
||
* `direct_policy`
|
||
* `test_url`
|
||
* `test_interval`
|
||
* `provider_interval`
|
||
* `rule_interval`
|
||
* `created_at`
|
||
* `updated_at`
|
||
|
||
`profile_sources`
|
||
|
||
* `id`
|
||
* `profile_id`
|
||
* `source_id`
|
||
* `order_index`
|
||
* `enabled`
|
||
|
||
`rule_modules`
|
||
|
||
* `id`
|
||
* `key`
|
||
* `name`
|
||
* `description`
|
||
* `file_path`
|
||
* `behavior`
|
||
* `format`
|
||
* `default_policy`
|
||
* `default_no_resolve`
|
||
* `default_payload_json`
|
||
* `category`
|
||
* `created_at`
|
||
* `updated_at`
|
||
|
||
`profile_rule_modules`
|
||
|
||
* `id`
|
||
* `profile_id`
|
||
* `rule_module_id`
|
||
* `enabled`
|
||
* `order_index`
|
||
* `policy_override`
|
||
* `payload_override_json`
|
||
* `no_resolve_override`
|
||
|
||
`policy_groups`
|
||
|
||
* `id`
|
||
* `profile_id`
|
||
* `name`
|
||
* `group_kind`
|
||
* `type`
|
||
* `order_index`
|
||
* `filter_regex`
|
||
* `proxies_json`
|
||
* `url`
|
||
* `interval`
|
||
* `tolerance`
|
||
* `enabled`
|
||
|
||
这里的 `group_kind` 建议至少支持：
|
||
|
||
* `static`
|
||
* `filter`
|
||
* `generated`
|
||
|
||
这比单纯用一个 `config_json` 更适合当前项目，因为现有组装里同时存在静态组和按 regex 选节点的组。
|
||
|
||
#### 仓储层建议
|
||
|
||
新增仓储抽象，例如：
|
||
|
||
* `SourceRepository`
|
||
* `ProfileRepository`
|
||
* `RuleModuleRepository`
|
||
* `PolicyGroupRepository`
|
||
|
||
让生成服务只依赖仓储接口，而不是依赖数据库实现细节。
|
||
|
||
验收标准：
|
||
|
||
* 使用数据库也能生成与阶段 1 基本一致的 bundle/thin 配置
|
||
* 可以从原 YAML 导入初始配置
|
||
* 切换配置来源时，渲染层无需大改
|
||
|
||
---
|
||
|
||
### 阶段 3：渲染流水线模块化与输出主路线收敛
|
||
|
||
目标：
|
||
|
||
* 把“源处理、规则处理、组装渲染”彻底做成稳定流水线
|
||
* 明确 bundle 是主输出路线
|
||
* thin/provider 进入兼容保留状态
|
||
|
||
本阶段任务：
|
||
|
||
1. 拆分服务层职责：
|
||
* `source_fetcher.py`
|
||
* `source_parser.py`
|
||
* `proxy_processor.py`
|
||
* `policy_group_builder.py`
|
||
* `rule_resolver.py`
|
||
* `profile_renderer.py`
|
||
2. 引入统一内部节点模型
|
||
3. 引入统一内部“已解析 profile”模型
|
||
4. 将当前 `build_bundle_profile()` 的逻辑拆成多步处理
|
||
5. 清理当前 token 展开逻辑，明确保留哪些模板 token
|
||
|
||
#### 内部模型建议
|
||
|
||
不要把节点模型收得太死。建议：
|
||
|
||
```python
|
||
class ProxyNode(BaseModel):
|
||
name: str
|
||
type: str
|
||
server: str | None = None
|
||
port: int | None = None
|
||
udp: bool = True
|
||
tags: list[str] = Field(default_factory=list)
|
||
attrs: dict[str, Any] = Field(default_factory=dict)
|
||
```
|
||
|
||
其中：
|
||
|
||
* 通用字段单独保留
|
||
* 协议特有字段放 `attrs`
|
||
* 最终输出时再按协议合并回 YAML 结构
|
||
|
||
这样比单纯的 `raw` 更可控。
|
||
|
||
#### 规则系统建议
|
||
|
||
这一阶段不要急着把所有规则文件改成 `{{ target_group }}` 模板格式。
|
||
先保留当前模式：
|
||
|
||
* 文件内容仍是 payload
|
||
* policy 在 profile 绑定关系上决定
|
||
|
||
原因：
|
||
|
||
* 当前 thin 模式的 `rule-providers` 仍依赖 payload 文件输出
|
||
* 先保留兼容性，后面再决定是否升级规则文件模板化
|
||
|
||
验收标准：
|
||
|
||
* bundle 渲染主路径清晰可测
|
||
* 服务层之间依赖方向清楚
|
||
* 配置仓储和渲染器分离
|
||
|
||
---
|
||
|
||
### 阶段 4：管理接口与最小面板
|
||
|
||
目标：
|
||
|
||
* 提供最小配置管理能力
|
||
* 不做复杂前后端分离
|
||
|
||
本阶段任务：
|
||
|
||
1. 增加管理 API：
|
||
* source CRUD
|
||
* profile CRUD
|
||
* rule module 查看与 profile 绑定管理
|
||
* policy group 查看与编辑
|
||
2. 增加预览接口
|
||
3. 增加最小页面：
|
||
* sources
|
||
* profiles
|
||
* rule bindings
|
||
* preview
|
||
4. 提供 profile 级 bundle 下载入口
|
||
|
||
建议接口：
|
||
|
||
* `GET /api/sources`
|
||
* `POST /api/sources`
|
||
* `PUT /api/sources/{id}`
|
||
* `GET /api/profiles`
|
||
* `POST /api/profiles`
|
||
* `PUT /api/profiles/{id}`
|
||
* `GET /api/profiles/{id}/rules`
|
||
* `PUT /api/profiles/{id}/rules`
|
||
* `GET /api/profiles/{id}/groups`
|
||
* `PUT /api/profiles/{id}/groups`
|
||
* `POST /api/profiles/{id}/preview`
|
||
* `GET /profiles/{key}/bundle.yaml`
|
||
|
||
面板技术建议：
|
||
|
||
* Jinja2
|
||
* HTMX 或最少量原生 JS
|
||
|
||
不建议此时做：
|
||
|
||
* React/Vue 前后端分离
|
||
* 复杂权限系统
|
||
* 在线全文规则编辑器
|
||
|
||
验收标准：
|
||
|
||
* 不改代码即可新增一个 source
|
||
* 不改 YAML 文件即可调整 profile 规则顺序
|
||
* 页面可直接预览 bundle 输出
|
||
|
||
---
|
||
|
||
### 阶段 5：快照、缓存升级与可追踪性
|
||
|
||
目标：
|
||
|
||
* 从“能生成”升级到“可追踪、可复现、可排查”
|
||
|
||
本阶段任务：
|
||
|
||
1. 增加 `generated_artifacts`
|
||
2. 增加内容指纹缓存
|
||
3. 增加源同步状态记录
|
||
4. 增加简单 diff 能力
|
||
5. 增加错误展示
|
||
|
||
推荐新增表：
|
||
|
||
`generated_artifacts`
|
||
|
||
* `id`
|
||
* `profile_id`
|
||
* `request_sources_json`
|
||
* `content`
|
||
* `content_hash`
|
||
* `source_hash`
|
||
* `rules_hash`
|
||
* `profile_hash`
|
||
* `headers_json`
|
||
* `generated_at`
|
||
|
||
`source_sync_logs`
|
||
|
||
* `id`
|
||
* `source_id`
|
||
* `status`
|
||
* `error_message`
|
||
* `response_headers_json`
|
||
* `content_hash`
|
||
* `created_at`
|
||
|
||
#### 缓存策略建议
|
||
|
||
当前项目 bundle 缓存是 TTL 模式。后续应逐步改为：
|
||
|
||
* fetch cache: TTL
|
||
* parsed snapshot cache: 源内容 hash
|
||
* bundle cache: `source_hash + rules_hash + profile_hash + request_sources`
|
||
|
||
这样才能真正做到：
|
||
|
||
* 配置没变就稳定复用
|
||
* 配置变了就精准失效
|
||
|
||
验收标准：
|
||
|
||
* 能查看某个 profile 最近几次生成记录
|
||
* 能知道本次 bundle 为什么重新生成
|
||
* 能追踪某个源最近一次同步是否失败
|
||
|
||
---
|
||
|
||
## 6. 推荐实施顺序
|
||
|
||
如果按投入产出比排序，建议实际开发顺序如下：
|
||
|
||
1. 阶段 0
|
||
2. 阶段 1
|
||
3. 阶段 2
|
||
4. 阶段 3
|
||
5. 阶段 4
|
||
6. 阶段 5
|
||
|
||
其中真正的“第一版可交付里程碑”建议定在阶段 2 结束时。
|
||
|
||
因为到了阶段 2，已经具备：
|
||
|
||
* 数据库存储配置
|
||
* 可继续生成完整 YAML
|
||
* 配置不再绑死在单文件 YAML 中
|
||
|
||
这时即使还没有面板，系统内核已经完成了最关键升级。
|
||
|
||
---
|
||
|
||
## 7. 每阶段风险点
|
||
|
||
### 阶段 1 风险
|
||
|
||
风险：
|
||
|
||
* 拆 YAML 时容易出现字段兼容问题
|
||
|
||
控制方式：
|
||
|
||
* 先保留兼容加载层
|
||
* 老配置格式在一段时间内继续可读
|
||
|
||
### 阶段 2 风险
|
||
|
||
风险：
|
||
|
||
* 数据建模过度，导致表过多、实现过重
|
||
|
||
控制方式：
|
||
|
||
* 第一批只建运行必需表
|
||
* 快照与日志延后
|
||
|
||
### 阶段 3 风险
|
||
|
||
风险：
|
||
|
||
* 过早重写规则系统，导致 thin 模式兼容性下降
|
||
|
||
控制方式：
|
||
|
||
* 先保留 payload 模式
|
||
* 规则模板化放后续增量处理
|
||
|
||
### 阶段 4 风险
|
||
|
||
风险：
|
||
|
||
* 过早投入页面开发，拖慢主流程
|
||
|
||
控制方式：
|
||
|
||
* 先 API 后页面
|
||
* 页面只做最小可用
|
||
|
||
### 阶段 5 风险
|
||
|
||
风险：
|
||
|
||
* 快照和缓存逻辑做得太复杂，维护成本上升
|
||
|
||
控制方式：
|
||
|
||
* 先做内容哈希与生成记录
|
||
* diff 与审计能力逐步补
|
||
|
||
---
|
||
|
||
## 8. 明确不建议的做法
|
||
|
||
1. 不建议一开始就删除当前 thin/provider 能力
|
||
2. 不建议一开始就把所有规则文件模板化
|
||
3. 不建议把 profile 的源集合只做成一个 `source_ids_json`
|
||
4. 不建议把策略组全塞进一个不透明 `config_json`
|
||
5. 不建议先做复杂前端再补业务内核
|
||
6. 不建议先做快照系统再做数据库配置层
|
||
|
||
---
|
||
|
||
## 9. 建议的第一批实际改动
|
||
|
||
如果下一步开始真正动代码，建议先做这几件事：
|
||
|
||
1. 新建阶段 0 的测试和基线文档
|
||
2. 拆分 `sources.yaml`，完成阶段 1
|
||
3. 引入 SQLAlchemy/Alembic 和最小表结构
|
||
4. 增加 YAML -> DB 导入脚本
|
||
5. 让 bundle 渲染从数据库读取 profile / source / rules 配置
|
||
|
||
这五步完成后，再去做页面，整体节奏会稳很多。
|
||
|
||
---
|
||
|
||
## 10. 一句话结论
|
||
|
||
`sub-provider` 的重构最稳路线是：
|
||
|
||
> 先做配置解耦，再做数据库配置层，再做渲染流水线固化，最后补管理页面和快照系统。
|
||
|
||
这样每一阶段都能保留一个可运行版本，也最符合当前项目已经有代码基础的现实情况。
|