From 1b60b0a4324cdc97dc3699d86caaef1b89ca7a79 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E8=A2=81=E9=9C=87?= Date: Mon, 6 Apr 2026 13:58:53 +0800 Subject: [PATCH] docs: reorganize README for local surge-sync and multi-channel pipeline --- README.md | 203 ++++++++++++++++++++++-------------------------------- 1 file changed, 84 insertions(+), 119 deletions(-) diff --git a/README.md b/README.md index 5ca0f631e..afee35a7e 100644 --- a/README.md +++ b/README.md @@ -1,172 +1,137 @@ # gitea-shunt-rules -一个最小可用的规则生成器： +基于 **Surge 单源** 的规则生成器： -- 先全量拉取上游 `ios_rule_script` 的 `Surge` 规则到本地缓存 -- 再在本地做合并去重并转换多渠道 -- 输入按目录分类（默认读取 `upstream/rule/Surge//...`） -- 输出仅包含你要的两种格式： - - `dist/surge/.list` - - `dist/loon/.list` - - `dist/clash/.yaml` - - `dist/mihomo/.yaml` -- 当前策略：**只使用 Surge 作为上游源，Clash 由 Surge 规则转换生成** +1. 同步上游 `ios_rule_script` 的 `rule/Surge` 到本地缓存 +2. 本地按分类做合并去重 +3. 统一生成多端兼容规则 -## 为什么这个方案适合你 +当前输出目录： -`ShuntRules` 公开仓库基本只留了发布索引，生成器不在仓库中。这个项目按它的输出思路重建了可控版本，并把数据源切到 Gitea，便于你自己托管。 +- `dist/surge/.list` +- `dist/loon/.list` +- `dist/clash/.yaml` +- `dist/mihomo/.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. `.list` 2. `_Domain.list` 3. `_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` +- `_All.list` +- `_Domain.list` +- `_Resolve.list` +- `.list` -## 定时更新建议 +另外，`*_Domain.list` 中无前缀的裸域名会自动规范化为 `DOMAIN-SUFFIX,`。 -你可以在 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 +```