docs: add project readme

2026-07-08 00:04:19 +08:00
parent 5ee64bde60
commit c50b000d08
1 changed files with 301 additions and 0 deletions
@@ -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.