Ubuntu系统Docker部署AstrBot和NapCat

前言

在 AI 技术快速发展的今天，聊天机器人已经成为了许多场景下的重要工具。AstrBot 作为一个多平台大模型机器人基础设施，配合 NapCat 这个基于无头 QQNT 的 OneBot 协议实现端，可以让我们轻松构建一个功能强大的 QQ 聊天机器人。本教程将详细介绍如何在 Ubuntu 系统上使用 Docker 部署这两个组件。

点击查看最终效果展示
![效果展示](https://imgbed.astrasolis.top/file/blog/1763310969706_Ubuntu-AstrBot-Tutorial.png)

什么是 AstrBot？

AstrBot 是一个易于上手的多平台聊天机器人及开发框架，具有以下特点：

核心特性

多平台支持：同时支持 QQ、微信、Telegram、飞书、钉钉等多种消息平台

易于上手：支持 Docker、Windows 一键安装器等多种部署方式

高扩展性：基于事件总线和流水线的架构设计，完全模块化

大语言模型集成：支持 OpenAI、Anthropic、DeepSeek、智谱 AI 等多个模型提供商

主要功能

快速构建、部署和管理跨平台的智能聊天机器人

内置 AI 知识库能力，免除繁杂部署

支持基于 Docker 的沙箱化代码执行器

让大模型接入互联网进行网页搜索

什么是 NapCat？

NapCat（NapCatQQ）是基于无头 QQNT 的 OneBot 协议实现端，它本质上运行了一个 QQNT 实例，为 QQ 机器人开发提供了稳定的协议支持。

NapCat 特点

稳定可靠：基于官方 QQ 客户端，稳定性更好

功能完整：支持文字、图片、语音、文件等多种消息类型

易于部署：提供 Docker、一键脚本等多种部署方式

Web 管理界面：提供直观的 Web UI 进行配置和管理

系统要求

在开始部署之前，请确保你的 Ubuntu 系统满足以下要求：

Ubuntu 18.04 或更高版本

至少 2GB RAM

至少 10GB 可用磁盘空间

稳定的网络连接

一个 QQ 号（建议不是新创建的 QQ 号）

一台具有摄像功能的手机用于扫码登录

准备工作

更新系统

首先更新 Ubuntu 系统到最新状态：

Copy
sudo apt update && sudo apt upgrade -y

注意：本教程假设你已经安装了 Docker 和 Docker Compose。如果尚未安装，请参考 Docker 官方文档进行安装。

配置防火墙端口

在部署之前，需要确保相关端口能够正常访问。根据服务器类型选择对应的配置方法：

国外服务器（如 AWS、DigitalOcean、Vultr 等）

国外服务器通常使用 UFW（Uncomplicated Firewall）进行防火墙管理，但Ubuntu 系统默认 UFW 是关闭状态：

Copy
# 首先检查UFW状态
sudo ufw status

Copy
# 如果显示 "Status: inactive"，说明防火墙未启用，无需额外配置
# 如果需要启用防火墙（可选），可以执行以下步骤：

# 放行SSH端口（重要：避免被锁定）
sudo ufw allow 22

# 放行AstrBot Web管理界面端口
sudo ufw allow 6180

# 放行NapCat Web管理界面端口
sudo ufw allow 6099

# 放行NapCat通信端口
sudo ufw allow 3000
sudo ufw allow 3001

# 放行AstrBot与NapCat通信端口
sudo ufw allow 6199

Copy
# 启用UFW防火墙
sudo ufw enable

Copy
# 查看防火墙状态
sudo ufw status

注意：大多数情况下，国外 VPS 默认 UFW 是关闭的，可以直接部署服务而无需配置防火墙。

国内服务器（如阿里云、腾讯云、华为云等）

国内服务器主要通过云服务商控制台的安全组进行端口管理：

云服务商安全组配置：

需要在云服务商控制台的安全组中添加以下入站规则：

| | |
端口 | 协议 | 来源 | 说明
6180 | TCP | 0.0.0.0/0 | AstrBot Web 管理界面
6099 | TCP | 0.0.0.0/0 | NapCat Web 管理界面
3000 | TCP | 0.0.0.0/0 | NapCat 通信端口
3001 | TCP | 0.0.0.0/0 | NapCat 通信端口
6199 | TCP | 127.0.0.1/32 | AstrBot 与 NapCat 内部通信

具体操作步骤：

阿里云：进入 ECS 控制台 → 安全组 → 配置规则 → 添加安全组规则

腾讯云：进入 CVM 控制台 → 安全组 → 入站规则 → 添加规则

华为云：进入 ECS 控制台 → 安全组 → 入方向规则 → 添加规则

注意：大多数情况下，国内服务器只需要配置安全组即可，无需额外配置系统防火墙

注意事项：

如果只需要本地访问 Web 界面，可以将来源 IP 限制为你的公网 IP

端口 6199 用于内部通信，建议限制来源为 127.0.0.1

生产环境建议使用更严格的安全组规则

方法一：使用 Docker Compose 一键部署（推荐）

这是最简单也是最推荐的部署方式，可以同时部署 AstrBot 和 NapCat，并且自动配置好它们之间的连接。

1. 创建项目目录

Copy
mkdir ~/astrbot-napcat
cd ~/astrbot-napcat

2. 下载 Docker Compose 配置文件

Copy
curl -o astrbot.yml https://raw.githubusercontent.com/NapNeko/NapCat-Docker/main/compose/astrbot.yml

3. 启动服务

Copy
NAPCAT_UID=$(id -u) NAPCAT_GID=$(id -g) docker-compose -f ./astrbot.yml up -d

4. 查看服务状态

Copy
docker-compose -f ./astrbot.yml ps

5. 查看 NapCat 日志获取登录二维码

Copy
docker logs napcat

在日志中，你会看到：

QQ 登录二维码（使用手机 QQ 扫码登录）

NapCat WebUI 管理界面地址（通常是 http://your-server-ip:6099）

6. 扫码登录 QQ

使用你要作为机器人的 QQ 号对应的手机 QQ 扫描日志中显示的二维码进行登录。

方法二：分别部署 AstrBot 和 NapCat

如果你希望更灵活地控制部署过程，可以选择分别部署两个组件。

部署 NapCat

1. 使用 Docker 运行 NapCat

Copy
docker run -d \
-e NAPCAT_GID=$(id -g) \
-e NAPCAT_UID=$(id -u) \
-p 3000:3000 \
-p 3001:3001 \
-p 6099:6099 \
--name napcat \
--restart=always \
mlikiowa/napcat-docker:latest

2. 查看日志并登录

Copy
docker logs napcat

按照日志中的提示扫码登录 QQ。

部署 AstrBot

1. 使用 Docker 运行 AstrBot

Copy
docker run -d \
-p 6180:6180 \
-v ~/astrbot_data:/app/data \
--name astrbot \
--restart=always \
soulter/astrbot:latest

2. 访问 AstrBot 管理界面

打开浏览器访问 http://your-server-ip:6180，进入 AstrBot 的 Web 管理界面。

配置连接

无论使用哪种部署方式，都需要配置 AstrBot 和 NapCat 之间的连接。

在 AstrBot 中配置 aiocqhttp 适配器

打开 AstrBot 管理面板（http://your-server-ip:6180）

点击左侧菜单的 消息平台

点击 + 新增适配器

选择 aiocqhttp(OneBotv11)

配置参数如下：

ID: 随意填写，用于区分不同的消息平台实例（如：qq-bot）

启用: 勾选

反向 WebSocket 主机地址: 0.0.0.0

反向 WebSocket 端口: 6199（或其他未被占用的端口）

点击 保存 完成配置。

配置管理员

在 AstrBot 管理面板中，点击 配置 页面

点击 其他配置 选项卡

找到 管理员ID，填写你的 QQ 号（不是机器人的 QQ 号）

点击右下角 保存

AstrBot 会自动重启并应用配置。

在 NapCat 中添加 WebSocket 客户端

打开 NapCat 管理面板（http://your-server-ip:6099）

点击 网络配置 -> 新建 -> WebSockets客户端

配置参数：

启用: 勾选

URL: ws://localhost:6199/ws（注意：这里的 IP 是 localhost，端口要与 AstrBot 中配置的一致，后面必须加/ws）

消息格式: Array

心跳间隔: 5000

重连间隔: 5000

点击 保存 完成配置。

验证连接

检查连接状态

在 AstrBot 管理面板的 控制台 页面，查看是否出现类似以下的蓝色日志：

Copy
aiocqhttp(OneBot v11) 适配器已连接。

如果看到此日志，说明连接成功。

测试机器人功能

使用你的个人 QQ 号（管理员 QQ 号）私聊机器人 QQ 号，发送 /help 命令。如果机器人正常回复帮助信息，说明部署成功。

配置大语言模型

AstrBot 支持多种大语言模型提供商，以下以配置 OpenAI 为例：

1. 进入模型配置

在 AstrBot 管理面板中，点击 配置 页面

点击 大语言模型 选项卡

2. 添加模型提供商

点击 + 新增提供商

选择 OpenAI

填写配置信息：

API Key: 你的 OpenAI API 密钥

Base URL: https://api.openai.com/v1（或其他兼容的 API 地址）

模型名称: gpt-3.5-turbo 或 gpt-4

3. 保存配置

点击 保存 完成模型配置。

常用管理命令

Docker Compose 方式部署的管理命令

Copy
# 查看服务状态
docker-compose -f ./astrbot.yml ps

# 查看日志
docker-compose -f ./astrbot.yml logs

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

# 停止服务
docker-compose -f ./astrbot.yml down

# 更新服务
docker-compose -f ./astrbot.yml pull
docker-compose -f ./astrbot.yml up -d

单独部署的管理命令

Copy
# 查看容器状态
docker ps

# 查看NapCat日志
docker logs napcat

# 查看AstrBot日志
docker logs astrbot

# 重启容器
docker restart napcat
docker restart astrbot

# 停止容器
docker stop napcat astrbot

# 删除容器
docker rm napcat astrbot

故障排除

常见问题及解决方案

1. NapCat 无法登录 QQ

问题现象: 扫码后提示登录失败或风控

解决方案:

确保使用的 QQ 号不是新注册的账号

尝试在手机上正常登录该 QQ 号后再进行扫码

检查网络连接是否稳定

如果仍然失败，可以尝试更换 QQ 号

2. AstrBot 和 NapCat 连接失败

问题现象: AstrBot 控制台没有显示连接成功的日志

解决方案:

检查端口配置是否一致

确认 WebSocket URL 格式正确（必须以/ws结尾）

检查防火墙设置，确保相关端口未被阻止

查看两个服务的日志，寻找错误信息

3. 机器人不回复消息

问题现象: 发送消息给机器人，但机器人没有回复

解决方案:

确认管理员 QQ 号配置正确

检查大语言模型配置是否正确

查看 AstrBot 日志，确认是否有错误信息

尝试发送 /help 命令测试基础功能

4. Docker 容器启动失败

问题现象: 容器无法正常启动

解决方案:

检查 Docker 服务是否正常运行：sudo systemctl status docker

确认端口没有被其他服务占用：netstat -tlnp | grep :端口号

查看容器日志：docker logs 容器名

检查磁盘空间是否充足：df -h

5. 无法访问 Web 管理界面

问题现象: 浏览器无法打开 AstrBot 或 NapCat 的 Web 界面

解决方案:

检查云服务商安全组是否配置正确（这是最常见的原因）

如果使用国外服务器，检查 UFW 防火墙状态：sudo ufw status（通常显示 inactive，无需处理）

检查服务是否正常运行：docker ps

尝试使用服务器内网 IP 访问

检查端口是否被正确映射：docker port 容器名

日志查看

查看详细日志

Copy
# 查看NapCat详细日志
docker logs -f napcat

# 查看AstrBot详细日志
docker logs -f astrbot

# 如果使用Docker Compose
docker-compose -f ./astrbot.yml logs -f

日志文件位置

AstrBot 日志通常保存在容器的 /app/data/logs/ 目录

可以通过数据卷映射将日志保存到宿主机

安全建议

1. 网络安全

防火墙配置：

只开放必要的端口，关闭不需要的服务端口

对于 Web 管理界面，建议限制访问来源 IP

内部通信端口（如 6199）应限制为本地访问

端口安全建议：

Copy
# 限制Web界面只允许特定IP访问（以UFW为例）
sudo ufw delete allow 6180
sudo ufw allow from YOUR_IP_ADDRESS to any port 6180

# 限制NapCat管理界面访问
sudo ufw delete allow 6099
sudo ufw allow from YOUR_IP_ADDRESS to any port 6099

其他安全措施：

如果服务器暴露在公网，建议使用反向代理（如 Nginx）并配置 SSL 证书

定期更新系统和 Docker 镜像

考虑使用 VPN 或跳板机访问管理界面

2. 账号安全

不要使用重要的 QQ 号作为机器人账号

定期检查机器人的行为，确保没有异常活动

合理设置机器人的权限和功能

3. 数据备份

Copy
# 备份AstrBot数据
docker cp astrbot:/app/data ./astrbot_backup

# 备份NapCat配置
docker cp napcat:/app/napcat ./napcat_backup

进阶配置

1. 配置插件

AstrBot 支持丰富的插件生态，你可以通过 Web 界面安装和管理插件：

在管理面板中点击 插件 页面

浏览可用插件并点击 安装

根据插件说明进行配置

2. 多 QQ 号支持

如果需要同时运行多个 QQ 机器人，可以：

为每个 QQ 号创建单独的 NapCat 容器

使用不同的端口避免冲突

在 AstrBot 中配置多个 aiocqhttp 适配器

3. 自定义配置

你可以通过修改配置文件来自定义更多功能：

AstrBot 配置文件位于 /app/data/config/

NapCat 配置文件位于 /app/napcat/config/

效果展示

部署完成后，经过简单的配置就可以实现以下效果：

写在最后

经过这一番折腾，相信大家都已经成功搭建起了属于自己的 QQ 聊天机器人。AstrBot 的 Web 界面做得相当不错，基本上所有配置都能通过点点点完成，不用再去翻那些复杂的配置文件。而 NapCat 作为 QQ 协议端也很稳定，比起以前用过的一些方案，这个确实让人省心不少。

一些使用心得

在实际使用过程中，我发现几个小技巧分享给大家：

关于 QQ 号选择：不建议用刚注册的小号，最好用个有一定历史的号，平时正常聊天的那种。

服务器选择：如果预算允许，建议选择国外的 VPS，网络环境相对宽松一些。国内服务器虽然速度快，但是各种限制比较多。

模型选择：可以选择 Gemini 的免费的 API，对于个人使用完全够用了。也可以选择 DeepSeek 的 API, 现在很便宜，效果也不错。

插件生态：AstrBot 的插件生态还是挺丰富的，可以根据自己的需求安装一些实用的插件，比如天气查询、翻译等等。

总的来说，这套方案还是很值得推荐的。而且搭建完成，后续的维护成本很低。而且随着项目的不断更新，功能会越来越完善。

好了，教程就到这里。如果这篇文章对你有帮助或者有什么问题也欢迎在评论区交流，我会尽量回复的。

最后，祝大家都能搭建出满意的聊天机器人！

相关链接

AstrBot 官网

AstrBot 文档

AstrBot GitHub

NapCat 文档

NapCat GitHub

NapCat Docker

本教程基于 AstrBot 和 NapCat 的最新版本编写，如有更新请以官方文档为准。

此文由 Mix Space 同步更新至 xLog
原始链接为 https://blog.astrasolis.top/posts/tutorial/docker-astrbot-tutorial