AstrBot + NapCat 搭建教程：打造你的 QQ AI 机器人

本教程将手把手教你使用 Docker 一键部署 AstrBot + NapCat，从零开始搭建一个接入大语言模型的 QQ 智能机器人。全程命令行操作，适合有基本 Linux 基础的用户。

目录

• 简介
• 环境准备
• 部署服务
• 登录 QQ
• 对接配置
• 接入大模型
• 安装插件
• 进阶配置
• 常见问题

简介

AstrBot

AstrBot 是一个开源的多平台大模型机器人框架，支持接入 OpenAI、Gemini、Claude、DeepSeek 等主流大语言模型，并提供插件系统和 Web 管理面板。

NapCat

NapCat 是基于 NTQQ 的现代 QQ 协议端，实现了 OneBot 11 标准协议，负责收发 QQ 消息。

架构关系

┌──────────────┐     OneBot 11 协议     ┌──────────────┐     API 调用     ┌──────────────┐
│   QQ 用户    │ ◄──────────────────► │    NapCat     │ ◄────────────► │   AstrBot    │
│  发送/接收   │                       │  QQ 协议层    │   反向WebSocket  │  机器人逻辑   │
│   QQ 消息    │                       │  端口: 6099   │                 │  端口: 6185   │
└──────────────┘                       └──────────────┘                 └──────┬───────┘
                                                                               │
                                                                               ▼
                                                                      ┌──────────────┐
                                                                      │  大语言模型   │
                                                                      │ GPT / Gemini  │
                                                                      │ Claude / DS   │
                                                                      └──────────────┘

简单来说：NapCat 负责和 QQ 通信，AstrBot 负责处理逻辑和调用 AI，两者通过 OneBot 协议连接。

一、环境准备

1.1 系统要求

1.2 安装 Docker

# 一键安装 Docker
curl -fsSL https://get.docker.com | sh

# 启动 Docker 并设置开机自启
sudo systemctl start docker && sudo systemctl enable docker

# 验证安装
docker --version && docker compose version

国内服务器如果下载慢，可以使用阿里云安装源：

curl -fsSL https://get.docker.com | sh -s -- --mirror Aliyun

1.3 开放防火墙端口

如果使用云服务器，需要在安全组中开放以下端口：

二、部署 AstrBot + NapCat

2.1 创建项目目录

mkdir -p /opt/astrbot && cd /opt/astrbot

2.2 编写 docker-compose.yml

cat > docker-compose.yml << 'EOF'
services:
  # NapCat - QQ 协议端
  napcat:
    image: mlikiowa/napcat-docker:latest
    container_name: napcat
    restart: always
    environment:
      - NAPCAT_UID=0
      - NAPCAT_GID=0
      - MODE=astrbot    # 关键：自动配置与 AstrBot 的连接
    ports:
      - "6099:6099"      # NapCat WebUI
    volumes:
      - ./data:/AstrBot/data          # 与 AstrBot 共享数据目录
      - ./napcat/config:/app/napcat/config  # NapCat 配置
      - ./ntqq:/app/.config/QQ        # QQ 登录数据持久化
    networks:
      - astrbot_network

  # AstrBot - 机器人逻辑层
  astrbot:
    image: soulter/astrbot:latest
    container_name: astrbot
    restart: always
    environment:
      - TZ=Asia/Shanghai
    ports:
      - "6185:6185"      # AstrBot 管理面板
    volumes:
      - ./data:/AstrBot/data          # 数据持久化
    networks:
      - astrbot_network

networks:
  astrbot_network:
    driver: bridge
EOF

关于 MODE=astrbot：这个环境变量会让 NapCat 自动配置反向 WebSocket 连接到 AstrBot，省去手动对接的步骤。

2.3 启动服务

docker compose up -d

2.4 确认服务状态

# 查看容器运行状态
docker compose ps

# 查看 AstrBot 启动日志
docker logs -f astrbot

# 查看 NapCat 启动日志（另开终端）
docker logs -f napcat

当 AstrBot 日志出现 Dashboard started 字样，说明启动成功。按 Ctrl+C 退出日志查看。

2.5 数据目录说明

/opt/astrbot/
├── docker-compose.yml          # 编排配置
├── data/                       # AstrBot 数据（插件、配置等）
├── napcat/config/              # NapCat 配置文件
└── ntqq/                       # QQ 登录凭据（重要，勿删）

⚠️ ntqq/ 目录保存了 QQ 登录状态，删除后需要重新扫码登录。

三、登录 QQ 账号

3.1 访问 NapCat WebUI

浏览器打开：

http://你的服务器IP:6099

3.2 扫码登录

1. 页面会显示一个 QQ 登录二维码
2. 打开手机 QQ → 扫一扫 → 确认登录
3. 登录成功后页面会自动跳转，NapCat 开始接收消息

⚠️ 重要提醒

• 务必使用小号！ 机器人账号存在被风控的风险，切勿使用主力 QQ 号
• 建议使用有一定注册时间的 QQ 号，新号容易被限制
• 如二维码刷新太快，可通过日志获取：docker logs napcat 2>&1 | grep -i "qr\|url"

