🤖 TG 群管机器人 v2 — 重构规划
📌 项目信息
| 项 |
值 |
| 项目路径 |
/vol3/1000/Code/tg-spam-guard/ |
| Git 仓库 |
GitHub ngfchl/tg-spam-guard |
| 运行环境 |
Python 3.12 + Docker |
| Web 框架 |
FastAPI + uvicorn |
| ORM |
Tortoise ORM + aerich |
| 数据库 |
PostgreSQL (192.168.123.5:15432) |
| Bot |
python-telegram-bot ≥ 22 |
| AI |
Ollama (qwen3:8b) |
| 知识库 |
sentence-transformers + BGE-zh + numpy |
| 前端 |
Element UI 单页 |
🏗️ 项目结构
📦 数据库设计（PostgreSQL）
核心表
-- 消息记录
CREATE TABLE messages (
id BIGSERIAL PRIMARY KEY,
msg_id BIGINT,
chat_id BIGINT NOT NULL,
user_id BIGINT NOT NULL,
username VARCHAR(255),
first_name VARCHAR(255),
text TEXT,
is_spam BOOLEAN DEFAULT FALSE,
spam_reason VARCHAR(255),
created_at TIMESTAMPTZ DEFAULT NOW()
);
CREATE INDEX idx_messages_user_id ON messages(user_id);
CREATE INDEX idx_messages_created_at ON messages(created_at);
CREATE INDEX idx_messages_is_spam ON messages(is_spam);
-- 封禁记录
CREATE TABLE bans (
id BIGSERIAL PRIMARY KEY,
user_id BIGINT NOT NULL,
username VARCHAR(255),
first_name VARCHAR(255),
reason VARCHAR(500),
method VARCHAR(50), -- 'auto' / 'command' / 'verify_fail'
duration_minutes INTEGER,
auto_unban BOOLEAN DEFAULT TRUE,
unban_at TIMESTAMPTZ,
created_at TIMESTAMPTZ DEFAULT NOW()
);
CREATE INDEX idx_bans_user_id ON bans(user_id);
-- 操作日志（入群/退群/删除/解封/警告等）
CREATE TABLE actions (
id BIGSERIAL PRIMARY KEY,
action VARCHAR(50) NOT NULL, -- JOIN/LEAVE/DELETE/UNBAN/WARN/MUTE/KICK
user_id BIGINT,
username VARCHAR(255),
operator_id BIGINT, -- 执行操作的管理员
details JSONB, -- 扩展字段
created_at TIMESTAMPTZ DEFAULT NOW()
);
CREATE INDEX idx_actions_action ON actions(action);
CREATE INDEX idx_actions_created_at ON actions(created_at);
-- 入队验证
CREATE TABLE verify_queue (
id BIGSERIAL PRIMARY KEY,
user_id BIGINT NOT NULL,
username VARCHAR(255),
question VARCHAR(500),
answer VARCHAR(500),
attempts INTEGER DEFAULT 0,
status VARCHAR(20) DEFAULT 'pending', -- pending/verified/failed/expired
created_at TIMESTAMPTZ DEFAULT NOW(),
verified_at TIMESTAMPTZ
);
CREATE INDEX idx_verify_user_id ON verify_queue(user_id);
-- 账号绑定（TG ↔ Harvest）
CREATE TABLE user_bindings (
id BIGSERIAL PRIMARY KEY,
tg_user_id BIGINT UNIQUE NOT NULL,
tg_username VARCHAR(255),
harvest_uid VARCHAR(255),
harvest_token VARCHAR(500),
bound_at TIMESTAMPTZ DEFAULT NOW()
);
-- 警告记录
CREATE TABLE warnings (
id BIGSERIAL PRIMARY KEY,
user_id BIGINT NOT NULL,
username VARCHAR(255),
reason VARCHAR(500),
issued_by BIGINT,
active BOOLEAN DEFAULT TRUE,
created_at TIMESTAMPTZ DEFAULT NOW()
);
CREATE INDEX idx_warnings_user_id ON warnings(user_id);
CREATE INDEX idx_warnings_active ON warnings(active);
-- 游戏积分
CREATE TABLE game_scores (
id BIGSERIAL PRIMARY KEY,
user_id BIGINT NOT NULL,
username VARCHAR(255),
game_type VARCHAR(50),
score INTEGER DEFAULT 0,
wins INTEGER DEFAULT 0,
total INTEGER DEFAULT 0,
streak INTEGER DEFAULT 0,
last_played TIMESTAMPTZ,
UNIQUE(user_id, game_type)
);
-- 群组配置
CREATE TABLE group_config (
key VARCHAR(100) PRIMARY KEY,
value JSONB,
updated_at TIMESTAMPTZ DEFAULT NOW()
);
📋 功能清单（去掉 PT 专属）
| # |
模块 |
优先级 |
说明 |
| 1 |
🛡️ 垃圾信息阻挡 |
✅ 已有 |
三级检测：缓存→正则→AI，保留优化 |
| 2 |
⚡ 防刷屏 |
🔴 P0 |
令牌桶限速，超阈值删除多余消息 |
| 3 |
🔒 新人限制 |
🔴 P0 |
入群 N 分钟内禁止发链接/图片/文件/贴纸 |
| 4 |
👋 入群欢迎 |
🔴 P0 |
自定义欢迎卡片 + 群规 + 60s 自动删 |
| 5 |
✅ 入群验证 |
🔴 P0 |
新人答题/点按钮，超时踢出 |
| 6 |
🔗 账号绑定 |
🔴 P0 |
TG ↔ Harvest 授权绑定 |
| 7 |
🌙 夜间模式 |
🟡 P1 |
定时全员禁言，管理员不受影响 |
| 8 |
🔨 管理工具 |
🟡 P1 |
/warn /mute /kick /purge /slowmode /stats |
| 9 |
📊 操作审计 |
🟡 P1 |
所有管理员操作记录到 DB |
| 10 |
👥 退群告别 |
🟡 P1 |
可选，默认关闭 |
| 11 |
📚 知识库问答 |
✅ 已有 |
/ask + RAG，保持 |
| 12 |
🎉 气氛组 |
🟢 P2 |
关键词触发表情、连击、撒花、里程碑 |
| 13 |
🎮 小游戏 |
🟢 P2 |
答题/签到/积分排行/抽奖 |
| 14 |
🎂 生日祝福 |
🟢 P3 |
记录生日，当天自动祝福 |
🔄 开发阶段
Phase 1：基建（SQLite→PG + 重构 + Git）
- 初始化 Git 仓库
- 项目目录结构搭建
- config.py（环境变量管理）
- db/（Tortoise ORM 模型 + aerich 初始化）
- docker-compose.yaml（接入 PostgreSQL 网络）
- requirements.txt / pyproject.toml 更新
- main.py 瘦身：只保留启动逻辑
Phase 2：核心安全（P0）
- handlers/spam.py + services/spam_detector.py（从旧 main.py 提取）
- handlers/admin.py（/ban /unban /warn /mute /kick /stats /purge）
- 防刷屏中间件
- 新人限制（禁止链接/图片/文件）
Phase 3：入群流程（P0）
- handlers/welcome.py（入群欢迎/退群告别）
- handlers/verify.py + services/verify_service.py（入群验证）
- templates/（消息模板）
Phase 4：账号绑定（P0）
- handlers/bind.py + services/bind_service.py
- 对接 go-harvest-server verify 接口
- /bind /unbind 命令
Phase 5：夜间模式 + 管理增强（P1）
- handlers/night_mode.py + services/night_scheduler.py
- APScheduler 集成
- 操作审计
Phase 6：社交 + 游戏（P2-P3）
- handlers/fun.py + services/game_service.py
- 气氛组（关键词触发、连击、撒花）
- 小游戏（答题、签到、积分）
- 生日祝福
Phase 7：Web 面板升级
- web/api.py（所有 API 路由）
- web/static/index.html（适配新数据结构）
- SSE 实时推送适配
⚙️ 环境变量（.env）
📝 备忘
- 旧数据迁移：JSON → PostgreSQL（一次性脚本，放在 scripts/migrate_json_to_pg.py）
- docker-compose 需要加入
1panel-network 网络
- aerich 配置写在 aerich.toml，用
aerich init / aerich migrate 管理
- wheels/ 目录保留（torch 等大包不走网络）
- 知识库模块（knowledge/）保持独立，不改动
- 旧 main.py 备份为 main.py.bak
ngfchl