Skip to content

配置说明

Jump to bottom
Aethersailor edited this page Aug 11, 2026 · 4 revisions

⚙️ 配置说明

🧭 页面导航： Wiki 首页 · Linux 部署方式 · OpenWrt 使用指南 · 故障排查 · 隐私说明

OpenWrt 用户通常只需使用 LuCI，也就是 OpenWrt 的 Web 管理界面。本文主要说明 Linux 版本使用的 JSON 配置文件，也可以帮助理解 LuCI 中各项设置的含义。JSON 是一种有固定括号、引号和字段名称的文本格式；修改时需要保留这些符号。

📌 本页导航： 控制接口 · 基本设置 · 连接 Mihomo · Rule-Bot · 检查配置 · 保护数据

Mihomo 控制接口是什么

Mihomo 内置了一套 HTTP 管理接口，配置项通常叫 external-controller。Mihomo 管理面板（Dashboard）、OpenClash、Nikki 和其他管理工具都可以通过这个接口读取 Mihomo 状态。本文把它称为「Mihomo 控制接口」，英文资料和程序日志中也常写作 Controller。

Rule-Bot Client 通过这个接口读取 Mihomo 日志和当前连接。它不是需要另外安装的程序。

连接控制接口通常需要两项信息：

  • 控制接口地址：例如 http://127.0.0.1:9090。其中 127.0.0.1 表示同一台设备，9090 是示例端口。
  • 控制接口密钥：对应 Mihomo 配置中的 secret。Mihomo 没有设置 secret 时可以留空。

OpenWrt 软件包可以自动发现本机的 OpenClash 或 Nikki。手工配置和 Linux 部署需要从 Mihomo、OpenClash 或 Nikki 的现有设置中查找 external-controller 和 secret。不要把 Rule-Bot 访问令牌填入 Mihomo 控制接口密钥。

一套网络通常只运行一个 Rule-Bot Client。部署位置能够访问多个 Mihomo 控制接口时，把它们添加到同一份配置的 instances 列表即可，不需要为每个 Mihomo 内核重复部署客户端。

从示例开始

不同安装方式使用的示例位置如下：

  • Debian 软件包：/etc/rule-bot-client/config.json；
  • Docker Compose：容器配置示例；
  • 原生压缩包：config.example.json。

普通部署直接在权限受限的配置文件中填写 Mihomo 控制接口密钥和 Rule-Bot 访问令牌。secret_file、secret_env、token_file 和 token_env 面向已有密钥管理方案的进阶用户，首次安装不需要使用。

Tip

首次配置先使用直接填写的 secret，并保持 rule_bot.enabled=false。确认本地收集正常后，再决定是否启用 Rule-Bot 或改用文件、环境变量管理凭据。

最小的本地收集配置如下：

{
  "version": 1,
  "output": "/var/lib/rule-bot-client/domains.txt",
  "domain_mode": "registrable_domain",
  "instances": [
    {
      "name": "home",
      "url": "http://127.0.0.1:9090",
      "secret": "replace-with-your-mihomo-secret"
    }
  ]
}

Mihomo 没有设置 secret 时，删除该字段。不要保留值为空的 secret。

基本设置

字段 默认值 说明
version 无 必填；当前只能填写 1
output 无 必填；保存本地域名清单的文件路径。相对路径以配置文件所在目录为基准
domain_mode hostname 决定保存完整主机名，还是只保存可注册部分；建议明确填写 registrable_domain
flush_interval 5s 把新结果写入本地文件的间隔
include_failed_connections true 是否收集连接失败、但最终由 Mihomo 兜底规则 MATCH 处理的域名
include_single_label_hosts false 是否处理不含点的局域网主机名，例如 printer；只有 domain_mode=hostname 时才会最终保留
status_file 未设置 可选的运行状态 JSON 文件；主要供界面或监控读取，OpenWrt 会自动管理
runtime_cache_dir 未设置 可选的运行时去重缓存目录；普通部署无需设置
instances 无 必填；需要连接的 Mihomo 控制接口列表，至少包含一项
rule_bot 关闭 可选的 Rule-Bot 发送设置