四、对接 AstrBot 与 NapCat

由于我们在 docker-compose 中设置了 MODE=astrbot，NapCat 会自动完成对接配置。但如果你需要手动配置或排查问题，以下是详细步骤。

4.1 登录 AstrBot 管理面板

浏览器打开：

http://你的服务器IP:6185

默认账号密码均为 astrbot，首次登录后请立即修改密码。

4.2 验证平台连接

进入管理面板后：

1. 点击左侧 「平台」 菜单
2. 应该能看到一个已自动配置好的 aiocqhttp 平台适配器
3. 状态显示为 已连接 即表示对接成功

4.3 手动配置（如自动对接失败）

如果平台列表中没有看到 aiocqhttp 适配器，需要手动添加：

1. 点击 「添加平台」
2. 选择 aiocqhttp（OneBot 11 协议适配器）
3. 填写配置：

4. 保存配置并重启 AstrBot

然后在 NapCat WebUI 的网络配置中添加反向 WebSocket 地址：

ws://astrbot:6199/ws

注意这里使用 astrbot 而非 127.0.0.1，因为在 Docker 网络中容器之间通过服务名通信。

五、接入大语言模型

5.1 添加 LLM 服务

在 AstrBot 管理面板中，进入 「服务提供商」 页面，点击 「添加」。

5.2 配置示例

OpenAI / 兼容接口（推荐）：

支持的模型提供商：

• OpenAI：GPT-4o、GPT-4o-mini
• Google：Gemini 2.0 Flash、Gemini 2.0 Pro
• Anthropic：Claude 3.5 Sonnet、Claude 3.5 Haiku
• DeepSeek：DeepSeek-V3、DeepSeek-R1
• 通义千问、智谱 GLM、Ollama 本地模型 等
• 任何兼容 OpenAI 接口格式的服务

5.3 测试对话

配置完成后，用你的 QQ 号向机器人发送消息测试：

/ask 你好，请介绍一下你自己

或者在群里 @机器人 你好 触发对话。

如果机器人正常回复，恭喜搭建成功！🎉

六、安装插件（可选）

AstrBot 支持丰富的插件生态，可以扩展机器人的功能。

通过管理面板安装

1. 进入 「插件市场」 → 浏览可用插件 → 点击安装
2. 或进入 「插件」 → 「安装插件」 → 输入 GitHub 仓库地址

推荐插件

插件安装后在 「插件」 页面可进行配置和管理。

七、进阶配置

7.1 Nginx 反向代理（推荐）

为 AstrBot 管理面板配置 HTTPS 访问：

server {
    listen 443 ssl;
    server_name bot.yourdomain.com;

    ssl_certificate     /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    # AstrBot 管理面板
    location / {
        proxy_pass http://127.0.0.1:6185;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

配置完成后可以关闭防火墙的 6185 端口直接暴露，通过域名 + HTTPS 访问更安全。

7.2 资源限制（低配服务器）

如果服务器内存较小，可以在 docker-compose.yml 中添加资源限制：

services:
  astrbot:
    # ... 其他配置 ...
    deploy:
      resources:
        limits:
          memory: 512M
  napcat:
    # ... 其他配置 ...
    deploy:
      resources:
        limits:
          memory: 512M

7.3 数据备份

定期备份整个项目目录，防止数据丢失：

# 备份（建议每周一次）
tar -czf /backup/astrbot_$(date +%Y%m%d).tar.gz -C /opt astrbot

# 恢复
tar -xzf /backup/astrbot_20260210.tar.gz -C /opt

7.4 版本更新

cd /opt/astrbot

# 拉取最新镜像
docker compose pull

# 重启服务（数据不会丢失）
docker compose up -d

# 确认更新后的版本
docker compose ps

八、常见问题

Q: NapCat 扫码后一直显示登录失败？

检查 NapCat 日志中的报错信息：

docker logs napcat --tail 50

常见原因：QQ 号被风控、网络不通、QQ 版本不兼容。建议换一个有历史的 QQ 号重试。

Q: AstrBot 面板打不开？

# 检查容器是否在运行
docker ps | grep astrbot

# 检查端口是否被监听
ss -tlnp | grep 6185

# 检查防火墙是否放行
sudo ufw status  # Ubuntu
sudo firewall-cmd --list-all  # CentOS

Q: 国内服务器拉取镜像很慢？

使用镜像加速站，修改 docker-compose.yml 中的 image：

# 替换为加速镜像
image: m.daocloud.io/docker.io/soulter/astrbot:latest
image: m.daocloud.io/docker.io/mlikiowa/napcat-docker:latest

Q: 机器人不回复消息？

按以下顺序排查：

1. NapCat 是否在线 → 检查 NapCat WebUI 登录状态
2. 平台是否连接 → 检查 AstrBot 面板「平台」页面连接状态
3. LLM 是否配置 → 检查「服务提供商」是否添加了有效的模型配置
4. 触发方式 → 确认使用 /ask 或 @机器人 触发

Q: 如何同时查看所有日志？

docker compose logs -f --tail 100

相关链接

本教程由 AI 辅助编写，如有疏漏欢迎指正。