模块	技术
Bot / API	Python、FastAPI、python-telegram-bot
数据库	PostgreSQL、Tortoise ORM、Aerich
Web 前端	Vue 3、Vite、SoybeanUI
实时日志	Server-Sent Events
AI 检测	Ollama
部署	Docker Compose

目录结构

.
├── 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. 准备配置

复制配置样例：

cp .env.example .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 网络，容器内会连接：

postgres://user_eNPcQS:${POSTGRES_PASSWORD}@127.0.0.1:15432/tg-spam-guard

因此需要确保宿主机已有对应数据库、用户和权限。

3. 准备 Ollama

默认容器内访问宿主机 Ollama：

http://127.0.0.1:11434

推荐轻量模型：

ollama pull qwen3:8b

4. 构建前端

cd front
npm install
npm run build
cd ..
cp -r front/dist/* web/static/

5. 启动服务

docker compose up -d --build

在当前部署环境中，如果系统 sg 被占用，需要使用：

/usr/bin/sg docker -c "docker compose up -d --build"

查看状态：

docker compose ps

访问后台：

http://127.0.0.1:8766

常用维护命令

编译检查

python3 -m py_compile web/api.py
python3 -m py_compile handlers/admin.py handlers/spam.py services/spam_detector.py

前端构建

cd front
npm run build
cd ..
cp -r front/dist/* web/static/

重新部署

/usr/bin/sg docker -c "docker compose up -d --build"

查看容器状态

/usr/bin/sg docker -c "docker compose ps"

查看日志

/usr/bin/sg docker -c "docker compose logs -f --tail=200"

规则管理

规则目录：

rules/
├── spam_keywords.txt       # 关键词规则
├── spam_regex.txt          # 正则规则
└── adblock_domains.txt     # Adblock 域名规则

规则原则：

短消息默认放行，避免误杀“好的 / OK / 1 / 收到”等正常回复。
AI 只做兜底，不确定时放行。
Adblock 域名规则只在文本包含 URL / 域名时匹配。
Web 后台写入规则会做清洗、查重、正则校验，并热加载。

白名单策略

白名单严格按群组隔离：

chat_id + user_id

效果：

白名单用户命中垃圾规则时，消息仍会被删除。
不会自动封禁白名单用户。
后台手动封禁 / 删除并封禁会拦截白名单用户。
封禁记录右键“加入白名单并解封”会先写入白名单，再立即解封。

指令权限

公开指令：

/ask /stats /checkin /trivia /score /rank /shop /buy /bind /me /help

管理员指令：

/ban /unban /warn /mute /dban /dmute /dwarn /purge /night /lottery /panel

私聊绑定类：

/start /bind /auth /me

知识库

默认轻量模式：

KNOWLEDGE_SEARCH_MODE=lite

轻量索引只依赖：

knowledge/index/metadata.json

重建轻量索引：

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.

Languages

Python 64.3%

Vue 18.2%

CSS 13.8%

HTML 2.6%

PLpgSQL 0.8%

Other 0.2%

README.md Unescape Escape

TG Spam Guard

功能概览

群组安全

Web 管理后台

知识库问答

积分与活动

技术栈