sunlei 6fb762c6f8 docs: 设计NapCat运行态协议Profile

2026-06-18 09:57:41 +08:00

16 KiB

Raw Blame History

QQBot NapCat Linux Runtime 与协议风险 Profile 设计

背景

线上 QQBot 使用 API 通过 NAS SSH 托管多个 NapCat Docker 容器。前一阶段已经完成按账号持久化 QQ 数据目录、hostname、MAC 和 /etc/machine-id，避免普通容器重建被 QQ 直接识别成全新设备。

本轮用户明确的目标是：让线上 NapCat Docker 环境更像真实 Linux 环境，并把协议特征也纳入方案。这里的“协议特征”只覆盖 NapCat/OneBot 可配置项、版本漂移、发送行为和自动化行为降噪，不包括绕过 QQ 安全验证或篡改 QQ 协议签名。

只读审计得到的当前线上状态：

4 个线上 NapCat 容器都运行 mlikiowa/napcat-docker:latest。
已有 bridge 网络、固定 hostname/MAC、只读 /etc/machine-id、QQ 数据目录持久化。
容器入口脚本已隐藏部分容器痕迹：/.dockerenv 不存在，/proc/1/cgroup 为 0::/。
仍存在明显容器默认态：/dev/shm=64M、CgroupnsMode=private、Init=<nil>、NAPCAT_UID/GID=0、QQ/Xvfb 进程以 root 运行。
运行态 locale 只有 C/C.utf8/POSIX，未显式设置 LANG / LC_ALL / XDG 目录。
当前 hostname 形如 kt-qqbot-napcat-<QQ号>，稳定但不接近普通 Linux 主机名。
当前 MAC 前缀为 02:42，符合 Docker 默认风格。
当前 NapCat 配置里 packetBackend=auto，o3HookMode=1。
当前 OneBot 配置只开启反向 WebSocket，messagePostFormat=array、reportSelfMessage=false、debug=false、parseMultMsg=false。
当前镜像 digest、NapCat 版本、QQNT 版本需要进入常规自检证据，不能只在灰度或故障排查时临时读取。

上游资料约束：

NapCat Docker README 确认 QQ 持久化数据路径为 /app/.config/QQ，配置目录为 /app/napcat/config，插件目录为 /app/napcat/plugins。
NapCat Docker compose 示例使用 network_mode: bridge 并固定 mac_address。
NapCat 安全页建议：频繁掉线可通过更换账号或设备改善；遇到复杂网络可调整 IP/代理；无法更换账号或设备时可尝试 o3Hook=0 关闭包拦截。
NapCat 基础配置说明 OneBot 的 HTTP/WS 服务端、客户端配置结构，以及账号级 onebot11_<uin>.json 文件。
Docker 文档说明 --init、--shm-size、--network、macvlan 等运行参数和网络模型边界；macvlan 可以让容器表现为物理网络接口，但会引入 host 访问与网络运维复杂度。

目标

建立 NapCat Linux Runtime Profile：让托管 NapCat 容器在可控范围内接近普通 Linux 桌面程序运行环境。
建立 NapCat Protocol Risk Profile：把 NapCat/OneBot 配置、o3HookMode 灰度、版本 pin 和自动行为降噪纳入统一 profile。
保持现有账号设备身份稳定，避免无意迁移 hostname/MAC/machine-id 触发额外新设备验证。
提供线上自检证据：容器运行态、NapCat 配置、OneBot 配置、协议风险状态都能被 API 查询或记录。
先以测试账号灰度闭环，再决定是否迁移现有账号的 hostname/MAC。

非目标

不绕过 QQ 验证码、新设备验证或安全验证。
不伪造 QQ 协议签名，不修改 QQ/NTQQ 私有协议字段。
不默认启用 --privileged、--pid=host、--uts=host、--network=host。
不直接全量切换 o3HookMode=0。
不做账号级每小时或每日发送上限，也不做变相累计硬额度。
不在本轮引入 macvlan/ipvlan 作为默认网络模型；它只保留为后续增强方案。

方案总览

本轮采用安全增量方案：

