script/telegram/README.md

Telegram Bot Worker

tg-bot.js 是一个部署在 Cloudflare Workers 上的 Telegram 双向私聊中继 Bot。它会把用户私聊消息转发到管理员论坛群的独立 topic 中，管理员在对应 topic 内回复即可把消息发回用户，同时提供验证、过滤、封禁、备注、自动回复、备份和 Telegram 内联管理面板。

来源与致谢

本脚本基于 huliyoudiangou/TG_Chat_Bot-D1 二次修改与自用优化。原项目是一个基于 Cloudflare Worker 和 D1 数据库的 Telegram 双向机器人，并在 GitHub 页面中标注为 forked from moistrr/TGbot-D1。

感谢原作者提供 Cloudflare Worker + D1 + Telegram forum topic 的完整实现思路。本仓库版本主要保留原项目的核心工作流，并针对个人使用习惯做了精简、无回执体验、消息编辑同步和安全加固。

本版本调整

• 去掉用户侧“已送达”和管理员侧“已回复”回执，减少打扰和额外 API 调用。
• 兼容无 username 的 Telegram 用户，资料卡仍可通过 tg://user?id=... 建立用户链接。
• 支持用户编辑消息后，在管理员 topic 中记录修改前后内容。
• 支持管理员编辑 topic 内消息后，主动通知用户“对方修改了消息”。
• 支持 Webhook secret 校验，配置 TELEGRAM_WEBHOOK_SECRET 后会拒绝非 Telegram webhook 请求。
• 网页验证提交会校验 Telegram WebApp initData，并使用 nonce 防止伪造 user_id。
• 管理员 ID 与协管 ID 使用精确匹配，避免字符串片段误判。
• 屏蔽词和自动回复正则使用安全包装，降低坏正则导致 Worker 异常或 ReDoS 的风险。
• 新增 /del 命令：用户和管理员都可以删除消息（详见下方说明）。

核心功能

• 私聊用户消息转发到管理员群论坛 topic。
• 每个用户自动创建独立 topic，并推送用户身份卡片。
• 管理员在对应 topic 内回复，即可把消息复制回用户私聊。
• 支持 Cloudflare Turnstile 或 Google reCAPTCHA 人机验证。
• 支持二次问答验证。
• 支持文本、媒体、链接、转发、频道转发、音频、贴纸/GIF 等类型过滤。
• 支持关键词自动回复和屏蔽词计数封禁。
• 支持黑名单 topic、用户解封、备注、资料卡置顶。
• 支持消息编辑记录同步。
• 支持消息备份到指定群或频道。
• 内置 Telegram 管理面板，主管理员通过 /start 打开。
• 支持双向消息删除：用户和管理员都可以通过 /del 命令删除消息。

运行环境

• Cloudflare Workers
• Cloudflare D1 数据库绑定
• Telegram Bot Token
• 启用话题的 Telegram 管理群
• 可选：Cloudflare Turnstile 或 Google reCAPTCHA 密钥

必需环境变量

名称	说明
BOT_TOKEN	Telegram Bot Token
ADMIN_IDS	主管理员 Telegram user id，多个用英文或中文逗号分隔
ADMIN_GROUP_ID	管理员论坛群 ID，通常是 -100...
WORKER_URL	Worker 公开访问地址，不要带结尾斜杠

可选环境变量

名称	说明
TURNSTILE_SITE_KEY	Cloudflare Turnstile site key
TURNSTILE_SECRET_KEY	Cloudflare Turnstile secret key
RECAPTCHA_SITE_KEY	Google reCAPTCHA site key
RECAPTCHA_SECRET_KEY	Google reCAPTCHA secret key
WELCOME_MESSAGE	默认欢迎语，对应配置项 welcome_msg
VERIF_QUESTION	默认问答验证问题，对应 verif_q
VERIF_ANSWER	默认问答验证答案，对应 verif_a
TELEGRAM_WEBHOOK_SECRET	Telegram Webhook secret token，配置后会校验请求头

大多数运行时配置也可以在管理员面板中调整，并优先保存到 D1。

D1 绑定

Worker 需要绑定一个 D1 数据库，绑定名必须是：

TG_BOT_DB

脚本会自动创建和维护以下表：

• config：配置项。
• users：用户状态、封禁状态、topic 映射、用户资料。
• messages：用户消息与管理员群 topic 消息的映射。

默认配置

