TeleWatchdog

TeleWatchdog 是一个基于 Cloudflare Workers 的 Telegram 入群申请审核机器人项目，适用于需要“申请加入”模式的群组。

它的核心流程很简单：

1. 检查申请人是否有头像。
2. 检查申请人是否有 bio。
3. 只要头像或 bio 缺失，直接进入验证。
4. 如果两者都存在，则调用 AI 做二分类判断。
5. AI 返回 approve 时，直接通过入群申请。
6. AI 返回 challenge 时，发送验证消息，让用户完成验证。

需要验证的用户可以二选一：

• Cloudflare Turnstile
• Telegram WebApp BiometricManager 生物识别

如果 10 分钟内没有完成验证，定时任务会自动拒绝申请，并清理消息和 KV 记录。

功能特性

• 支持 Telegram chat_join_request webhook
• 基于 Cloudflare Worker 部署
• Telegram 小程序验证页
• Cloudflare Turnstile 人机验证
• Telegram 原生生物识别验证
• AI 二分类审核
• 验证超时自动清理
• 验证成功或超时后自动删除验证消息

技术栈

• Cloudflare Workers
• Cloudflare KV
• Telegram Bot API
• Cloudflare Turnstile
• OpenAI 兼容聊天补全接口

项目结构

src/index.ts           Worker 主逻辑
package.json           项目配置与脚本
tsconfig.json          TypeScript 配置
wrangler.toml.example  Wrangler 示例配置

需要的 Secrets

使用 wrangler secret put 写入：

• BOT_TOKEN
• TG_WEBHOOK_SECRET
• AI_BASE_URL
• AI_API_KEY
• TURNSTILE_SECRET

需要的变量

在 wrangler.toml 中配置：

• AI_MODEL
• TURNSTILE_SITE_KEY
• VERIFICATION_ORIGIN

创建 KV

先创建 KV namespace：

npx wrangler kv namespace create PENDING_JOINS

然后把返回的 namespace id 填进你的 wrangler.toml。

本地使用

npm install
copy wrangler.toml.example wrangler.toml

然后编辑 wrangler.toml，填入你自己的真实配置。

部署

npx wrangler deploy

配置 Telegram Webhook

部署完成后，把 webhook 指向：

https://你的-worker-域名/telegram/webhook

PowerShell 示例：

$botToken = "YOUR_BOT_TOKEN"
$secret = "YOUR_TG_WEBHOOK_SECRET"
$body = @{
  url = "https://your-worker-domain/telegram/webhook"
  secret_token = $secret
  allowed_updates = @("chat_join_request")
} | ConvertTo-Json -Compress

Invoke-RestMethod -Method Post -Uri "https://api.telegram.org/bot$botToken/setWebhook" -ContentType "application/json" -Body $body

Telegram 侧要求

机器人需要：

• 被添加到目标群组
• 是管理员
• 拥有审批入群申请权限

同时群组需要开启“加入需要管理员审批”。

验证流程

直接通过

满足以下条件时会直接通过：

• 用户有头像
• 用户有 bio
• AI 返回 approve

这条路径下：

• 直接批准入群申请
• 不给用户发送任何消息

进入验证

满足以下任意条件时会进入验证：

• 没有头像
• 没有 bio
• AI 返回 challenge
• AI 请求失败

这条路径下：

• 发送一条验证消息
• 用户通过 Telegram 小程序打开验证页
• 完成 Turnstile 或生物识别验证
• 机器人批准入群
• 自动删除验证消息
• 自动删除 KV 记录

超时处理

• 申请保持待验证状态超过 10 分钟
• 定时任务自动拒绝该申请
• 自动删除验证消息
• 自动删除 KV 记录

说明

• 这里的生物识别使用的是 Telegram.WebApp.BiometricManager，不是 WebAuthn。
• 首次使用生物识别时会通过 Telegram WebApp 在本机安全存储一个随机凭据；服务端只保存该凭据的哈希。
• Telegram 小程序的 initData 会在服务端校验后，才接受验证结果。
• 公共仓库使用者需要自己准备 Worker 域名、Turnstile、KV namespace 和 AI 凭据。

License

如果你要公开发布，建议自行补充许可证文件。