KTeam/kt-template-online-api
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
60be4e6210
kt-template-online-api/docs/plans/2026-06-18-qqbot-napcat-runtime-protocol-profile-implementation-plan.zh-CN.md

14 KiB
Raw Blame History

QQBot NapCat Runtime / Protocol Profile 中文方案

本文是给人读的中文方案说明。英文版 2026-06-18-qqbot-napcat-runtime-protocol-profile-implementation-plan.md 是给执行代理使用的逐任务实施清单，后续代码实现以英文清单为准。

一句话结论

这轮不是单纯把 Docker 做得更像 Linux，而是先把 QQBot 的登录事件、会话行为、协议配置和运行环境都变成可观测、可回滚、可灰度的 Profile。真正优先级是：会话/行为画像、登录事件最小化、官方建议的 o3HookMode=0/IP/设备迁移，最后才是 Docker/中文桌面运行态卫生。

当前状态

  • 设计文档已确认：docs/specs/2026-06-18-qqbot-napcat-linux-runtime-protocol-profile-design.md。
  • 英文实施计划已生成：docs/plans/2026-06-18-qqbot-napcat-runtime-protocol-profile-implementation-plan.md。
  • 当前还没有进入代码实现阶段，线上规则仍按现有 NapCat 链路运行。
  • 用户已确认：现有账号已经进入风控，可以做受控设备身份迁移；MAC 不走 Docker/QEMU/KVM/VMware/Hyper-V 风格前缀；zh_CN.UTF-8 派生镜像和真实中国桌面环境必须做；不做账号级每小时/每日发送预算。

总目标

  1. 让每个 NapCat 账号拥有稳定、可审计的设备身份：dataDir、hostname、MAC、machine-id。
  2. 让登录恢复链路稳住 quick -> password，减少无意义的 docker rm -f、重建容器、刷新二维码和反复扫码。
  3. 建立 Session Behavior Profile，降低“零客户端行为 + 永久在线 + 登录后立即自动化输出”的异常画像。
  4. 建立 Protocol Risk Profile，统一管理 NapCat/OneBot 配置、o3HookMode 灰度、版本 drift、出口/IP/代理证据。
  5. 构建 KT 受控的 Chinese Desktop Runtime 派生镜像，提供 zh_CN.UTF-8、中文字体、fontconfig、上海时区、XDG/Home、DBus/Xvfb/QQ 进程环境。
  6. Admin 先做只读证据展示，危险操作后续单独设计，不在首版开放批量按钮。

明确不做

  • 不绕过 QQ 验证码、新设备验证或安全验证。
  • 不伪造 QQ/NTQQ 私有协议签名，不写未验证的内部协议“真人模拟”。
  • 不启用 --privileged、--network=host、--pid=host、--uts=host、host IPC。
  • 不把 watchdog 做成自动扫码、自动刷新二维码、自动反复重建容器的兜底机制。
  • 不做账号级每小时/每日累计发送预算，也不做变相累计硬额度。
  • 不把 OneBot 心跳当成 QQ 登录成功证据。

架构分层

Admin 只读展示
  -> API QQBot Core
  -> QqbotAccountNapcatRuntimePort
  -> NapCat Runtime/Profile 应用层
     -> 设备身份 Profile
     -> 登录事件 Profile
     -> Session Behavior Profile
     -> Protocol Risk Profile
     -> Chinese Desktop Runtime Profile
  -> NAS SSH / Docker / NapCat WebUI / OneBot reverse WS

边界原则：

  • Core 只通过端口消费 NapCat 能力，不直接拼 Docker/NapCat 细节。
  • NapCat 模块内部负责 profile 生成、配置写入、证据采集、恢复租约和登录事件。
  • Admin 首版只展示 evidence 和状态，不直接承载危险批量迁移。
  • 所有敏感字段在入库前、日志前、API 返回前三层脱敏。

数据表设计摘要

napcat_device_identity

