# 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 访问与网络运维复杂度。

## 目标

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

## 非目标

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

## 方案总览

本轮采用安全增量方案：

```text
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 分为三层：

1. **设备身份层**：账号稳定的 dataDir、hostname、MAC、machine-id。
2. **Linux runtime 层**：镜像、UID/GID、shm、init、locale、XDG、持久目录、日志目录。
3. **协议风险层**：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` 作为增强项。

### 持久目录

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

```text
$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。

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

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

## Protocol Risk Profile

### NapCat 配置统一生成

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

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

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

### NapCat 协议配置

默认 profile：

```json
{
  "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。
- 命令冷却。
- 规则冷却。
- 复读机阈值、短文本限制、同会话最小间隔。

### 新增降噪策略

1. **图片与大消息限频**
   - 图片、大 CQ 消息、长文本回复使用独立最小间隔。
   - BangDream 等图片命令不能在同一会话连续快速刷图。

2. **错误回复限频**
   - 同一命令、同一会话、同一错误摘要在短窗口内只回复一次。
   - 后续错误只写日志，不继续刷屏。

3. **冷启动低频窗口**
   - 刚登录成功后进入短时间低频模式。
   - 完成验证码或新设备验证后进入低频模式。
   - 低频模式限制自动回复、复读机、事件插件主动回复；手动命令仍允许但走正常实时节流。

4. **风险事件降载**
   - 出现 `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 最小配置。
- 行为降噪测试覆盖图片/大消息限频、错误回复限频、冷启动低频、风险事件降载。
- 测试明确断言不存在账号级小时/日发送预算配置。

### 线上灰度

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

## 上线顺序

1. 先只落 profile 生成、自检和只读展示。
2. 对新建测试账号启用完整 runtime profile。
3. 灰度 `o3HookMode=0`，仅测试账号。
4. 验证登录与收发闭环。
5. 观察稳定后再讨论现有账号 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/