Next Gen Forward - 基于 Cloudflare Workers 部署的 Telegram 双向私聊机器人

Next Gen Forward v1.6.2

点击进入 Github 项目仓库

这是一个基于 Cloudflare Workers 部署的 Telegram 双向私聊机器人，通过群组话题管理私聊，免费、安全、高效。

支持本地题库 + Cloudflare Turnstile（可选）双重人机验证方式，一键切换。

支持本地规则 + Workers AI（可选）双重垃圾消息拦截，一键开关。

内置设置面板，便于在群组内直接控制机器人各项功能。

本项目基于 telegram_private_chatbot ，进行了大幅修改，并更新保姆级部署教程。

在此对原项目作者 Vaghr 以及我的好兄弟 打钱 & 逆天 表示特别感谢！

v1.6.2 版本更新（2026-01-16）

• 添加WORKER_URL域名自动规范化功能：已支持对WORKER_URL变量进行域名自动规范化，修复了极少数情况下因域名格式填写不规范导致的人机验证报错。
• 修复ADMIN_IDS变量设置后未生效问题：现在设置ADMIN_IDS变量已经可以正常控制群组内管理员的指令使用权。
• 修复用户私聊消息限流失效问题：现在可依据配置常量参数正常对消息限流。

v1.6.1 版本更新（2026-01-16）

• 垃圾消息规则优化：优化垃圾消息识别规则，当前已支持通过清空默认本地规则的方式，来实现纯 AI 识别。
• 默认 AI 自信度调整：将默认 AI 识别自信度调整为threshold: 0.65，识别更激进。

✨ 核心特性

💻 指令说明

📝 前期准备

1. Cloudflare 账号（免费注册）：请提前注册登录 Cloudflare 账号，并将 Cloudflare 页面设置为中文。

2. Telegram Bot（免费申请）：在 @BotFather 创建一个机器人，获取 Token。

   • ⚠️请务必保管好自己的 Token，确保不要泄露给其他人。
   • 重要设置：选择机器人，在 Bot Setting 中关闭 Group Privacy。

3. 管理员群组（免费创建）：创建一个 Telegram 群组，并 开启话题功能 (Topics)。

   • 将机器人拉入群组，并 设为管理员，务必给予管理员机器人管理话题权限。
   • 获取群组SUPERGROUP_ID，在 Telegram 桌面端右键群内任意消息，复制链接，链接里会有一段 xxxxxxxxxx 数字，在前面加上 -100 就是完整的SUPERGROUP_ID，例如 -100xxxxxxxxxx。

🚀 部署方法（二选一）

部署方法 1：GitHub 一键连接部署

这是最简单的自动化部署方式，当您更新 GitHub 仓库时，Cloudflare 会自动重新部署您的 Worker。

1. 进入本项目仓库 Fork 到您的 GitHub 账户
2. 登录 Cloudflare Dashboard
3. 选择控制台左侧 计算和 AI -> Workers 和 Pages
4. 点击页面中的 创建应用程序
5. 选择 Connect Github
6. 在弹出的页面中授权 Cloudflare 访问您的 GitHub Repository 完成仓库关联
7. 选择 Continue with Github，选择您刚才 Fork 的 NextGenForward 仓库，点击下一步
8. Set up your application：
   • 项目名称：nextgenforward (或任意名称)
   • 其他配置保持默认
   • 点击 部署，等待部署完成

部署方法 2：手动复制本项目仓库中的 worker.js 代码部署

如果您不想关联 GitHub，可以直接复制本项目仓库中的 worker.js 代码部署，此方法后期将需要手动实现更新。

1. 登录 Cloudflare Dashboard
2. 选择控制台左侧 计算和 AI -> Workers 和 Pages
3. 点击页面中的 创建应用程序
4. 选择 从 Hello World! 开始
5. 编辑 Worker name：nextgenforward (或任意名称)
6. 点击 部署，等待部署完成
7. 点击 Cloudflare 当前 Worker 页面右上角的 编辑代码
8. 删除所有代码，复制并粘贴本 Github 项目仓库中 worker.js 文件的所有代码
9. 点击右上角 部署，等待页面底部提示 版本已保存，即为部署成功

部署完成后查看 Worker 域名

