AstrBot + NapCat：用 Docker 搭一个 QQ 机器人

本文属于「自托管 Docker 部署实战」系列（共 35 篇），第 14 篇。示例中的 IP（192.0.2.10）、域名（example.com）、密码均为占位符，请按实际环境替换。

它是什么

NapCat：基于 NTQQ 的 OneBot v11 协议端，负责登录 QQ、收发消息；
AstrBot：LLM 聊天机器人框架，内置 WebUI、插件市场、多平台适配器；
两者通过 OneBot v11 反向 WebSocket 连接：NapCat 主动连 AstrBot 的 6199 端口。

前置条件

一台 Linux 服务器（1C1G 起步；Java 类应用建议 2C4G 以上）；
已安装 Docker 与 Compose v2，执行 docker compose version 有版本号输出；
所有示例里的 IP / 域名 / 密码都是占位符，实际部署请替换成自己的。

# 安装 Docker（已安装可跳过）
curl -fsSL https://get.docker.com | sh

# 目录约定：一个服务一个目录，后文的 ./data 均指栈目录内
mkdir -p /srv/docker/active/<stack> && cd /srv/docker/active/<stack>

镜像地址

soulter/astrbot:v4.28.0
mlikiowa/napcat-docker:latest

目录结构

/srv/docker/active/qqbot/
├── docker-compose.yml
├── astrbot/data/                    # AstrBot 数据（配置、插件、聊天库）
└── napcat/
    ├── config/                      # NapCat 配置（账号、OneBot 设置）
    └── ntqq/                        # QQ 客户端数据

部署步骤

# docker-compose.yml
services:
  astrbot:
    image: soulter/astrbot:v4.28.0
    container_name: astrbot
    restart: always
    environment:
      - TZ=Asia/Shanghai
    ports:
      - "6185:6185"      # WebUI
      - "6199:6199"      # OneBot v11 反向 WS
    volumes:
      - ./astrbot/data:/AstrBot/data

  napcat:
    image: mlikiowa/napcat-docker:latest
    container_name: napcat
    restart: always
    network_mode: host          # 协议端建议 host 网络
    privileged: true
    environment:
      - TZ=Asia/Shanghai
      - NAPCAT_UID=0
      - NAPCAT_GID=0
    volumes:
      - ./napcat/config:/app/napcat/config
      - ./napcat/ntqq:/app/.config/QQ

docker compose up -d
docker compose logs -f astrbot      # 等 WebUI 起来

浏览器打开 http://<SERVER_IP>:6185 初始化 AstrBot；
NapCat WebUI（默认 6099，host 网络下直接访问 http://<SERVER_IP>:6099）扫码登录 QQ；
NapCat 里新建 WebSocket 客户端，地址填：

text ws://<SERVER_IP>:6199/ws

Token 留空或与 AstrBot 适配器里一致； 4. AstrBot 的「消息平台」里启用 aiocqhttp / OneBot v11 适配器，监听 6199； 5. 控制台看到「适配器已连接」即成功。

关键配置

6199 是反向 WS 端口，不是 HTTP 端口，别用浏览器直接访问；
NapCat 与 AstrBot 如果都跑 bridge 网络，也可以直接连 ws://astrbot:6199/ws，省掉主机 IP；
协议端登录的是真实 QQ 号，建议用小号，并在 NapCat 配置里限制可使用的群/好友。

注意事项

风控：新号、频繁操作、异地 IP 都可能触发冻结，登录后先养号；
数据备份：AstrBot 的 data/ 是核心，data/plugins/*/data 里往往还有聊天存档插件的大缓存（缓存目录不要跟着一起备份）；
权限：privileged: true 是为了 NapCat 能操作 QQ 客户端，等于把容器提升到接近 root，务必只在内网跑；
时区：不设 TZ 时消息时间会差 8 小时；
升级：AstrBot 版本跨度大时先备份 data/ 再拉新镜像，部分插件需要跟随升级。

备份与升级

# 备份：AstrBot 数据 + NapCat 账号配置
tar czf "backup-$(date +%F).tar.gz" ./astrbot ./napcat

# 升级
docker compose pull
docker compose up -d
docker compose logs --tail=100 astrbot

AstrBot 的插件与聊天库都在 astrbot/data，升级前必须先备份；
NapCat 的 ntqq/ 是登录态，换机迁移一起带走可免扫码（不要外传）。