Skip to content

README.md

Latest commit

 

History

History
205 lines (140 loc) · 14.9 KB

README.md

File metadata and controls

205 lines (140 loc) · 14.9 KB
Raw

Rule-Bot Client

发现 Mihomo 最终规则命中的域名，把值得检查的目标整理成清单。

本地保存优先 · 可选接入 Rule-Bot · 一个客户端可监听多个 Mihomo

最新版本 CI 状态 OpenWrt 构建 许可证

⬇️ 下载 · 📖 用户 Wiki · 💬 问题反馈

Rule-Bot Client 用来发现可能需要补充规则的域名。它读取 Mihomo 的连接信息，找出最终由兜底规则 MATCH 处理的域名，并保存为本地清单。需要时，还可以把域名发送给 Rule-Bot 做进一步检查。

Tip

第一次使用？ 先了解下面四个概念，再根据设备选择一种部署方式。安装后先验证本地收集，确认正常后再决定是否启用 Rule-Bot。

🧭 先了解几个关键概念

  • Mihomo：实际处理代理连接和规则匹配的内核。OpenClash、Nikki 等工具可以管理 Mihomo 内核。
  • MATCH：Mihomo 规则列表末尾的兜底规则。连接没有命中前面的规则时，才会交给 MATCH 处理。命中 MATCH 不一定代表规则错误，但这些域名通常值得检查。
  • Mihomo 控制接口：Mihomo 自带的 HTTP 管理接口，配置项通常叫 external-controller。管理面板和其他工具通过它读取 Mihomo 的运行状态。Rule-Bot Client 也通过这个接口读取日志和当前连接；它不是需要另行安装的程序。英文资料和部分界面也把它称为 Controller。
  • Rule-Bot：可选的配套服务。它会检查域名是否已有规则、是否已被 GeoSite 域名库覆盖，以及是否符合服务端策略。本地收集不需要 Rule-Bot。

✨ 它能做什么

  • 把最终由 MATCH 处理的域名整理成去重后的本地清单。
  • 一个客户端同时连接多个 Mihomo 控制接口，采集多个正在运行的 Mihomo 内核，包括由 OpenClash 或 Nikki 管理的内核。
  • 可选把域名发送给 Rule-Bot，由服务端决定是否补充直连规则。

Rule-Bot Client 不是代理客户端，也不会修改 Mihomo 配置。它不会记录 URL 路径、查询参数、网页内容或应用名称，也不能代替完整的流量审计工具。

🔄 它怎样工作

① 数据来源 ② 客户端处理 ③ 默认结果
Mihomo 日志和当前连接 Rule-Bot Client 筛选最终由 MATCH 处理的域名 保存到本地域名清单

Note

启用可选的 Rule-Bot 后，客户端还会把域名发送给 Rule-Bot 检查；通过检查的域名才会进入 GitHub 规则仓库。

Rule-Bot 发送功能默认关闭。只使用本地收集时，域名不会发送给 Rule-Bot。

🔗 与其他项目的关系

Rule-Bot Client 可以独立完成本地域名收集。其余项目只在对应场景中使用：

项目 作用 是否必需
Rule-Bot 检查候选域名，并按服务端策略写入目标 GitHub 规则仓库 可选；本地收集不需要
Custom_OpenClash_Rules 项目公共 Rule-Bot 的目标规则仓库 仅使用公共提交服务时相关
SubConverter-Extended 可选的订阅转换后端，可使用 Custom_OpenClash_Rules 模板生成配置 与域名收集和发送没有直接依赖

公共服务中的数据流为：

Mihomo 的 MATCH 连接 → Rule-Bot Client 本地收集 → 用户主动启用发送 → Rule-Bot 检查 → Custom_OpenClash_Rules

✅ 安装前需要确认

  • 已有正在运行的 Mihomo 内核。使用 OpenClash 或 Nikki 时，需要确认它们当前使用的是 Mihomo。
  • 安装 Rule-Bot Client 的设备能够访问 Mihomo 控制接口。控制接口设置了密钥时，还需要准备对应密钥。
  • Mihomo 日志级别为 info 或更详细。日志级别只保留警告或错误时，客户端看不到用于判断 MATCH 的连接日志。
  • 已确认有权收集设备或网络中的域名。共享网络尤其需要先了解下方的隐私边界。

