monitor-qq-bot

基于 NoneBot2 + OneBot V11 + NapCat + Redis + Docker Compose 的 QQ 群静默监控与管理员群告警机器人。默认一体化启动：redis + bot + napcat 三个容器。

安全边界：不在学生群回复、不自动私聊、不自动踢人/禁言/撤回、不下载或执行群文件，所有告警只发送到管理员群。

---

1. 项目背景

在学校混省护的时候，学生的主线大概都是"看群"，其次才是看态势感知，不过手工看低效且无聊，所以有了一个小小的监控 bot，后续时间空出来了拿 AI 大人零零散散迭代了一段时间，就有了现在这个项目。

2. 功能一览

• 监听指定 QQ 群，默认静默。
• 管理员群只收确凿告警：黑名单用户/关键词、消息与连续拆分消息、入群/改名资料、转发消息内文本与发送人昵称命中黑名单。
• 资源群只收人工复核资源：图片、文件信息、转发消息集合（含有限嵌套展开后内嵌的图片/文件）；未配置资源群则仅落审计。
• 普通关键词自动变成"可穿插空白和不可见字符"的模糊正则，re: 开头为高级正则。
• 连续拆分消息拼接检测：命中后展示完整拼接序列，并自动结束本轮拼接重新匹配。
• 转发消息集合有限嵌套识别：内嵌文本、发送人昵称跑黑名单；内嵌图片/文件走资源群复核。
• 管理员群内 /guard 命令维护监控群、黑白名单，分层帮助（/guard <命令> help）。
• Redis 保存配置、状态与告警审计；/guard audit stats 输出 群/人 触发统计。
• 支持同一服务器多实例部署。

3. 快速开始

# 1. 克隆仓库
git clone https://github.com/PapButfly/monitor-qq-bot.git
cd monitor-qq-bot

# 2. 配置（必填项说明见 docs/config.md）
cp .env.example .env
vim .env

# 3. 启动（首次构建需几分钟）
docker compose up -d --build
docker compose ps   # redis / bot / napcat 三个容器 Up 即成功

容器起来后还需登录 NapCat 并配置 OneBot 连接（约 5 分钟），完整步骤见 docs/install.md。

4. 文档目录

文档	内容
docs/install.md	部署：完整流程、NapCat 登录、OneBot 连接、多实例、升级重建、常见问题
docs/usage.md	使用：各检测机制的行为与边界、告警示例、已知限制
docs/commands.md	命令：/guard 全部命令、权限与示例
docs/config.md	配置：.env 全部变量、正则规则、Redis 保存内容

5. 注意事项

• 规则要由管理员持续维护：拼音、谐音、花字、emoji 替字和图片文字都可能绕过自动检测。
• 图片和转发合集默认交给人工复核（资源群），不内置 OCR。
• 本项目不实现自动处置（踢人、禁言、撤回），处置由管理员人工执行。
• 多实例必须使用不同的 COMPOSE_PROJECT_NAME、BOT_PORT/NAPCAT_*_PORT 和 REDIS_PREFIX。

6. 更新计划

暂无固定排期，可能的方向（视时间与需求）：

• 图片 OCR：识别图片内文字（目前图片完全靠人工复核）
• 加入 AI 功能实现半自动
• 更多绕过检测：繁体/谐音/拼音/花字等开放集变形
• 更多告警渠道

如果你有很棒的想法，请务必提 Issue 或者 PR！

7. 开源协议

本项目基于 MIT License 开源，详见 LICENSE。