程序会拒绝不认识的 JSON 字段。字段名称拼错时，配置检查会直接报错，不会静默忽略。

Debian 随附的 systemd 系统服务限制了程序可以写入的位置，默认允许写入 /var/lib/rule-bot-client。如果把 output 改到其他目录，除了修改文件权限，还需要调整 systemd 服务的可写路径限制。

选择域名保存方式

  • hostname：保存完整主机名。例如，api.example.com 仍保存为 api.example.com。
  • registrable_domain：根据内置的公共后缀表，只保存可注册部分。例如，api.example.com 保存为 example.com，service.example.co.uk 保存为 example.co.uk。这种方式通常能减少完整子域带来的识别风险。

OpenWrt 和仓库随附示例都明确使用 registrable_domain。Linux 自行编写配置时，如果省略 domain_mode，程序会使用 hostname 并保留完整子域。

输出文件只追加新内容。修改 domain_mode 不会重写已有结果。如果需要切换保存方式并保持文件内容一致，先停止服务并备份旧输出，再使用新的空输出文件和新的 Rule-Bot 发送进度文件。保持 send_existing=false 可以避免重新发送历史内容。

连接 Mihomo 控制接口

instances 中的每一项代表一个监听目标，也就是一个 Mihomo 控制接口：

字段 是否必填 说明
name 是 监听目标的名称，用于区分日志和状态；可使用 1 至 64 个英文字母、数字、点、下划线或连字符
url 是 Mihomo 控制接口地址，只允许 HTTP 或 HTTPS；不要附加 /logs 等 API 路径或查询参数
secret 否 直接填写 Mihomo 配置中的 secret；Mihomo 没有设置密钥时省略
secret_file 否 从文件读取密钥，与 secret、secret_env 三选一
secret_env 否 从环境变量读取密钥，与其他密钥来源三选一
tls 否 使用 HTTPS 时的自定义证书颁发机构（CA）证书和服务器名称等设置
reconnect 否 连接失败后的重试间隔；普通部署无需修改

在 OpenWrt 的「监听目标」页面中，url 对应「控制器地址」，secret 对应「控制器密钥」。这里的「控制器」就是 Mihomo 控制接口。

一个客户端可以同时连接多个控制接口：

"instances": [
  {
    "name": "home",
    "url": "http://127.0.0.1:9090",
    "secret": "replace-with-home-secret"
  },
  {
    "name": "remote",
    "url": "https://controller.example:9090",
    "secret": "replace-with-remote-secret",
    "tls": {
      "ca_file": "/etc/rule-bot-client/private-ca.pem",
      "server_name": "controller.example"
    }
  }
]

每个监听目标独立连接和重连，但所有目标共享同一个输出文件、全局去重结果和一套 Rule-Bot 发送进度。一个目标离线不会阻止其他目标收集。

只有在网络相互隔离、没有任何一台设备能够访问全部控制接口时，才需要在不同网络中分别部署客户端。多个客户端不会共享本地去重结果或 Rule-Bot 发送进度。

reconnect.initial_delay 和 reconnect.max_delay 默认分别为 500ms 和 30s。连接失败时，重试等待时间会在这个范围内逐步增加，通常无需修改。

安全连接

  • 控制接口与客户端位于同一台设备时，可以使用 http://127.0.0.1:9090。
  • 控制接口需要跨越不可信网络时，使用 HTTPS 或受保护的专用网络。
  • HTTPS 证书校验默认开启。insecure_skip_verify=true 会关闭证书验证，只用于短时间排查，并应在排查后恢复。
  • 不要把没有设置密钥的 Mihomo 控制接口暴露到公网或其他不可信网络。

可选：发送给 Rule-Bot

本地收集不需要 Rule-Bot。只有需要自动检查和补充规则时，才启用以下设置：

