ViperEkura's Blog
Astrbot与NapCat部署指南
ViperEkura Lv1
  2026-04-01 19:31:10   2026-04-06 21:02:02  

本文档提供 AstrBot（聊天机器人框架）与 NapCat（QQ 协议端）的完整部署流程，适用于通过 Docker Compose 在 Linux 服务器上部署，并通过 Nginx 反向代理将 WebUI 暴露在子路径 /bot/ 下。

1. 概述

  • AstrBot: 开源的多平台聊天机器人框架，支持 QQ、微信、Telegram 等平台，可接入多种大语言模型（LLM）。
  • NapCat: 基于 QQ 官方客户端协议的协议端，允许使用 QQ 个人号作为机器人账号，通过 OneBot v11 协议与 AstrBot 通信。

部署目标: - 在服务器上使用 Docker Compose 运行 AstrBot 和 NapCat 容器。 - 通过 Nginx 反向代理将 AstrBot 的 WebUI 映射到 https://your-domain.com/bot/。 - 实现 QQ 小号自动收发消息。

2. 前提条件

2.1 服务器要求

  • Linux 服务器（Ubuntu 20.04+ 或其他发行版）
  • 已安装 Docker（版本 ≥ 20.10）和 Docker Compose（版本 ≥ v2.0）
  • 已安装 Nginx（或其他反向代理）
  • 拥有一个域名（已解析到服务器 IP，并配置 SSL 证书）

2.2 检查工具

1
2
3
sudo docker --version
sudo docker compose version
nginx -v

2.3 目录结构

建议所有操作在 /root/workspace/AstrBot（或你自定义的目录）下进行。

3. 部署步骤

3.1 准备项目目录

1
cd /root/workspace/AstrBot

3.2 编写 compose.yml

使用以下 compose.yml，该文件已包含 AstrBot 和 NapCat 服务，并针对无 GPU 环境优化：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
services:
  napcat:
    environment:
      - NAPCAT_UID=${NAPCAT_UID:-1000}
      - NAPCAT_GID=${NAPCAT_GID:-1000}
      - MODE=astrbot
      - TZ=Asia/Shanghai
      - LIBGL_ALWAYS_SOFTWARE=1
      - EGL_PLATFORM=surfaceless
      - QT_QUICK_BACKEND=software
      - QT_X11_NO_MITSHM=1
      - ELECTRON_DISABLE_GPU=1
      - CHROMIUM_FLAGS=--disable-gpu --disable-software-rasterizer
    ports:
      - "6099:6099"
    container_name: napcat
    restart: always
    image: docker.1ms.run/mlikiowa/napcat-docker:latest
    volumes:
      - ./data:/AstrBot/data
      - ./napcat/config:/app/napcat/config
      - ./ntqq:/app/.config/QQ
      - ./machine-id/machine-id:/etc/machine-id:ro
      - /etc/localtime:/etc/localtime:ro
    networks:
      - astrbot-network

  astrbot:
    environment:
      - TZ=Asia/Shanghai
    image: m.daocloud.io/docker.io/soulter/astrbot:latest
    container_name: astrbot
    restart: always
    ports:
      - "6185:6185"
      - "6199:6199"
    volumes:
      - ./data:/AstrBot/data
      - /etc/localtime:/etc/localtime:ro
    networks:
      - astrbot-network

networks:
  astrbot-network:
    driver: bridge

重要说明: - 镜像已使用 DaoCloud 加速源，适用于中国大陆用户。 - NapCat 的环境变量已设置禁用 GPU，避免因服务器无 GPU 导致的启动问题。 - 挂载卷 ./data 用于持久化 AstrBot 数据。 - 挂载卷 ./napcat/config 用于持久化 NapCat 配置文件。 - 挂载卷 ./ntqq 用于持久化 QQ 登录状态与缓存。 - 挂载卷 ./machine-id/machine-id 用于固定设备标识，防止 QQ 风控。 - 两个容器均已挂载宿主机的 /etc/localtime 以同步时区。

