Docker 部署 NapCat：轻松搭建 QQ Bot 协议端平台

共计 9268 个字符，预计需要花费 24 分钟才能阅读完成。

本文基于  mlikiowa/napcat-docker:v4.18.28，跟做引擎  NapCat v4.18.28，测试平台  Ubuntu 24.04 Linux。

群里要挂一个能收发消息的机器人：有人在 Windows 上解压 Shell 包、对齐 QQ 版本，升级一次就重来；有人把协议端和应用层糊在同一台开发机，调试日志、登录态、插件目录搅在一起。换 Linux 服务器后，无头环境、依赖和权限又要重踩一遍。

放到第三方托管 Bot，账号与群聊内容都出域；内网脚本、运维告警、知识库问答本来就不该默认经过公网中转。很多机房或 NAS 上已经有一台跑 Docker 的 Ubuntu，缺的是：协议端镜像能拉、登录态落本机、浏览器打开 WebUI 就能扫码，再把 OneBot 口交给应用框架或自己的脚本。

NapCat（GitHub · NapNeko/NapCatQQ、文档站 ）是基于  NTQQ  的 Bot  协议端 ：提供 WebUI 与 OneBot 标准接口，可对接  AstrBot、Koishi、NoneBot 等。本文跟做  mlikiowa/napcat-docker（ 镜像页、Docker 说明）：容器内 WebUI 6099，OneBot HTTP / WS 常见为  3000 / 3001；配置与 QQ 数据分别在  /app/napcat/config、/app/.config/QQ。

部署跑通之后，你实际能做这些事：

用  轩辕镜像  加速拉取  mlikiowa/napcat-docker:v4.18.28，Docker Compose  启动。把下文 IP、Token、QQ 号换成你的。无 Compose 见第七节。

上手要点

• 主路径：第四节 Compose；备选 docker run 见第七节
• 标签：跟做 v4.18.28；勿写 latest
• 挂载：./config→/app/napcat/config；./QQ→/app/.config/QQ；可选 ./plugins
• 端口：宿主机 13300→容器 3000；3001→3001；6099→6099（勿占宿主机 3000）
• 权限：NAPCAT_UID / NAPCAT_GID 用 $(id -u) / $(id -g)（root 时为 0/0）
• 两套口令：WEBUI_TOKEN 进管理面板；HTTP 服务端另设鉴权 Token（可与前者不同）
• 发消息：先在「网络配置」启用 HTTP 服务端，再对 13300 调接口（WebUI 不是聊天窗）
• 启动标志 ：NapCat.Core Version: 4.18.28、 网络已连接、出现二维码或 WebUI 地址
• 体积：DISK 2.12GB / CONTENT 597MB
• 目录：Linux /www/wwwroot/napcat；macOS ~/docker/napcat
• 合规：合法授权场景；建议小号；遵守当地法规与平台条款

官方：NapCatQQ · NapCat-Docker · 文档  ·  镜像页  ·  标签列表 · Docker Hub

一、mlikiowa/napcat-docker 是什么？

把 NapCat 打成可拉取镜像：协议端与 WebUI 跑在容器里，配置与 QQ 登录态挂到宿主机，对外提供 OneBot 端口。和本机 Shell / AppImage 比，更适合服务器、NAS 上「协议层单独常驻」。

脚本 / AstrBot / Koishi
        │  HTTP :13300 或 WS :3001
        ▼
NapCat v4.18.28 ── WebUI :6099/webui
        ├── /app/napcat/config  ← ./config
        └── /app/.config/QQ     ← ./QQ

Hub 上还有  napcat-framework-docker  等关联镜像；本文只跟做  mlikiowa/napcat-docker:v4.18.28。

二、环境要求

docker --version
docker compose version

Linux 未装 Docker 可使用轩辕镜像一键安装脚本：

