手把手教你部署NapCat（含常见问题 + AstrBot 对接）
一、NapCat 是什么
NapCat（NapCatQQ）是一个基于 NTQQ（新版 QQ Windows/Linux 客户端）实现的 OneBot 11 协议框架。它通过 WebSocket / HTTP 等方式，把 QQ 消息转发给你的机器人框架（如 AstrBot、NoneBot、go-cqhttp 生态等），从而让你用自己的 QQ 号作为机器人运行。因为它不侵入 QQ 进程、不修改 QQ 文件，被封号风险相对较低。
二、最常用的三种部署方式
方式 1：Docker 部署（最推荐，适合服务器 / 无桌面环境）
这是最省心、隔离性最好的方式，适合 Linux VPS、NAS、宝塔面板等。
# 拉取镜像
docker pull mlikiowa/napcat-docker:latest
# 运行容器（4455 是 OneBot 正向 WebSocket 端口，6099 是 NapCat WebUI 端口）
docker run -d \
-e ACCOUNT=<你的QQ号> \
-e WS_ENABLE=true \
-e NAPCAT_UID=$(id -u) \
-e NAPCAT_GID=$(id -g) \
-p 4455:3001 \
-p 6099:6099 \
-v ./napcat:/app/napcat \
--name napcat \
--restart=always \
mlikiowa/napcat-docker:latest登录说明：启动后打开 http://服务器IP:6099，用手机 QQ 扫码登录即可。容器内生成的 WebUI 密钥会在日志里打印，首次登录需要输入。
环境变量参考（详见
https://github.com/NapNeko/NapCat-Docker ）：
ACCOUNT：要登录的 QQ 号
WS_ENABLE：开启正向 WebSocket（对接 AstrBot 必需）
NAPCAT_UID / NAPCAT_GID：以非 root 运行，避免文件权限问题
HTTP_ENABLE、HTTP_PORT：开启 HTTP 时使用
方式 2：Linux 无头（Headless）直接部署
不需要 Docker，直接把 NapCat 跑在服务器上，需要 Node.js 环境。
# 1. 准备 Node.js 18+ 环境
curl -fsSL https://deb.nodesource.com/setup_18.x | bash -
apt-get install -y nodejs
# 2. 获取 NapCat Linux 无头版本（到 Release 下载 zip）
wget https://github.com/NapNeko/NapCatQQ/releases/latest/download/NapCat.Shell.zip
unzip NapCat.Shell.zip -d NapCat
# 3. 启动（无头模式，用 QQ 扫码登录）
cd NapCat
sudo node ./main.mjs首次运行会用 WebUI 方式扫码。配置好 WebSocket 端口后，建议配合 pm2 守护进程：
npm install -g pm2
pm2 start "node ./main.mjs" --name napcat
pm2 save
pm2 startup三、常见问题解决
四、与 AstrBot 连接
AstrBot 是一个支持多平台的聊天机器人框架（支持 DeepSeek、OpenAI、MCP 等大模型后端）。
先装好 AstrBot（Docker 或 pip 安装均可，详见 AstrBot 官方文档）。
NapCat 端：确保已开启 正向 WebSocket（
WS_ENABLE=true），对外监听端口比如4455。登录成功后，NapCat 会在http://ip:4455提供 OneBot 11 的 WS 接口（/ws或类似路径）。AstrBot 端添加平台适配器：
打开 AstrBot 控制台 → 添加平台 → 选择 "OneBot 11"（内部是 aiocqhttp / astrbot-dashboard 适配器，参见 接入 OneBot v11 协议）。
连接方式选 反向 WebSocket（让 AstrBot 主动去连 NapCat），填入地址：
ws://127.0.0.1:4455（服务器部署时
127.0.0.1换成 NapCat 所在机器 IP）端口填
4455，保存并连接。
验证：AstrBot 状态显示"已连接"后，给自己的 QQ 机器人发消息，能收到 AI 回复即对接成功。
五、官方文档链接
NapCatQQ GitHub：
https://github.com/NapNeko/NapCatQQ NapCat 官方文档：
https://napneko.github.io/ NapCat-Docker：
https://github.com/NapNeko/NapCat-Docker AstrBot 官方文档：
https://docs.astrbot.app/ AstrBot 接入 OneBot v11 协议：
https://docs.astrbot.app/platform/aiocqhttp.html