3.3 启动容器

1
NAPCAT_UID=$(id -u) NAPCAT_GID=$(id -g) docker compose up -d

3.4 验证服务状态

1
docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"

应看到 astrbot 和 napcat 两个容器均为 Up 状态，且端口映射正确。

3.5 查看日志

1
2
docker logs astrbot --tail 10
docker logs napcat --tail 10

AstrBot 日志应出现 WebUI 已启动 等信息；NapCat 日志应出现二维码或登录提示。

4. 配置 NapCat

4.1 登录 QQ 账号

NapCat 提供了 WebUI 用于登录 QQ。由于容器映射了端口 6099，你可以通过以下方式访问：

  1. 如果服务器有图形界面：直接访问 http://localhost:6099（本地）或 http://服务器IP:6099（远程）。
  2. 如果服务器无图形界面： 
    1
    docker logs -f napcat
    在日志中查找二维码图案或二维码解码 URL，复制 URL 到二维码生成网站，使用手机 QQ 扫码登录。

4.2 确认 WebSocket 配置

NapCat 默认配置文件已包含指向 AstrBot 的 WebSocket 客户端。如需手动确认，检查 ./napcat/config/onebot11.json（若已取消注释挂载）： 

1
2
3
4
5
6
7
8
9
"websocketClients": [
  {
    "enable": true,
    "name": "rws",
    "url": "ws://astrbot:6199/ws",
    "heartInterval": 30000,
    "reconnectInterval": 30000
  }
]
确保 url 为 ws://astrbot:6199/ws（容器间通信）。

5. 配置 AstrBot

5.1 访问 WebUI

AstrBot WebUI 默认运行在 6185 端口。你可以通过以下方式访问： - 直接访问 http://localhost:6185（本地） - 通过 Nginx 反向代理访问 https://your-domain.com/bot/（详见第6节）

默认登录凭证: - 用户名：astrbot - 密码：astrbot

5.2 创建 OneBot v11 机器人

  1. 登录 WebUI 后，进入左侧菜单 机器人。
  2. 点击 + 创建机器人。
  3. 选择 OneBot v11 类别。
  4. 填写表单：
    • ID：任意名称，如 napcat
    • 启用：勾选
    • 反向 WebSocket 主机地址：0.0.0.0
    • 反向 WebSocket 端口：6199
    • 反向 Websocket Token：（若 NapCat 配置了 token 则填写，否则留空）
  5. 点击 保存。

5.3 验证连接

查看 AstrBot 日志，确认连接成功： 

1
docker logs astrbot --tail 10 | grep -i "aiocqhttp\|OneBot"
若出现 aiocqhttp(OneBot v11) 适配器已连接 蓝色日志，说明连接成功。

6. Nginx 反向代理配置（可选）

如果你希望将 AstrBot WebUI 通过子路径（如 /bot/）对外提供服务，请配置 Nginx 反向代理。

6.1 编辑 Nginx 配置文件

通常位于 /etc/nginx/sites-available/default。在 server 块内添加以下内容：

