Linux 与 Docker

Wiki 首页 · OpenWrt 使用指南 · 配置说明 · 故障排查 · 隐私说明

Linux 用户可以选择 Debian 软件包、Docker Compose 或原生二进制。三种方式都使用 JSON 配置文件；只有 OpenWrt 软件包提供 LuCI Web 界面。

选择部署方式

方式	支持范围	适合场景
Debian 软件包	`amd64`、`arm64`、`armhf`	Debian、Ubuntu 等使用 systemd 的系统
Docker Compose	`linux/amd64`、`linux/arm64`	已安装 Docker，希望简化运行与更新
原生二进制	Releases 中列出的 AMD64、386、ARM、MIPS、MIPS64、RISC-V 等架构	Docker 不可用，或需要自行管理服务

开始前，确认 Mihomo 外部控制器可以从部署位置访问，并将日志级别设为 info 或更详细。Controller URL 只填写源地址，例如 http://127.0.0.1:9090。

使用 Debian 软件包

1. 下载并校验

从 Releases 下载与系统架构匹配的 .deb 文件及同一版本的 checksums.txt。以下示例使用当前 amd64 软件包；其他架构替换为 Release 中的精确文件名：

package='rule-bot-client_0.2.0_amd64.deb'
awk -v file="./$package" '$2 == file { print }' checksums.txt | sha256sum -c -

确认目标 .deb 显示 OK 后再安装：

sudo apt install ./rule-bot-client_0.2.0_amd64.deb

ARM64 或 ARMHF 设备将文件名中的 amd64 换成实际下载的架构。软件包会创建 rule-bot-client 系统用户，安装 systemd 服务，并将示例配置写入 /etc/rule-bot-client/config.json。

2. 编辑并检查配置

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

至少需要修改 instances 中的 Controller URL 和 secret。Mihomo 没有设置密钥时，可以删除 secret 字段。只在需要提交给 Rule-Bot 时，才把 rule_bot.enabled 改为 true 并填写真实入口和 Token。

--check 只验证配置内容和引用的凭据、TLS 文件，不测试 Controller 网络连接。

3. 启动并验证

sudo systemctl enable --now rule-bot-client
sudo systemctl status rule-bot-client --no-pager
sudo journalctl -u rule-bot-client -n 100 --no-pager

日志出现 instance=... connected 后，产生一次此前未收集、实际命中 MATCH 的有效域名。等待最长一个刷新间隔，再检查：

sudo cat /var/lib/rule-bot-client/domains.txt

4. 更新

下载新版本 .deb 后再次执行 sudo apt install ./文件名.deb。配置文件属于软件包保留配置；如包管理器提示配置差异，应先审阅再选择。

当前 Debian 软件包不会在升级后自动重启已经运行的服务。安装完成后执行：

sudo -u rule-bot-client \
  /usr/bin/rule-bot-client --config /etc/rule-bot-client/config.json --check
sudo systemctl restart rule-bot-client
sudo systemctl status rule-bot-client --no-pager

使用 Docker Compose

正式镜像只发布 linux/amd64 和 linux/arm64。示例使用普通的 rootful Docker Engine、宿主机网络和固定 UID/GID，方便容器直接连接只监听在宿主机 127.0.0.1:9090 的 Mihomo；Rule-Bot Client 本身不监听端口。

以下 docker compose 命令需要由已经获准访问 Docker daemon 的账户执行；否则按本机 Docker 安装方式使用 sudo。不要仅为运行这些命令随意放宽 Docker socket 权限，访问 Docker daemon 等同于获得主机上的高权限。

Rootless Docker、userns-remap 或启用 SELinux 强制策略的主机需要按实际环境调整 UID/GID 映射或 bind mount 标签，不能直接照用下面的权限值。

1. 准备目录和版本匹配的文件

以下命令将配置、Compose 文件和镜像固定到当前正式版本 v0.2.0。Wiki 会随正式版本更新；执行前仍应对照 Releases 确认版本。