"rule_bot": {
  "enabled": true,
  "endpoint": "https://rule-bot.example.com/api/v1/rule-bot-client/replace-with-private-path",
  "token": "replace-with-your-rule-bot-token",
  "state_file": "/var/lib/rule-bot-client/rulebot-state.json",
  "send_existing": false,
  "privacy": {
    "reduce_to_registrable_domain": true,
    "exclude_suffixes": ["internal.example"]
  }
}
字段 默认值 说明
enabled false 是否把域名发送给 Rule-Bot
endpoint 无 服务方提供的完整提交地址；必须是带有具体路径的 HTTP 或 HTTPS URL
token 无 直接填写访问令牌，作用类似密码；配置文件必须限制访问
token_file 未设置 从文件读取访问令牌，与 token、token_env 三选一
token_env 未设置 从环境变量读取访问令牌，与其他来源三选一
state_file <output>.rulebot-state.json 记录发送进度，避免重启后重复发送；不能与 output 使用同一个文件
send_existing false 仅在首次启用且发送进度文件不存在时，决定是否发送本地清单中的历史内容
privacy.reduce_to_registrable_domain true 发送前只保留域名的可注册部分
privacy.exclude_suffixes 空 永远不发送的域名后缀
privacy.exclude_file 未设置 从文件读取排除后缀，每行一项；可以包含空行和以 # 开头的注释
proxy_url 未设置 可选的 HTTP、HTTPS、SOCKS5 或 SOCKS5H 代理地址
proxy_from_environment false 是否读取服务进程的标准代理环境变量；不能与 proxy_url 同时使用

公网提交地址必须使用 HTTPS。完整地址中不要包含 URL 查询参数、片段或用户名密码。

首次使用建议保持 send_existing=false 和 privacy.reduce_to_registrable_domain=true。这样，在没有发送进度文件时，客户端只发送启用后新增的域名，并在发送前减少完整子域信息。

进阶：文件、环境变量和代理

环境变量凭据不会仅凭字段名自动出现在服务进程中。systemd 用户需要通过权限受限的 EnvironmentFile 或服务覆盖配置显式注入。Docker Compose 用户需要在自己的 compose.yaml 中配置 environment 或 env_file。

仓库的默认 Compose 文件不会自动继承宿主机上的任意变量。不熟悉这些方式时，直接在权限受限的配置文件中填写 secret 和 token 更简单。

排除文件会在处理每个域名前重新读取，修改后无需重启。文件缺失、过大或包含无效内容时，客户端不会发送当前域名，也不会推进发送进度；主进程会退出并报告错误。systemd 或 OpenWrt 服务管理器可能随后重启进程。客户端不会绕过排除规则继续发送。

怎样理解 Rule-Bot 的处理结果

以下结果都表示 Rule-Bot 已经处理完当前域名，不需要重试：

  • 已添加到规则；
  • 规则中已经存在；
  • GeoSite 域名库已经覆盖；
  • 服务端策略拒绝添加。

限流、服务异常、网络错误和身份验证失败表示处理尚未完成。客户端会保留发送进度并自动重试。使用 token_file 时，每次重试都会重新读取访问令牌。

社区用户应从对应 Rule-Bot 的私聊入口获取完整提交地址和个人访问令牌。群聊只用于资格验证，不是客户端发送域名或接收结果的通道。

检查配置

Debian 软件包应使用实际运行服务的账户检查配置：

sudo -u rule-bot-client \
  /usr/bin/rule-bot-client --config /etc/rule-bot-client/config.json --check

Docker Compose：

cd /opt/rule-bot-client
docker compose run --rm rule-bot-client --config /data/config.json --check

原生安装也应使用最终运行服务的账户执行 --check。成功时命令输出 configuration is valid。该命令只检查配置、凭据和证书文件，不连接 Mihomo，也不会开始持续收集。

保护配置和结果

  • Debian 配置建议保持所有者 root:rule-bot-client、权限 0640。
  • Docker 配置建议保持所有者 root:10001、权限 0640；数据目录保持所有者 10001:10001、权限 0750。
  • 原生单用户配置至少使用 0600 权限。
  • 不要把真实配置、访问令牌、Mihomo 控制接口密钥或域名输出提交到 Git。

数据发送范围、出口 IP 和撤回限制见隐私说明。

🧭 Rule-Bot Client

🚀 安装与使用

🧰 配置与故障排查

Clone this wiki locally