QqbotNapcatContainerService
  -> NapcatRuntimeProfileService
     -> 解析账号的 Linux runtime profile
     -> 解析账号的协议风险 profile
     -> 生成 Docker run 参数、环境变量、挂载目录
     -> 生成 NapCat/OneBot 配置文件内容
  -> 远程 NAS create/recreate script
     -> 准备持久目录和 profile 文件
     -> 写入 webui/onebot/napcat 配置
     -> docker run with runtime profile
  -> NapcatRuntimeProfileInspector
     -> SSH/docker inspect/docker exec 读取运行态证据
     -> 写入最近 profile evidence

profile 分为三层：

设备身份层：账号稳定的 dataDir、hostname、MAC、machine-id。
Linux runtime 层：镜像、UID/GID、shm、init、locale、XDG、持久目录、日志目录。
协议风险层：NapCat packetBackend / o3HookMode、OneBot 配置、发送节流和风险事件降载。

Docker 与 Linux Runtime Profile

镜像 pin

生产环境必须显式配置 QQBOT_NAPCAT_IMAGE，并优先使用明确 tag 或 digest。

允许：mlikiowa/napcat-docker@sha256:<digest>。
允许：明确版本 tag，前提是上线前记录 digest。
不推荐：mlikiowa/napcat-docker:latest。

API 的 profile inspector 需要记录当前容器实际 RepoDigest 与 ImageId，用于判断线上是否漂移。

进程与共享内存

Docker run 增加：

--init：让容器内有 init 处理信号与子进程回收。
--shm-size "$NAPCAT_SHM_SIZE"：默认建议 512m，后续可按内存观察调整到 1g。

不启用 host PID/UTS/IPC。保持容器隔离和多账号端口池模型。

非 root 运行

当前镜像入口脚本需要 root 做初始化，然后用 gosu napcat 启动 Xvfb 与 QQ。我们不改镜像入口行为，只改变传入的 NAPCAT_UID/GID：

默认不再传 0/0。
引入 QQBOT_NAPCAT_RUNTIME_UID 和 QQBOT_NAPCAT_RUNTIME_GID，默认值使用 NAS 上专用普通 UID/GID。
容器启动后自检 QQ/Xvfb 进程是否已从 root 切换到该 UID/GID。

远程创建脚本在启动容器前必须检查并修正 QQ、cache、config、plugins、logs、local-share 目录归属，再用目标 UID/GID 做写入探测。权限不满足时，容器创建失败应明确记录为 runtime profile failure，而不是被吞成普通登录失败，也不能静默回退成 root 运行。

Locale 与 XDG

Docker env 增加：

LANG=C.UTF-8
LC_ALL=C.UTF-8
HOME=/app
XDG_CONFIG_HOME=/app/.config
XDG_CACHE_HOME=/app/.cache
XDG_DATA_HOME=/app/.local/share
TZ=Asia/Shanghai

当前镜像只有 C/C.utf8/POSIX，所以第一阶段不强行生成 zh_CN.UTF-8，避免需要派生镜像。若后续使用派生镜像，再把 zh_CN.UTF-8 作为增强项。

持久目录

每个账号的数据目录保留并扩展：

$DATA_DIR/
  QQ/                 -> /app/.config/QQ
  cache/              -> /app/.cache
  local-share/        -> /app/.local/share
  config/             -> /app/napcat/config
  plugins/            -> /app/napcat/plugins
  logs/               -> /app/napcat/logs
  machine-id          -> /etc/machine-id:ro
  device.env
  runtime-profile.json
  protocol-profile.json

重置登录态只允许清理 QQ 登录态相关数据，不删除 device.env、machine-id、runtime-profile.json、protocol-profile.json、cache/local-share/logs，除非用户明确执行“重建设备身份”。

设备身份策略

新账号默认策略

新账号使用更接近普通 Linux/VM 的稳定身份：

hostname：例如 ubuntu-pc-<stableHash> 或 linux-pc-<stableHash>，不包含 QQ 号、bot、napcat、docker 等词。
MAC：可从 02:42 切到稳定 VM 风格前缀，例如 52:54:00:<hash>。
machine-id：继续稳定生成 32 位十六进制值并只读挂载。

现有账号迁移策略

现有 4 个账号已经有线上可用设备身份，本轮默认不迁移 hostname/MAC。

如果要迁移，必须走单账号灰度：

记录迁移前 hostname/MAC/machine-id/登录状态。
重建容器写入新 hostname/MAC。
观察是否触发新设备验证。
完成登录后记录新的 device evidence。
至少观察一个业务窗口后再推广。

