NapCat 一键部署包（QQ 桥接 · distrobox 容器版）

在全新的 distrobox Fedora 容器（内已装官方 LinuxQQ）里一键部署
NapCat，并通过 OneBot11 协议
（WebSocket + HTTP）为 harbour-qqcat 等 QQ 桥接类 App 提供后端。

本包是实战踩坑的结晶：今天在新机部署时遇到的每一个问题，
都已变成脚本里的自动防护。目标——一条命令，扫一次码，一次跑通。

包内文件

文件用途napcat-deploy.sh⭐ 一键部署主脚本（装依赖/下载/注入/预写配置/扫码/验证一条龙）napcat-status.sh部署后/日常自检：进程、三端口、在线状态、花名册API、token、最近错误harbour-qqcat-1.0.0-1.aarch64.rpmQQ 桥接 App 安装包（宿主机安装：zypper in ./xxx.rpm 或 pkcon）README.md本文档

App 安装：devel-su zypper in ./harbour-qqcat-1.0.0-1.aarch64.rpm

前端：https://openrepos.net/sites/default/files/packages/19652/harbour-qqcat-1...

后端（参考快速开始宿主装，单独下载后先改名为new-deployment-qqcat.tar.gz然后解压，把两个sh文件放宿主）：https://openrepos.net/sites/default/files/packages/19652/new-deployment-...

（依赖容器里已部署好的 NapCat，先跑 napcat-deploy.sh 再装 App 体验最佳）

环境要求

• 宿主机：SailfishOS 或其它带 distrobox 的 Linux
• 容器：Fedora（distrobox 创建），已安装官方 LinuxQQ（/opt/QQ/qq 存在）
• 容器内 defaultuser 可免密 sudo（distrobox 默认配置即可）
• 手机 QQ 登录着机器人要用的那个 QQ 号（用来扫码授权）

快速开始

# 0. 把本目录整个拷到新机宿主，比如 ~/new-deployment-qqcat/

# 1. 容器没起来的话先拉一下
distrobox enter fedora44 -- true

# 2. 一键部署（QQ号换成你自己的）
cd ~/new-deployment-qqcat
bash napcat-deploy.sh <你的QQ号>

# 3. 按提示用手机 QQ 扫描 ~/napcat-qrcode.png 并点授权确认

# 4. 自检
bash napcat-status.sh

看到 ✓ 登录成功！ 和最终摘要里的三个 ✓ 即为成功。

napcat-deploy.sh 参数

bash napcat-deploy.sh <QQ号> [容器名] [GitHub代理] [--install-service]

参数说明默认<QQ号>必填。机器人账号；提前写好 OneBot 配置用的—[容器名]distrobox 容器名fedora44[代理]GitHub 下载代理，如 http://<代理IP>:<端口>直连--install-service同时安装 systemd 用户服务实现开机自启不装

环境变量：NAPCAT_CONTAINER / NAPCAT_PROXY / NAPCAT_VERSION（默认锁定
v4.18.19，可设 latest 或任意 tag）/ NAPCAT_QR_OUT（二维码落盘路径）。

脚本会自动做的事

1. 检查容器内 QQ、sudo 免密、安装 unzip/Xvfb
2. 彻底清场（含僵尸实例），校验 REMAIN=0
3. 下载 NapCat.Shell.zip（复用容器内已有完整 zip；直连失败可用代理）
4. 备份原始 package.json → .orig，解压注入，改 "main": "./napcat.mjs"
5. 把 OneBot11 配置同时写入两处生效路径：
   • ~/.config/QQ/NapCat/config/onebot11_<QQ号>.json
   • /opt/QQ/resources/app/config/onebot11_<QQ号>.json
     两处都含 WebSocket(:3001) 和 HttpApi(:3000) —— 缺一不可
6. 启动（固定 xvfb 显示号 :88，保持设备指纹稳定不掉登录），同步二维码到宿主
7. 轮询日志等登录成功；若检测到"账号已在其他设备登录"会给精确处置指引
8. 验证 :3001 监听 → 设置 autoLoginAccount → 打印 WebUI token 与桥接三项

部署完成后：桥接 App 配置

harbour-qqcat 设置页填三项（脚本结束时也会打印）：

wsUrl      = ws://127.0.0.1:3001
webuiBase  = http://127.0.0.1:6099
webuiToken = <脚本打印的 token>

token 由 NapCat 首次启动随机生成，存放在容器内
/opt/QQ/resources/app/config/webui.json。
认准这份！容器里可能有别的旧副本，别抄错。

状态自检

bash napcat-status.sh            # 默认容器
bash napcat-status.sh mycontainer

逐项输出进程实例数、三端口、get_status 在线状态、花名册 API 实测、token、最近错误行。

正常标准：实例 1 个；三端口全监听；online: true；HTTP 返回好友数据。

