Skip to content

Rule Bot Client 接入

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

🔌 Rule-Bot Client 接入

在明确隐私与安全边界后，接入私用或社区客户端。

🏠 首页 · 🛠️ 部署与故障排查 · ⚙️ 配置说明 · 🔐 隐私说明

Rule-Bot Client 可以把实际流量中捕获的域名提交给 Rule-Bot。Rule-Bot 随后执行与 Telegram 相同的域名规范化、去重、GeoSite、DNS、NS、GeoIP、限流和 GitHub 写入检查。

Note

客户端不能指定目标仓库、规则文件、提交身份、说明或强制添加。最终写入位置始终由 Rule-Bot 部署配置决定。

Warning

Rule-Bot Client 可能观察家庭、组织或共享网络中多个设备访问的域名。 启用前，必须确认有权收集和提交这些数据。成功添加的域名会公开写入 GitHub 规则文件和提交历史，无法作为临时私密数据撤回。

🧭 选择接入方式

方式 默认端口 适合场景 凭据 管理方式
🔒 私用入口 8765 部署者自己的客户端 一个部署者管理的静态高强度 Token 部署者自行创建和轮换
👥 社区入口 7654 为群成员提供接入 每位用户独立 Token 通过 Telegram 签发、续签和吊销

Important

两个入口默认关闭，不能共用同一个监听地址和端口，也不应共享凭据。

✅ 共同要求

  • 使用 HTTPS。可以通过反向代理、Cloudflare Tunnel 或 Rule-Bot 内置 TLS 终止。
  • 宿主机端口只绑定到 127.0.0.1，再由 HTTPS 入口转发。
  • 使用随机 API 路径减少扫描噪声，但始终保留 Bearer Token 鉴权。
  • 不在 Compose、仓库、聊天记录、URL 查询参数或公开日志中明文保存 Token。
  • 启用社区入口时，持久化 /app/data。

API 路径必须以 / 开头，只能包含字母、数字、/、_ 和 -，总长度为 12 至 200 个字符。Token 和签名密钥至少为 32 个字符。

🔑 准备目录和密钥

在 docker-compose.yml 所在目录执行：

mkdir -p data secrets
openssl rand -hex 32 > secrets/private-token
openssl rand -hex 32 > secrets/signing-key
chown -R 1000:1000 data secrets
chmod 700 data secrets
chmod 400 secrets/private-token secrets/signing-key

如果只启用一个入口，可以只创建对应密钥文件。

在 Compose 服务中启用持久化目录和只读密钥目录：

volumes:
  - ./data:/app/data
  - ./secrets:/run/secrets/rule-bot:ro

🔒 私用入口

1️⃣ 发布回环端口

ports:
  - "127.0.0.1:8765:8765"

2️⃣ 添加环境变量

environment:
  RULE_BOT_CLIENT_PRIVATE_API_ENABLED: "true"
  RULE_BOT_CLIENT_PRIVATE_API_PORT: "8765"
  RULE_BOT_CLIENT_PRIVATE_API_PATH: "/api/v1/rule-bot-client/replace-with-a-random-private-path"
  RULE_BOT_CLIENT_PRIVATE_API_TOKEN_FILE: "/run/secrets/rule-bot/private-token"

可选配置：

配置项 默认值 说明
RULE_BOT_CLIENT_PRIVATE_API_HOST 0.0.0.0 容器内监听地址；通常无需修改
RULE_BOT_CLIENT_PRIVATE_API_RATE_LIMIT_PER_HOUR 1000 私用入口每小时请求上限
RULE_BOT_CLIENT_PRIVATE_API_TLS_CERT_FILE 未设置 内置 TLS 证书文件
RULE_BOT_CLIENT_PRIVATE_API_TLS_KEY_FILE 未设置 内置 TLS 私钥文件，必须与证书同时设置

Warning

私用 Token 没有社区入口的逐用户身份、同意、续签和吊销能力。不要把私用 Token 分发给社区用户。

👥 社区入口

社区入口必须先启用 Telegram 群成员验证。以下三项缺一不可：

environment:
  REQUIRED_GROUP_ID: "-1001234567890"
  REQUIRED_GROUP_NAME: "示例交流群"
  REQUIRED_GROUP_LINK: "https://t.me/example_group"

1️⃣ 发布回环端口

ports:
  - "127.0.0.1:7654:7654"

2️⃣ 添加环境变量