Protocol Risk Profile

NapCat 配置统一生成

API 创建或重建容器时统一生成以下文件：

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

这样默认配置与账号级配置不会漂移。账号级文件优先包含完整配置，默认文件只作为 fallback。

NapCat 协议配置

默认 profile：

{
  "packetBackend": "auto",
  "packetServer": "",
  "o3HookMode": 1,
  "bypass": {
    "hook": false,
    "window": false,
    "module": false,
    "process": false,
    "container": false,
    "js": false
  }
}

灰度 profile：

o3HookMode=0 只允许账号级配置启用。
默认只用于测试账号。
灰度必须记录：账号、切换时间、镜像 digest、NapCat 版本、QQNT 版本、登录状态、收发测试结果、是否触发验证码/新设备/掉线。

packetBackend 第一阶段保持 auto。只有出现明确 PacketBackend 异常时，才设计单独切换策略。

版本与配置漂移

profile 自检必须记录：

容器镜像 ref、digest、image id。
NapCat 版本。
QQNT 版本。
napcat.json / napcat_<uin>.json hash。
onebot11.json / onebot11_<uin>.json hash。

版本信息属于常规 runtime/protocol evidence，不只在 o3HookMode=0 灰度时记录。这样线上出现登录失败、验证码、新设备验证或频繁掉线时，可以区分设备身份变化、镜像升级、NapCat/QQNT 升级和配置漂移。

OneBot 配置

保持当前最小反向 WebSocket 模型：

不启用 HTTP server/client。
不启用 WebSocket server。
只启用 WebSocket client，连接 API reverse WS。
messagePostFormat=array
reportSelfMessage=false
reconnectInterval=5000
heartInterval=30000
debug=false
parseMultMsg=false
enableLocalFile2Url=false

后续实现时应继续避免把 OneBot 心跳当作 QQ 登录态证据。OneBot 连接只证明容器与 API 通信，不证明 QQ 账号在线。

行为协议降噪

本轮不做账号级小时/日累计预算，只做实时节流、异常降载和自动行为降噪。

保留现有实时节流

继续使用已有：

全局发送间隔。
单会话发送间隔。
jitter。
命令冷却。
规则冷却。
复读机阈值、短文本限制、同会话最小间隔。

新增降噪策略

图片与大消息限频
- 图片、大 CQ 消息、长文本回复使用独立最小间隔。
- BangDream 等图片命令不能在同一会话连续快速刷图。
错误回复限频
- 同一命令、同一会话、同一错误摘要在短窗口内只回复一次。
- 后续错误只写日志，不继续刷屏。
冷启动低频窗口
- 刚登录成功后进入短时间低频模式。
- 完成验证码或新设备验证后进入低频模式。
- 低频模式限制自动回复、复读机、事件插件主动回复；手动命令仍允许但走正常实时节流。
风险事件降载
- 出现 KickedOffLine、验证码、新设备验证、连续发送失败后，账号进入降载状态。
- 降载期间不自动触发复读/自动回复类事件。
- Admin 或后端 smoke 可以执行低频手动测试。
- 恢复条件由时间窗口、重新登录成功、手动解除三者之一触发。

不做的行为控制

不统计“账号每小时最多发 N 条”或“每天最多发 N 条”。
不在每日零点重置任何发送额度。
不用累计额度阻断用户手动测试。

数据模型

当前 napcat_device_identity 继续作为设备身份真相源。

新增或扩展的持久化应保持以下边界：

`napcat_device_identity`

继续负责：

account_id
container_id
data_dir
hostname
machine_id_path
mac_address
verification_status
last_login_evidence

不把行为风险状态塞进该表。

`napcat_runtime_profile`

新增账号级 runtime/profile 表，建议字段：

id
account_id
container_id
device_identity_id
profile_version
image_ref
image_digest
runtime_uid
runtime_gid
shm_size
locale
xdg_config_home
xdg_cache_home
xdg_data_home
persist_cache
persist_local_share
persist_logs
hostname_strategy
mac_strategy
migrate_device_identity
profile_status
last_check_evidence JSON
last_checked_at
create_time
update_time

`napcat_protocol_profile`

新增账号级协议 profile 表，建议字段：