继续作为设备身份真相源，保存账号稳定的 dataDir、hostname、MAC、machine-id、验证状态和最近登录证据。它只管“这台设备是谁”，不塞会话行为或风险降载状态。

napcat_runtime_profile

保存 Docker/中文桌面运行态证据，包括镜像 ref/digest、base digest、desktop profile version、locale、fontconfig、时区、UID/GID、shm、XDG、持久目录、自检 evidence、profile 状态。

napcat_protocol_profile

保存 NapCat/OneBot 协议配置，包括 packetBackend、packetServer、o3HookMode、账号级灰度状态、OneBot/NapCat 配置 JSON 与 hash、版本 drift evidence。

napcat_session_behavior_profile

保存会话行为策略，包括冷启动窗口、housekeeping 是否启用、下一次 housekeeping、presence 能力、自动能力阶段和最近行为 evidence。这个表不保存小时/日发送额度。

napcat_login_event

记录登录侧风控事件，包括 quick 尝试、password 尝试、容器 restart/recreate、二维码生成/扫码、验证码、新设备验证、恢复挂起。它用于审计和熔断，不是消息发送预算。

风险降载状态

可独立成轻量表，也可落在现有账号运行态里，但语义必须独立于 QQ 登录态、OneBot 连接态和发送日志。状态只表达 normal、cooldown、manual_only 这类运行模式，不表达每日额度。

第一优先级：登录事件最小化

每一次容器删除重建、扫码、验证码、新设备验证，都会增加登录侧风险。watchdog 的目标不是“永远自动恢复”，而是“在不制造新登录事件的前提下尽量恢复”。

watchdog 自动链路只允许：

  1. 获取同账号恢复租约，保证同一账号同一时间只有一个恢复流程。
  2. 检查账号绑定唯一、容器唯一、账号与容器一致。
  3. 复用当前容器、当前 dataDir、当前 hostname/MAC/machine-id。
  4. 先 quick 恢复。
  5. quick 失败且账号保存了密码时，再 password 恢复。
  6. 密码登录成功后清理运行态密码环境，清理失败必须阻断成功。
  7. 遇到验证码、新设备验证、二维码兜底、账号不匹配、连续恢复失败或 profile drift，立即挂起自动恢复并通知 Admin。

watchdog 明确不做：

  • 不自动清理 QQ 登录态。
  • 不自动删除 dataDir。
  • 不反复 docker rm -f。
  • 不自动刷新二维码。
  • 不在验证码或新设备验证 pending 时切换其他登录路径。

第二优先级：会话行为 Profile

重点是降低无头会话画像，而不是简单“少发消息”。

首版只做低副作用行为：

  • 登录成功后的冷启动窗口：先允许手动 smoke，再逐步恢复文本命令、图片命令、自动回复、复读机。
  • 低频 housekeeping：刷新自身状态、账号登录态、群/好友基础缓存或 NapCat 稳定公开接口，不能变成群聊刷存在感。
  • presence capability detection：只有 NapCat/OneBot 有稳定公开能力时才启用在线/离开类状态切换；没有公开能力就不做。
  • 风险事件降载：出现验证码、新设备验证、KickedOffLine、连续发送失败后，自动回复/复读机进入保守状态，管理员手动命令仍可低频测试。

housekeeping 或 presence 失败只记录 evidence，不触发登录 reset、密码重试、容器重建或二维码刷新。

第三优先级：Protocol Risk Profile

NapCat/OneBot 配置由 API 统一生成，不再依赖手工漂移：

  • webui.json
  • napcat.json
  • napcat_<uin>.json
  • onebot11.json
  • onebot11_<uin>.json

默认策略：

  • packetBackend=auto
  • o3HookMode=1
  • OneBot 只启用反向 WebSocket client。
  • messagePostFormat=array
  • reportSelfMessage=false
  • debug=false
  • parseMultMsg=false
  • 不启用 HTTP server/client、WebSocket server。

