# 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.