diff --git a/telegram/README.md b/telegram/README.md index edf5429..8c44fb1 100644 --- a/telegram/README.md +++ b/telegram/README.md @@ -1,6 +1,12 @@ # Telegram Bot Worker -`tg-bot.js` 是一个部署在 Cloudflare Workers 上的 Telegram 双向私聊中继 Bot。它会把用户私聊消息转发到管理员论坛群的独立 topic 中，管理员在对应 topic 内回复即可把消息发回用户，同时提供验证、过滤、封禁、备注、自动回复、备份和 Telegram 内联管理面板。 +`tg-bot.js` 是一个部署在 Cloudflare Workers 上的 Telegram 双向私聊中继 Bot（版本 v3.68）。它会把用户私聊消息转发到管理员论坛群的独立 topic 中，管理员在对应 topic 内回复即可把消息发回用户，同时提供验证、过滤、封禁、备注、自动回复、备份和 Telegram 内联管理面板。 + +**核心特点：** +- **无回执体验**：移除了用户侧"已送达"和管理员侧"已回复"回执提示，减少打扰 +- **安全加固**：支持 Webhook secret 校验、WebApp initData 验证、nonce 防伪造、管理员精确匹配 +- **消息编辑同步**：用户和管理员编辑消息时，对方会收到修改通知 +- **双向删除**：用户和管理员都可以通过 `/del` 命令删除消息 ## 来源与致谢 @@ -8,32 +14,61 @@ 感谢原作者提供 Cloudflare Worker + D1 + Telegram forum topic 的完整实现思路。本仓库版本主要保留原项目的核心工作流，并针对个人使用习惯做了精简、无回执体验、消息编辑同步和安全加固。 -## 本版本调整 +## 本版本调整 (v3.68) -- 去掉用户侧“已送达”和管理员侧“已回复”回执，减少打扰和额外 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` 命令**：用户和管理员都可以删除消息（详见下方说明）。 +### 用户体验优化 +- ✅ 去掉用户侧"已送达"和管理员侧"已回复"回执，减少打扰和额外 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` 命令删除消息（详见下方说明） +- ✅ **引用消息支持**：用户使用 `>`、`》` 或 `>` 开头的文本会被渲染为引用块 +- ✅ **媒体欢迎语**：支持图片/视频/GIF 作为欢迎语，可设置 caption +- ✅ **话题自愈机制**：当 topic 失效时自动重建并迁移数据 ## 核心功能 -- 私聊用户消息转发到管理员群论坛 topic。 -- 每个用户自动创建独立 topic，并推送用户身份卡片。 -- 管理员在对应 topic 内回复，即可把消息复制回用户私聊。 -- 支持 Cloudflare Turnstile 或 Google reCAPTCHA 人机验证。 -- 支持二次问答验证。 -- 支持文本、媒体、链接、转发、频道转发、音频、贴纸/GIF 等类型过滤。 -- 支持关键词自动回复和屏蔽词计数封禁。 -- 支持黑名单 topic、用户解封、备注、资料卡置顶。 -- 支持消息编辑记录同步。 -- 支持消息备份到指定群或频道。 -- 内置 Telegram 管理面板，主管理员通过 `/start` 打开。 -- **支持双向消息删除**：用户和管理员都可以通过 `/del` 命令删除消息。 +### 消息转发 +- 私聊用户消息转发到管理员群论坛 topic +- 每个用户自动创建独立 topic，并推送用户身份卡片 +- 管理员在对应 topic 内回复，即可把消息复制回用户私聊 +- 支持消息引用关系保持（用户和管理员均可引用回复） + +### 验证系统 +- 支持 Cloudflare Turnstile 或 Google reCAPTCHA 人机验证 +- 支持二次问答验证 +- 支持验证码模式动态切换（Turnstile ↔ reCAPTCHA ↔ 关闭） +- 验证状态持久化，无需重复验证 + +### 消息类型控制 +- 支持文本、媒体、链接、转发、频道转发、音频、贴纸/GIF 等类型过滤 +- 管理员可单独控制每种消息类型的转发开关 +- 管理员不受过滤限制，所有消息类型均可发送 + +### 智能回复 +- 支持关键词自动回复（格式：`关键词===回复内容`） +- 支持屏蔽词计数封禁（可配置阈值） +- 支持忙碌模式自动回复 + +### 用户管理 +- 支持黑名单 topic、用户解封、备注、资料卡置顶 +- 支持消息编辑记录同步 +- 支持消息备份到指定群或频道 +- 内置 Telegram 管理面板，主管理员通过 `/start` 打开 + +### 双向消息删除 +- **用户侧**：引用自己发送的消息，发送 `/del` 命令，可以删除该消息并通知管理员 +- **管理员侧**：在 topic 中引用消息，发送 `/del` 命令，可以同时删除用户侧和管理员侧的消息 +- **权限控制**：用户只能删除自己发送的消息，无法删除管理员回复的消息 ## 运行环境 @@ -85,16 +120,20 @@ TG_BOT_DB | 配置项 | 默认值 | 说明 | | --- | --- | --- | -| `welcome_msg` | `欢迎 {name}！使用前请先完成验证。` | 欢迎语，支持 `{name}` 或 `{user}` | +| `welcome_msg` | `欢迎 {name}！使用前请先完成验证。` | 欢迎语，支持 `{name}` 或 `{user}`，也可配置为媒体（图片/视频/GIF） | | `enable_verify` | `true` | 是否启用网页人机验证 | | `enable_qa_verify` | `true` | 是否启用问答验证 | | `captcha_mode` | `turnstile` | 验证模式：`turnstile` 或 `recaptcha` | -| `verif_q` | `1+1=?` | 问题验证题目 | +| `verif_q` | `1+1=?\n提示：答案在简介中。` | 问题验证题目 | | `verif_a` | `3` | 问题验证答案 | | `block_threshold` | `5` | 命中屏蔽词多少次后封禁 | | `busy_mode` | `false` | 是否启用非营业自动回复 | | `enable_admin_receipt` | `false` | 管理员回执开关，当前版本默认不发送回执 | +**注意**：`welcome_msg` 支持两种格式： +1. 纯文本：直接输入文字，支持 `{name}` 占位符 +2. 媒体配置：发送图片/视频/GIF 给机器人，会自动转换为 JSON 配置 + ## 部署流程 1. 在 Telegram 中创建 Bot，拿到 `BOT_TOKEN`。 @@ -122,6 +161,12 @@ curl -X POST "https://api.telegram.org/bot/setWebhook" \ 9. 访问 Worker 根路径，若返回 `Bot v3.68 Active`，说明 Worker 基本可用。 10. 主管理员私聊 Bot 发送 `/start`，打开控制面板。 +11. **首次启动建议**： + - 在面板中配置欢迎语（可选媒体） + - 设置验证问题和答案 + - 添加协管管理员（如有需要） + - 配置自动回复规则 + - 设置屏蔽词列表 ## Webhook 路由 @@ -134,51 +179,108 @@ curl -X POST "https://api.telegram.org/bot/setWebhook" \ ## 管理员面板 -主管理员私聊 Bot 发送 `/start` 后会打开配置面板，包含： +主管理员私聊 Bot 发送 `/start` 后会打开配置面板，包含以下模块： -- 基础：欢迎语、验证问题、验证答案、验证码模式、问题验证开关。 -- 自动回复：添加或删除关键词自动回复。 -- 屏蔽词：添加或删除正则关键词，命中后累计封禁。 -- 过滤：控制转发、媒体、语音、贴纸、链接、频道、文本等类型。 -- 协管：维护额外授权管理员。 -- 备份/通知：设置备份群、重置黑名单 topic。 -- 营业状态：切换忙碌模式并修改自动回复语。 +### 📝 基础配置 +- 欢迎语（支持文字或图片/视频/GIF） +- 验证问题与答案 +- 验证码模式切换（Cloudflare / Google / 关闭） +- 问题验证开关 -自动回复新增格式： +### 🤖 自动回复 +- 添加或删除关键词自动回复 +- 格式：`关键词===回复内容` +- 示例：`价格===请联系人工客服` -```text -关键词===回复内容 -``` +### 🚫 屏蔽词 +- 添加或删除正则关键词 +- 命中后累计计数，达到阈值自动封禁 +- 建议使用简单正则，避免复杂表达式 -授权管理员可输入多个 ID： +### 🛠 过滤设置 +- 控制转发、媒体、语音、贴纸、链接、频道、文本等类型 +- 可单独开启/关闭每种消息类型 +- 管理员不受过滤限制 -```text -123456,789012 -``` +### 👮 协管管理 +- 维护额外授权管理员列表 +- 支持批量输入：`123456,789012` +- 协管拥有回复权限，但无法访问管理面板 + +### 💾 备份/通知 +- 设置备份群 ID，所有消息会异步归档 +- 重置黑名单 topic + +### 🌙 营业状态 +- 切换忙碌模式 +- 修改非营业时间自动回复语 ## 用户流程 1. 用户私聊 Bot 发送 `/start`。 -2. Bot 发送欢迎语。 +2. Bot 发送欢迎语（可能是文字或媒体）。 3. 如果启用网页验证，用户点击按钮完成 Turnstile 或 reCAPTCHA。 4. 如果启用问答验证，用户继续回答问题。 5. 验证通过后，用户消息会转发到管理员群中的个人 topic。 6. 管理员在 topic 中回复，Bot 会把回复发送给该用户。 7. 用户或管理员编辑消息时，Bot 会同步对应的编辑提示。 -8. **删除消息**： +8. **引用消息**：用户可以使用 `>`、`》` 或 `>` 开头来引用之前的内容。 +9. **删除消息**： - **用户侧**：引用自己发送的消息，发送 `/del` 命令，可以删除该消息并通知管理员。 - **管理员侧**：在 topic 中引用消息，发送 `/del` 命令，可以同时删除用户侧和管理员侧的消息。 - **注意**：用户只能删除自己发送的消息，无法删除管理员回复的消息。 +### 特殊语法 +- **引用块**：以 `>`、`》` 或 `>` 开头的文本会被渲染为 HTML 引用块 +- **媒体欢迎语**：管理员可以在面板中上传图片/视频/GIF 作为欢迎语 + ## 安全建议 +### 🔐 认证与授权 - 推荐配置 `TELEGRAM_WEBHOOK_SECRET`；未配置时会保持兼容模式，不强制校验 Telegram Webhook secret。 -- `ADMIN_IDS` 和协管列表会按逗号拆分后精确匹配。 +- `ADMIN_IDS` 和协管列表会按逗号拆分后精确匹配，避免子串误判。 +- 请妥善保护 `BOT_TOKEN`、验证码 secret、D1 数据库和 Cloudflare 账号权限。 + +### 🛡️ 防护措施 - 管理员群必须开启 Topics，否则自动创建用户话题会失败。 - `WORKER_URL` 要使用 HTTPS 公开地址，否则 Telegram Web App 验证页面无法正常工作。 - Turnstile 和 reCAPTCHA 至少配置一种；如果关闭网页验证，可只使用问答验证。 -- 屏蔽词和自动回复支持正则，但建议保持简单，避免复杂表达式造成匹配性能问题。 -- 请妥善保护 `BOT_TOKEN`、验证码 secret、D1 数据库和 Cloudflare 账号权限。 +- 屏蔽词和自动回复支持正则，但建议保持简单，避免复杂表达式造成匹配性能问题或被拒绝。 + +### ⚠️ 正则安全 +- 系统内置正则安全检查，会拒绝以下模式： + - 嵌套量词（如 `(a+)+`） + - 反向引用（如 `\1`） + - 环视断言（如 `(?<=...)`、`(?256 字符） +- 这可以有效防止 ReDoS（正则表达式拒绝服务攻击） + +### 📊 性能优化 +- 系统使用内存缓存减少 D1 数据库读写（缓存 TTL 60 秒） +- 用户 topic 创建有锁机制，防止并发冲突 +- 警告消息有 3 秒冷却时间，防止刷量攻击 + +## 技术细节 + +### 数据库结构 +- **config**：存储配置项（键值对） +- **users**：用户状态、封禁状态、topic 映射、用户资料（JSON） +- **messages**：用户消息与管理员群 topic 消息的双向映射 + +### 缓存机制 +- 配置缓存：TTL 60 秒，减少 D1 查询 +- 管理员集合缓存：TTL 60 秒，加速权限检查 +- 用户锁机制：防止同一用户并发创建多个 topic + +### API 调用策略 +- 使用 `copyMessage` 优先，保持消息引用关系 +- 降级使用 `forwardMessage`（不支持引用时） +- 错误自愈：topic 失效时自动重建并重试 + +### 版本历史 +- **v3.68**（当前版本）：无回执模式 + 安全加固 + 双向删除 +- 基于 [huliyoudiangou/TG_Chat_Bot-D1](https://github.com/huliyoudiangou/TG_Chat_Bot-D1) 二次开发 +- 上游 fork 自 [moistrr/TGbot-D1](https://github.com/moistrr/TGbot-D1) ## 许可证与上游