📦 AstrBot 详细部署教程

AstrBot 是一个开源的一站式 Agent 聊天机器人平台及开发框架，支持接入 QQ、微信、飞书、钉钉、Telegram 等主流即时通讯平台。它集成了大语言模型对话、多模态、Agent、MCP、知识库等能力，并拥有超过 1000 个社区插件。

准备工作：

  • 一台服务器（或本地电脑），推荐配置 2GB 内存以上。
  • （可选）一个想要接入的 IM 平台账号（如 QQ、飞书等）。
  • 一个 LLM 服务提供商的 API Key（如 DeepSeek、OpenAI、硅基流动等）。

⚡ 方案一：uv 一键部署（推荐新手体验）

这是官方推荐的快速体验方式，适合熟悉命令行的用户。此方式部署的 AstrBot 不支持通过 WebUI 升级，更新需重新执行命令。

1. 安装 uv 包管理器

访问 uv 官方网站 安装，它支持 Linux、Windows 和 macOS。

2. 安装并运行 AstrBot

打开终端，执行以下命令：

1
2
3
4
5
6
7
8
# 使用 uv 安装 astrbot，并指定 Python 3.12 版本
uv tool install astrbot --python 3.12

# 仅首次运行需要初始化环境（这会将 AstrBot 安装到当前目录）[citation:9]
astrbot init

# 启动 AstrBot
astrbot run

注意：macOS 用户首次运行因安全检查，启动可能较慢（约 10-20 秒）。

3. 更新 AstrBot

1
uv tool upgrade astrbot --python 3.12

🐳 方案二：Docker 部署（推荐生产环境）

Docker 部署更稳定，适合需要长期运行的生产环境。

1. 克隆项目并启动

确保已安装 Docker 和 Git，然后执行：

1
2
3
git clone https://github.com/AstrBotDevs/AstrBot --depth 1
cd AstrBot
docker compose up -d

国内网络加速：若拉取镜像失败，可编辑 compose.yml 文件，将 image: soulter/astrbot:latest 替换为 image: m.daocloud.io/docker.io/soulter/astrbot:latest。

🖥️ 方案三：宝塔面板部署（适合可视化操作）

此方法适合使用宝塔面板的用户，可通过 Docker 容器部署并与 NapCat（QQ 协议端）配合，快速搭建 QQ 机器人。

1. 创建 AstrBot 容器

登录宝塔面板 → Docker → 容器 → 创建容器：

  • 容器名称：astrbot（自定义）
  • 镜像：soulter/astrbot:latest
  • 端口映射：6199:6199（反向 WebSocket）和 6185:6185（WebUI）

2. 创建 NapCat 容器

NapCat 负责与 QQ 通信，作为 AstrBot 的“耳朵”和“嘴巴”。

  • 参考相关教程，创建 NapCat 容器，映射 6099:6099 WebUI 端口。
  • 登录 NapCat WebUI 并使用手机 QQ 扫码登录。

3. 连接两个容器

  • 在宝塔面板的 Docker → 网络 中创建一个新网络（如 astrbot-napcat）。
  • 将 astrbot 和 napcat 两个容器都加入到这个新网络，并记录 astrbot 容器的 IP 地址。

4. 配置 NapCat 的 WebSocket 客户端

在 NapCat WebUI 中，新建一个 WebSocket 客户端，URL 填写 ws://<astrbot容器IP>:6199/ws，消息格式选 Array，保存。

5. 配置 AstrBot

访问 http://<服务器IP>:6185 登录 AstrBot WebUI（默认账号密码均为 astrbot），在 机器人 页面创建 OneBot v11 类型机器人，反向 WebSocket 地址填写 astrbot 容器的 IP 和端口 6199。

🔧 通用配置步骤（所有方案适用）

无论使用哪种部署方式，启动后都需要进行基础配置。

1. 访问 WebUI 并登录

  • 访问地址：http://<你的服务器IP>:6185。
  • 默认账号/密码：均为 astrbot。首次登录会强制修改密码。

2. 配置 LLM 模型提供商

以硅基流动 (SiliconFlow) 为例：

  1. 进入 服务提供商 → 新增提供商 → 选择 硅基流动。
  2. 填写从硅基流动获取的 API Key 和 模型名称（如 Qwen/Qwen2.5-7B-Instruct）。
  3. 点击 保存，并可用“刷新”按钮测试连通性。

3. 接入消息平台（以飞书为例）

  1. 在 AstrBot WebUI 的 机器人 页面，点击 + 创建机器人。
  2. 选择 lark（飞书）。
  3. 填写从飞书开发者后台获取的 app_id 和 app_secret。
  4. 在 配置文件 中，将默认聊天模型选择为你刚创建的提供商。
  5. 在飞书开发者后台，配置事件订阅（使用长连接）和权限管理，并发布应用。
  6. 在飞书 APP 中将机器人添加到群聊，发送 hi 测试响应。

🚀 扩展与进阶功能

  • 插件市场：AstrBot 拥有超过 1000 个插件，可在 WebUI 中一键安装。
  • 接入 QQ：通常需要配合 NapCatQQ 等协议端，通过 OneBot v11 协议连接。可直接使用社区提供的一键部署脚本（面向国内网络）。
  • Agent 沙箱：支持隔离、安全地执行代码和 Shell 调用，适合运行自动化任务。
  • 知识库功能：内置 RAG 能力，可为机器人构建专属知识库。

❓ 常见问题

  • 无法访问 WebUI：检查服务器防火墙/安全组是否放行 6185 端口。
  • Docker 拉取镜像失败：尝试使用国内镜像加速器，或替换 compose.yml 中的镜像地址。
  • 消息平台无法连接：确认 WebSocket 地址、端口、Token 配置是否正确，以及容器间网络是否互通。
  • 如何更新：uv 部署方式用 uv tool upgrade astrbot 命令；Docker 部署方式在项目目录下执行 docker compose pull && docker compose up -d。

更详细的配置和故障排除，可查阅 AstrBot 官方文档。