当您使用以上两种方法的任意一种完成部署后，您可以在 Worker 的 概述 页面查看您的 Worker 域名

• 格式为 your-worker-name.your-subdomain.workers.dev
• 例如 nextgenforward.xxxxxx.workers.dev

💡您的域名之后会用到

🔗 关联和绑定

必要步骤 1：创建并绑定 KV 命名空间

无论您使用以上哪种方法完成部署，都必须绑定 KV 命名空间，否则项目将无法运行。

1. 选择控制台左侧 存储和数据库 -> Workers KV
2. 点击页面右上角的 Create Instance 创建 KV 命名空间
3. 命名空间名称填写TOPIC_MAP，点击 创建 ，等待创建完成
4. 选择控制台左侧 计算和 AI -> Workers 和 Pages
5. 点击进入您刚才部署的 Worker 页面，注意 不要点击到 Worker 域名
6. 进入 Worker 的 绑定 页面 -> 添加绑定 -> 选择左侧的 KV 命名空间 -> 添加绑定
7. 变量名称 必须 填写TOPIC_MAP，KV 命名空间选择您刚才创建的TOPIC_MAP命名空间，点击 添加绑定
8. 绑定完成

必要步骤 2：添加环境变量

无论您使用以上哪种方法完成部署，都必须添加环境变量，否则项目将无法运行。

1. 选择控制台左侧 计算和 AI -> Workers 和 Pages
2. 点击进入您刚才部署的 Worker，注意 不要点击到 Worker 域名
3. 进入 Worker 的 设置 页面，找到 变量和机密
4. 添加 以下环境变量，一般变量设置为 文本，加密变量推荐设置为 密钥，可选变量按需设置

可选配置 1：设置 Cloudflare Turnstile

Cloudflare Turnstile 人机验证为可选配置，只有当您完成以下配置，并添加WORKER_URL CF_TURNSTILE_SITE_KEY和CF_TURNSTILE_SECRET_KEY所有三个环境变量之后才可以使用。
机器人默认为本地题库验证方案，配置完成后请在群组内使用/settings命令通过设置面板切换为 Cloudflare 验证。

1. 首先复制您的 Worker 域名，例如 nextgenforward.xxxxxx.workers.dev
2. 选择控制台左侧 应用程序安全 -> Turnstile
3. 点击 添加小组件 ，设置任意小组件名称
4. 点击 添加主机名 ，在 添加自定义主机名 中粘贴您的 Worker 域名（注意这里的域名不要带https://开头和/结尾），点击右侧 添加
5. 在下方 所选主机名中 勾选您刚添加的 Worker 域名，点击底部 添加
6. 再次在 主机名下勾选您刚添加的 Worker 域名，小组件模式选择 托管，预先许可选择否
7. 点击页面最右下角 创建
8. 创建完成后页面会显示您的 站点密钥（site_key），和您的 密钥（secret_key），分别对应您的CF_TURNSTILE_SITE_KEY和CF_TURNSTILE_SECRET_KEY两个变量

⚠️请务必保管好自己的密钥，确保不要泄露给其他人。

可选配置 2：绑定 Cloudflare Workers AI

使用 Workers AI 作为垃圾消息识别兜底，此项为可选配置。
机器人默认为本地规则识别方案，当您完成以下配置，机器人会自动启用 AI 进行兜底识别，变为 本地规则 + AI 识别兜底。

1. 选择控制台左侧 计算和 AI -> Workers 和 Pages
2. 点击进入您刚才部署的 Worker 页面，注意 不要点击到 Worker 域名
3. 进入 Worker 的 绑定 页面 -> 添加绑定 -> 选择左侧的 Workers AI -> 添加绑定
4. 变量名称 必须 填写AI，点击 添加绑定
5. 绑定完成

💡本项目代码中默认使用的 Workers AI 模型为@cf/meta/llama-3.1-8b-instruct-fast
如需更换其他模型，请确保使用 Workers AI 可用的 Text Generation 模型，且必须支持 JSON Mode
如果您希望更换为其他 AI 模型，或调整识别自信度，可手动编辑项目代码中第 201 - 206 行附近的代码

  ai: {
    enabled: true,
    model: "@cf/meta/llama-3.1-8b-instruct-fast",
    // v1.6.1: AI 阈值默认更激进（更愿意拦截）
    threshold: 0.65
  }