常见问题排查（症状 → 原因 → 解决）

① app 显示「WebUI auth failed / 授权失败」

• 原因：app 里填的 token 与运行实例不一致（最常见：抄了旧配置目录的死值）
• 解决：bash napcat-status.sh 看"WebUI token"一行，填它

② 日志出现「当前账号已登录,无法重复登录」

• 原因：另一台设备（旧机 NapCat / 其它桌面端）持有该号的 PC 会话；
  或同容器有多个 QQ 实例互抢
• 解决：停掉其它设备（旧机：systemctl --user stop napcat），
  确认 napcat-status.sh 显示实例只有 1 个，重跑 deploy 脚本

③ 快速登录报「登录需要手Q验证」

• 原因：新设备风控，腾讯要求手机 QQ 授权
• 解决：手机 QQ 上弹出的确认框点同意即可完成登录；
  若没弹窗或过期，按二维码重新扫一次
• 根治：启动命令给 qq 加环境变量（见下文"免验证重启"）

④ WS 正常、消息能收，但 app 花名册一直转圈 / 卡 starting bridge

• 原因：HttpApi(:3000) 没配！花名册走的是 HTTP 而不是 WebSocket
• 解决：检查两处 onebot11 配置里是否有 httpServers(端口3000)，
  补上后重启 QQ。v2 脚本的 seedcfg 已自带，理论上不会再遇到

⑤ :3001 在监听但 get_status 无响应

• 原因：OneBot 配置被 NapCat 规范化覆盖成空服务列表
• 解决：把 websocketServers/httpServers 合并回
  /opt/QQ/resources/app/config/onebot11_<QQ号>.json 后重启

⑥ 二维码扫了没反应 / 提示过期

• 二维码约 2 分钟自动刷新，~/napcat-qrcode.png 会持续更新，关掉图片重开再扫
• 扫码后注意手机上的授权确认弹窗，必须点同意

⑦ 下载 NapCat.Shell.zip 失败

• 直连 GitHub 超时属正常，传代理参数：bash napcat-deploy.sh <QQ号> fedora44 http://IP:7897
• 或手动下载 zip 放到容器 /tmp/NapCat.Shell.zip，脚本检测到完整 zip 会直接复用

容器内文件位置速查

文件说明/opt/QQ/resources/app/package.json.orig原始 QQ 入口备份（卸载还原用）/opt/QQ/resources/app/package.json已改为 "main": "./napcat.mjs"/opt/QQ/resources/app/napcat/ + napcat.mjsNapCat 本体/opt/QQ/resources/app/config/webui.json⭐ 生效的 WebUI 配置（token在这）/opt/QQ/resources/app/config/onebot11_<uin>.json⭐ 生效的 OneBot 配置~/.config/QQ/NapCat/config/onebot11_<uin>.json同内容备份路径/tmp/napcat.log运行日志

开机自启

bash napcat-deploy.sh <QQ号> fedora44 "" --install-service

生成 ~/.config/systemd/user/napcat.service：启动前自动清场防 crash-loop，
固定显示号 :88 保持设备指纹。管理命令：

systemctl --user status napcat
systemctl --user restart napcat
systemctl --user disable napcat   # 多台设备二选一时，停用方务必 disable

免验证重启（可选加固）

新设备频繁重启会反复触发手Q验证。设置密码快速登录可跳过：

编辑 service 的 ExecStart，在 qq 前加：

env ACCOUNT=<QQ号> NAPCAT_QUICK_PASSWORD=你的QQ密码

⚠️ 密码写在本机 service 文件里即可，不要提交到仓库或发给别人。

卸载 / 回滚

# 进容器执行
distrobox enter fedora44
cd /opt/QQ/resources/app
pkill -9 -f '/opt/QQ'                    # 停 QQ
cp package.json.orig package.json        # 还原入口
rm -rf napcat napcat.mjs loadNapCat.js   # 移除 NapCat
# config/ 下 onebot11_*.json webui.json 可一并删除

宿主机卸载自启：systemctl --user disable --now napcat && rm ~/.config/systemd/user/napcat.service

安全提醒

• WebUI(6099) 监听所有网卡，不要暴露到公网；token 泄露就改 webui.json 重启
• 多台设备不可同时跑同一账号的 NapCat（互踢）；迁移时先停旧机再上新机
• 分发本包前可用 grep -nE '<你的QQ号>|token值' * 自查一遍隐私

版本

• napcat-deploy.sh v2（2026-08-25）：吸收新机实战全部坑位
  • 双路径预写 OneBot 配置（含 HttpApi:3000，修"花名册卡住"）
  • 文件式清场杜绝 pkill 自匹配僵尸实例
  • token 只认运行实例；三级下载回退 + zip 缓存；幂等重跑