小菲机器人 · Telegram Group Bot
功能完整的 Telegram 群组管理机器人，支持入群验证、内容过滤、防刷屏、等级积分、抽奖，以及 Telegram Mini App 可视化管理面板。
功能概览
| 模块 | 功能 |
|---|
| 入群验证 | Mini App 内嵌 Cloudflare Turnstile 人机验证，无需跳出 TG，超时自动踢 |
| 内容过滤 | 内置垃圾广告识别、链接/邀请/手机号/频道转发拦截、自定义关键词 |
| 防刷屏 | 滑动窗口频率限制，自动警告/禁言/封禁 |
| 等级系统 | 发言获取经验值，自动升级，可自定义各级称号 |
| 每日签到 | 连续签到积分奖励，7天/30天里程碑加成 |
| 抽奖系统 | 等级门槛、积分花费、自动/手动开奖，群内公告 |
| 排行榜 | Mini App 内嵌可视化群大盘：支持经验榜与资产榜展示及排名查询 |
| Mini App | Telegram 内嵌可视化管理面板全集成 |
| 权限控制 | 每个 API 端点实时验证 Telegram 管理员身份 |
| 审计日志 | 所有管理操作记录，90 天自动清理 |
| Chatwoot 网关 | 可选：拦截 Chatwoot Telegram inbox 私聊消息，未验证用户不进 Chatwoot（部署说明） |
Mini App 管理面板
在机器人私聊中点击 📱 管理面板 按钮即可打开，支持亮色/暗色主题自动切换。
| 标签页 | 功能 |
|---|
| ⚙️ 设置 | 开关入群验证、调整验证时长、超时处理方式 |
| 🛡 过滤 | 总开关、链接/邀请/手机号/频道转发开关、违规处理方式、自定义关键词管理 |
| 🌊 刷屏 | 防刷屏总开关、消息频率预设、触发后操作、禁言时长 |
| 🏷 称号 | 查看/添加/修改/删除等级称号，点击列表行直接填入编辑框，恢复默认 |
| 🎰 抽奖 | 查看进行中的抽奖、立即开奖、取消抽奖、创建新抽奖 |
权限隔离：Mini App 只展示当前登录用户担任管理员的群组，其他群组不可见。
技术栈
- 运行时：Node.js 20 + TypeScript
- Bot 框架：grammY
- Web 框架：Fastify + EJS
- 数据库：PostgreSQL 16 + TypeORM
- 缓存：Redis 7
- 验证：Cloudflare Turnstile + Telegram WebApp initData HMAC
- 容器化：Docker + Docker Compose
- CI/CD：GitHub Actions → ghcr.io
快速部署
前置要求
- Linux 服务器（1 GB+ RAM）
- Docker + Docker Compose
- 域名 + SSL 证书（Webhook 必须 HTTPS）
- Telegram Bot Token（@BotFather）
- Cloudflare Turnstile 密钥（控制台）
1. 拉取镜像与配置文件
mkdir sufegroup-bot && cd sufegroup-bot
# 下载生产配置
curl -LO https://raw.githubusercontent.com/Shannon-x/sufegroup_bot/master/docker-compose.prod.yml
curl -LO https://raw.githubusercontent.com/Shannon-x/sufegroup_bot/master/.env.example
cp .env.example .env
nano .env
2. 必填环境变量
# Telegram 机器人
BOT_TOKEN=your_bot_token # 从 @BotFather 获取
BOT_USERNAME=your_bot_username # 不带 @
BOT_WEBHOOK_DOMAIN=https://your-domain.com
BOT_WEBHOOK_SECRET=random_string # openssl rand -hex 32
BOT_MINIAPP_SHORT_NAME=app # BotFather 中配置的 Web App 短名称 (强烈推荐)
# 数据库
DB_PASSWORD=strong_password # openssl rand -hex 16
# Redis
REDIS_PASSWORD=strong_password # openssl rand -hex 16
# Cloudflare Turnstile
TURNSTILE_SITE_KEY=your_site_key
TURNSTILE_SECRET_KEY=your_secret_key
# hCaptcha (选填：为电脑端用户提供备用双轨验证方案)
HCAPTCHA_SITE_KEY=your_hcaptcha_sitekey
HCAPTCHA_SECRET_KEY=your_hcaptcha_secret
# 安全密钥
JWT_SECRET=random_string # openssl rand -hex 32
HMAC_SECRET=random_string # openssl rand -hex 32
3. 启动服务
docker compose -f docker-compose.prod.yml up -d
# 查看日志
docker compose -f docker-compose.prod.yml logs -f bot
# 健康检查
curl http://localhost:8080/health
4. Nginx 反向代理
server {
listen 443 ssl http2;
server_name your-domain.com;
ssl_certificate /path/to/cert.pem;
ssl_certificate_key /path/to/key.pem;
location / {
proxy_pass http://127.0.0.1:8080;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
server {
listen 80;
server_name your-domain.com;
return 301 https://$host$request_uri;
}
从源码构建
git clone https://github.com/Shannon-x/sufegroup_bot.git
cd sufegroup_bot
cp .env.example .env
nano .env
docker compose build
docker compose up -d
docker compose up -d
🚀 版本升级指南 (至 v1.3.x+)
最新的版本中，我们对整个流程进行了极大的翻新。过去用户点击入群验证需要跳转到第三方浏览器，而从新版开始，入群验证与群成员的数据排行榜都已经被完全整合进了 Telegram 自带的 Mini App 中，不再有割裂感！
为了让您的现有 Bot 拥抱全新的内嵌体验，老用户请按以下三步走进行快速迁移：
1. 配置 Telegram Web App
- 打开您的 @BotFather，发送
/newapp 指令（或通过 /mybots -> Bot Settings -> Menu Button -> Configure menu button）。
- 按照提示选择您的机器人，设置标题与描述。
- Web App URL (核心): 这里请输入您服务署名的 URL，并加上
/mini-app 后缀。例如：https://your-domain.com/mini-app。
- Short Name (必填): BotFather 会要求你设定一个短名字，比如
app、verify 或 rank。请记住这个名字！
2. 更新环境变量
用编辑器打开您服务器上的 .env 文件，加入您上一阶段获取到的 Short Name：
BOT_MINIAPP_SHORT_NAME=您设置的短名字
3. 重启生效
更新代码后，重新编译或者拉取新镜像，并重启服务：
docker compose build # 如果您是本地编译
docker compose up -d
注：如果您没有配置 BOT_MINIAPP_SHORT_NAME 这个环境变量，没关系，为了防止报错，系统会自动无损降级回旧版本的“私聊提供外部浏览器验证”的流程。
配置了 Mini App 时，入群验证消息在「🔐 点击验证」下面还有一个「📱 打不开？点这里验证」按钮。Telegram X 等第三方客户端打不开 Mini App 链接（提示“尚未支持这种链接类型”），点这个按钮会进入机器人私聊，私聊里除了「🔐 开始验证」还有「🌐 打不开？用浏览器验证」，用浏览器完成同样的人机验证。浏览器验证链接只在本人私聊里发出，不会出现在群里。
使用说明
首次使用
- 私聊机器人，发送
/start
- 点击聊天框下方「➕ 添加到群聊」按钮，将机器人加入你的群组
- 在群组管理员设置中将机器人设为管理员（需要"删除消息"和"封禁用户"权限）
- 回到私聊，点击「📱 管理面板」进行配置
⚠️ 必须先设为管理员，否则机器人无法删除消息或封禁用户。
命令参考
所有用户
| 命令 | 说明 |
|---|
/help | 显示帮助信息 |
/checkin | 每日签到领积分 |
/profile | 查看个人等级和资料 |
/rank | 活跃排行榜 |
/lottery list | 查看进行中的抽奖 |
/join [ID] | 参与抽奖 |
管理员（群组内）
| 命令 | 说明 |
|---|
/admin | 打开管理面板 |
/settings | 查看/修改群组设置 |
/kick @用户 [原因] | 踢出用户 |
/ban @用户 [时长] [原因] | 封禁用户 |
/unban @用户 | 解封用户 |
/mute @用户 [时长] | 禁言用户 |
/unmute @用户 | 解除禁言 |
/stats | 查看群组统计 |
内容过滤
| 命令 | 说明 |
|---|
/filter | 查看过滤状态 |
/filter on / off | 开关内容过滤 |
/filter add 词1 词2 | 添加自定义关键词 |
/filter del 词1 | 删除关键词 |
/filter list | 查看关键词列表 |
/filter action warn|mute|ban | 违规处理方式 |
/filter url|invite|phone|forward on|off | 开关子规则 |
/filter flood on|off | 开关防刷屏 |
/filter flood limit 10 10 | 10 秒内最多 10 条 |
This is the beginning of the README. Read the rest at the original. Read the full README ↗
