Skip to content

登录与上线流程 ​

mode 2(自建上线)的每一步都可能失败,而且失败后的正确动作不同:凭据错要停, 网络断要重登,注册被拒要退避。把「当前在哪一步」显式建模成状态机,比散落的 boolean 好排查,也方便宿主 UI 直接显示进度。

源码:packages/session/src/state.ts、packages/bot/src/createBot.ts。

状态机 ​

text
idle ──→ preflight ──→ logging-in ──→ logged-in ──→ registering ──→ online
  │          │              │              │               │            │
  └──────────┴──────────────┴──────────────┴───────────────┴────────────┤
                                                                        ↓
                                        degraded ←───────────────────────┘
                                           │  ↑
                              logging-in ──┘  └── online(native 自己重连成功)
状态含义
idle还没开始
preflight环境预检:平台、QQ 安装路径、VM 可用性、native 能力
logging-inquickLogin(a1) 换票
logged-in拿到 a2/d2/d2Key,尚未注册
registeringopenSession(mode 2):SsoInfoSync 注册 + 首屏同步 + 挂推送
online在线:心跳由 native 维持,事件从 sink 进来
degraded掉线重试中(退避等待 / 重登)
closed终止态

迁移不允许跳步,跳步会抛 IllegalTransitionError。唯一例外是 closed:任何状态都能 一步关掉。

degraded 有两条出口:

  • → logging-in:a1 还能用时重新换票;
  • → online:native 自己完成了重连(reconnected),不重走登录。

每一步的失败处理 ​

preflight ​

检查项:平台支持、QQ 安装路径存在、签名 VM 可用、native 能力齐全、vault 里有 a1, 以及(控制台形态下)该账号的 nt_msg.db 没有被 QQ 本体持有。

nt_msg.db 的路径优先取 qq.dbPath;没配时按数据根 + 账号推导 (Windows <数据根>/<uin>/nt_qq/nt_db/,Linux / macOS <数据根>/nt_qq_<hash>/nt_db/, hash = md5(md5(uid) + "nt_kernel"))。推到的是存在的路径才会拿去做在线判定。

任一失败都停在这里并报具体项 —— 这一步能查出来的问题,拖到联网阶段只会更难定位。

logging-in ​

quickLogin(a1) 的失败分三类,处理方式完全不同:

类型表现动作
a1 失效140022014 / 140022015 / 140022016「用户身份已失效,请重新登录」停,抛 A1_EXPIRED;宿主清除该账号凭据,提示重新登录 QQ 或扫码
网络错误超时 / 连接失败退避重试
风控unusual-device 等停并报错

不要拿失效 a1 硬重试

反复用失效 a1 调用 quickLogin 只会引发风控。命中上面三个码中任意一个时必须停下来。

异常设备确认不是失败

服务端要求手机确认(unusual-device)时 native 会在登录链路里自己轮询,最长 45 秒。 这段时间不是错误、也不是网络卡顿,宿主应当通过 login-progress 事件把「请在手机上 确认登录」显示给用户 —— 否则页面上只剩一个转圈。

:::

registering ​

openSession(mode 2) 内部完成:连接 → 注册(SsoInfoSync)→ 心跳 → 首屏同步。 TS 侧再额外等 session.syncGraceMs(默认 15s),因为慢账号的 InfoSyncPush 可能晚到。

等不到仍然报 REGISTER_FAILED,不会假装在线 —— 「状态显示在线但收不到消息」比直接 报错难查得多。

online ​

心跳由 native 维持。TS 侧只接两件事:

  • 推送 sink:解码成 BotEvent;
  • 状态 sink:kicked 直接终止(正常不该出现,因为我们不抢登录);closed 按网络 掉线走退避重登。

退避与重登 ​

text
degraded → 等 1s → logging-in → 失败 → 等 2s → 4s → 8s → 16s → …

maxReloginAttempts(默认 5)耗尽后进入 relogin-failed,进程停止重试。

a1 还能用就不用重新登录 QQ —— 重登只是重新 quickLogin(a1)。

崩溃恢复 ​

进程重启 = 从 vault 拿 a1 → 重走一遍 preflight 之后的所有步骤。

不需要持久化任何票据:a2 / d2 / d2Key 都是派生物,重新换就行。这也避免了 「票据过期但状态显示在线」的假象。

优雅下线 ​

bot.stop() 会走 closeSession → 发 UnRegister,服务端才会把这条会话摘掉。

CLI 接了三个信号:

信号场景
SIGINTCtrl-C
SIGTERMsystemd / docker / kill 默认
SIGHUP关终端窗口

SIGHUP 之前漏过 —— 在终端里直接关窗口时进程会被直接杀掉,UnRegister 根本发不出去, 手机端会一直显示「电脑在线」。

SIGKILL 接不住(内核直接回收),那种情况只能靠服务端心跳超时把会话摘掉。

离线原因(OfflineReason) ​

离线是一等事件,必须报告原因,否则上层无法决定要不要重登:

值含义
kicked服务端 KickNT。正常情况下不该出现(我们不与 QQ 抢登录)
network网络断 / 心跳超时
closed主动下线(用户关账号 / bot 停止)
bot-exitOneBot bot_exit 主动下线
relogin-failed重登失败次数耗尽
register-failed注册阶段就被拒(凭据失效 / 风控)

事件格式见会话事件。

版本未定(0.0.0 是占位);文档与代码同步演进,以主仓为准