BetterForward

English README

为更好地转发 Telegram 消息而设计。

使用群组「话题」功能，将用户私聊消息转发到群组中——每位用户对应一个独立话题，多位管理员可协同处理，且无需暴露个人账号。

特点

• 隐私与协作：用户消息进入群组话题，管理员在群内回复，个人账号不直接暴露。
• 多语言：支持英语、简体中文、日语（en_US / zh_CN / ja_JP）。
• 自动回复：按关键词（支持正则）自动回复，可设置生效时段。
• 人机验证：按钮、数学题、Emoji、自定义问答、贴纸或 TGuard 验证，支持随机选择和按天设置验证有效期。
• 垃圾消息过滤：关键词识别后自动转入垃圾话题，不打扰正常会话。
• 权限控制：按消息类型限制用户可发送的内容；支持全局默认与单用户单独设置，可查看与重置。
• 用户管理：封禁/解封、封禁用户自动回复、结束会话、话题备注、广播消息等。

在群组主话题发送 /help 可打开管理菜单。

快速开始

1. 从 @BotFather 创建机器人并获取 Token。
2. 创建开启话题的群组，将机器人设为管理员（需能管理话题、删除消息）。
3. 获取群组 ID（可邀请 @sc_ui_bot 发送 /id）。
4. 部署 BetterForward（见下方 Docker 说明）。

用户私聊机器人的消息将转发到群组中对应的话题。

部署

可用语言：zh_CN（简体中文）、en_US（英语）、ja_JP（日语）。欢迎贡献更多语言翻译。

Docker（推荐）

Docker Compose

1. 下载 docker-compose.yml：

wget https://github.com/SideCloudGroup/BetterForward/raw/refs/heads/main/docker-compose.yml

2. 编辑并替换占位符：

   • your_bot_token_here → 机器人 Token
   • your_group_id_here → 群组 ID
   • zh_CN → 语言（en_US / zh_CN / ja_JP）
   • TG_API → 自定义 API 地址（留空使用默认）
   • WORKER → 工作线程数（流量大时可适当调高）

3. 启动：

docker compose up -d

Docker Run

将 /path/to/data 替换为实际数据目录：

docker run -d --name betterforward \
    -e TOKEN=<your_bot_token> \
    -e GROUP_ID=<your_group_id> \
    -e LANGUAGE=zh_CN \
    -e WORKER=2 \
    -v /path/to/data:/app/data \
    --restart unless-stopped \
    ghcr.io/sidecloudgroup/betterforward:latest

自定义 API

通过环境变量 TG_API 设置自定义 Telegram API 地址；留空则使用官方 API。

更新

使用 Docker 部署时，可通过 WatchTower 自动更新（请将下方命令中的容器名改为实际名称）：

docker run --rm \
-v /var/run/docker.sock:/var/run/docker.sock \
containrrr/watchtower -cR \
<容器名>

Bot 启动时会自动升级数据库。升级前会先把数据库备份为数据目录下的 storage.db.bak-<旧版本号>（保留最近 3 份）；升级失败时，停止容器，删除 storage.db-wal 和 storage.db-shm（如果有），再用备份覆盖 storage.db 即可恢复。

同一版本已有的备份会保留，升级失败后重启不会覆盖原始备份。备份完整写入后才会发布到上述路径。

功能说明

以下功能均在群组主话题发送 /help 后，通过管理菜单配置（除非另有说明）。

自动回复

• 添加、管理多条自动回复规则
• 支持正则匹配关键词
• 可设置规则生效时间段

菜单：自动回复

默认消息

设置用户首次联系机器人时收到的欢迎/提示消息。

菜单：默认消息

封禁与封禁回复

• 封禁指定用户，阻止其继续发消息
• 可为被封禁用户配置自动回复文案（也可关闭回复）

菜单：已封禁用户、封禁用户回复

人机验证

支持六种方式（在 验证码设置 中可启用多种，每次需要验证时随机选择一种）：

1. 按钮验证 — 点击按钮即可
2. 数学题验证 — 解答简单算术题
3. Emoji 验证 — 点击与题目对应的表情
4. 自定义问答验证 — 配置问题及可接受的答案，支持多个答案，忽略大小写和首尾空格
5. 贴纸验证 — 发送任意贴纸，或发回管理员指定的贴纸
6. TGuard 验证 — 需在 TGuard API 设置 中配置 API 地址与密钥，验证界面通过 Telegram Mini App 打开

在 验证码设置 → 验证有效期 中输入非负整数，单位为天，例如 7 或 30。默认 0 表示永久有效；设置大于 0 的天数后，从最近一次验证通过起计算，到期后的下一条消息会触发重新验证。适用于全部验证方式；普通聊天不会延长有效期。关闭验证码时不会要求重新验证。

