配置说明

⚙️ 配置说明

从四项必需变量开始，再按需要启用群聊、数据源与性能选项。

🏠 首页 · 🛠️ 部署与故障排查 · 🔌 Rule-Bot Client 接入

---

Rule-Bot 通过环境变量配置。仓库中的 docker-compose.yml 已包含常用配置示例；默认只启用 Telegram 私聊和 GitHub 直连规则管理。

Important

第一次部署只需填写四项必需配置。群聊、群成员验证、播报、管理员和 Rule-Bot Client 均为可选能力，建议在基础功能验证成功后逐项启用。

🧭 配置地图

目标	配置区域
启动基础 Telegram 机器人	必需配置
指定分支、日志和数据目录	GitHub 与日志
启用群验证、群聊、播报或管理员	在 Telegram 群组中使用
调整 DoH 和数据更新	数据源
调整缓存、连接或内存限制	性能与资源配置
保护 Token 与配置文件	配置安全

修改配置后，在 Compose 文件所在目录执行：

docker compose up -d
docker compose logs --tail=100 rule-bot

🔑 必需配置

配置项	说明
TELEGRAM_BOT_TOKEN	@BotFather 提供的 Bot Token
GITHUB_TOKEN	能够读取和更新目标仓库内容的 GitHub Token
GITHUB_REPO	目标仓库，格式为 owner/repository
DIRECT_RULE_FILE	直连规则文件相对于仓库根目录的路径

Note

目标规则文件必须已经存在，并使用 DOMAIN-SUFFIX,example.com 格式。Rule-Bot 不会自动创建仓库或规则文件。

🧑‍💻 GitHub 与日志

配置项	默认值	说明
GITHUB_BRANCH	仓库默认分支	指定规则写入分支
GITHUB_COMMIT_EMAIL	noreply@users.noreply.github.com	Rule-Bot 提交使用的邮箱；提交者名称固定为 Rule-Bot
LOG_LEVEL	INFO	支持 DEBUG、INFO、WARNING、ERROR
LOG_FORMAT	compact	使用 verbose、full 或 detail 时显示详细日志位置
TZ	Asia/Shanghai	容器时区
DATA_DIR	/app/data	GeoIP、IP 段、GeoSite 和可选数据库的容器内目录
DATA_UPDATE_INTERVAL	21600	外部数据更新间隔，单位为秒

PROXY_RULE_FILE 是尚未开放的代理规则功能预留项，当前无需配置。

在 Telegram 群组中使用

🔒 私聊前验证群成员身份

以下三项必须同时配置，缺少任意一项都会关闭群成员验证：

配置项	说明
REQUIRED_GROUP_ID	要求用户加入的 Telegram 群组 ID
REQUIRED_GROUP_NAME	机器人提示中显示的群组名称
REQUIRED_GROUP_LINK	用户加入群组时打开的链接

示例：

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

机器人必须已经加入该群组，并能够读取成员状态。

💬 在指定群组响应 @提及

设置 ALLOWED_GROUP_IDS。多个群组 ID 使用逗号分隔：

- ALLOWED_GROUP_IDS=-1001234567890,-1009876543210

启用前还需要：

1. 在 @BotFather 中关闭机器人的 Privacy Mode。
2. 把机器人移出群组并重新加入，使新设置生效。
3. 确认机器人能够读取群消息。

Warning

群聊模式只处理明确 @机器人 的文本消息。它会自动完成检查和添加，不再要求二次确认。

📣 私聊成功后发送群组播报

设置：

- ANNOUNCEMENT_GROUP_ID=-1001234567890

机器人必须在目标群组中具有发言权限。播报失败不会撤销已经完成的 GitHub 提交；群聊和 Rule-Bot Client 添加不会触发这项播报。

🛡️ 设置管理员

设置 ADMIN_USER_IDS。多个 Telegram 用户 ID 使用逗号、空格或分号分隔：

- ADMIN_USER_IDS=123456789,987654321

管理员可以强制添加被归属地策略拒绝的域名，但不能绕过无效域名、重复规则和 .cn 处理。

数据源

Rule-Bot 默认使用多个 DoH、GeoIP 和 GeoSite 数据源。通常无需修改。

配置项	说明
DOH_SERVERS	查询 A 记录的 DoH 服务，多个值使用 name=https://... 并以逗号分隔
NS_DOH_SERVERS	查询 NS 记录的 DoH 服务，格式同上
DATA_UPDATE_INTERVAL	GeoIP、IP 段和 GeoSite 数据更新间隔，单位为秒

只接受 https:// DoH 地址。自定义列表无法解析时，Rule-Bot 会记录警告并继续使用默认值。

示例：

- DOH_SERVERS=alibaba=https://dns.alidns.com/dns-query,cloudflare=https://cloudflare-dns.com/dns-query
- NS_DOH_SERVERS=cloudflare=https://cloudflare-dns.com/dns-query,google=https://dns.google/dns-query

🔌 Rule-Bot Client

Warning

Rule-Bot Client 的私用和社区入口默认关闭。不要只设置端口后直接暴露到公网。

接入所需的路径、Token、签名密钥、持久化目录、TLS 和限流配置见 Rule-Bot Client 接入。

📊 性能与资源配置

以下默认值适用于常规部署。只有在日志或监控已经证明需要调整时再修改。

🔧 查看缓存与连接参数

配置项	默认值	说明
DNS_CACHE_TTL	60	DNS 结果缓存时间，单位为秒
DNS_CACHE_SIZE	1024	DNS 缓存条目上限
NS_CACHE_TTL	300	NS 结果缓存时间，单位为秒
NS_CACHE_SIZE	512	NS 缓存条目上限
DNS_MAX_CONCURRENCY	20	DNS 查询并发上限
DNS_CONN_LIMIT	30	DNS HTTP 连接总上限
DNS_CONN_LIMIT_PER_HOST	10	每个 DoH 主机的连接上限
DNS_TIMEOUT_TOTAL	10	DNS 请求总超时，单位为秒
DNS_TIMEOUT_CONNECT	3	DNS 建立连接超时，单位为秒
GEOSITE_CACHE_TTL	3600	GeoSite 查询缓存时间，单位为秒
GEOSITE_CACHE_SIZE	2048	GeoSite 缓存条目上限
GEOIP_CACHE_TTL	21600	GeoIP 查询缓存时间，单位为秒
GEOIP_CACHE_SIZE	4096	GeoIP 缓存条目上限
GITHUB_FILE_CACHE_TTL	60	GitHub 规则文件缓存时间，单位为秒
GITHUB_FILE_CACHE_SIZE	4	GitHub 文件缓存条目上限

TTL 或缓存大小可以设为 0。连接数和超时必须大于 0。

可选的 MEMORY_SOFT_LIMIT_MB 和 MEMORY_HARD_LIMIT_MB 用于设置进程地址空间限制，默认不设置。硬限制不得小于软限制。容器级资源限制通常比进程地址空间限制更容易观察和维护。

🔐 配置安全

Caution

不要把真实 Token、签名密钥或隐藏 API 路径提交到 Git，也不要公开未脱敏的 docker compose config 输出。

• 限制 Compose 文件和密钥文件的读取权限。
• 为 GitHub Token 使用最小仓库范围和最小权限。
• 凭据泄露后，先撤销或轮换凭据，再处理日志和历史记录中的副本。

---

🏠 返回首页 · 🛠️ 查看部署与故障排查 · 🔌 继续接入 Rule-Bot Client