353 lines
14 KiB
Markdown
353 lines
14 KiB
Markdown
# QQBot NapCat 源码 Fork 二维码刷新修复设计
|
||
|
||
## 背景
|
||
|
||
线上账号 `1914728559` 的更新登录链路已经证明 API 侧旧二维码回传被挡住：刷新会话不再把旧 QR 传给 Admin/SSE，接口会保持 `pending` 并清空二维码。但同一个容器内的 NapCat WebUI 仍存在源头问题：
|
||
|
||
- 正确通过 `/api/auth/login` 换取 `Credential` 后，`CheckLoginStatus` 与 `GetQQLoginQrcode` 仍返回旧二维码 hash `47fb616d3f27c93a`。
|
||
- `/app/napcat/cache/qrcode.png` 的 mtime、size、sha256 不变化。
|
||
- Docker 日志只有“当前账号(1914728559)已登录,无法重复登录”，没有二维码生成日志。
|
||
- NapCat WebUI 内部 `QQLoginStatus=true` 与实际 `selfInfo.online=false` 发生分裂，导致 `RefreshQRcode` / `GetQQLoginQrcode` 被旧登录态短路。
|
||
|
||
上一轮 `kt-napcat-desktop-cn:desktop-cn-v2` 是在派生镜像里解压 `NapCat.Shell.zip` 并用脚本 patch bundled JS。这条路验证了方向，但它仍是脆弱的产物补丁：上游构建压缩、文件结构或字符串变化都会让补丁静默失效。本轮选择 fork NapCat 源码，在源代码层修复登录态与二维码刷新语义，再把源码构建产物注入 KT 受控中文桌面派生镜像。
|
||
|
||
## 目标
|
||
|
||
1. 建立 KT 可维护的 `NapCatQQ` 源码 fork，不再依赖对 `napcat.mjs` 的字符串补丁。
|
||
2. 在 NapCat WebUI 源码层修复 `QQLoginStatus=true` 但真实账号离线时的登录态误判。
|
||
3. 让 `RefreshQRcode` 的结果可观测：区分“刷新请求已被 QQ 内核接受”和“新的 QR URL 已经到达 WebUI 缓存”。
|
||
4. 让 `GetQQLoginQrcode` / `CheckLoginStatus` 不再对 stale QR 做成功式返回。
|
||
5. 保留 API 侧 fresh QR 护栏，避免未来 NapCat 或 QQ 内核异常时 Admin/SSE 再展示旧码。
|
||
6. 生成 KT 受控 `NapCat.Shell.zip` artifact，并接入 `kt-napcat-desktop-cn:desktop-cn-v3` 镜像。
|
||
7. 完成本地构建验证、镜像验证、线上单账号 canary 验证，再决定是否替换所有账号容器。
|
||
|
||
## 非目标
|
||
|
||
- 不绕过 QQ/Tencent 验证码、新设备验证或安全验证。
|
||
- 不修改 QQ/NTQQ 私有协议字段，不伪造协议签名。
|
||
- 不重写 NapCat Docker 上游镜像链路；首版继续复用 KT 的中文桌面派生镜像。
|
||
- 不删除 API 侧已完成的旧二维码防护。
|
||
- 不在登录 SSE 流程里恢复 Docker 重建、重启或运行态补 env。
|
||
- 不把 OneBot 反向 WebSocket 在线当作 QQ 账号登录成功证据。
|
||
|
||
## 源码仓库与基线
|
||
|
||
新增一个长期维护的独立源码 fork：
|
||
|
||
```text
|
||
D:\MyFiles\KT\GitHub\NapCatQQ
|
||
```
|
||
|
||
基线使用上游 `NapNeko/NapCatQQ` 的 `origin/main`，当前已审计的上游基线 commit 为：
|
||
|
||
```text
|
||
5c18a62530d87dbadf53d267002894faa6ca7e90
|
||
```
|
||
|
||
实现阶段必须重新拉取并确认实际基线。如果上游已经前进，先把本设计的源改动 rebased 到新的 `origin/main`，并记录实际基线 commit。`D:\MyFiles\KT\.kt-workspace\upstream\NapCatQQ` 只允许作为临时只读审计目录，不作为最终 fork 或构建真相源。
|
||
|
||
fork 分支建议：
|
||
|
||
```text
|
||
codex/qr-refresh-login-state
|
||
```
|
||
|
||
KT API 仓库只保存构建脚本、镜像集成和验证逻辑，不提交 `NapCat.Shell.zip` 二进制 artifact。
|
||
|
||
## 源码改动设计
|
||
|
||
### 登录态统一 helper
|
||
|
||
在 `packages/napcat-webui-backend/src/helper/Data.ts` 增加 WebUI 登录运行态 helper。它读取三类状态：
|
||
|
||
- WebUI 缓存态：`QQLoginStatus`。
|
||
- 实际核心态：`OneBotContext?.core?.selfInfo?.online`。
|
||
- 当前二维码缓存：`QQQRCodeURL`。
|
||
|
||
helper 的语义：
|
||
|
||
- `QQLoginStatus=true` 且 `online=true`：真实在线，登录类接口继续返回已登录。
|
||
- `QQLoginStatus=true` 且 `online=false`：stale 登录态，必须把 `QQLoginStatus` reconcile 为 `false`，并允许重新走 quick/password/manual QR。
|
||
- `online` 为 `undefined`：启动早期或上下文未初始化，不能直接判定离线；保留原行为，避免登录成功到 adapter 初始化之间的短窗口误伤。
|
||
- stale 登录态被 reconcile 时，允许清空旧 QR 或标记旧 QR 为不可用，避免 `GetQQLoginQrcode` 对外返回历史二维码。
|
||
|
||
helper 返回结构建议包含：
|
||
|
||
```ts
|
||
{
|
||
webuiLoginStatus: boolean;
|
||
online?: boolean;
|
||
isActuallyLogin: boolean;
|
||
isStaleLoginStatus: boolean;
|
||
canStartLoginFlow: boolean;
|
||
qrcodeurl: string;
|
||
qrcodeRevision: number;
|
||
qrcodeUpdatedAt: number;
|
||
}
|
||
```
|
||
|
||
字段命名可按上游风格调整，但语义必须完整保留。
|
||
|
||
### QQLogin handlers 收敛
|
||
|
||
`packages/napcat-webui-backend/src/api/QQLogin.ts` 中所有直接用 `WebUiDataRuntime.getQQLoginStatus()` 短路登录流程的 handler，都改为使用统一 helper：
|
||
|
||
- `QQGetQRcodeHandler`
|
||
- `QQSetQuickLoginHandler`
|
||
- `QQRefreshQRcodeHandler`
|
||
- `QQPasswordLoginHandler`
|
||
- `QQCaptchaLoginHandler`
|
||
- `QQNewDeviceLoginHandler`
|
||
|
||
`QQCheckLoginStatusHandler` 当前已经读取 `selfInfo.online`，但仍可能附带旧 `qrcodeurl`。它也必须切到同一个 helper，保证返回的 `isLogin`、`qrcodeurl`、错误信息和 revision 一致。
|
||
|
||
关键约束：
|
||
|
||
- 只有 `isActuallyLogin=true` 时才返回 `QQ Is Logined`。
|
||
- stale 登录态不能阻止 `RefreshQRcode`。
|
||
- stale 登录态不能把旧 QR 作为新二维码返回。
|
||
- quick 登录报“当前账号已登录”后仍要由真实在线态决定是否完成登录，而不是由 WebUI 缓存态决定。
|
||
|
||
### 二维码 revision 与刷新可观测性
|
||
|
||
在 `Data.ts` 中给二维码缓存增加 revision/更新时间：
|
||
|
||
- `setQQLoginQrcodeURL(url)` 只有在 URL 变化时递增 `qrcodeRevision`。
|
||
- 每次 QR URL 变化记录 `qrcodeUpdatedAt`。
|
||
- 清空 stale QR 时也更新 revision，让调用方能知道旧码已失效。
|
||
|
||
`refreshQRCode()` 不再只返回 `void`。它应返回刷新结果，例如：
|
||
|
||
```ts
|
||
{
|
||
accepted: boolean;
|
||
updated: boolean;
|
||
qrcodeurl: string;
|
||
qrcodeRevision: number;
|
||
error?: string;
|
||
}
|
||
```
|
||
|
||
实现语义：
|
||
|
||
1. 记录刷新前的 QR URL/revision。
|
||
2. 调用 `onRefreshQRCode`。
|
||
3. 如果底层返回 `false`，则 `accepted=false`。
|
||
4. 如果底层接受请求，则等待一次 `onQRCodeGetPicture` 写入新 QR，或在短等待窗口后返回 `accepted=true, updated=false`。
|
||
5. 只有 QR URL/revision 变化，才返回 `updated=true`。
|
||
|
||
等待窗口必须短且有上限，不能把 WebUI HTTP 请求变成长期阻塞。首版建议只在 WebUI 内做短等待，API 侧仍保持 SSE/polling pending。
|
||
|
||
### Shell 与 Framework callback
|
||
|
||
二维码真正进入 WebUI 缓存的位置在：
|
||
|
||
- `packages/napcat-shell/base.ts`
|
||
- `packages/napcat-framework/napcat.ts`
|
||
|
||
这两个入口里：
|
||
|
||
- `onQRCodeGetPicture` 继续调用 `setQQLoginQrcodeURL`，并触发 revision 更新。
|
||
- `setRefreshQRCodeCallback` 不再吞掉底层返回值，应把 `loginService.getQRCodePicture()` 的 `boolean` 返回给 `refreshQRCode()`。
|
||
|
||
这样 WebUI 能知道 QQ 内核是否接受了取 QR 请求，API 也能通过 WebUI 响应判断“待产码”和“已有新码”。
|
||
|
||
## KT 镜像集成
|
||
|
||
继续使用 `Node/kt-template-online-api/ci/napcat-desktop-cn` 作为 KT 中文桌面派生镜像入口，但移除 bundled JS patch。
|
||
|
||
### 构建输入
|
||
|
||
实现阶段新增构建脚本，把 fork 仓库构建出的 `NapCat.Shell.zip` staged 到 `.kt-workspace` 下的 Docker build context。API 仓库不直接提交二进制 zip。
|
||
|
||
推荐流程：
|
||
|
||
```text
|
||
NapCatQQ fork
|
||
-> pnpm build shell artifact
|
||
-> .kt-workspace/napcat-desktop-cn-build/NapCat.Shell.zip
|
||
-> ci/napcat-desktop-cn/Dockerfile COPY into /app/NapCat.Shell.zip
|
||
-> kt-napcat-desktop-cn:desktop-cn-v3
|
||
```
|
||
|
||
Docker `COPY` 不能引用 build context 之外的文件，所以实现脚本必须显式 staging context，而不是在 Dockerfile 里直接读 `D:\MyFiles\KT\GitHub\NapCatQQ`。
|
||
staging context 必须同时包含 Dockerfile、`verify.sh`、fork artifact marker 和 `NapCat.Shell.zip`，避免 Dockerfile 在仓库目录、`COPY` 源却在另一个 context 的路径错位。
|
||
|
||
### Dockerfile 变化
|
||
|
||
`ci/napcat-desktop-cn/Dockerfile` 保留：
|
||
|
||
- `zh_CN.UTF-8`
|
||
- `Asia/Shanghai`
|
||
- 中文字体与 fontconfig
|
||
- XDG/Home 环境
|
||
- `verify.sh`
|
||
|
||
删除：
|
||
|
||
- `ci/napcat-desktop-cn/patches/qq-login-real-online-guard.sh`
|
||
- 解压 `/app/NapCat.Shell.zip` 后用 Perl/字符串改 `napcat.mjs` 的步骤
|
||
|
||
新增：
|
||
|
||
- 从 staged context 复制源码构建的 `NapCat.Shell.zip` 到 `/app/NapCat.Shell.zip`
|
||
- 写入 fork artifact marker，例如 `/ci/napcat-desktop-cn/fork-artifact.json`，包含 upstream base commit、fork commit、build time、artifact sha256
|
||
|
||
### verify.sh 变化
|
||
|
||
`ci/napcat-desktop-cn/verify.sh` 不再 grep JS patch 字符串，而是验证：
|
||
|
||
- `/app/NapCat.Shell.zip` 存在且能解压。
|
||
- artifact sha256 与 marker 一致。
|
||
- marker 中存在 upstream base commit 和 fork commit。
|
||
- locale/fontconfig/timezone/XDG 仍通过。
|
||
- 能在解压后的 WebUI backend bundle 中找到 QR revision 或 runtime helper 的可观测 marker。
|
||
|
||
## API 侧边界
|
||
|
||
API 不再承担 NapCat 内部登录态修复职责，但继续保留防旧码护栏：
|
||
|
||
- `scan/refresh` 继续要求 fresh QR。
|
||
- `scan/status` 继续拒绝把旧 QR 当成新码返回。
|
||
- `scan/qrcode/refresh` 继续在未拿到新 QR 时保持 `pending`。
|
||
- QQ 登录态仍以 NapCat WebUI/login logs 为准，不以 OneBot heartbeat 兜底。
|
||
|
||
需要更新的 API 文件范围：
|
||
|
||
- `ci/napcat-desktop-cn/Dockerfile`
|
||
- `ci/napcat-desktop-cn/verify.sh`
|
||
- `ci/napcat-desktop-cn/README.md`
|
||
- `ci/napcat-desktop-cn/patches/qq-login-real-online-guard.sh` 删除
|
||
- `src/modules/qqbot/napcat/application/runtime/napcat-runtime-profile.service.ts`
|
||
- `test/modules/qqbot/napcat/napcat-desktop-cn-image.spec.ts`
|
||
- `test/modules/qqbot/napcat/runtime-protocol-profile.spec.ts`
|
||
- 可能涉及 `test/qqbot/napcat/qqbot-napcat-container.service.spec.ts`
|
||
- `docs/qqbot-nas-runtime.md`
|
||
- `README.md` / `API.md` 中涉及镜像 tag 或 NapCat runtime 的说明
|
||
|
||
默认 profile 版本升级到：
|
||
|
||
```text
|
||
desktop-cn-v3
|
||
```
|
||
|
||
生产仍通过 `QQBOT_NAPCAT_IMAGE` 控制实际镜像，不在 API 代码里硬编码生产 digest。
|
||
|
||
## 数据流
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant Admin
|
||
participant API
|
||
participant NapCatWebUI
|
||
participant QQKernel
|
||
|
||
Admin->>API: 更新登录 / scan/refresh
|
||
API->>NapCatWebUI: CheckLoginStatus / GetQQLoginInfo
|
||
NapCatWebUI->>NapCatWebUI: helper reconcile QQLoginStatus + selfInfo.online
|
||
API->>NapCatWebUI: RefreshQRcode
|
||
NapCatWebUI->>QQKernel: getQRCodePicture()
|
||
QQKernel-->>NapCatWebUI: accepted / rejected
|
||
QQKernel-->>NapCatWebUI: onQRCodeGetPicture(new QR)
|
||
NapCatWebUI->>NapCatWebUI: setQQLoginQrcodeURL + revision++
|
||
NapCatWebUI-->>API: accepted, updated, qrcodeRevision, qrcodeurl
|
||
API-->>Admin: pending + new QR 或 pending + 正在生成
|
||
```
|
||
|
||
若 QQ 内核接受刷新但未产码，API/SSE 显示“正在生成二维码/等待 NapCat 返回二维码”，不展示旧码。
|
||
|
||
## 错误处理
|
||
|
||
- `online=undefined` 不做 stale reconcile，避免启动过程误判。
|
||
- `online=false` 且 `QQLoginStatus=true` 时 reconcile 失败必须写 WebUI 错误信息，并允许后续刷新重试。
|
||
- `refreshQRCode.accepted=false` 时返回明确错误，不继续使用旧 QR。
|
||
- `accepted=true, updated=false` 时保持 pending，API 继续轮询或允许手动刷新。
|
||
- QR revision 变化但 URL 为空，表示旧码已清空，不能被 API 当成可展示二维码。
|
||
- 源码 fork 构建失败时不得回退到 bundled JS patch 镜像；构建阶段直接失败。
|
||
- 线上 canary 失败时回滚 `QQBOT_NAPCAT_IMAGE` 到上一版镜像，并保留 API 旧码防护。
|
||
|
||
## 验证计划
|
||
|
||
### NapCatQQ fork
|
||
|
||
需要在 fork 仓库运行：
|
||
|
||
```powershell
|
||
corepack pnpm install --frozen-lockfile
|
||
corepack pnpm run typecheck
|
||
corepack pnpm test
|
||
corepack pnpm run build:shell
|
||
```
|
||
|
||
若上游 monorepo 的测试脚本或 package 名称变化，以 `package.json` 为准，但必须覆盖：
|
||
|
||
- WebUI backend 登录态 helper。
|
||
- `QQLogin.ts` handler 对 stale login status 的行为。
|
||
- `refreshQRCode()` accepted/updated/revision。
|
||
- shell/framework callback 返回值。
|
||
|
||
### KT API 镜像集成
|
||
|
||
需要在 API 仓库运行：
|
||
|
||
```powershell
|
||
corepack pnpm exec jest test/modules/qqbot/napcat/napcat-desktop-cn-image.spec.ts test/modules/qqbot/napcat/runtime-protocol-profile.spec.ts --runTestsByPath --runInBand
|
||
corepack pnpm run typecheck
|
||
git diff --check
|
||
```
|
||
|
||
如果改到容器创建逻辑，再追加：
|
||
|
||
```powershell
|
||
corepack pnpm exec jest test/qqbot/napcat/qqbot-napcat-container.service.spec.ts --runTestsByPath --runInBand
|
||
```
|
||
|
||
### 镜像验证
|
||
|
||
在 NAS 或本地 Docker 构建：
|
||
|
||
```bash
|
||
docker build \
|
||
--build-arg NAPCAT_BASE_IMAGE="$NAPCAT_BASE_IMAGE" \
|
||
-t kt-napcat-desktop-cn:desktop-cn-v3 \
|
||
-f .kt-workspace/napcat-desktop-cn-build/ci/napcat-desktop-cn/Dockerfile \
|
||
.kt-workspace/napcat-desktop-cn-build
|
||
docker run -d --name kt-napcat-v3-verify kt-napcat-desktop-cn:desktop-cn-v3
|
||
docker exec kt-napcat-v3-verify sh /ci/napcat-desktop-cn/verify.sh
|
||
docker rm -f kt-napcat-v3-verify
|
||
```
|
||
|
||
记录镜像 digest、fork commit、artifact sha256。
|
||
|
||
### 线上 canary
|
||
|
||
1. 只对一个测试账号或用户指定账号切换 `QQBOT_NAPCAT_IMAGE=kt-napcat-desktop-cn:desktop-cn-v3`。
|
||
2. 不在 SSE 流程中重建在线容器；只有用户明确执行容器迁移/重建时才创建 v3 容器。
|
||
3. 触发更新登录，观察：
|
||
- quick 已登录错误后 WebUI 会 reconcile stale 登录态。
|
||
- `RefreshQRcode` 触发 NapCat 产码日志。
|
||
- `/app/napcat/cache/qrcode.png` mtime/hash 变化。
|
||
- API `scan/status` 返回新 QR，不返回旧 QR。
|
||
- SSE/Admin 从“扫码”推进到扫码后状态或明确 pending 原因。
|
||
4. 若扫码后触发新设备或验证码，按既有链路继续，不把它当作 fork 失败。
|
||
|
||
## 上线顺序
|
||
|
||
1. 在 API 仓库提交本设计文档。
|
||
2. 进入 `KT plan writing`，把源码 fork、KT 镜像集成、测试和线上 canary 拆成实施任务。
|
||
3. 创建或更新 `D:\MyFiles\KT\GitHub\NapCatQQ` fork 分支。
|
||
4. 先实现并验证 NapCatQQ 源码修复。
|
||
5. 再修改 API 仓库的派生镜像构建脚本和测试。
|
||
6. 构建 `desktop-cn-v3`，在 NAS 上验证镜像。
|
||
7. 推送 API 仓库并观察 Jenkins/K8s。
|
||
8. 线上单账号 canary，通过后再迁移剩余账号。
|
||
|
||
## 完成标准
|
||
|
||
- NapCatQQ fork 有明确 base commit、fork commit 和可重复构建命令。
|
||
- `desktop-cn-v3` 镜像不再包含 bundled JS 字符串 patch。
|
||
- stale `QQLoginStatus=true + online=false` 不再阻止刷新二维码。
|
||
- `RefreshQRcode` 能表达 accepted/updated/revision。
|
||
- API/Admin/SSE 不展示旧 QR，线上 canary 能看到新 QR 或明确的未产码 pending 原因。
|
||
- 相关测试、镜像 verify、线上 canary 证据完整。
|