雨云服务器部署 AstrBot + NapCat 完整教程

2501_91919859

66人浏览 · 2026-08-30 13:05:45

2501_91919859 · 2026-08-30 13:05:45 发布

雨云服务器部署 AstrBot + NapCat 完整教程

本教程将带你在一台雨云（RainYun）云服务器上，使用 Docker 部署 AstrBot（LLM 聊天机器人框架）与 NapCat（QQ 协议端），实现 QQ 机器人接入大语言模型对话。

一、简介

组件	作用
NapCat	基于 QQNT 的无头 QQ 协议实现，负责登录 QQ 账号、收发消息，对外提供 OneBot v11 API
AstrBot	大模型聊天机器人框架，负责对接各类 LLM（DeepSeek、OpenAI、Gemini 等）、插件系统与消息处理

两者关系：

QQ 消息 ↔ NapCat（协议端） ↔ OneBot v11 WebSocket ↔ AstrBot（逻辑端） ↔ 大模型 API

二、准备工作

一个雨云账号（https://www.rainyun.com/XiaoYu_）
一个备用 QQ 号：专用于机器人，建议提前挂几天（新号风控严格，容易登录失败或冻结）
一个 LLM API Key：如 DeepSeek、OpenAI、Moonshot、Mimo 等，任选其一
基本的 SSH 使用能力（本教程会给出全部命令）

三、购买并连接雨云服务器

3.1 购买服务器

登录雨云控制台 → 云服务器 → 购买
推荐配置：
- 区域：国内（如宿迁 BGP / 南京）或香港，QQ 登录建议选国内节点（境外 IP 登录 QQ 触发风控概率高）
- 配置：2核 2G 内存起步（AstrBot + NapCat + Docker 合计占用约 700MB~1GB）
- 系统：Ubuntu 22.04 / 24.04 或 Debian 12（本教程以 Ubuntu 为例）
付款后进入实例详情页，记下：
- 公网 IP
- SSH 端口（雨云默认映射端口不是 22，在详情页可见，如 38822）
- root 密码（或自行在面板重置密码）

3.2 连接服务器

Windows 可用 PowerShell 自带的 ssh，或使用终端工具（Tabby、Xshell、FinalShell 等）：

ssh root@你的公网IP -p 你的SSH端口
# 例如：ssh root@123.45.67.89 -p 38822

首次连接输入 yes 回车，然后输入密码即可登录。

💡 也可以在雨云控制台使用网页 VNC 登录，但日常操作推荐 SSH。

连接成功界面

3.3 更新系统（可选但建议）

apt update && apt upgrade -y

四、安装 Docker

4.1 一键安装

curl -fsSL https://get.docker.com | bash

💡 如果服务器在国内且拉取缓慢，可使用国内镜像源安装：
curl -fsSL https://get.docker.com | bash -s docker --mirror Aliyun

4.2 验证安装

docker -v
docker compose version

两条命令都能输出版本号即安装成功（新版 Docker 自带 docker compose 插件）。

4.3 设置开机自启

systemctl enable docker

五、部署 NapCat

NapCat 在 Docker 中不能使用宿主机网络模式（QQNT 协议需要独立网络环境），推荐使用 Macvlan 方式为容器分配一个独立局域网 IP，这是兼容性最好的方案。

5.1 创建 Docker 网络（Macvlan）

先在雨云控制台或系统内查看服务器的内网 IP 和网关：

ip addr show
ip route

典型输出中：inet 10.0.x.x 是内网 IP，default via 10.0.x.1 中的是网关。

创建 macvlan 网络（请把 subnet、gateway、容器 IP 替换为你实际的网段，容器 IP 选同网段未被占用的一个）：

docker network create -d macvlan \
  --subnet=10.0.0.0/24 \
  --gateway=10.0.0.1 \
  -o parent=eth0 \
  napcat-network

⚠️ 说明：

eth0 是网卡名，以 ip addr 输出为准

Macvlan 分配的独立 IP 需要在雨云控制台绑定弹性公网 IP 或使用 NAT 映射才能对外访问（详见 5.4）

5.2 创建目录与编排文件

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

创建 docker-compose.yml：