编辑完成后重新部署即可自动生效。

最后一步（关键）：激活 Webhook

无论您使用以上哪种方法完成部署，都必须激活 Webhook，否则项目将无法运行。

直接使用浏览器访问网址激活 Webhook

未设置WEBHOOK_SECRET变量：

https://api.telegram.org/bot<你的BOT_TOKEN>/setWebhook?url=https://<你的Worker域名>

例如：https://api.telegram.org/bot12345678:A43eUzq3/setWebhook?url=https://nextgenforward.xxxxxx.workers.dev

如果页面返回 {"ok":true, "result":true, "description":"Webhook was set"}，即表示激活成功！

已设置WEBHOOK_SECRET变量：

https://api.telegram.org/bot<你的BOT_TOKEN>/setWebhook?url=https://<你的worker域名>/&secret_token=<你的WEBHOOK_SECRET>

例如：https://api.telegram.org/bot12345678:A43eUzq3/setWebhook?url=https://nextgenforward.xxxxxx.workers.dev/&secret_token=Abc_1234-5d6F7G

如果页面返回 {"ok":true, "result":true, "description":"Webhook was set"}，即表示激活成功！

🎉 大功告成！至此您已完成项目的所有部署和配置，可以正常开始使用！

💡 此时建议您访问一下自己的 Worker 域名，如果页面返回 OK，则表示已经部署成功，如果报错则说明您的部署过程出现问题。

⚙️ 一些额外的配置（仅了解即可）

在 worker.js 文件开头包含一些可调配置常量，可按需手动更改，重新部署后生效，实现部分实用功能调节

// 用户速率限制
RATE_LIMIT_VERIFY: 3,              // 用户5分钟内最多可尝试人机验证次数，不可设为0
RATE_LIMIT_MESSAGE: 45,            // 用户私聊消息发送速率限制，不可设为0
RATE_LIMIT_WINDOW: 60,             // 用户私聊消息速率限制窗口（秒），不可设为0

// 人机验证配置
VERIFY_BUTTON_TEXT: "🤖 点击进行人机验证",     // 人机验证按钮文本
PENDING_MAX_MESSAGES: 10,          // 人机验证期间最多暂存消息数量，不可设为0

❓ 常见问题及解决方法

Q: 为什么机器人没反应？
A: 您的环境变量设置有误 / 未绑定 KV 命名空间 / 未设置 Webhook，未在 Bot Setting 中关闭 Group Privacy，请检查。

Q: 为什么机器人不创建话题？
A: 请确保您的群组已开启话题（Topics）功能，并且已给予机器人管理员权限，开启了机器人的管理话题权限，SUPERGROUP_ID环境变量已正确设置。

Q: 为什么群组内不显示指令菜单？
A: 请访问一下您的 Worker 域名，若页面返回 OK，此时返回您的 Telegram 首页，再次打开群组就可以刷新出来了。

Q: 为什么我将用户封禁后立刻查看黑名单无法找到他？
A: 这是由于 Cloudflare 边缘节点最终一致性所导致的延迟问题，一般等待几秒后即可正常刷新。

Q: 我误用 /trust 命令将错误的人加进了白名单，怎样移除？
A: /ban 他。

Q: 本地垃圾消息拦截规则中的 max_links=n 使用方法不明确？
A: max_links=n表示“只要链接数量达到n条，就会实施拦截”。例如max_links=1时，只要消息中存在1条及以上链接，就会被拦截。另外，max_links=0表示无限制。

Q: 为什么用户打开人机验证页面报错 Worker Origin Error？
A: 请确保您的WORKER_URL CF_TURNSTILE_SITE_KEY和CF_TURNSTILE_SECRET_KEY所有三个环境变量均已在 CF 控制台设置，一般这个报错是您未设置WORKER_URL所导致的。

Q: 我重命名了我的 Worker 并重新设置了 WORKER_URL 变量，为什么 CF 验证总是失败？
A: 请不要忘了到您的 Turnstile 设置中将您的新 Worker 域名添加主机名并更新设置。

Q: 怎样取消激活 Webhook？
A: https://api.telegram.org/bot<BOT_TOKEN>/deleteWebhook?drop_pending_updates=true