orion/script
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor(core): ♻️ 重构 Telegram Bot 安全机制与缓存逻辑

Browse Source 
重构核心转发逻辑并引入多项安全加固措施，主要变更包括：

- 增强安全性：新增 Webhook secret 校验、WebApp initData 验证及 nonce 随机数检查。
- 优化缓存：升级缓存系统，新增管理员权限缓存（admin cache）以降低数据库 D1 的读写压力。
- 管理员匹配：优化管理员识别逻辑，支持精确匹配与正则表达式安全检查。
- 文档更新：在 README 中完善项目来源致谢，并详细说明 v3.68 版本的安全加固与无回执体验调整。

此版本重点提升了机器人在高频使用场景下的性能表现与防护能力。
This commit is contained in:
Orion
2026-05-04 02:18:01 +08:00
parent 6a0fe9dded
commit 737e83541d
2 changed files with 192 additions and 50 deletions
Download Patch File Download Diff File Expand all files Collapse all files

87
telegram/README.md
View File

@@ -1,10 +1,27 @@
# Telegram Bot Worker
`tg-bot.js` 是一个部署在 Cloudflare Workers 上的 Telegram Bot。它把用户私聊消息转发到管理员论坛群的独立话题中，并提供验证、过滤、封禁、备注、自动回复、备份和配置面板。
`tg-bot.js` 是一个部署在 Cloudflare Workers 上的 Telegram 双向私聊中继 Bot。它会把用户私聊消息转发到管理员论坛群的独立 topic 中，管理员在对应 topic 内回复即可把消息发回用户，同时提供验证、过滤、封禁、备注、自动回复、备份和 Telegram 内联管理面板。
## 来源与致谢
本脚本基于 [huliyoudiangou/TG_Chat_Bot-D1](https://github.com/huliyoudiangou/TG_Chat_Bot-D1) 二次修改与自用优化。原项目是一个基于 Cloudflare Worker 和 D1 数据库的 Telegram 双向机器人，并在 GitHub 页面中标注为 forked from [moistrr/TGbot-D1](https://github.com/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 的风险。
## 核心功能
- 私聊用户消息转发到管理员群论坛话题。
- 私聊用户消息转发到管理员群论坛 topic。
- 每个用户自动创建独立 topic，并推送用户身份卡片。
- 管理员在对应 topic 内回复，即可把消息复制回用户私聊。
- 支持 Cloudflare Turnstile 或 Google reCAPTCHA 人机验证。
@@ -14,7 +31,7 @@
- 支持黑名单 topic、用户解封、备注、资料卡置顶。
- 支持消息编辑记录同步。
- 支持消息备份到指定群或频道。
- 内置 Telegram 管理面板，管理员通过 `/start` 打开。
- 内置 Telegram 管理面板，主管理员通过 `/start` 打开。
## 运行环境
@@ -29,10 +46,25 @@
| 名称 | 说明 |
| --- | --- |
| `BOT_TOKEN` | Telegram Bot Token |
| `ADMIN_IDS` | 管理员 Telegram user id，多个用英文或中文逗号分隔 |
| `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 数据库，绑定名必须是：
@@ -47,20 +79,6 @@ TG_BOT_DB
- `users`：用户状态、封禁状态、topic 映射、用户资料。
- `messages`：用户消息与管理员群 topic 消息的映射。
## 可选环境变量
| 名称 | 说明 |
| --- | --- |
| `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` |
大多数运行时配置也可以在管理员面板中调整，并优先保存到 D1。
## 默认配置
| 配置项 | 默认值 | 说明 |
@@ -73,7 +91,7 @@ TG_BOT_DB
| `verif_a` | `3` | 问题验证答案 |
| `block_threshold` | `5` | 命中屏蔽词多少次后封禁 |
| `busy_mode` | `false` | 是否启用非营业自动回复 |
| `enable_admin_receipt` | `false` | 管理员回执开关 |
| `enable_admin_receipt` | `false` | 管理员回执开关，当前版本默认不发送回执 |
## 部署流程
@@ -83,14 +101,25 @@ TG_BOT_DB
4. 在 Cloudflare 创建 D1 数据库并绑定为 `TG_BOT_DB`。
5. 创建 Worker，把 [tg-bot.js](tg-bot.js) 作为 Worker 代码。
6. 配置环境变量 `BOT_TOKEN`、`ADMIN_IDS`、`ADMIN_GROUP_ID`、`WORKER_URL`。
7. 设置 Telegram Webhook：
7. 如果使用网页验证，配置 Turnstile 或 reCAPTCHA 的 site key 与 secret key。
8. 设置 Telegram Webhook。
不使用 secret token 时：
```bash
curl "https://api.telegram.org/bot<BOT_TOKEN>/setWebhook?url=<WORKER_URL>"
```
8. 访问 Worker 根路径，若返回 `Bot v3.67 Active`，说明 Worker 基本可用。
9. 管理员私聊 Bot 发送 `/start`，打开控制面板。
推荐配置 `TELEGRAM_WEBHOOK_SECRET`，并设置 Webhook secret token：
```bash
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 路由
@@ -103,7 +132,7 @@ curl "https://api.telegram.org/bot<BOT_TOKEN>/setWebhook?url=<WORKER_URL>"
## 管理员面板
管理员私聊 Bot 发送 `/start` 后会打开配置面板，包含：
主管理员私聊 Bot 发送 `/start` 后会打开配置面板，包含：
- 基础：欢迎语、验证问题、验证答案、验证码模式、问题验证开关。
- 自动回复：添加或删除关键词自动回复。
@@ -133,12 +162,18 @@ curl "https://api.telegram.org/bot<BOT_TOKEN>/setWebhook?url=<WORKER_URL>"
4. 如果启用问答验证，用户继续回答问题。
5. 验证通过后，用户消息会转发到管理员群中的个人 topic。
6. 管理员在 topic 中回复，Bot 会把回复发送给该用户。
7. 用户或管理员编辑消息时，Bot 会同步对应的编辑提示。
## 注意事项
## 安全建议
- `ADMIN_IDS` 使用字符串包含判断，建议使用完整 ID 并用逗号分隔，避免 ID 片段误匹配。
- 推荐配置 `TELEGRAM_WEBHOOK_SECRET`；未配置时会保持兼容模式，不强制校验 Telegram Webhook secret。
- `ADMIN_IDS` 和协管列表会按逗号拆分后精确匹配。
- 管理员群必须开启 Topics，否则自动创建用户话题会失败。
- `WORKER_URL` 要使用 HTTPS 公开地址，否则 Telegram Web App 验证页面无法正常工作。
- Turnstile 和 reCAPTCHA 至少配置一种；如果关闭网页验证，可只使用问答验证。
- Worker 使用内存缓存减少 D1 读取，配置修改后脚本会主动清缓存。
- 屏蔽词和自动回复支持正则，但建议保持简单，避免复杂表达式造成匹配性能问题。
- 请妥善保护 `BOT_TOKEN`、验证码 secret、D1 数据库和 Cloudflare 账号权限。
## 许可证与上游
原项目 [huliyoudiangou/TG_Chat_Bot-D1](https://github.com/huliyoudiangou/TG_Chat_Bot-D1) 采用 MIT License。本仓库中的修改版沿用原项目开源精神，仅作个人维护与自用优化；如需完整部署教程、上游更新和问题讨论，请优先参考原作者仓库。