environment:
  RULE_BOT_CLIENT_COMMUNITY_API_ENABLED: "true"
  RULE_BOT_CLIENT_COMMUNITY_API_PORT: "7654"
  RULE_BOT_CLIENT_COMMUNITY_API_PATH: "/api/v1/rule-bot-client/replace-with-a-different-random-path"
  RULE_BOT_CLIENT_COMMUNITY_API_BASE_URL: "https://rule-bot.example.com"
  RULE_BOT_CLIENT_COMMUNITY_TOKEN_SIGNING_KEY_FILE: "/run/secrets/rule-bot/signing-key"
  RULE_BOT_CLIENT_COMMUNITY_TOKEN_DATABASE: "/app/data/rule_bot_client_tokens.sqlite3"

RULE_BOT_CLIENT_COMMUNITY_API_BASE_URL 必须是一个 HTTP 或 HTTPS 源地址，不能包含路径、查询参数、用户名或密码。公网部署应使用 HTTPS。

可选配置：

配置项 默认值 说明
RULE_BOT_CLIENT_COMMUNITY_API_HOST 0.0.0.0 容器内监听地址；通常无需修改
RULE_BOT_CLIENT_COMMUNITY_API_RATE_LIMIT_PER_HOUR 50 每个社区 Token 主体每小时请求上限
RULE_BOT_CLIENT_COMMUNITY_TOKEN_TTL_DAYS 90 Token 有效期，可设置为 1 至 365 天
RULE_BOT_CLIENT_COMMUNITY_API_TLS_CERT_FILE 未设置 内置 TLS 证书文件
RULE_BOT_CLIENT_COMMUNITY_API_TLS_KEY_FILE 未设置 内置 TLS 私钥文件，必须与证书同时设置

用户在 Telegram 私聊主菜单的“Rule-Bot Client Community 接入”页面阅读并确认隐私说明后申请 Token。Token 只显示一次；重新签发会废止旧 Token。隐私说明版本更新后，现有 Token 会暂停，用户确认新版本后才能继续使用。

🌐 HTTPS 与反向代理

推荐保持 Compose 的回环端口映射：

私用 HTTPS 域名    → 127.0.0.1:8765
社区 HTTPS 域名    → 127.0.0.1:7654

Caution

不要把容器端口映射为 0.0.0.0:8765:8765 或 0.0.0.0:7654:7654 后直接暴露到公网。HTTPS 保护传输，但不代替 Token 鉴权；隐藏路径也不是密码。

如果不使用反向代理，可以成对设置对应入口的 TLS_CERT_FILE 和 TLS_KEY_FILE。只设置其中一个时，Rule-Bot 会拒绝启动。

Cloudflare、反向代理或其他 TLS 终止服务在技术上能够处理出口 IP、请求时间、路径、Authorization 请求头和请求正文。详细边界见 隐私说明。

🧪 启动与验证

应用配置：

docker compose up -d
docker compose ps
docker compose logs --tail=200 rule-bot

先确认容器为 healthy，并且日志没有入口配置错误。然后：

  • 私用入口： 在自己的 Rule-Bot Client 中填写 HTTPS 地址、随机路径和私用 Token，提交一个非敏感测试域名。
  • 社区入口： 在 Telegram 私聊中申请 Token，再把 HTTPS 地址、路径和 Token 写入 Rule-Bot Client 的独立只读凭据文件。

Tip

验证结果： 客户端返回明确处理结果，目标 GitHub 仓库出现预期提交。不要为了测试把真实 Token 放进命令行历史、截图或 Issue。

💾 数据与恢复

备份以下内容：

  • ./data/rule_bot_client_tokens.sqlite3；
  • ./secrets/signing-key；
  • ./secrets/private-token；
  • 已脱敏或受保护的 Compose 配置。

社区数据库记录签发、到期、吊销和隐私同意状态。丢失数据库会丢失这些状态；丢失或更换签名密钥会使现有社区 Token 无法继续通过校验。

🔐 隐私边界

Rule-Bot Client API 只接受 version 和 domain，不会接受客户端指定仓库、规则文件、提交身份、说明或来源。API 业务事件不记录原始域名，HTTP access log 默认关闭；成功添加的域名仍会公开进入 GitHub 历史。

Rule-Bot Client 的本地文件、主域缩减、排除项、代理和可靠投递边界见 Rule-Bot Client 隐私说明。服务端社区入口的数据处理和用户控制见 Rule-Bot 隐私说明。

🏠 返回首页 · 🛠️ 查看部署与故障排查 · ⚙️ 返回配置说明

🤖 Rule-Bot

📚 使用文档

🔗 快捷入口

Clone this wiki locally