修改有效期会立即用于已有验证记录。升级前的已验证用户保留验证状态，以数据库升级时间作为计时起点；默认永久有效的行为不变。

管理员也可在用户话题中使用 /verify true 手动标记用户为已验证并刷新有效期，或使用 /verify false 撤销验证。过期或旧消息中的验证按钮无法重复用于通过新验证。

垃圾消息过滤

• 在管理菜单中添加、查看、删除垃圾关键词
• 命中关键词的消息会转入专用垃圾话题，不创建用户话题

菜单：垃圾关键词

权限控制

在 权限设置 中可配置：

• 默认权限设置 — 全局控制用户能否发送：图片、贴图/动图、视频、语音、文件（含文档与音频）、链接、@用户名。默认全部允许，可按需关闭。
• 权限限制时的回复消息 — 用户发送被禁止类型的消息时，可自动回复提示（支持自定义模板，{permission} 会替换为对应类型名称）；也可关闭回复以实现静默拦截。

在用户话题中，管理员可单独调整该用户的权限：

命令	说明
/permissions	查看该用户各项权限状态
/allow <类型...>	单独允许，例如 /allow photo link
/disallow <类型...>	单独禁止，例如 /disallow sticker
/resetpermissions <类型...>	清除单独设置，恢复继承全局默认

类型键：photo、sticker、video、voice、file、link、username；使用 all 可一次操作全部类型（不含纯文本）。

广播与时区

• 广播消息 — 向所有用户发送通知
• 时区设置 — 影响自动回复等与时间相关的功能

话题备注

在用户话题中：

• /setnote <内容> — 设置或清除该话题的备注
• /getnote — 查看备注

用户标签（Tag）

通过机器人的启动链接给用户记录标签，例如标记用户来自哪个渠道，无需在管理菜单中配置。

1. 将 YourBot 替换为自己的机器人用户名，分享链接：https://t.me/YourBot?start=channel_a。
2. 用户打开链接并点击「开始」，机器人收到 /start channel_a 后，会将 channel_a 保存为该用户的标签。用户也可直接在与机器人的私聊中发送 /start channel_a。
3. 用户发送消息并创建话题后，标签会以 #标签 的形式显示在该话题的初始置顶用户资料中，例如 • 标签: #channel_a；如果话题已存在，管理员需在该用户话题中发送 /refresh，重新发送并置顶包含最新标签的用户资料。

显示时的 # 由机器人自动添加，启动链接参数和 /start 参数中只需填写标签本身，不要包含 #。

标签长度为 1–64 个字符，只允许英文字母、数字、下划线 _ 和连字符 -，例如 channel_a、website、campaign-2026；不支持中文或空格。

每位用户只保存一个标签，后续有效的 /start <标签> 会覆盖旧值；不带参数的 /start、/help 或无效参数不会清除已有标签。目前没有管理员手动设置、清除标签或按标签筛选/广播的命令。需要管理员填写的备注可使用 /setnote。

统计与用户信息

• /stats — 在群组内查看用户数、今日新增/活跃用户、今日收到与回复的消息数、封禁与已验证人数、消息队列状态
• /info — 在用户话题中查看该用户的资料、首次联系时间、最近消息时间、消息数、验证与封禁状态

升级前已有的用户，首次联系时间显示为“未知”，消息数按已有记录估算。

回复模板

在 回复模板 菜单中添加或删除常用回复。在用户话题中发送 /r <编号> 即可把对应模板发给用户，发送 /r 查看模板列表。

管理菜单每页显示 10 条模板。超长模板的详情会省略部分预览，但 /r <编号> 仍发送完整内容；模板列表过长时，/r 会分条显示。

菜单：回复模板

处理确认表情

用户或管理员发送的消息被 Bot 成功转发时，原消息上会出现 ❤ 表情，约 3 秒后自动消失，用来确认 Bot 正常在线。被验证、封禁、权限或垃圾过滤拦下的消息不会出现。

管理员命令

在群组内可用（部分命令仅适用于用户话题）：

命令	说明
/help	打开管理菜单
/ban	封禁当前话题用户
/unban [用户 ID]	解封用户；在用户话题中可省略 ID
/terminate [用户 ID]	结束会话并删除话题；在用户话题中可省略 ID
/delete	删除消息（回复要删除的消息后使用）
/verify	将用户标记为已通过验证
/setnote <内容>	设置话题备注
/getnote	查看话题备注
/refresh	刷新话题中的用户信息
/permissions	查看用户权限状态
/allow <类型...>	单独允许权限
/disallow <类型...>	单独禁止权限
/resetpermissions <类型...>	重置为继承全局默认
/stats	查看统计数据
/info	查看当前话题用户的信息
/r [编号]	发送回复模板；不带编号时列出模板

用户私聊中可用：/start [标签]、/help、/delete。

交流社区

• Telegram 频道 @betterforward

请通过 issues 报告问题或提出功能建议。