QQ 群管机器人

代码仓库：https://github.com/GuiDI-666/qq-group-bot （公开） 发布新版本用 python deploy/release.py v1.x.x "说明"，会自动提交并推送。

一套开箱即用的 QQ 群管理机器人，基于 NoneBot2 + OneBot v11（NapCat 协议端） 实现，不依赖任何智能体平台，自己电脑/服务器上跑起来就是一个独立的群管服务。

功能一览

分类	能力
入群审批	自动通过 QQ 等级达标的入群申请（门槛可设），不达标按策略忽略/拒绝
广告拦截	按正则规则识别广告/引流内容，撤回 + 禁言；管理员发言仅提示、不误伤
违禁词	自定义违禁词表，命中即撤回并禁言
成员管理	禁言 / 解除禁言 / 踢出，支持 @ 或直接写 QQ 号
黑名单	拉黑 / 解除拉黑 / 查看名单，拉黑自动踢出且拒绝再次入群
欢迎语	入群欢迎、退群提示文案可热改
潜水名单	未发言 命令按 30/60/90 天拉取未发言成员，结果可合并转发并落盘存档
菜单 / 存活	菜单 查看指令，存活 检查在线状态与运行时长
运行保障	看门狗守护进程 + 登录失效自动重登 + 睡眠唤醒自愈 + 开机自启

安全设计（重要）

• 只在自己的群里干活：managed_groups 白名单之外的群，机器人完全不响应（不回复、不处理）
• 机器人不是管理员的群，同样静默：避免在无权限的群里刷屏
• 管理群名单类命令只能私聊使用：群内发无效，防止普通成员误操作
• 权限分级：超级管理员 / 群主 / 群管理员 才能执行管理命令，普通成员发指令无任何反馈
• 不误伤管理员：管理员触发广告规则只提示"发言不规范"，不撤回不禁言

快速开始

1. 安装 Python 3.10+（脚本会自动装依赖）
2. 复制 部署配置.example.json → 改名为 部署配置.json，填入：机器人 QQ 号、超级管理员 QQ 号、NapCat 目录
3. 双击 一键部署.bat —— 自动检查环境、安装依赖、下载配置协议端、部署机器人、跑自检
4. 双击 启动机器人.bat —— 进入看门狗守护模式常驻运行
5. 首次登录需手机 QQ 扫码（协议端会生成二维码图片），之后可免扫码快速登录

仓库不含任何真实账号信息：所有个人配置都走 *.example 模板（部署配置.json、qq-group-bot/.env、qq-group-bot/config.json 均已被 .gitignore 排除）。

目录结构

QQ群管机器人/
├── 一键部署.bat / 一键自检.bat / 启动机器人.bat / 重新登录.bat
├── 开启开机自启.bat / 关闭开机自启.bat
├── 部署配置.example.json   部署参数模板（复制为 部署配置.json 后填写）
├── 说明.md                部署文档
├── 维护文档.md            维护手册：启停/排障 FAQ/备份/升级/服务器部署
├── CHANGELOG.md           版本更新记录（VERSION 为当前版本号）
├── deploy/                部署与运维脚本
│   ├── deploy.py          一键部署（环境检查+安装+写配置）
│   ├── self_check.py      9 项部署自检
│   ├── watchdog.py        看门狗：进程守护 + 失效重登 + 唤醒自愈
│   ├── autostart.py       开机自启管理（Windows 启动项 / Linux systemd 模板）
│   └── release.py         版本发布（更新版本号+CHANGELOG+提交打标+推送）
└── qq-group-bot/          机器人本体（NoneBot2 项目）
    ├── bot.py             入口
    ├── config.json        热配置：审批门槛/广告规则/欢迎词/管理群/管理员
    ├── .env               端口、超级管理员、命令前缀
    └── src/plugins/       功能插件
        ├── common.py      公共规则（管理群判定、机器人管理员判定）
        ├── approval.py    入群自动审批
        ├── guard.py       广告/违禁词拦截
        ├── admin.py       禁言/解禁/踢出
        ├── blacklist.py   黑名单
        ├── welcome.py     入群欢迎/退群提示
        ├── inactive.py    未发言潜水名单
        ├── settings.py    热设置（等级/广告规则/欢迎词/管理群）
        ├── status.py      存活检测
        └── help.py        指令菜单

常用指令

场景	指令
禁言 / 解禁 / 踢出	禁言 @某人 30、禁言 1234567 30、解除禁言 @某人、踢出 @某人
黑名单	拉黑 @某人、解除拉黑 1234567、黑名单
潜水名单	未发言、未发言 60、未发言 90（私聊可加群号：未发言 <群号> 30）
热设置	设置等级 30、添加广告词 xxx、设置欢迎 xxx、设置退群 xxx
管理群（仅私聊）	添加管理群 <群号>、移除管理群 <群号>、管理群列表
状态	菜单、存活、ping

⚠ 自 v1.8.0 起命令只认 / 前缀（如 /菜单、/禁言），裸命令已停用。

部署说明

方式一：Windows 本机 / 自己的服务器（推荐，全自动）

1. 安装 Python 3.10+（服务器部署.bat 会自动找/装合适的版本）
2. 复制 部署配置.example.json → 改名 部署配置.json，填入：机器人 QQ 号、超级管理员 QQ 号、管理群号
3. 双击 一键部署.bat —— 自动安装依赖、下载 NapCat 协议端、写配置、跑自检
4. 双击 启动机器人.bat —— 看门狗守护模式常驻运行
5. 首次登录手机 QQ 扫码（协议端生成二维码到项目根目录 需要扫码登录.png），之后凭据新鲜期内免扫码快速登录

方式二：阿里云等云服务器

与方式一相同，额外注意：

• 部署完成后登录自启（开启开机自启.bat）建议开启，避免远程桌面注销后服务消失
• 机房 IP 风控更严格：更容易被踢下线；部署配置.json 的 napcat_password 填密码后掉线可走密码重登，但机房 IP 上密码登录大概率每次都触发短信验证码（需人工到 NapCat WebUI 完成验证），无法全自动
• 详细运维（看门狗机制、掉线恢复、日志排障）见 维护文档.md

运行保障机制

机制	说明
看门狗守护	协议端 / 机器人进程掉线自动拉起，假在线（会话僵死）经心跳自检发现后强制重登
自动重登	登录失效自动重登，最多 2 次（max_relogin_attempts 可调），超限停机待人工
心跳自检	默认每 30 分钟实测发一条消息验证收发闭环（zombie_check_interval 可调），失败 60 秒快速复测
密码回退	配置 napcat_password 后快速登录失效时自动改用密码登录（需 NapCat 4.16+）
日志黑匣子	watchdog.log 写入失败自动降级备用文件；启动自检日志可写性

注意事项

• 使用第三方协议端（NapCat）属于非官方方案，存在账号风控风险，建议使用小号并控制操作频率
• 全局配置为单份，跨群生效（白名单机制用于限定生效范围）
• 睡眠/休眠会中断进程与网络，长时间挂机请关闭睡眠；看门狗已支持唤醒后自愈
• 仓库不含任何真实账号/IP/密码：个人配置一律走 *.example 模板 + .gitignore 排除，提 PR 前请同样自查