QQ 机器人协议端选型 Mirai 已死与 NapCat 掉线根因 (QQ Bot Protocol Backend: Mirai Deprecation and NapCat Disconnect Root Cause)

2026-09-17 暂无评论

1. 结论先行

Mirai 不能再作为 QQ 机器人协议端使用，原版 mamoe/mirai 与安卓端的 MiraiAndroid 均已实质停更，旧协议被腾讯回收，第三方签名服务（qsign / unidbg-fetch-qsign）停运，登录必然失败。
NapCat 掉线不是框架缺陷，是腾讯风控踢账号登录态（KickedOffLine）。换协议端框架无法规避，因为踢的是账号不是进程。
选型第一原则：判断"掉"是掉进程还是掉登录。两者根因、处置、甚至是否该换框架都完全不同。

常见误解澄清：Mirai 不是安卓生态的东西。它是纯 Java 库（JVM 上跑 mirai-core + mirai-console）；安卓侧只有 MiraiAndroid 这一个把它塞进手机 App 的外壳，且同样已失效。

2. 出现场景

在 tx 服务器（ubuntu@124.221.137.194）上排查 AstrBot + NapCat 反复掉线时，提出"换成 Mirai 是否能更稳"。

3. 判定证据（实机验证，2026-09-17）

3.1 AstrBot 侧

ls /home/ubuntu/workspace/ops/astrbot/app/astrbot/core/platform/sources/
# aiocqhttp dingtalk discord kook lark line mattermost misskey
# qqofficial qqofficial_webhook satori slack telegram webchat
# wecom wecom_ai_bot weixin_oc weixin_official_account

grep -rli "mirai" /home/ubuntu/workspace/ops/astrbot/app/astrbot/
# （空输出）

版本 AstrBot 4.25.1。18 个适配器里没有 mirai，整个包内零处 mirai 引用。即便强上 Mirai，也只能靠 aiocqhttp（OneBot v11）桥接，绕不开 Mirai 本体登不上这一关。

3.2 Mirai 的可获取性与维护状态

经 mihomo 代理（127.0.0.1:7890，见 /home/ubuntu/AGENTS.md）查 GitHub API：

mamoe/mirai           最新 release  v2.16.0   published_at 2023-10-22
                      最后 push    2024-09-23   archived: false
project-mirai/mirai-api-http
                      最新 release  v2.10.0   published_at 2023-11-27

mirai-api-http-2.10.0.mirai2.jar 可直接下载，服务器上 openjdk-17-jre-headless 也有候选版本。

所以结论要分清：Mirai 是"装得上、登不上"，不是"装不上"。 本体近三年未发版，旧协议与签名服务已被腾讯回收，下载得下来也无济于事。

踩坑记录：初次排查时用 curl https://github.com 得超时，据此写下"GitHub 不通"。复测直连与代理均返回 200，系单次超时误判。海外请求必须先按 AGENTS.md 导出 http_proxy/https_proxy 再下结论，未走代理的失败不能当作网络不可达的证据。

3.3 掉线现场（journalctl）

09-17 10:49:15 [error] | [KickedOffLine] [下线通知] 你的账号当前登录已失效，请重新登录。
09-17 10:49:16 [info]  | 账号状态变更为离线

重启该实例后快速登录继续失败：

09-17 08:14:59 [error] 快速登录错误：你的用户身份已失效，为保证账号安全，请你重新登录。
09-17 08:15:36 [error] 快速登录错误：登录态已失效，请重新登录。

进程侧：systemctl show napcat-1369934060.service -p NRestarts 为 0 —— 进程从未崩溃，掉的是登录态。

3.4 对照组（关键证据）

同一台机器、同一个 NapCat 本体、同样 systemd 托管，两个账号 7 天内被踢次数：

实例	账号	`KickedOffLine` 次数（7 天）
`napcat-1369934060.service`	1369934060	4
`napcat-bot2.service`	1808666025	1

差 4 倍。框架相同、宿主相同，唯一变量是账号 —— 这就是"掉的不是框架，是号"的证伪/证成。

4. 根因

腾讯 NTQQ 风控对以下特征敏感：新注册号、低活跃号、云服务器 IP 异地登录、短时间高频发消息、敏感词命中。

KickedOffLine 的语义是服务端主动吊销登录凭证，客户端只能重新扫码。NapCat 的重连机制对此无能为力 —— 重连需要有效凭证，而凭证已被吊销。

5. 处置方向（按性价比排序）

养号：用注册时间长的老号；先在本地住宅网络登录挂机数日再迁到服务器。
确认账号未被多端占用：同一 QQ 在手机手 Q 上登录会挤掉协议端会话，是"莫名掉线"的常见人为原因。
降低行为特征：AstrBot 侧开启回复流控/冷却，避免 LLM 高频刷屏。
持久化登录数据：挂载 /QQ（或 --user-data-dir 指定的目录）保留凭证与设备锁信息，避免每次重启都要扫码。
要绝对稳定则放弃个人号：改用 qqofficial 适配器对接 QQ 开放平台官方机器人，走官方 OpenAPI，无风控踢下线风险，代价是主动发信额度与群场景受官方限制。