配置项	默认值	说明
welcome_msg	欢迎 {name}！使用前请先完成验证。	欢迎语，支持 {name} 或 {user}
enable_verify	true	是否启用网页人机验证
enable_qa_verify	true	是否启用问答验证
captcha_mode	turnstile	验证模式：turnstile 或 recaptcha
verif_q	1+1=?	问题验证题目
verif_a	3	问题验证答案
block_threshold	5	命中屏蔽词多少次后封禁
busy_mode	false	是否启用非营业自动回复
enable_admin_receipt	false	管理员回执开关，当前版本默认不发送回执

部署流程

1. 在 Telegram 中创建 Bot，拿到 BOT_TOKEN。
2. 创建一个启用 Topics 的 Telegram 群，把 Bot 拉入群。
3. 给 Bot 管理员权限，至少需要发消息、管理话题、置顶消息等能力。
4. 在 Cloudflare 创建 D1 数据库并绑定为 TG_BOT_DB。
5. 创建 Worker，把 tg-bot.js 作为 Worker 代码。
6. 配置环境变量 BOT_TOKEN、ADMIN_IDS、ADMIN_GROUP_ID、WORKER_URL。
7. 如果使用网页验证，配置 Turnstile 或 reCAPTCHA 的 site key 与 secret key。
8. 设置 Telegram Webhook。

不使用 secret token 时：

curl "https://api.telegram.org/bot<BOT_TOKEN>/setWebhook?url=<WORKER_URL>"

推荐配置 TELEGRAM_WEBHOOK_SECRET，并设置 Webhook secret token：

curl -X POST "https://api.telegram.org/bot<BOT_TOKEN>/setWebhook" \
  -d "url=<WORKER_URL>" \
  -d "secret_token=<TELEGRAM_WEBHOOK_SECRET>"

9. 访问 Worker 根路径，若返回 Bot v3.68 Active，说明 Worker 基本可用。
10. 主管理员私聊 Bot 发送 /start，打开控制面板。

Webhook 路由

路径	方法	用途
/	GET	健康检查
/verify	GET	Telegram Web App 验证页面
/submit_token	POST	验证 token 提交
/	POST	Telegram Webhook 更新入口

管理员面板

主管理员私聊 Bot 发送 /start 后会打开配置面板，包含：

• 基础：欢迎语、验证问题、验证答案、验证码模式、问题验证开关。
• 自动回复：添加或删除关键词自动回复。
• 屏蔽词：添加或删除正则关键词，命中后累计封禁。
• 过滤：控制转发、媒体、语音、贴纸、链接、频道、文本等类型。
• 协管：维护额外授权管理员。
• 备份/通知：设置备份群、重置黑名单 topic。
• 营业状态：切换忙碌模式并修改自动回复语。

自动回复新增格式：

关键词===回复内容

授权管理员可输入多个 ID：

123456,789012

用户流程

1. 用户私聊 Bot 发送 /start。
2. Bot 发送欢迎语。
3. 如果启用网页验证，用户点击按钮完成 Turnstile 或 reCAPTCHA。
4. 如果启用问答验证，用户继续回答问题。
5. 验证通过后，用户消息会转发到管理员群中的个人 topic。
6. 管理员在 topic 中回复，Bot 会把回复发送给该用户。
7. 用户或管理员编辑消息时，Bot 会同步对应的编辑提示。
8. 删除消息：
   • 用户侧：引用自己发送的消息，发送 /del 命令，可以删除该消息并通知管理员。
   • 管理员侧：在 topic 中引用消息，发送 /del 命令，可以同时删除用户侧和管理员侧的消息。
   • 注意：用户只能删除自己发送的消息，无法删除管理员回复的消息。

安全建议

• 推荐配置 TELEGRAM_WEBHOOK_SECRET；未配置时会保持兼容模式，不强制校验 Telegram Webhook secret。
• ADMIN_IDS 和协管列表会按逗号拆分后精确匹配。
• 管理员群必须开启 Topics，否则自动创建用户话题会失败。
• WORKER_URL 要使用 HTTPS 公开地址，否则 Telegram Web App 验证页面无法正常工作。
• Turnstile 和 reCAPTCHA 至少配置一种；如果关闭网页验证，可只使用问答验证。
• 屏蔽词和自动回复支持正则，但建议保持简单，避免复杂表达式造成匹配性能问题。
• 请妥善保护 BOT_TOKEN、验证码 secret、D1 数据库和 Cloudflare 账号权限。

许可证与上游

原项目 huliyoudiangou/TG_Chat_Bot-D1 采用 MIT License。本仓库中的修改版沿用原项目开源精神，仅作个人维护与自用优化；如需完整部署教程、上游更新和问题讨论，请优先参考原作者仓库。