灰度策略：

  • o3HookMode=0 只允许账号级灰度。
  • 先用测试账号，记录 NapCat 版本、QQNT 版本、镜像 digest、登录结果、收发结果、是否触发验证码/新设备/掉线。
  • 如果测试账号收益明确，再按账号批次推广。

IP/代理/出口证据：

  • 本轮先做可观测，不自动全局切换网络。
  • 记录账号相关连接出口、地域、代理策略和变化窗口。
  • 后续是否引入账号级代理，单独做方案。

第四优先级：真实设备身份迁移

新账号和现有账号都走稳定设备身份，但现有账号已经被确认风控，因此允许直接迁移到真实设备风格：

  • hostname 不包含 QQ 号、bot、napcat、docker 等词。
  • MAC 使用真实物理设备风格 OUI catalog。
  • 明确排除 Docker 02:42、QEMU/KVM 52:54:00、VMware、Hyper-V 等虚拟化前缀。
  • machine-id 继续稳定生成并只读挂载。

迁移流程：

  1. 记录迁移前 hostname/MAC/machine-id/登录状态。
  2. 生成新的真实设备风格 hostname/MAC/machine-id。
  3. 按登录事件最小化规则重建目标容器。
  4. 如触发新设备验证，按现有新设备链路完成，不当作代码失败。
  5. 登录完成后记录迁移后 evidence、登录事件和收发结果。
  6. 单账号失败只回滚单账号，不做盲目全量反复重建。

第五优先级：Chinese Desktop Runtime

这一层是运行卫生和证据能力，不是主要风控缓解项。必须做，但不能把它的收益讲过头。

派生镜像要求：

  • 基础镜像必须 pin 到明确 digest。
  • 镜像内生成并启用 zh_CN.UTF-8。
  • 默认 LANG=zh_CN.UTF-8、LC_ALL=zh_CN.UTF-8、LANGUAGE=zh_CN:zh。
  • 时区固定 Asia/Shanghai。
  • 安装可再分发中文字体，预生成 fontconfig cache。
  • fc-match 能解析常见中文字体 fallback。
  • 保持上游 QQ/Xvfb/NapCat entrypoint 行为，不破坏隐藏容器痕迹的初始化逻辑。
  • 支持 XDG/Home、cache、local-share、config、plugins、logs 持久化。

Docker run 运行态：

  • 增加 --init。
  • 增加 --shm-size，默认建议 512m。
  • 不启用 host PID/UTS/IPC/network。
  • 默认不再以 root 运行 QQ/Xvfb，改用 NAS 专用普通 UID/GID。
  • 非 root 改动必须验证没有削弱 entrypoint 现有容器隐藏行为。

持久目录建议：

account-data/
  QQ/
  cache/
  local-share/
  config/
  plugins/
  logs/
  machine-id
  device.env
  runtime-profile.json
  protocol-profile.json

重置登录态时不得删除 device/profile/cache/local-share/logs，除非用户明确执行“重建设备身份”。

API 和 Admin 首版能力

API 首版提供只读接口：

  • runtime profile 摘要。
  • protocol profile 摘要。
  • session behavior profile 摘要。
  • profile drift。
  • 最近登录事件。
  • 风险降载状态。
  • 下一次自动恢复时间。
  • 最近 housekeeping/presence evidence。

Admin 首版做只读 Drawer：

  • 镜像 ref/digest、base digest、desktop profile version。
  • zh_CN.UTF-8、字体/fontconfig、时区、XDG、UID/GID、shm。
  • hostname/MAC/machine-id 一致性。
  • packetBackend、o3HookMode、OneBot 配置 hash。
  • 冷启动窗口、housekeeping、presence、自动能力阶段。
  • 最近 docker rm -f、重建、扫码、验证码、新设备验证、恢复挂起记录。
  • 风险降载原因和解除时间。

首版不开放批量 o3HookMode=0、批量设备迁移、批量清登录态等危险按钮。