OpenWrt 软件包可以自动发现本机的 OpenClash 或 Nikki。其他部署方式通常需要填写 Mihomo 控制接口的地址和密钥。

具体位置和示例见 Wiki 的配置说明。

🎯 只选择一个部署位置

Important

同一套网络通常只需部署一个 Rule-Bot Client，不需要在 OpenWrt 和 Linux 上各安装一份。只要部署位置能够访问各个 Mihomo 控制接口，一个客户端就能同时采集多个正在运行的 Mihomo 内核，并统一去重。

优先选择能够长期运行、且可以访问各个 Mihomo 控制接口的 Linux、NAS 或其他能够运行 Docker 的设备。只有 OpenWrt 是唯一合适的常驻设备时，再把客户端安装到 OpenWrt。仅当网络相互隔离，没有任何一个部署位置能够访问全部控制接口时，才需要部署多个客户端。

🚀 选择安装方式

使用环境 推荐方式 说明
🐳 已安装 Docker 的 Linux 或 NAS Docker Compose 镜像支持 linux/amd64 和 linux/arm64
📦 Debian 或 Ubuntu .deb 软件包 支持 amd64、arm64 和 armhf，作为系统服务运行
🧰 不使用 Docker 的 Linux 原生二进制 提供 AMD64、386、ARM、MIPS、MIPS64、RISC-V 等构建，需要自行管理服务
🪟 Windows 10 或 11 便携压缩包 提供 AMD64 和 ARM64 构建，解压后编辑配置即可运行
📡 只有 OpenWrt 常驻设备 LuCI 软件包 支持 OpenWrt 24.10 和 25.12 的四种常见架构，通过 OpenWrt Web 界面配置

当前没有 macOS 正式构建。OpenWrt 必须使用专用的 IPK 或 APK 软件包，不要安装通用 Linux 压缩包。

推荐：Linux、NAS 或 Docker

Debian 软件包、Docker Compose 和原生二进制的完整步骤见 Linux 部署方式。

Linux 版本没有 Web 管理页面，需要编辑 JSON 文本配置文件，并通过日志和输出文件确认状态。

Windows 便携版

从正式版本页面下载与设备匹配的 Windows 压缩包。解压、复制并编辑示例配置后即可运行，不需要安装程序。完整步骤见 Windows 便携版。

只有 OpenWrt 设备时

Warning

OpenWrt 包由本项目通过 GitHub Releases 发布，不属于 OpenWrt 官方软件源。固件升级不能保证保留或自动重装该包。

如果新固件没有包含它，Rule-Bot Client 程序、后台服务和 LuCI 管理页面会消失。选择保留设置且保留清单完整时，配置和默认持久化数据可以继续保留；软件包丢失后仍需重新安装。详见 OpenWrt 使用指南。

软件包安装后会启用后台服务并尝试启动。默认设置会自动发现 OpenClash，并且只在本地保存域名；Rule-Bot 发送功能默认关闭。运行安装命令前，需要确认允许在这台路由器上收集域名。

在 OpenWrt 的 SSH 终端中运行：

wget -O /tmp/install-rule-bot-client-openwrt.sh \
  https://github.com/Aethersailor/Rule-Bot-Client/releases/latest/download/install-rule-bot-client-openwrt.sh
cat /tmp/install-rule-bot-client-openwrt.sh
sh /tmp/install-rule-bot-client-openwrt.sh

脚本会识别 OpenWrt 版本、软件包格式和设备架构，并在安装前校验下载文件。

安装完成后，打开「服务 → Rule-Bot Client」。首次连接和验证步骤见 OpenWrt 使用指南。

🔎 怎样确认已经正常工作

安装成功不代表已经连接 Mihomo。按下面的顺序检查：