bash <(wget -qO- https://get.xuanyuan.cloud/docker.sh)

备用地址：

bash <(wget -qO- https://get.xuanyuan.me/docker.sh)

更多见  轩辕镜像使用手册。

三、拉取镜像

3.1 标签怎么选

完整列表见  标签页。升级时改 Compose 标签，并对照  Releases。

3.2 用轩辕镜像加速拉取

docker pull docker.xuanyuan.run/mlikiowa/napcat-docker:v4.18.28

Ubuntu 24.04 实测：

v4.18.28: Pulling from mlikiowa/napcat-docker
44136fa355b3: Download complete
8c7fb09262c1: Pull complete
9b3a18efc3dd: Pull complete
7c1df3ed6d32: Pull complete
4748ab99dc9a: Pull complete
6414378b6477: Pull complete
018488390058: Pull complete
490f82e472ca: Pull complete
933fab068b12: Download complete
Digest: sha256:2cc70b45244ae3fabc657ffc3aaa4de8fb893518171e519659ab83d80e6d36b5
Status: Downloaded newer image for docker.xuanyuan.run/mlikiowa/napcat-docker:v4.18.28
docker.xuanyuan.run/mlikiowa/napcat-docker:v4.18.28

IMAGE                                                 ID             DISK USAGE   CONTENT SIZE
docker.xuanyuan.run/mlikiowa/napcat-docker:v4.18.28   2cc70b45244a       2.12GB          597MB

四、Docker Compose 部署（推荐）

4.1 准备目录

sudo mkdir -p /www/wwwroot/napcat/{config,QQ,plugins}
cd /www/wwwroot/napcat

macOS 跟做把路径换成  ~/docker/napcat。

export NAPCAT_UID=$(id -u)
export NAPCAT_GID=$(id -g)
echo "UID=$NAPCAT_UID GID=$NAPCAT_GID"

root 下常见  UID=0 GID=0，可继续；普通用户须保证对  config / QQ  可写。

4.2 写入 compose.yaml

把  WEBUI_TOKEN  换成你自己的强随机口令：

cd /www/wwwroot/napcat
cat > compose.yaml <<'EOF'
services:
  napcat:
    image: docker.xuanyuan.run/mlikiowa/napcat-docker:v4.18.28
    container_name: napcat
    restart: unless-stopped
    environment:
      - NAPCAT_UID=${NAPCAT_UID:-1000}
      - NAPCAT_GID=${NAPCAT_GID:-1000}
      - WEBUI_TOKEN=ChangeMeStrongToken
      - TZ=Asia/Shanghai
    ports:
      - "13300:3000"
      - "3001:3001"
      - "6099:6099"
    volumes:
      - ./config:/app/napcat/config
      - ./QQ:/app/.config/QQ
      - ./plugins:/app/napcat/plugins
EOF

官方另有  AstrBot、Koishi  等联合模板；本文先单独跑通协议端。

4.3 启动与扫码登录

cd /www/wwwroot/napcat
NAPCAT_UID=$(id -u) NAPCAT_GID=$(id -g) docker compose up -d
docker compose ps
docker compose logs -f --tail=80 napcat

Ubuntu 24.04 实测：

[+] up 2/2
 ✔ Network napcat_default Created
 ✔ Container napcat       Started

NAME      IMAGE                                                 COMMAND                SERVICE   CREATED         STATUS         PORTS
napcat    docker.xuanyuan.run/mlikiowa/napcat-docker:v4.18.28   "bash entrypoint.sh"   napcat    8 seconds ago   Up 6 seconds   0.0.0.0:3001->3001/tcp, 0.0.0.0:6099->6099/tcp, 0.0.0.0:13300->3000/tcp

日志关键行（Token 已脱敏；无头环境常见 dbus / EGL 报错可忽略）：

正在配置 WebUI Token...
NapCat Shell App Loading...
[NapCat] [Core] NapCat.Core Version: 4.18.28
[NapCat] [WebUi] WebUi Token: < 你的 WEBUI_TOKEN>
[NapCat] [WebUi] WebUi User Panel Url: http://0.0.0.0:6099/webui?token=< 你的 WEBUI_TOKEN>
等待网络连接...
网络已连接
没有 -q 指令指定快速登录，将使用二维码登录方式
请扫描下面的二维码，然后在手 Q 上授权登录：二维码已保存到 /app/napcat/cache/qrcode.png
[Core] [Login] 二维码已被扫描，等待确认...
[AdapterManager] OneBot11 适配器初始化完成
[AdapterManager] 协议适配器初始化完成，已加载 2 个适配器

控制台二维码不好扫时：

docker cp napcat:/app/napcat/cache/qrcode.png /tmp/napcat-qrcode.png

也可按日志里的解码 URL 在其它站点生成二维码（含登录凭证，勿外传）。Ctrl+C  只退出跟随日志，容器继续跑。

4.4 打开 WebUI

http:// 服务器 IP:6099/webui

或：

http:// 服务器 IP:6099/webui?token=ChangeMeStrongToken

用  WEBUI_TOKEN  进入面板。若 4.3 已扫码成功，打开后多半已在线；也可在  快速登录  里选已有 QQ，或改用扫码 / 密码登录：

基础信息  可核对 NapCat 4.18.28、QQ 版本、系统与当前网络配置数量：

侧栏  关于我们 、 插件商店 、 系统配置 → OneBot  可按需浏览（安装插件、调超时 / 代理等）；发消息与事件上报以第五节  网络配置  为准：

公网请限制  6099  来源或加反代 HTTPS；OneBot 口同样不要裸暴露。

五、发消息与事件上报

WebUI 管登录和网络，不是  QQ 聊天窗。主动发消息走 HTTP  服务端 ；要把群消息实时推给你自己的服务，再加 HTTP  客户端。

文档：WebUI 配置 · API 一览 · Apifox 用例

5.1 启用 HTTP 服务端

Compose 已映射  13300→3000，仍须在 WebUI 新建并启用 HTTP 服务器，接口才会监听。

1. 网络配置  →  新建 → HTTP 服务器

2. Host=0.0.0.0，Port=3000，消息格式可选 Array；打开 启用；公网务必填鉴权 Token

3. 保存 后列表出现已启用卡片；探测用 http:// 服务器 IP:13300（不是 6099）

5.2 用 curl 发私聊 / 群聊

在本机或能访问  13300  的机器上执行。未设 HTTP Token 时可先去掉  Authorization（仅限内网试通）。

# 私聊
curl -sS -X POST 'http://127.0.0.1:13300/send_private_msg' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer 你的 HTTP 鉴权 token' \
  -d '{"user_id": 好友 QQ 号,"message":" 你好，来自 NapCat"}'

# 群聊
curl -sS -X POST 'http://127.0.0.1:13300/send_group_msg' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer 你的 HTTP 鉴权 token' \
  -d '{"group_id": 群号,"message":" 大家好，来自 NapCat"}'

成功时一般返回  status: ok  与  message_id。也可先  get_friend_list / get_group_list  再发。连不上时查：服务端是否启用、端口是否为容器内  3000、Token 是否一致。

5.3 启用 HTTP 客户端（实时上报）

上报地址填接收方给的 URL（含密钥），不要 填  6099 / 13300，也 不要 填容器访问不到的  http://localhost:...。

1. 网络配置  →  新建 → HTTP 客户端

2. 启用；名称自定；URL 粘贴 webhook；消息格式 string 或 array；上报自身消息 关闭（防循环）

3. 保存后应同时看到服务端与客户端且均为启用；群里 @ 测一条，接收方再回调 13300 发回复即可

上报失败看 NapCat 日志（超时 / 4xx / 5xx）与容器出网；能收事件但不回复，查接收方是否调通了 5.1 的服务端。

5.4 对接应用框架（可选）

同 Compose 网络内用 服务名 互访，不要写宿主机映射口。模板见  NapCat-Docker/compose，接入说明见  接入框架。

六、升级与备份

跨大版本先读 changelog。WebUI 端口被占用时可能自动 +1，以日志为准。

七、备选：docker run

mkdir -p /www/wwwroot/napcat/{config,QQ,plugins}

docker run -d \
  --name napcat \
  --restart unless-stopped \
  -e NAPCAT_UID=$(id -u) \
  -e NAPCAT_GID=$(id -g) \
  -e WEBUI_TOKEN=ChangeMeStrongToken \
  -e TZ=Asia/Shanghai \
  -p 13300:3000 \
  -p 3001:3001 \
  -p 6099:6099 \
  -v /www/wwwroot/napcat/config:/app/napcat/config \
  -v /www/wwwroot/napcat/QQ:/app/.config/QQ \
  -v /www/wwwroot/napcat/plugins:/app/napcat/plugins \
  docker.xuanyuan.run/mlikiowa/napcat-docker:v4.18.28

docker logs -f --tail=80 napcat

长期运行仍用第四节 Compose。

八、常见问题

Q：该用哪个版本？
A：跟做  v4.18.28，不要写  latest。

Q：为什么宿主机不用 3000？
A：本系列避开宿主机  3000。容器内仍是 3000，对外  13300:3000。

Q：WebUI Token 和 HTTP Token 一样吗？
A：不必相同。前者是  WEBUI_TOKEN（进面板）；后者在 HTTP 服务器配置里填，给  Authorization: Bearer …  用。

Q：登录后怎么在 WebUI 里点开发消息？
A：没有聊天窗。启用 HTTP 服务端后用 5.2 的  curl，或接 AstrBot 等框架。

Q：HTTP 客户端 URL 填什么？
A：接收方 webhook 完整地址，不是  6099 / 13300。详见 5.3。

Q：curl 13300 失败？
A：HTTP 服务器是否启用、容器端口是否  3000、Token 是否一致；别拿 6099 当 API 口。

Q：日志里 dbus / EGL / GPU 报错？
A：无头容器常见，不影响 Core 启动与扫码，可忽略。

Q：控制台二维码扫不上？
A：docker cp napcat:/app/napcat/cache/qrcode.png /tmp/napcat-qrcode.png，或用日志解码 URL（勿外传）。

Q：permission denied？
A：核对  NAPCAT_UID / NAPCAT_GID。群晖等 NAS 还可能要在文件管理器里给挂载目录授读写。

Q：6099 / 13300 能对公网裸开吗？
A：不建议。强 Token + 来源限制或 HTTPS 反代。

Q：合规吗？
A：仅用于合法、授权场景；建议小号；遵守当地法规与平台条款。

九、命令速查

docker pull docker.xuanyuan.run/mlikiowa/napcat-docker:v4.18.28

sudo mkdir -p /www/wwwroot/napcat/{config,QQ,plugins}
cd /www/wwwroot/napcat
# 先写入第四节 compose.yaml
export NAPCAT_UID=$(id -u) NAPCAT_GID=$(id -g)
docker compose up -d
docker compose ps
docker compose logs -f napcat

curl -sS -X POST 'http://127.0.0.1:13300/send_private_msg' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer 你的 HTTP 鉴权 token' \
  -d '{"user_id": 好友 QQ 号,"message":" 你好 "}'
curl -sS -X POST 'http://127.0.0.1:13300/send_group_msg' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer 你的 HTTP 鉴权 token' \
  -d '{"group_id": 群号,"message":" 大家好 "}'

docker compose down

验证：WebUI :6099/webui · API :13300 · 标签  v4.18.28

十、延伸阅读

总结

• 跟做 v4.18.28，挂载 config / QQ，映射 13300 / 3001 / 6099。
• Compose 启动 → 日志扫码 → WebUI 用 WEBUI_TOKEN 管理。
• 发消息：启用 HTTP 服务端 → 13300 调 OneBot；实时事件再加 HTTP 客户端 webhook。
• 6099 与 OneBot 口勿裸暴露公网；合法合规使用。

阅读原文

• 轩辕镜像官方博客：https://xuanyuan.cloud/blog/docker-napcat-qq-bot-deploy