部署 QQ 机器人：AstrBot + NapCat + （Dockge）

环境信息

组件简介

AstrBot

AstrBot 是一个 LLM 驱动的聊天机器人框架，内置大量插件，原生支持多种聊天平台。得益于其通用的消息平台适配器设计，同一套配置可以同时接入 QQ、微信官方机器人、Telegram 等多种渠道。

• 官方文档：https://docs.astrbot.app
• WebUI 端口：6185

NapCat

NapCat 是基于 NTQQ 的 OneBot v11 协议实现端，提供了完整的 QQ API 接口。AstrBot 不直接与 QQ 通信，而是通过 OneBot 协议连接 NapCat，由 NapCat 负责所有 QQ 消息的收发。

• 官方文档：https://napneko.github.io
• WebUI 端口：6099

Dockge（可选）

Dockge 是 Uptime Kuma 作者开发的轻量级 Docker Compose 可视化管理工具，适合管理以 compose.yaml 方式部署的容器堆栈。

• 官方文档：https://github.com/louislam/dockge
• WebUI 端口：5001

架构总览

部署链路：

Docker Engine → Docker Compose → AstrBot + NapCat（通过官方 astrbot.yml 一键启动）

容器通信：

AstrBot（:6185，AI 核心）← 反向 WebSocket → NapCat（:6099，QQ 适配器）→ 腾讯 QQ 服务器
AstrBot → DeepSeek API

两个容器通过 Docker Compose 自动加入同一自定义网络，NapCat 可以直接通过容器名 astrbot 连接 AstrBot，无需暴露额外端口到宿主机。

脚本说明

提供两个脚本，按需选用：

两个脚本遵循以下设计原则：

• 部署路径在脚本顶部变量区集中配置，修改一处即可
• 检测已安装组件自动跳过，适合中途失败后重跑
• 每步操作前询问确认，不会静默修改系统
• 自动识别 apt / dnf / yum / pacman / zypper，未识别的发行版使用 Docker 官方脚本兜底

以下教程以 standalone 版为例，完整版唯一的区别是多了一步 Dockge 部署。

部署步骤

第一步：上传脚本

scp deploy-astrbot-napcat-standalone.sh user@your-server:~/

第二步：执行脚本

sudo ./deploy-astrbot-napcat-standalone.sh

脚本会依次执行四个步骤：

1. 安装 Docker Engine（检测是否已安装，未安装则询问）
2. 检查 Docker Compose（不可用则安装）
3. 部署 AstrBot + NapCat（询问部署目录、下载官方 astrbot.yml、拉取镜像、启动容器）
4. 检查容器状态并输出配置指引

第三步：关键配置

脚本顶部变量区，如需修改直接编辑：

# 部署目录（sudo 运行时自动使用实际用户的 home，不会跑到 /root）
ASTROBOT_DIR="${HOME}/astrbot-deploy"

# 官方 astrbot.yml（来自 NapCat-Docker 仓库，已内置 AstrBot 和 NapCat 两个服务）
ASTROBOT_COMPOSE_URL="https://raw.githubusercontent.com/NapNeko/NapCat-Docker/main/compose/astrbot.yml"

Dockge 版的 astrbot 部署目录默认为 /opt/stacks/astrbot/，放在 Dockge 的堆栈目录下方便在 WebUI 中统一管理。

部署后配置

脚本执行完毕会自动输出详细指引，以下是各步骤的补充说明。

一、获取 NapCat Token 并扫码登录

docker logs napcat 2>&1 | grep -i 'token\|WebUiToken'

浏览器打开 http://服务器IP:6099/webui/，输入 Token，用机器人 QQ 号的手机 QQ 扫码登录。

注意：不要用常用大号跑机器人，建议使用有等级的老号。新号或异地登录极易触发腾讯风控。

二、NapCat 配置反向 WebSocket

NapCat WebUI → 网络配置 → 新建 → WebSocket 客户端：

三、登录 AstrBot WebUI

docker logs astrbot 2>&1 | grep -i password

浏览器打开 http://服务器IP:6185：

进入后：配置 → 机器人 → 创建 → 选择 OneBot v11 (QQ个人号)：

四、接入 DeepSeek

模型提供商 → 新增：

五、设置管理员

配置 → 其他配置 → 管理员 ID → 填写你自己的 QQ 号（非机器人 QQ 号）。

管理员可以在 QQ 聊天中直接向机器人发送管理指令。

防火墙端口

云服务器需要在安全组放行以下端口：

常用命令

# 进入部署目录
cd ~/astrbot-deploy

# 查看状态
sudo docker compose -f astrbot.yml ps

# 实时日志
sudo docker compose -f astrbot.yml logs -f

# 重启服务
sudo docker compose -f astrbot.yml restart

# 停止并删除容器
sudo docker compose -f astrbot.yml down

# 更新镜像
sudo docker compose -f astrbot.yml pull

# 重新启动
sudo docker compose -f astrbot.yml up -d

单独查看日志：

docker logs astrbot
docker logs napcat

Dockge 管理命令（仅完整版）：

cd /opt/dockge
sudo docker compose up -d
sudo docker compose down

常见问题

QQ 扫码登录后频繁掉线

检查 NapCat 容器的 MAC 地址是否固定。官方 astrbot.yml 已配置固定 MAC（02:42:ac:13:00:02），不要随意修改。
另外注意勾选快速登录，否则每次都需要扫码登录NapCat才会启用。

国内服务器拉取镜像失败

重跑脚本，在"是否使用国内镜像加速"步骤选 y，脚本会将镜像替换为 DaoCloud 代理。或手动配置 Docker 镜像加速器。

NapCat 已扫码但 AstrBot 收不到消息

1. 确认 NapCat 的反向 WebSocket 配置指向 ws://astrbot:6199/ws
2. 确认 AstrBot 的消息平台适配器已启用
3. 分别执行 docker logs astrbot 和 docker logs napcat 查看连接日志

重启后需要重新扫码吗

不需要。QQ 登录缓存已持久化到数据卷（napcat/qq 目录），重启容器不会丢失登录状态。

附件-脚本下载链接

deploy-astrbot-napcat-standalone.sh
deploy-astrbot-napcat.sh