174 lines
3.9 KiB
Markdown
174 lines
3.9 KiB
Markdown
# 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 兼容聊天补全接口
|
||
|
||
## 项目结构
|
||
|
||
```text
|
||
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：
|
||
|
||
```bash
|
||
npx wrangler kv namespace create PENDING_JOINS
|
||
```
|
||
|
||
然后把返回的 namespace id 填进你的 `wrangler.toml`。
|
||
|
||
## 本地使用
|
||
|
||
```bash
|
||
npm install
|
||
copy wrangler.toml.example wrangler.toml
|
||
```
|
||
|
||
然后编辑 `wrangler.toml`，填入你自己的真实配置。
|
||
|
||
## 部署
|
||
|
||
```bash
|
||
npx wrangler deploy
|
||
```
|
||
|
||
## 配置 Telegram Webhook
|
||
|
||
部署完成后，把 webhook 指向：
|
||
|
||
```text
|
||
https://你的-worker-域名/telegram/webhook
|
||
```
|
||
|
||
PowerShell 示例：
|
||
|
||
```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
|
||
|
||
如果你要公开发布，建议自行补充许可证文件。
|