cat > docker-compose.yml << 'EOF'
services:
  napcat:
    image: mlikiowa/napcat-docker:latest
    container_name: napcat
    restart: always
    mac_address: 02:42:ac:11:00:11
    networks:
      napcat-network:
        ipv4_address: 10.0.0.10   # 与上面创建网络时同网段，自行指定
    environment:
      - NAPCAT_GID=0
      - NAPCAT_UID=0
      - ACCOUNT=10000            # 改成你的机器人QQ号，也可留空启动后在WebUI扫码
      - WEBUI_TOKEN=napcat123    # NapCat WebUI 的访问令牌，改成你自己的
    volumes:
      - ./config:/app/napcat/config
      - ./data:/app/napcat/data
    ports:
      - "6099:6099"              # NapCat WebUI
      - "3001:3001"              # OneBot WebSocket 服务端口
networks:
  napcat-network:
    external: true
EOF

5.3 启动 NapCat

cd /opt/napcat
docker compose up -d
docker logs -f napcat

看到输出中包含 WebUI 地址（形如 http://0.0.0.0:6099/webui?token=xxx）即启动成功，Ctrl+C 退出日志。

5.4 雨云防火墙放行端口

进入雨云控制台 → 你的服务器 → 防火墙，放行以下 TCP 端口：

端口	用途
6099	NapCat WebUI（登录扫码用）
6185	AstrBot WebUI（管理用）

🔒 安全提示：两个 WebUI 建议用完后在防火墙中关闭，仅需要时再放行；务必修改默认令牌/密码。

六、登录 QQ

浏览器访问：http://你的公网IP:6099/webui
输入令牌（compose 文件中 WEBUI_TOKEN 的值，默认为 napcat123）登录
在 网络配置 → 快速登录 处，使用手机 QQ 扫描二维码登录机器人 QQ 号
登录成功后，页面会显示账号的在线状态

6.1 配置 OneBot v11 反向 WebSocket（推荐）

登录成功后，在 NapCat WebUI 中：

进入 网络配置 → 添加网络配置 → 选择 WebSocket 客户端（反向 WS）
填写：
- 名称：astrbot
- URL：ws://astrbot:6199/ws
- 其余保持默认，启用该配置并保存

💡 这里假设 AstrBot 与 NapCat 在同一个 docker compose 网络中通过容器名互访（见第七章，我们将把它们放入同一网络）。如果你选择分开部署，可将 URL 填为 ws://宿主机内网IP:6199/ws。

七、部署 AstrBot

7.1 编写 docker-compose.yml

cd /opt/astrbot
cat > docker-compose.yml << 'EOF'
services:
  astrbot:
    image: soulter/astrbot:latest
    container_name: astrbot
    restart: always
    ports:
      - "6185:6185"     # AstrBot WebUI
      - "6199:6199"     # aiocqhttp 适配器监听端口（NapCat 反向WS连接此端口）
    environment:
      - TZ=Asia/Shanghai
    volumes:
      - ./data:/AstrBot/data
    networks:
      - napcat-network

networks:
  napcat-network:
    external: true
EOF

7.2 启动 AstrBot

docker compose up -d
docker logs -f astrbot

看到 WebUI 已启动 之类日志即成功，Ctrl+C 退出。

7.3 访问 AstrBot WebUI

浏览器打开：

http://你的公网IP:6185

默认用户名：astrbot
默认密码：astrbot

登录后请立即在「设置」中修改默认账号密码。 Astrbot

八、配置 AstrBot 对接 NapCat

进入 AstrBot WebUI → 平台适配器（或「消息平台」）→ 新增适配器
选择 aiocqhttp（OneBot v11 / NapCat / Lagrange 等）
配置项填写：
- 启用反向 WebSocket（正向模式关闭）：开启
- 监听端口：6199
- 其他保持默认
保存配置

此时回到 NapCat WebUI，查看之前添加的反向 WS 连接状态，应显示已连接。

九、配置大模型服务商

以 DeepSeek 为例：

AstrBot WebUI → 大模型服务商 → 新增服务商
选择 deepseek（或选择 OpenAI 兼容并填入对应 base_url）
填入：
- API Key：你在 DeepSeek 开放平台申请的 Key
- 模型：如 deepseek-chat
保存后点击启用

💡 其他服务商（OpenAI、Moonshot、智谱、Gemini 等）同理，选择对应模板填 Key 即可。

十、测试机器人

用另一个 QQ 号（你的个人号）添加机器人为好友
私聊发送：/help —— 机器人应回复帮助菜单
直接发送任意消息，机器人会调用大模型回复

常用聊天指令（默认前缀 /，可在 AstrBot 设置中修改）：