检查内容 正常表现
🟢 后台服务 OpenWrt「概览」显示正在运行，或 Linux、Docker 显示进程正在运行
🔗 Mihomo 控制接口 OpenWrt「测试连接」成功，或 Linux 日志出现 instance=... connected
📝 本地收集 访问一个此前未收集、最终由 MATCH 处理的域名后，「本地结果」或输出文件出现新行
🤖 Rule-Bot 处理 启用后，日志显示已添加、规则已存在、GeoSite 已覆盖或策略拒绝等最终结果

本地输出默认每 5 秒刷新一次。--check 只检查 JSON 格式、凭据和 HTTPS 证书文件，不会连接 Mihomo。因此，出现 configuration is valid 只代表配置可以读取，不代表 Mihomo 已经连通。

如果不确定某次连接是否由 MATCH 处理，可以先在 Mihomo 管理面板、OpenClash 日志或连接详情中查看命中的规则。所有连接都命中前面的其他规则时，没有新增域名是正常现象。

🔐 隐私与使用边界

Caution

域名清单可能反映个人、家庭或组织网络的访问行为。本地清单不会自动过期。成功添加的域名会进入目标仓库的提交历史；目标仓库公开时，域名也会公开。之后吊销访问令牌或关闭客户端，无法撤回已有提交。

  • 本地域名清单每行只包含一个域名，不为每个域名记录访问次数或时间戳；运行日志和可选状态文件仍会包含运维时间与计数。
  • 默认也会收集连接失败、但最终由 MATCH 处理的域名；不需要时可以在配置中关闭。
  • OpenWrt 和随附示例默认只保存可注册部分。例如，service.example.co.uk 保存为 example.co.uk，从而减少完整子域带来的识别风险。
  • Mihomo 的实时日志没有历史队列。客户端断线期间已经结束的短连接可能无法补回，因此本项目不保证审计级的零丢失。
  • 使用公网 Rule-Bot 提交地址时必须使用 HTTPS。不要把访问令牌、Mihomo 控制接口密钥或完整配置发布到 Issue、聊天记录或公开仓库。

启用 Rule-Bot 前，请阅读完整的 客户端隐私说明 和对应服务方的隐私说明。使用项目公共服务时，同时阅读 Rule-Bot 隐私说明。

🤖 可选：发送给 Rule-Bot

本地收集正常后，可以填写服务方提供的 Rule-Bot 提交地址和访问令牌（Token）：

  • 私用地址由 Rule-Bot 部署者提供。
  • 社区用户可以按照 Wiki 的接入公共 Rule-Bot流程，私聊 @asailor_rulebot，阅读并同意隐私说明，通过群成员验证后领取个人访问令牌。
  • 群聊只用于社区资格验证。客户端不会读取群消息，也不会把处理结果发送到群内。
  • 首次启用且没有发送进度文件时，默认只发送之后新增的域名，不发送本地清单中的历史内容。已有发送进度文件时，重新启用会从原进度继续。

项目公共 Rule-Bot 会把通过检查的域名写入 Custom_OpenClash_Rules 的 rule/Custom_Direct.list。自行部署的 Rule-Bot 可以使用其他目标仓库；客户端不会自行选择仓库或规则文件。

具体字段见 Wiki 的配置说明。

自行部署 Rule-Bot 时，另见 Rule-Bot Client 接入说明。

📚 用户文档

文档 内容
🐧 Linux 部署方式 根据系统选择 Debian 软件包、Docker Compose 或原生二进制
🪟 Windows 便携版 下载、配置、运行和自动更新 Windows 便携包
📡 OpenWrt 使用指南 安装、首次配置、升级、备份和卸载
⚙️ 配置说明 Mihomo 控制接口、域名保存方式、Rule-Bot、HTTPS 和代理设置
🔗 接入公共 Rule-Bot 申请个人 Token、配置客户端、验证处理结果和管理凭据
🩺 故障排查 无法启动、无法连接、没有结果和 Rule-Bot 发送失败
🔐 隐私说明 本地保存、发送到外部的数据、出口 IP 和用户控制
🛡️ 安全策略 私密报告安全问题，以及公开反馈前需要移除的信息

💬 反馈与许可

使用问题或功能建议可以提交到 GitHub Issues。公开反馈前，请移除访问令牌、Mihomo 控制接口密钥、私有地址和真实域名清单。

本项目采用 GNU Affero General Public License v3.0。