分期落地路径

Phase 1：表结构和门禁

  • 建 profile/event/risk 相关表。
  • 加 SQL verify。
  • 加 no daily/hour budget、MAC 前缀排除、敏感字段脱敏的测试门禁。

Phase 2：设备身份和配置生成

  • 收敛 hostname/MAC/machine-id 策略。
  • 引入真实物理设备风格 OUI catalog。
  • 统一生成 NapCat/OneBot 配置并计算 hash。
  • 记录 profile drift evidence。

Phase 3：登录事件和 watchdog 稳定化

  • 加恢复租约。
  • 记录登录事件。
  • 强制 watchdog 只走 quick -> password。
  • 遇到验证码、新设备验证、二维码兜底和连续失败时挂起自动恢复。

Phase 4：Session Behavior Profile

  • 实现冷启动窗口。
  • 实现 housekeeping 调度和 evidence。
  • 实现 presence capability detection。
  • 实现自动能力逐步恢复和风险降载。

Phase 5：Chinese Desktop Runtime

  • 构建 KT 派生镜像。
  • 验证 zh_CN.UTF-8、中文字体、fontconfig、时区、XDG、DBus/Xvfb/QQ 进程环境。
  • 引入 --init、--shm-size、非 root UID/GID。
  • 验证不破坏 entrypoint 现有隐藏能力。

Phase 6：API/Admin 只读闭环

  • 暴露 runtime/protocol/session behavior/login event 只读接口。
  • Admin 账号页接 Runtime Profile Drawer。
  • 页面明确区分 QQ 登录态、OneBot 连接态、容器状态、恢复状态。

Phase 7：线上灰度和迁移

  • 测试账号先跑完整 profile 自检和收发 smoke。
  • 测试账号灰度 o3HookMode=0。
  • 测试账号做真实设备身份迁移。
  • 现有风控账号按批次迁移。
  • 每个账号记录迁移前后 evidence、登录事件、收发结果和回滚点。

验收标准

本轮完成后，至少要能证明：

  • API 能查询每个账号的 runtime/protocol/session behavior profile。
  • 登录事件能区分 quick、password、restart、recreate、QR、captcha、新设备、suspended。
  • watchdog 不会自动进入 QR、不反复 docker rm -f、不自动刷新二维码。
  • o3HookMode=0 只能账号级灰度，且有版本/digest/收发证据。
  • MAC 策略排除 Docker/QEMU/KVM/VMware/Hyper-V 前缀。
  • Chinese Desktop 派生镜像通过 zh_CN.UTF-8、fontconfig、时区、XDG、QQ/Xvfb 进程、entrypoint 行为验证。
  • Admin 能只读展示 profile evidence 和风险状态。
  • 没有账号级小时/日累计发送预算配置。
  • 敏感字段不会进入日志、API 响应或未脱敏 evidence。
  • 线上至少完成一个测试账号闭环，再迁移现有账号。

回滚策略

  • 表结构新增不影响旧链路，必要时先停用 profile 服务，不删除数据。
  • o3HookMode=0 可按账号回滚到 1。
  • Chinese Desktop Runtime 失败时可按账号回滚到旧镜像 ref，但保留 profile evidence。
  • 非 root UID/GID 失败时只回退进程用户策略，不回退中文 locale/字体/时区镜像建设。
  • 设备身份迁移失败时只回滚单账号的 device identity，不并发重建其他账号。
  • watchdog 熔断后等待人工处理，不用自动重试掩盖问题。

和英文实施计划的关系

  • 本中文文档用于确认方向、边界、风险和验收。
  • 英文实施计划用于执行，里面有具体文件、测试、提交节奏和任务拆分。
  • 后续开始实现时，应按英文计划走 KT batch execution 或 KT local execution。
  • 如果实现阶段发现英文计划与本中文方案冲突，以本中文方案的目标和边界为准，再同步修订英文计划。