1
2
3
4
5
6
7
8
9
10
11
12
13
# AstrBot 反向代理 - 使用 /bot/ 子路径
location /bot/ {
    proxy_pass http://127.0.0.1:6185/;
    proxy_http_version 1.1;
    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;
    proxy_set_header X-Forwarded-Host $host;
    proxy_set_header X-Forwarded-Prefix /bot;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

6.2 测试并重载 Nginx

1
2
sudo nginx -t
sudo systemctl reload nginx

6.3 访问 WebUI

现在可以通过 https://your-domain.com/bot/ 访问 AstrBot WebUI。

7. 测试聊天

向已登录的 QQ 小号发送任意消息，AstrBot 应能收到并可在 WebUI 控制台中看到消息记录。若配置了对话模型，机器人将自动回复。

8. 故障排除

8.1 NapCat 无法解析 astrbot 主机名

确保两个容器在同一 Docker 网络。检查网络连接： 

1
docker network inspect astrbot_astrbot-network
若需要手动连接，执行： 
1
docker network connect astrbot_default napcat

8.2 端口连接被拒绝

检查 AstrBot 是否正在监听 6199 端口： 

1
docker exec astrbot netstat -tlnp | grep 6199
若未监听，确认 AstrBot 配置中已启用 OneBot v11 适配器。

8.3 二维码不显示或登录失败

  • 确保 NapCat 容器有足够内存（> 1GB）。
  • 检查日志中是否有 GPU 相关错误（可忽略，不影响功能）。
  • 尝试使用“快速登录”（若之前已登录过同一账号）。

8.4 WebUI 无法访问

  • 确认端口映射正确：宿主机 6185 → 容器 6185。
  • 检查防火墙是否放行对应端口。

9. 安全注意事项

  1. QQ 账号风控：NapCat 使用 QQ 官方客户端协议，存在账号风控风险，请勿使用重要账号。
  2. 网络暴露：建议不要将 NapCat WebUI（端口 6099）直接暴露在公网，仅通过内网或 SSH 隧道访问。
  3. 密码安全：首次登录 AstrBot WebUI 后，请立即修改默认密码。
  4. 定期备份：定期备份 ./data 目录（包含 AstrBot 配置和会话数据）。
 REWARD AUTHOR
  1. 1. 概述
  2. 2. 前提条件
    1. 2.1 服务器要求
    2. 2.2 检查工具
    3. 2.3 目录结构
  3. 3. 部署步骤
    1. 3.1 准备项目目录
    2. 3.2 编写 compose.yml
    3. 3.3 启动容器
    4. 3.4 验证服务状态
    5. 3.5 查看日志
  4. 4. 配置 NapCat
    1. 4.1 登录 QQ 账号
    2. 4.2 确认 WebSocket 配置
  5. 5. 配置 AstrBot
    1. 5.1 访问 WebUI
    2. 5.2 创建 OneBot v11 机器人
    3. 5.3 验证连接
  6. 6. Nginx 反向代理配置（可选）
    1. 6.1 编辑 Nginx 配置文件
    2. 6.2 测试并重载 Nginx
    3. 6.3 访问 WebUI
  7. 7. 测试聊天
  8. 8. 故障排除
    1. 8.1 NapCat 无法解析 astrbot 主机名
    2. 8.2 端口连接被拒绝
    3. 8.3 二维码不显示或登录失败
    4. 8.4 WebUI 无法访问
  9. 9. 安全注意事项
  1. 1. 概述
  2. 2. 前提条件
    1. 2.1 服务器要求
    2. 2.2 检查工具
    3. 2.3 目录结构
  3. 3. 部署步骤
    1. 3.1 准备项目目录
    2. 3.2 编写 compose.yml
    3. 3.3 启动容器
    4. 3.4 验证服务状态
    5. 3.5 查看日志
  4. 4. 配置 NapCat
    1. 4.1 登录 QQ 账号
    2. 4.2 确认 WebSocket 配置
  5. 5. 配置 AstrBot
    1. 5.1 访问 WebUI
    2. 5.2 创建 OneBot v11 机器人
    3. 5.3 验证连接
  6. 6. Nginx 反向代理配置（可选）
    1. 6.1 编辑 Nginx 配置文件
    2. 6.2 测试并重载 Nginx
    3. 6.3 访问 WebUI
  7. 7. 测试聊天
  8. 8. 故障排除
    1. 8.1 NapCat 无法解析 astrbot 主机名
    2. 8.2 端口连接被拒绝
    3. 8.3 二维码不显示或登录失败
    4. 8.4 WebUI 无法访问
  9. 9. 安全注意事项