docs: reorganize README for local surge-sync and multi-channel pipeline

2026-04-06 13:58:53 +08:00
parent c07b72f2ed
commit 1b60b0a432
1 changed files with 84 additions and 119 deletions
@@ -1,172 +1,137 @@
 # gitea-shunt-rules

-一个最小可用的规则生成器：
+基于 **Surge 单源** 的规则生成器：

- 先全量拉取上游 `ios_rule_script` 的 `Surge` 规则到本地缓存
- 再在本地做合并去重并转换多渠道
- 输入按目录分类（默认读取 `upstream/rule/Surge/<Name>/...`）
- 输出仅包含你要的两种格式：
-  - `dist/surge/<Name>.list`
-  - `dist/loon/<Name>.list`
-  - `dist/clash/<Name>.yaml`
-  - `dist/mihomo/<Name>.yaml`
- 当前策略：**只使用 Surge 作为上游源，Clash 由 Surge 规则转换生成**
+1. 同步上游 `ios_rule_script` 的 `rule/Surge` 到本地缓存
+2. 本地按分类做合并去重
+3. 统一生成多端兼容规则

-## 为什么这个方案适合你
+当前输出目录：

-`ShuntRules` 公开仓库基本只留了发布索引，生成器不在仓库中。这个项目按它的输出思路重建了可控版本，并把数据源切到 Gitea，便于你自己托管。
+- `dist/surge/<Name>.list`
+- `dist/loon/<Name>.list`
+- `dist/clash/<Name>.yaml`
+- `dist/mihomo/<Name>.yaml`
+
+## 设计原则
+
+- 上游只用 `Surge` 源，不直接拉 `Clash` 源
+- `Clash`/`Mihomo` 均由 Surge 规则转换生成
+- 本地先合并再转换，避免依赖远端即时拼接

 ## 运行环境

- Python 3.11+（可直接使用 TOML 配置）
- Python 3.10 也可用，但建议改用 JSON 配置（`config.example.json`）
+- Python 3.11+（推荐，支持 TOML 配置）
+- Python 3.10（可用 JSON 配置）

 ## 快速开始

-仓库已内置可直接跑的默认配置文件 `config.json`（本地源模式，默认读 `upstream/`）。
-
-1. 复制配置：
-
 ```bash
 cd /Users/yuan/Desktop/workspaces/docker/pve/gitea-shunt-rules
-cp config.example.toml config.toml
 ```

-2. 填写 `config.toml`：
-
- `gitea.base_url`：你的 Gitea 地址，例如 `https://git.xxx.com`
- `gitea.owner` / `gitea.repo`：规则仓库
- `source.root`：源规则根目录，默认 `rule/Surge`
-
-3. 设置 token（如果仓库私有）：
-
-```bash
-export GITEA_TOKEN='your-token'
-```
-
-如果数据源仓库是公开的（当前默认就是公开源），可以不设置 token。
-默认配置会生成约 600+ 分类（当前为 667 个可直接生成的分类）。
-
-3.1 先同步 Surge 全量源到本地缓存：
+1. 同步上游 Surge 全量源到本地缓存：

 ```bash
 bash scripts/sync_surge_full.sh
 ```

-4. 生成全部分类：
+2. 生成全部分类规则：

 ```bash
-python3 main.py --config config.toml
+python3 main.py --config config.json
 ```

-5. 只生成部分分类：
+3. 只生成指定分类：

 ```bash
-python3 main.py --config config.toml --names YouTube,Netflix
+python3 main.py --config config.json --names Apple,YouTube
 ```

-如果你是 Python 3.10，可用 JSON 配置：
+## 配置说明

-```bash
-cp config.example.json config.json
-python3 main.py --config config.json --names YouTube,Netflix
-```
+默认配置文件：`config.json`（已启用本地源模式）。

-## 目录规范（推荐）
+### `source` 关键字段

-建议你的 Gitea 仓库中按以下结构维护源数据：
+- `mode`
+  - `local`：从本地缓存读取（推荐）
+  - `gitea`：从 Gitea API 直接读取
+- `local_root`：本地缓存根目录（默认 `upstream`）
+- `root`：规则目录（默认 `rule/Surge`）
+- `filename_pattern`：分类主文件模板（默认 `{name}.list`）
+- `include_categories`：仅生成白名单分类
+- `exclude_categories`：排除分类（默认排除仅聚合目录）

-```text
-rule/Surge/
-  YouTube/
-    YouTube.list
-  Netflix/
-    Netflix.list
-```
+### `output` 关键字段

-每个 `.list` 文件示例：
+- `dir`：输出目录（默认 `dist`）
+- `clash_no_resolve`：Clash 的 `IP-CIDR/IP-CIDR6` 是否追加 `no-resolve`
+- `mihomo_no_resolve`：Mihomo 的 `IP-CIDR/IP-CIDR6` 是否追加 `no-resolve`

-```text
-# 注释会被忽略
-DOMAIN-SUFFIX,youtube.com
-DOMAIN-KEYWORD,youtube
-IP-CIDR,172.110.32.0/21,no-resolve
-USER-AGENT,*youtube*
-```
+## 本地合并规则（核心）

-## 转换规则说明
-
-### 基础合并策略（Surge）
-
-每个分类优先按下面三份源文件做合并去重（按顺序）：
+每个分类优先按以下顺序合并去重：

 1. `<Name>.list`
 2. `<Name>_Domain.list`
 3. `<Name>_Resolve.list`

