docs: add project readme
This commit is contained in:
ngfchl
@@ -0,0 +1,301 @@
|
||||
# TG Spam Guard
|
||||
|
||||
一个面向 Telegram 群组的反垃圾与群管理机器人，内置 Web 管理后台、规则管理、白名单、封禁审计、知识库问答、签到积分、商城与群抽奖等能力。
|
||||
|
||||
> 当前项目主要用于“收割机”群组的自动化治理，也可以按 `.env.example` 复制配置后部署到其他 Telegram 群。
|
||||
|
||||
## 功能概览
|
||||
|
||||
### 群组安全
|
||||
|
||||
- 自动识别垃圾广告、灰产引流、黑产关键词、可疑链接和高风险域名。
|
||||
- 支持关键词规则、正则规则、Adblock 域名规则三类规则源。
|
||||
- 支持 Ollama 本地大模型兜底识别。
|
||||
- 广告 / 灰产命中后自动删除并封禁。
|
||||
- 支持夜间模式、新人限制、防刷屏、入群验证、欢迎消息自动清理。
|
||||
- 管理指令权限隔离，普通用户只能使用公开查询 / 娱乐功能。
|
||||
|
||||
### Web 管理后台
|
||||
|
||||
- 群组安全总览：统计、聊天记录、实时日志、封禁记录。
|
||||
- 聊天记录右键操作：删除、删除并封禁、封印用户、加入白名单、写入拦截库、复制、回复。
|
||||
- 封禁时使用页面 Modal 选择时长：永久、1 小时、6 小时、1 天、7 天、30 天，也支持自定义分钟。
|
||||
- 封禁记录右键操作：解封、加入白名单并解封。
|
||||
- 规则管理：规则测试、AI 生成规则、关键词 / 正则 / Adblock 域名预览。
|
||||
- 白名单管理：按当前群组隔离，支持手动添加、移出白名单。
|
||||
- 商城管理：商品、库存、积分购买记录。
|
||||
- 抽奖管理：活动式群抽奖、满人开奖、定时开奖、即开即中、参与者查看。
|
||||
|
||||
### 知识库问答
|
||||
|
||||
- 支持基于本地 Markdown 文档构建知识库索引。
|
||||
- 默认轻量检索模式，只读取 `knowledge/index/metadata.json`。
|
||||
- 可选使用 `sentence-transformers + bge-small-zh` 在宿主机构建向量索引。
|
||||
- Telegram 长回复优先使用 HTML 格式发送，避免 Markdown 转义问题。
|
||||
|
||||
### 积分与活动
|
||||
|
||||
- 每日签到。
|
||||
- 知识答题。
|
||||
- 积分排行。
|
||||
- 积分商城。
|
||||
- 群抽奖活动。
|
||||
- 用户账号绑定。
|
||||
|
||||
## 技术栈
|
||||
|
||||
| 模块 | 技术 |
|
||||
|---|---|
|
||||
| Bot / API | Python、FastAPI、python-telegram-bot |
|
||||
| 数据库 | PostgreSQL、Tortoise ORM、Aerich |
|
||||
| Web 前端 | Vue 3、Vite、SoybeanUI |
|
||||
| 实时日志 | Server-Sent Events |
|
||||
| AI 检测 | Ollama |
|
||||
| 部署 | Docker Compose |
|
||||
|
||||
## 目录结构
|
||||
|
||||
```text
|
||||
.
|
||||
├── main.py # 服务入口，启动 Web API、Bot、调度任务
|
||||
├── config.py # 配置读取
|
||||
├── web/api.py # FastAPI 管理后台 API
|
||||
├── db/ # ORM 模型与数据库初始化
|
||||
├── handlers/ # Telegram 指令和事件处理
|
||||
├── services/ # 业务服务：垃圾检测、统计、知识库、积分、验证等
|
||||
├── front/ # Vue 管理后台源码
|
||||
├── web/static/ # 管理后台构建产物
|
||||
├── rules/ # 垃圾检测规则文件
|
||||
├── knowledge/ # 知识库索引、缓存、构建脚本
|
||||
├── logs/ # 运行日志，默认不提交
|
||||
├── docker-compose.yaml
|
||||
├── Dockerfile
|
||||
└── .env.example
|
||||
```
|
||||
|
||||
## 快速开始
|
||||
|
||||
### 1. 准备配置
|
||||
|
||||
复制配置样例：
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
编辑 `.env`，至少填写：
|
||||
|
||||
```env
|
||||
TG_BOT_TOKEN=your_telegram_bot_token
|
||||
TG_CHAT_ID=-100xxxxxxxxxx
|
||||
POSTGRES_PASSWORD=your_postgres_password
|
||||
ADMIN_USER_IDS=你的Telegram用户ID
|
||||
```
|
||||
|
||||
常用配置说明：
|
||||
|
||||
| 配置 | 说明 |
|
||||
|---|---|
|
||||
| `TG_BOT_TOKEN` | Telegram Bot Token |
|
||||
| `TG_CHAT_ID` | 默认管理群组 ID |
|
||||
| `DATABASE_URL` | 宿主机本地运行时使用的数据库连接 |
|
||||
| `POSTGRES_PASSWORD` | Docker Compose 中拼接 PostgreSQL 密码 |
|
||||
| `OLLAMA_URL` | Ollama API 地址 |
|
||||
| `OLLAMA_MODEL` | 垃圾检测兜底模型，如 `qwen3:8b` |
|
||||
| `PROXY_URL` | Telegram API 代理地址 |
|
||||
| `ADMIN_USER_IDS` | 逗号分隔的管理员 Telegram ID |
|
||||
| `WEB_PORT` | Web 管理后台端口，默认 `8766` |
|
||||
| `KNOWLEDGE_SEARCH_MODE` | 知识库检索模式，默认建议 `lite` |
|
||||
|
||||
> 注意：`.env` 包含敏感信息，已被 `.gitignore` 忽略，禁止提交。
|
||||
|
||||
### 2. 准备 PostgreSQL
|
||||
|
||||
项目使用 PostgreSQL。数据库 URL 使用 `postgres://` scheme，不是 `postgresql://`。
|
||||
|
||||
Docker Compose 当前使用 host 网络，容器内会连接：
|
||||
|
||||
```text
|
||||
postgres://user_eNPcQS:${POSTGRES_PASSWORD}@127.0.0.1:15432/tg-spam-guard
|
||||
```
|
||||
|
||||
因此需要确保宿主机已有对应数据库、用户和权限。
|
||||
|
||||
### 3. 准备 Ollama
|
||||
|
||||
默认容器内访问宿主机 Ollama：
|
||||
|
||||
```text
|
||||
http://127.0.0.1:11434
|
||||
```
|
||||
|
||||
推荐轻量模型：
|
||||
|
||||
```bash
|
||||
ollama pull qwen3:8b
|
||||
```
|
||||
|
||||
### 4. 构建前端
|
||||
|
||||
```bash
|
||||
cd front
|
||||
npm install
|
||||
npm run build
|
||||
cd ..
|
||||
cp -r front/dist/* web/static/
|
||||
```
|
||||
|
||||
### 5. 启动服务
|
||||
|
||||
```bash
|
||||
docker compose up -d --build
|
||||
```
|
||||
|
||||
在当前部署环境中，如果系统 `sg` 被占用，需要使用：
|
||||
|
||||
```bash
|
||||
/usr/bin/sg docker -c "docker compose up -d --build"
|
||||
```
|
||||
|
||||
查看状态：
|
||||
|
||||
```bash
|
||||
docker compose ps
|
||||
```
|
||||
|
||||
访问后台：
|
||||
|
||||
```text
|
||||
http://127.0.0.1:8766
|
||||
```
|
||||
|
||||
## 常用维护命令
|
||||
|
||||
### 编译检查
|
||||
|
||||
```bash
|
||||
python3 -m py_compile web/api.py
|
||||
python3 -m py_compile handlers/admin.py handlers/spam.py services/spam_detector.py
|
||||
```
|
||||
|
||||
### 前端构建
|
||||
|
||||
```bash
|
||||
cd front
|
||||
npm run build
|
||||
cd ..
|
||||
cp -r front/dist/* web/static/
|
||||
```
|
||||
|
||||
### 重新部署
|
||||
|
||||
```bash
|
||||
/usr/bin/sg docker -c "docker compose up -d --build"
|
||||
```
|
||||
|
||||
### 查看容器状态
|
||||
|
||||
```bash
|
||||
/usr/bin/sg docker -c "docker compose ps"
|
||||
```
|
||||
|
||||
### 查看日志
|
||||
|
||||
```bash
|
||||
/usr/bin/sg docker -c "docker compose logs -f --tail=200"
|
||||
```
|
||||
|
||||
## 规则管理
|
||||
|
||||
规则目录：
|
||||
|
||||
```text
|
||||
rules/
|
||||
├── spam_keywords.txt # 关键词规则
|
||||
├── spam_regex.txt # 正则规则
|
||||
└── adblock_domains.txt # Adblock 域名规则
|
||||
```
|
||||
|
||||
规则原则：
|
||||
|
||||
- 短消息默认放行，避免误杀“好的 / OK / 1 / 收到”等正常回复。
|
||||
- AI 只做兜底，不确定时放行。
|
||||
- Adblock 域名规则只在文本包含 URL / 域名时匹配。
|
||||
- Web 后台写入规则会做清洗、查重、正则校验，并热加载。
|
||||
|
||||
## 白名单策略
|
||||
|
||||
白名单严格按群组隔离：
|
||||
|
||||
```text
|
||||
chat_id + user_id
|
||||
```
|
||||
|
||||
效果：
|
||||
|
||||
- 白名单用户命中垃圾规则时，消息仍会被删除。
|
||||
- 不会自动封禁白名单用户。
|
||||
- 后台手动封禁 / 删除并封禁会拦截白名单用户。
|
||||
- 封禁记录右键“加入白名单并解封”会先写入白名单，再立即解封。
|
||||
|
||||
## 指令权限
|
||||
|
||||
公开指令：
|
||||
|
||||
```text
|
||||
/ask /stats /checkin /trivia /score /rank /shop /buy /bind /me /help
|
||||
```
|
||||
|
||||
管理员指令：
|
||||
|
||||
```text
|
||||
/ban /unban /warn /mute /dban /dmute /dwarn /purge /night /lottery /panel
|
||||
```
|
||||
|
||||
私聊绑定类：
|
||||
|
||||
```text
|
||||
/start /bind /auth /me
|
||||
```
|
||||
|
||||
## 知识库
|
||||
|
||||
默认轻量模式：
|
||||
|
||||
```env
|
||||
KNOWLEDGE_SEARCH_MODE=lite
|
||||
```
|
||||
|
||||
轻量索引只依赖：
|
||||
|
||||
```text
|
||||
knowledge/index/metadata.json
|
||||
```
|
||||
|
||||
重建轻量索引：
|
||||
|
||||
```bash
|
||||
python3 build_kb_lite.py
|
||||
```
|
||||
|
||||
如果使用向量模式，需要额外安装 `requirements-kb.txt`，并在宿主机 / 构建机离线构建索引，不建议放进运行镜像。
|
||||
|
||||
## 安全注意
|
||||
|
||||
- 不要提交 `.env`、数据库备份、日志、模型、wheel 包。
|
||||
- 不要把 Telegram Bot Token、Gitea Token、数据库密码写入 README 或代码。
|
||||
- 规则库改动前建议备份。
|
||||
- 手动封禁真实用户前确认目标群组和用户 ID。
|
||||
- 大规模导入外部规则时先抽样检查，避免泛词导致误杀。
|
||||
|
||||
## 开发约定
|
||||
|
||||
- 后端新增 API 后优先执行 `py_compile`。
|
||||
- 前端改动后执行 `npm run build`。
|
||||
- Docker 部署前确认 `.dockerignore` 排除 `.venv/`、logs、模型缓存、备份、`front/node_modules/`、`front/dist/`。
|
||||
- 多群组相关数据必须带 `chat_id`。
|
||||
- 数据库并发写入场景优先使用事务和行锁。
|
||||
|
||||
## License
|
||||
|
||||
Private / Internal use.
|
||||
Reference in New Issue
Block a user