From c50b000d08fafaccfa5094b93bbd484a0e84c756 Mon Sep 17 00:00:00 2001
From: ngfchl <ngfchl@users.noreply.github.com>
Date: Wed, 8 Jul 2026 00:04:19 +0800
Subject: [PATCH] docs: add project readme

---
 README.md | 301 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 301 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..817af22
--- /dev/null
+++ b/README.md
@@ -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.