-如果某分类不满足上述结构，会自动回退到 `_All.list` 等可用文件。
+如果某分类不完整，会自动回退到：

- Surge 输出：保留源规则（去重、清理空白）
- Loon 输出：基于 Surge 规则直接输出（同样去重、清理空白）
- Clash 输出：
-  - 自动移除注释/空行
-  - `USER-AGENT`、`URL-REGEX` 默认跳过（并在头部记录 `SKIPPED-*`）
-  - `DEST-PORT` 自动映射为 `DST-PORT`
-  - `IP-CIDR`/`IP-CIDR6` 可通过 `clash_no_resolve` 控制是否追加 `no-resolve`
- Mihomo 输出：
-  - 使用与 Clash 相同的 provider YAML 结构
-  - `DEST-PORT` 自动映射为 `DST-PORT`
-  - `USER-AGENT`、`URL-REGEX` 默认跳过（并在头部记录 `SKIPPED-*`）
-  - `IP-CIDR`/`IP-CIDR6` 可通过 `mihomo_no_resolve` 控制是否追加 `no-resolve`
+- `<Name>_All.list`
+- `<Name>_Domain.list`
+- `<Name>_Resolve.list`
+- `<Name>.list`

-## 定时更新建议
+另外，`*_Domain.list` 中无前缀的裸域名会自动规范化为 `DOMAIN-SUFFIX,<domain>`。

-你可以在 Gitea Actions 或系统 `cron` 做定时任务：
+## 多端转换策略

-1. 拉取源仓库
-2. 执行 `python3 main.py --config config.toml`
-3. 提交 `dist/` 目录到发布仓库或对象存储
+- `surge`：保留合并后的 Surge 规则
+- `loon`：与 Surge 规则兼容输出
+- `clash`：YAML provider 输出，类型适配：
+  - 跳过：`USER-AGENT`、`URL-REGEX`
+  - 映射：`DEST-PORT -> DST-PORT`
+- `mihomo`：YAML provider 输出，规则与 Clash 同步适配

-### Gitea Actions（已内置）
+## 自动化

-项目已包含工作流文件：
+### 1) 生成工作流

- `/Users/yuan/Desktop/workspaces/docker/pve/gitea-shunt-rules/.gitea/workflows/generate-rules.yml`
+文件：`.gitea/workflows/generate-rules.yml`

-你只需要做这几步：
+- 触发：`push` / `schedule` / 手动触发
+- 流程：
+  1. `scripts/sync_surge_full.sh`
+  2. `python3 main.py --config ...`
+  3. 若 `dist/` 有变化则自动提交

-1. 在仓库根目录放好 `config.toml` 或 `config.json`
-2. 在 Gitea 仓库 Secrets 中添加 `GITEA_TOKEN`（私有源仓库建议必须配置）
-3. 推送到 `main` 后会自动执行；也可在 Actions 页面手动触发
+### 2) 发布工作流（独立发布仓库）

-当前定时表达式是 `0 3 * * *`（UTC），对应北京时间（UTC+8）每天 `11:00`。
-工作流会先执行 `scripts/sync_surge_full.sh` 拉取上游 Surge 全量数据，再生成多渠道规则。
+文件：`.gitea/workflows/publish-rules.yml`

-### 发布到独立仓库/分支（已内置）
+- 适合“生成仓库”和“发布仓库”分离
+- 将 `dist/` 同步到目标仓库分支（如 `main` / `rules`）

-如果你希望“生成仓库”和“发布仓库”分离，使用：
+## 目录结构

- `/Users/yuan/Desktop/workspaces/docker/pve/gitea-shunt-rules/.gitea/workflows/publish-rules.yml`
-
-这个工作流会：
-
-1. 从你指定的源仓库读取规则并生成 `dist/`
-2. 把 `dist/` 内容同步到目标仓库的目标分支（可单独设为 `rules` / `gh-pages`）
-
-需要在 Gitea 仓库中配置：
-
- Secrets：
-  - `GITEA_BASE_URL`：例如 `https://gitea.example.com`
-  - `GITEA_TOKEN`：需要有读取源仓库 + 推送目标仓库权限
-  - `SOURCE_OWNER`
-  - `SOURCE_REPO`
-  - `TARGET_OWNER`
-  - `TARGET_REPO`
- Variables（可选）：
-  - `SOURCE_REF`（默认 `main`）
-  - `SOURCE_ROOT`（默认 `rule/Surge`）
-  - `TARGET_BRANCH`（默认 `main`）
-  - `CLASH_NO_RESOLVE`（默认 `false`）
-  - `MIHOMO_NO_RESOLVE`（默认 `false`）
-
-该工作流当前定时为 `15 3 * * *`（UTC），对应北京时间每天 `11:15`，也支持手动触发。
+```text
+gitea-shunt-rules/
+├── main.py
+├── config.json
+├── config.example.toml
+├── config.example.json
+├── scripts/
+│   └── sync_surge_full.sh
+├── upstream/                # 本地上游缓存（自动生成，默认忽略）
+│   └── rule/Surge/...
+├── dist/
+│   ├── surge/
+│   ├── loon/
+│   ├── clash/
+│   └── mihomo/
+└── .gitea/workflows/
+    ├── generate-rules.yml
+    └── publish-rules.yml
+```