机器人突然不回消息了，这是最常见的故障。很多人第一反应是重启容器，但重启往往解决不了 —— 因为问题可能根本不在容器上。

这篇按「从外到内」的顺序，把 OneBot WS 连不上的原因拆成 6 种，每种都给出判断方法和处理方案。

先分清两件事：端口在听不等于服务可用

这是最容易误判的地方。你在服务器上执行：

ss -lntp | grep 3001

看到 docker-proxy 在监听 *:3001，会以为服务正常。但从外面连，就是连不上。

原因是：docker-proxy 只负责把流量转发给容器，它不管你容器里的服务是否真的起来了。NapCat 的 OneBot WS 只有在 QQ 登录成功之后才会真正启动，没登录时端口转发还在，但后端是空的。

判断方法：

# 在服务器本机测，绕开所有网络层
curl -m 3 -o /dev/null -w "%{http_code}n" http://127.0.0.1:3001

• 返回 400 或 426：服务在，正常（只是 HTTP 握手不对，WS 本身是好的）
• 返回 000：连接失败，容器里根本没有服务在听

原因 1：QQ 根本没登录（最常见）

症状：WebUI（6099 端口）能打开，但 3001 怎么都连不上。

判断依据：WebUI 是框架启动就开的，不依赖 QQ 登录；OneBot WS 必须等 QQ 登录成功才启动。所以「WebUI 通 + WS 不通」基本可以断定是 QQ 掉线。

处理：打开 WebUI 看 QQ 状态。如果是未登录，用「快速登录」选历史账号，或者扫码。

扫码要节制。频繁扫码是 QQ 风控最敏感的行为，能快速登录就不要扫码。

原因 2：重启服务器后 QQ 没有自动登录

容器有 --restart=always 会自动拉起，但「容器起来」和「QQ 自动登录」是两件事。

如果登录态文件没持久化（没挂载 /app/.config/QQ），每次重启都要重新登录。

检查是否挂载了：

docker inspect napcat --format '{{range .Mounts}}{{.Source}} -> {{.Destination}}{{"n"}}{{end}}'

如果只看到 config 目录，没有 QQ 数据目录，迟早要踩这个坑。

原因 3：WebUI token 对不上

很多人凭记忆填 token，结果死活登不进去。token 的正确来源只有一处：

docker logs napcat 2>&1 | grep -i "webui token"

另外注意：新版 NapCat 的 WebUI 登录接口有变化，用 curl 直接 POST /api/auth/login 可能返回 token is empty，但用浏览器访问 /webui?token=xxx 是能进去的。所以排查时优先用浏览器，别跟 API 较劲。

原因 4：容器内存不足被 OOM 杀掉

小内存服务器（1G / 2G）很容易遇到。NapCat 跑久了内存会涨，超过宿主机的可用内存加 swap，内核会直接干掉它。

判断方法：

# 看容器被重启过几次
docker inspect napcat --format '{{.RestartCount}}'

# 看内核日志有没有 OOM 记录
dmesg | grep -i "killed process" | tail -5

处理：给容器加内存上限，让它自己先崩，而不是拖垮整台服务器：

docker update --memory 400m --memory-swap 600m napcat

原因 5：安全组或防火墙没放行

如果服务器本机 curl 127.0.0.1 是通的，但从外面连不上，就是这一层的问题。

检查顺序：

1. 云厂商安全组有没有放行这个端口
2. 系统防火墙（firewalld / iptables）
3. 如果装了宝塔，面板里还有一个独立的「系统防火墙」

原因 6：容器重建后配置丢了

有些人为了加参数，直接 docker rm 再 docker run，结果把挂载漏了。重建前一定要先导出原配置：

docker inspect napcat --format 'PORTS={{json .HostConfig.PortBindings}}'
docker inspect napcat --format 'MOUNTS={{range .Mounts}}{{.Source}}:{{.Destination}} {{end}}'
docker inspect napcat --format 'IMAGE={{.Config.Image}}'

照着原配置重建，只改你要改的那一项。

排查顺序总结

1. WebUI 能打开吗？
   ├─ 不能 → 容器没起来，看 docker ps / docker logs
   └─ 能 → 进 WebUI 看 QQ 在线吗？
        ├─ 不在线 → 登录 QQ（原因 1 / 2）
        └─ 在线 → 本机 curl 127.0.0.1:3001
             ├─ 000    → 服务没起，看重启日志
             └─ 400/426 → 服务正常，往外查安全组（原因 5）

应急恢复丙步

如果一时判断不出来，按这个顺序试，大多数情况能恢复：

1. WebUI 看 QQ 状态，未登录就快速登录
2. 已登录但 WS 不通，执行 docker restart napcat
3. 重启后还不通，docker logs --tail 50 napcat 看启动报错

相关文章

• 还没搭起来 →《QQ AI 机器人搭建教程：NapCat + OneBot 完整部署指南》
• 想长期跑稳 →《QQ 机器人长期稳定运行：内存、日志与风控的 7 条实战经验》