release='v0.2.0'
image_version=${release#v}

sudo install -d -m 0755 /opt/rule-bot-client
sudo install -d -o 10001 -g 10001 -m 0750 /opt/rule-bot-client/data

curl -fsSL \
  "https://raw.githubusercontent.com/Aethersailor/Rule-Bot-Client/$release/deploy/docker/config.json" \
  -o /tmp/rule-bot-client-config.json
sudo install -o root -g 10001 -m 0640 \
  /tmp/rule-bot-client-config.json /opt/rule-bot-client/config.json
rm /tmp/rule-bot-client-config.json

sudo curl -fsSL \
  "https://raw.githubusercontent.com/Aethersailor/Rule-Bot-Client/$release/compose.yaml" \
  -o /opt/rule-bot-client/compose.yaml
sudo sed -i "s#:latest\$#:${image_version}#" /opt/rule-bot-client/compose.yaml
sudo chmod 0644 /opt/rule-bot-client/compose.yaml

容器以 UID/GID 10001:10001 运行。不要跳过目录所有者和配置权限设置，否则容器可能无法读取配置或写入结果。

2. 编辑配置

sudo editor /opt/rule-bot-client/config.json

示例中的容器路径已经与 Compose 挂载匹配：配置文件是 /data/config.json，结果写入 /data/data/domains.txt。Controller 在其他设备上时，将 url 改为该设备的地址。

3. 检查并启动

cd /opt/rule-bot-client
docker compose config --quiet
docker compose run --rm rule-bot-client --config /data/config.json --check
docker compose up -d
docker compose ps
docker compose logs --tail=100

配置检查不会测试 Controller 网络连接。启动后应在日志中看到 instance=... connected。

产生一次此前未收集、实际命中 MATCH 的有效域名后，等待最长一个刷新间隔，再检查本地结果：

sudo cat /opt/rule-bot-client/data/domains.txt

4. 更新与停用

将 release 改成目标正式版本（保留开头的 v）。先下载同一标签下的新 Compose 和配置示例；配置示例只用于检查新增或变化的字段，不要覆盖包含真实凭据的现有配置：

release='v0.2.0'
image_version=${release#v}

curl -fsSL \
  "https://raw.githubusercontent.com/Aethersailor/Rule-Bot-Client/$release/compose.yaml" \
  -o /tmp/rule-bot-client-compose.yaml
sed -i "s#:latest\$#:${image_version}#" /tmp/rule-bot-client-compose.yaml
curl -fsSL \
  "https://raw.githubusercontent.com/Aethersailor/Rule-Bot-Client/$release/deploy/docker/config.json" \
  -o /tmp/rule-bot-client-config.example.json

cat /tmp/rule-bot-client-config.example.json
sudo install -m 0644 \
  /tmp/rule-bot-client-compose.yaml /opt/rule-bot-client/compose.yaml.next
rm /tmp/rule-bot-client-compose.yaml /tmp/rule-bot-client-config.example.json

根据目标版本的说明修改现有 config.json，并把自定义的环境变量、Rootless、userns 或 SELinux 设置合并到 compose.yaml.next。先用新 Compose 检查现有配置；检查失败时不要替换当前 Compose：

sudo editor /opt/rule-bot-client/config.json
sudo editor /opt/rule-bot-client/compose.yaml.next
cd /opt/rule-bot-client
docker compose -f compose.yaml.next config --quiet
docker compose -f compose.yaml.next pull
docker compose -f compose.yaml.next run --rm \
  rule-bot-client --config /data/config.json --check

以上检查都成功后，再切换到新 Compose 并更新容器：

cd /opt/rule-bot-client
sudo install -m 0644 compose.yaml.next compose.yaml
sudo rm compose.yaml.next
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=100

更新后确认实例已经连接，并再次检查本地结果。现有 config.json 和数据目录不会被上述步骤覆盖。

需要停用容器但保留配置和域名数据时，执行：

cd /opt/rule-bot-client
docker compose down

数据使用宿主机目录 /opt/rule-bot-client，docker compose down 不会删除该目录。

使用原生二进制

从 Releases 下载与系统架构匹配的 tar.gz 和同一版本的 checksums.txt。以下示例使用当前 RISC-V 64 位压缩包；将 archive 替换为实际下载的精确文件名：

archive='rule-bot-client_v0.2.0_linux_riscv64.tar.gz'
package=${archive%.tar.gz}
awk -v file="./$archive" '$2 == file { print }' checksums.txt | sha256sum -c -
tar -xzf "$archive"
cd "$package"
./rule-bot-client --version

安装并准备配置

以下命令把程序安装到 /usr/bin，以便之后复用项目提供的 systemd 服务文件。配置包含凭据，暂时保持 0600：

sudo install -m 0755 rule-bot-client /usr/bin/rule-bot-client
sudo install -d -m 0755 /etc/rule-bot-client
sudo install -m 0600 config.example.json /etc/rule-bot-client/config.json
sudo editor /etc/rule-bot-client/config.json

此时不运行程序。先创建下面的服务用户和状态目录，再以最终服务身份检查配置，避免留下服务用户无法访问的文件。

在 systemd 中运行

以下步骤适用于带有 systemd、getent、groupadd 和 useradd 的发行版。其他发行版应按本机的用户和服务管理方式调整；Debian 或 Ubuntu 用户优先使用 .deb 软件包。

getent group rule-bot-client >/dev/null || sudo groupadd --system rule-bot-client
nologin_path=
for candidate in /usr/sbin/nologin /sbin/nologin /usr/bin/nologin /bin/false /usr/bin/false; do
  if [ -x "$candidate" ]; then
    nologin_path=$candidate
    break
  fi
done
[ -n "$nologin_path" ] || { echo '找不到 nologin 或 false 可执行文件' >&2; exit 1; }
getent passwd rule-bot-client >/dev/null || \
  sudo useradd --system --gid rule-bot-client \
    --home-dir /var/lib/rule-bot-client --no-create-home \
    --shell "$nologin_path" rule-bot-client

sudo install -d -o rule-bot-client -g rule-bot-client -m 0750 /var/lib/rule-bot-client
sudo chown -R rule-bot-client:rule-bot-client /var/lib/rule-bot-client
sudo chown root:rule-bot-client /etc/rule-bot-client/config.json
sudo chmod 0640 /etc/rule-bot-client/config.json

release='v0.2.0'
curl -fsSL \
  "https://raw.githubusercontent.com/Aethersailor/Rule-Bot-Client/$release/deploy/systemd/rule-bot-client.service" \
  -o /tmp/rule-bot-client.service
sudo install -m 0644 /tmp/rule-bot-client.service /etc/systemd/system/rule-bot-client.service
rm /tmp/rule-bot-client.service

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

如需先验证 Controller，可以用最终服务身份前台运行。日志出现 instance=... connected 后按 Ctrl+C 结束：

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

确认无误后启用后台服务：

sudo systemctl daemon-reload
sudo systemctl enable --now rule-bot-client
sudo systemctl status rule-bot-client --no-pager

项目提供的服务文件固定使用 /usr/bin/rule-bot-client、rule-bot-client 用户和 /var/lib/rule-bot-client 状态目录。不要把程序装到 /usr/local/bin 后直接套用该文件，也不要让服务用户读取 root:root 0600 的配置。

更新原生安装

先下载、校验并解压新压缩包，不要覆盖现有配置。进入新解压目录后，把候选二进制放到临时路径，并以服务用户检查现有配置和引用文件：

sudo install -m 0755 rule-bot-client /usr/bin/rule-bot-client.new
sudo -u rule-bot-client \
  /usr/bin/rule-bot-client.new --config /etc/rule-bot-client/config.json --check

只有检查成功后才继续替换并重启：

sudo systemctl stop rule-bot-client
sudo mv /usr/bin/rule-bot-client.new /usr/bin/rule-bot-client
sudo systemctl start rule-bot-client
sudo systemctl status rule-bot-client --no-pager

候选检查失败不会影响当前服务，可以删除 /usr/bin/rule-bot-client.new 后继续排查。保留上一版本压缩包，便于新版本无法启动时按相同步骤换回旧二进制。若目标版本更新了 systemd 服务文件，也应下载同一标签下的新文件、审阅差异并执行 systemctl daemon-reload。使用环境变量凭据时，还需确保检查命令获得与 systemd 服务相同的受限环境。

查看版本

原生程序：

rule-bot-client --version

Docker Compose：

cd /opt/rule-bot-client
docker compose run --rm rule-bot-client --version

输出包含版本、源码提交和构建时间。配置字段及凭据用法见配置说明。

停用或卸载

卸载 Debian 软件包前，先显式停止并禁用服务：

sudo systemctl disable --now rule-bot-client
sudo apt remove rule-bot-client

不要假设卸载软件包会删除配置或域名数据。需要删除 /etc/rule-bot-client 或 /var/lib/rule-bot-client 时，应先检查并备份内容，再单独处理。

Docker Compose 使用上方的 docker compose down 即可停止并删除容器，同时保留 /opt/rule-bot-client 中的数据。

按本文配置的原生 systemd 安装可以这样移除程序和服务，同时保留配置与域名数据：

sudo systemctl disable --now rule-bot-client
sudo rm /etc/systemd/system/rule-bot-client.service
sudo rm /usr/bin/rule-bot-client
sudo systemctl daemon-reload

确认不再需要后，配置目录、状态目录和专用系统用户需要另行处理；不要把它们与程序一起直接删除。

🧭 Rule-Bot Client

🏠 Wiki 首页

🚀 安装与使用

🐧 Linux 部署方式
- 📦 Debian 软件包
- 🐳 Docker Compose
- 🧰 Linux 原生二进制
📡 OpenWrt 使用指南

🧰 配置与故障排查

⚙️ 配置说明
🩺 故障排查

Navigation Menu

Linux 与 Docker

Linux 与 Docker

选择部署方式

使用 Debian 软件包

1. 下载并校验

2. 编辑并检查配置

3. 启动并验证

4. 更新

使用 Docker Compose

1. 准备目录和版本匹配的文件

2. 编辑配置

3. 检查并启动

4. 更新与停用

使用原生二进制

安装并准备配置

在 systemd 中运行

更新原生安装

查看版本

停用或卸载

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

🧭 Rule-Bot Client

🚀 安装与使用

🧰 配置与故障排查

Clone this wiki locally