1. 写在前面：NapCatQQ 是什么

NapCatQQ 是一个基于 NTQQ 协议实现的 QQ 机器人框架，通常以「无头模式」运行 QQ 客户端，再通过 OneBot 11 标准协议对外提供 HTTP / WebSocket 接口，从而让 NoneBot2、Koishi、云崽等机器人框架能够接入 QQ。

它的优势很直接：

• 不需要图形界面，可以在 Linux 服务器上跑；
• 兼容 OneBot 11，生态里的插件基本可以直接复用；
• 支持扫码登录、快速登录，部署成本相对较低。

但它本质上仍然是「把官方客户端跑起来再挂协议」，所以很多坑并不是 NapCatQQ 本身的 Bug，而是账号风控、协议限制、环境依赖带来的。下面按「部署前 → 部署中 → 运行中 → 出问题怎么排查」的顺序整理。

2. 部署前的建议

2.1 账号选择：强烈建议用小号

这是最重要的一条，没有之一。

• 不要用主号。任何第三方协议登录都存在被风控、被限制登录甚至封号的可能，主号一旦出事，好友、群、聊天记录、绑定的各种服务都会受影响。
• 建议专门注册一个小号，并且提前养号：正常登录几天、加几个群、发几条消息，让账号有正常的活跃轨迹，比刚注册就挂机器人稳得多。
• 小号也建议绑定手机号并开启必要的安全设置，避免异地登录时直接被锁。

2.2 环境选择：优先 Linux + Docker

• 官方推荐使用 Docker 部署，镜像里已经把 QQ 客户端依赖打包好了，能省掉大量「缺库、缺字体、缺中文字体导致界面乱码」的问题。
• 如果不用 Docker，Linux 下需要自己补齐依赖（如 xvfb、字体、libnss3 等），Windows 下则要注意路径和权限问题。
• 服务器配置不用太高，1 核 2G 通常够用，但磁盘要留够，QQ 客户端会缓存大量图片和文件。

2.3 网络与端口规划

• NapCatQQ 默认会监听 WebSocket / HTTP 端口，务必确认防火墙、安全组已放行，或者只监听 127.0.0.1 由反向代理转发。
• 不要把管理端口直接暴露在公网。WebUI 和 OneBot 接口如果没有鉴权，等于把机器人交给别人控制。

3. 部署过程中的注意事项

3.1 登录方式的选择

NapCatQQ 常见有两种登录方式：

方式	说明	适用场景
扫码登录	启动后输出二维码，手机 QQ 扫码	首次登录、换设备
快速登录	复用已保存的登录态	重启后免扫码

建议：

• 首次部署用扫码登录，登录成功后及时保存数据目录（Docker 下通常是挂载出来的 napcat 数据卷），否则容器重建就要重新扫码。
• 快速登录依赖本地缓存的 token，换机器、换 IP、清空数据目录都会失效，不要以为配置一次就永久有效。

3.2 数据持久化一定要做

Docker 部署时最常见的翻车就是「容器删了，登录态没了」。务必把数据目录挂载到宿主机：

docker run -d \
  --name napcat \
  -p 3000:3000 \
  -p 3001:3001 \
  -v /opt/napcat/config:/app/napcat/config \
  -v /opt/napcat/qq:/app/.config/QQ \
  --restart unless-stopped \
  mlikiowa/napcat-docker:latest

具体路径以你使用的镜像文档为准，但核心原则是：配置和 QQ 登录数据都要落在宿主机上。

3.3 配置文件的坑

• OneBot 的 ws / http 配置项写错一个字段，机器人就是连不上，而且日志里往往只报「连接失败」，不会告诉你具体哪个字段错了。建议先用最小配置跑通，再逐项加。
• access_token 建议设置，并且和机器人框架侧保持一致，否则会出现「能连上但收不到消息」的诡异现象。
• 修改配置后记得重启 NapCatQQ，部分配置不支持热加载。

4. 运行中容易踩的坑

4.1 消息发不出去 / 被风控

这是最高频的问题，典型表现：

• 私聊能发，群聊发不出去；
• 发文字正常，发图片或链接被拦截；
• 突然所有消息都失败，日志提示风控相关错误。

应对思路：

• 降低发送频率。短时间内大量群发、@全体、发链接，是最容易触发风控的行为。
• 新号、异地登录的号风控阈值更低，前期尽量少做敏感操作。
• 图片、文件建议走本地缓存或对象存储，避免频繁拉取外链。
• 如果已经被限制，通常只能等（几小时到几天不等），期间不要反复重试，越试越严重。

4.2 掉线后不自动重连

• 网络抖动、服务器重启、QQ 客户端崩溃都可能导致掉线。
• 建议用 --restart unless-stopped 让容器自动拉起，同时在机器人框架侧做好「连接断开 → 重连」的逻辑。
• 但要注意：频繁重启登录可能触发风控，重连策略要有退避，不要一秒重试一次。

4.3 群消息收不到 / 只收到部分消息

常见原因：

• 机器人账号没有加入该群，或者被禁言；
• 群设置了「不允许机器人发言」或开启了严格的群管理；
• OneBot 配置里消息上报类型没开全（比如只开了私聊没开群聊）；
• 消息被框架侧的事件过滤器过滤掉了，先看框架日志而不是怀疑 NapCatQQ。

4.4 图片、语音、文件相关

• 收到的图片通常是 URL 或本地缓存路径，URL 有时效性，需要及时下载转存，否则过一段时间就 404。
• 发送本地图片时注意路径是容器内路径，宿主机路径不挂载进去是读不到的。
• 语音、视频等富媒体消息格式较复杂，不同框架的解析实现有差异，遇到解析异常先确认框架版本。

4.5 多账号 / 多实例

• 同一台机器跑多个 NapCatQQ 实例时，端口和数据目录必须完全隔离，否则会互相覆盖登录态。
• 多实例对服务器资源消耗是叠加的，注意内存和磁盘。

5. 安全与合规提醒

• 不要用机器人做违规内容分发，包括但不限于广告群发、涉黄涉政、诈骗引流，这类行为不仅封号，还可能涉及法律责任。
• 机器人账号的权限要最小化，不要给它管理员权限去操作群。
• WebUI 和接口务必加鉴权，公网暴露的机器人接口很容易被扫描到并滥用。
• 遵守 QQ 的用户协议和所在平台的规定，第三方协议登录本身存在风险，请自行评估。

6. 排查问题的通用思路

遇到问题时，按这个顺序排查，能省很多时间：

几个实用建议：

• 先看日志。NapCatQQ 和机器人框架的日志都要看，很多问题日志里其实写得很清楚。
• 最小化复现。把配置精简到最小可运行状态，再逐步加回，能快速定位是哪个配置项的问题。
• 保留现场。出问题时先备份数据目录和日志，再折腾，避免越修越乱。
• 关注版本。NapCatQQ 更新较频繁，升级前先看更新说明，重大版本变更可能改配置格式。

7. 小结

NapCatQQ 用起来门槛不高，但「能跑起来」和「稳定跑下去」是两回事。把下面几条记住，能避开大部分坑：

1. 用小号，别用主号；
2. 优先 Docker 部署，数据目录必须持久化；
3. 控制发送频率，别做敏感操作；
4. 接口加鉴权，别裸奔在公网；
5. 出问题先看日志，最小化复现。

剩下的就是耐心和一点点运维经验了。祝你的机器人稳定在线。