指令	作用
`/help`	查看帮助
`/provider`	查看当前模型
`/reset`	重置当前会话上下文

在这里插入图片描述

十一、常见问题

Q1：QQ 扫码后提示「扫码失败 / 风控」

新注册的 QQ 号风控严格，建议使用注册超过一周、有正常使用记录的号码
服务器选择国内节点（境外 IP 易触发风控）
登录成功后不要频繁重启容器，保持设备信息（/opt/napcat/data 目录）不删除

Q2：NapCat 无法连接 AstrBot（反向 WS 显示未连接）

检查 AstrBot 是否启动：docker ps 确认两个容器都是 Up 状态
检查 NapCat 中反向 WS 的 URL 是否正确：ws://astrbot:6199/ws
检查两个容器是否都在 napcat-network 网络中：docker network inspect napcat-network

Q3：机器人不回复消息

检查 AstrBot 中是否启用了大模型服务商
私聊无需前缀；群聊默认需要 @机器人 或使用 / 前缀指令
查看 AstrBot 日志：docker logs --tail 100 astrbot

Q4：浏览器打不开 WebUI

确认雨云防火墙已放行 6099 / 6185 端口
确认服务器本地端口在监听：ss -tlnp | grep -E "6099|6185"

Q5：容器更新

cd /opt/napcat && docker compose pull && docker compose up -d
cd /opt/astrbot && docker compose pull && docker compose up -d

⚠️ 更新 NapCat 后可能需要重新扫码登录 QQ。

十二、日常维护

常用命令

# 查看运行状态
docker ps

# 查看日志
docker logs -f napcat
docker logs -f astrbot

# 重启 / 停止
cd /opt/napcat && docker compose restart
cd /opt/astrbot && docker compose stop

数据备份

机器人全部数据都在这两个目录，定期打包即可：

tar czf backup_$(date +%F).tar.gz /opt/napcat/config /opt/napcat/data /opt/astrbot/data

结语

至此，你已经拥有一台部署在雨云服务器上的 7×24 小时在线 QQ 大模型机器人。后续你还可以在 AstrBot 的 WebUI 中：

安装插件（搜索指令、图片生成、定时任务等）
接入多个消息平台（微信、飞书、钉钉、Telegram 等）
配置人格设定（人设 Prompt）、对话上下文长度等个性化参数

祝玩得愉快！

雨云UID：580502

DAMO开发者矩阵

DAMO开发者矩阵，由阿里巴巴达摩院和中国互联网协会联合发起，致力于探讨最前沿的技术趋势与应用成果，搭建高质量的交流与分享平台，推动技术创新与产业应用链接，围绕“人工智能与新型计算”构建开放共享的开发者生态。

更多推荐

展会与营销高端商务活动人形机器人决策支持

DAMO开发者矩阵

Dyna-2：世界-动作模型的百万小时规模化定律（上）

DAMO开发者矩阵

Dyna-2：世界-动作模型的百万小时规模化定律（下）

DAMO开发者矩阵

所有评论(0)

查看更多评论

2501_91919859

@2501_91919859

已为社区贡献1条内容

雨云服务器部署 AstrBot + NapCat 完整教程

2501_91919859

雨云服务器部署 AstrBot + NapCat 完整教程

目录

一、简介

二、准备工作

三、购买并连接雨云服务器

3.1 购买服务器

3.2 连接服务器

3.3 更新系统（可选但建议）

四、安装 Docker

4.1 一键安装

4.2 验证安装

4.3 设置开机自启

五、部署 NapCat

5.1 创建 Docker 网络（Macvlan）

5.2 创建目录与编排文件

5.3 启动 NapCat

5.4 雨云防火墙放行端口

六、登录 QQ

6.1 配置 OneBot v11 反向 WebSocket（推荐）

七、部署 AstrBot

7.1 编写 docker-compose.yml

7.2 启动 AstrBot

7.3 访问 AstrBot WebUI

八、配置 AstrBot 对接 NapCat

九、配置大模型服务商

十、测试机器人

十一、常见问题

Q1：QQ 扫码后提示「扫码失败 / 风控」

Q2：NapCat 无法连接 AstrBot（反向 WS 显示未连接）

Q3：机器人不回复消息

Q4：浏览器打不开 WebUI

Q5：容器更新

十二、日常维护

常用命令

数据备份

结语

所有评论(0)

温馨提示：您尚未绑定手机号

2501_91919859