id
account_id
container_id
profile_version
packet_backend
packet_server
o3_hook_mode
o3_hook_gray_enabled
onebot_config_hash
onebot_config_json JSON
napcat_config_hash
napcat_config_json JSON
profile_status
last_check_evidence JSON
last_checked_at
create_time
update_time

风险降载状态

风险降载可先复用账号运行态字段或新增轻量状态表。设计上它不属于累计发送预算，建议保存：

account_id
risk_mode: normal / cooldown / manual_only
reason
source_event
expires_at
last_evidence

如果实现时已有合适账号状态字段，可不单独建表，但必须保证和发送日志、登录错误、OneBot 连接状态分离。

API 与 Admin 能力

API

新增或扩展账号运行态接口，提供：

当前 runtime profile 摘要。
当前 protocol profile 摘要。
最近自检证据。
是否存在 profile drift。
是否处于风险降载状态。

敏感字段脱敏：

WebUI token
reverse WS token
password/login runtime env
SSH target key path 不回显私钥内容

脱敏边界必须覆盖三层：入库 profile/evidence 前、日志输出前、API/Admin 返回前。onebot_config_json、napcat_config_json、last_check_evidence 不允许把 token、密码、临时登录 env 原文写入数据库后再依赖展示层隐藏。

Admin

Admin 第一阶段只需要只读展示：

镜像 ref/digest。
UID/GID、shm、locale、XDG。
hostname/MAC/machine-id 是否与 profile 一致。
packetBackend、o3HookMode、OneBot 配置 hash。
风险降载状态和原因。

o3HookMode=0、hostname/MAC 迁移等危险操作必须后续单独设计确认，不在首版页面上开放全量批量按钮。

失败处理

Docker run 参数不被宿主 Docker 支持时，容器创建失败并写入 profile failure。
非 root UID/GID 导致目录权限不正确时，容器创建失败，不回退成 root 静默运行。
profile 自检失败不应误报登录失败，但必须在账号运行态中显示 drift。
o3HookMode=0 灰度后如果出现登录失败、接口异常或发送异常，允许按账号回滚为 1 并重建容器。
风险降载不能清除已有 lastError，也不能把 OneBot WS close 当作 QQ 登录成功或失败。

验证计划

本地/单测

Docker create script 包含 --init、--shm-size、非 root UID/GID、locale/XDG env、cache/local-share/logs 挂载。
新账号 hostname/MAC 策略不包含 QQ 号、bot、napcat、docker 等词。
现有账号默认不迁移 hostname/MAC。
NapCat config writer 同时生成默认文件与账号级文件。
o3HookMode=0 只能通过账号级灰度配置启用。
OneBot config 保持反向 WS 最小配置。
行为降噪测试覆盖图片/大消息限频、错误回复限频、冷启动低频、风险事件降载。
测试明确断言不存在账号级小时/日发送预算配置。

线上灰度

使用一个测试账号。
记录旧容器 profile evidence。
重建为 Linux Runtime Profile。
自检 Docker inspect 与容器内 runtime evidence。
登录或更新登录，必要时完成验证码/新设备验证。
执行手动命令、图片命令、自动回复、复读机 smoke。
若测试 o3HookMode=0，先只对该账号开启，记录 NapCat/QQNT 版本、收发结果和掉线情况。
观察至少一个业务窗口，再决定是否推广。

上线顺序

先只落 profile 生成、自检和只读展示。
对新建测试账号启用完整 runtime profile。
灰度 o3HookMode=0，仅测试账号。
验证登录与收发闭环。
观察稳定后再讨论现有账号 hostname/MAC 迁移。

参考来源

NapCat Docker README: https://github.com/NapNeko/NapCat-Docker/blob/main/README.md
NapCat Docker compose: https://github.com/NapNeko/NapCat-Docker/blob/main/compose/ws.yml
NapCat 安全相关: https://napneko.github.io/other/security
NapCat 基础配置: https://napneko.github.io/config/basic
NapCat 高级配置: https://napneko.github.io/config/advanced
Docker run: https://docs.docker.com/reference/cli/docker/container/run/
Docker networking: https://docs.docker.com/engine/network/
Docker macvlan: https://docs.docker.com/engine/network/drivers/macvlan/

16 KiB Raw Blame History Unescape Escape