AstrBot 全平台零基础部署教程-殇恋社区

一、AstrBot 是什么

AstrBot 是一个开源的多平台聊天机器人框架，主要面向 QQ、微信、Telegram 等即时通讯软件。它的核心功能是：把 AI 大语言模型接入到聊天平台中，让机器人能像真人一样和你对话。

举个例子：你把 AstrBot 部署好，配置上 DeepSeek 的 API，然后在 QQ 群里 @机器人问“今天深圳天气怎么样”，机器人就会调用 AI 生成一段回复发到群里。

AstrBot 的几个核心特点：

支持多种大模型：OpenAI（GPT-4/3.5）、DeepSeek、豆包、通义千问、智谱 AI 等，在后台切换就行。
支持多种聊天平台：QQ（个人号）、QQ 频道（官方机器人）、微信（个人号，需谨慎使用）、Telegram、飞书、钉钉。
有 Web 管理后台：所有配置在网页上点一点就能完成，不需要手写配置文件。
插件系统：图片生成、表情包、每日新闻、AI 绘画等，社区持续贡献新插件。
完全开源免费：GitHub 仓库地址：https://github.com/Soulter/AstrBot

二、部署之前：你需要准备的三样东西

在动手部署之前，需要先准备好以下三样东西。这三样缺一不可，请确认全部准备好之后再往下看。

2.1 一台电脑或云服务器

如果只是想体验一下：用自己的 Windows 电脑就可以。缺点是一关机机器人就下线。
如果想要 24 小时在线：买一台云服务器。推荐阿里云、腾讯云的最低配置（1 核 CPU、1G 内存、CentOS 7.9 或 Ubuntu 20.04 系统），学生价一年几十块钱。
如果用的是 Mac：同样可以部署，本教程会包含 macOS 的部署步骤。

2.2 一个 AI 大模型的 API Key

AI 大模型不是免费用的，需要去对应的平台注册账号、获取 API Key。本教程以DeepSeek 为例，因为它注册简单、国内可直接访问、新用户赠送免费额度（2025 年政策，具体以官网为准）。

获取 DeepSeek API Key 的步骤（全程 5 分钟）：

打开浏览器，访问 https://platform.deepseek.com
点击右上角“注册”，用手机号或邮箱注册账号。
注册成功后登录，进入管理控制台。
在左侧菜单找到 “API Keys”，点击进入。
点击 “创建 API Key” 按钮，给这个 Key 起个名字（比如“astrbot”），点击确定。
页面会显示一串类似 sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 的密钥。立刻复制并保存到一个安全的地方（记事本或密码管理器）。这个密钥只会显示这一次，关闭页面后就看不到了。
确认账户有余额或免费额度。DeepSeek 新用户注册通常赠送一定额度，用完后需要充值（价格比 OpenAI 便宜很多，几块钱能用很久）。

2.3 一个 QQ 号作为机器人

强烈建议申请一个全新的 QQ 号，不要使用自己日常使用的 QQ 号。原因：机器人被风控的风险始终存在，万一被封号，不会影响你的主号。
用手机 QQ 或 PC QQ 注册一个新的 QQ 号。记住账号和密码。
用手机 QQ 登录这个新号一次，完善一些基本资料（头像、昵称等），让这个号看起来像一个正常用户。这一步可以减少后续登录时的风控概率。

三、部署方式一：Windows 直接部署（适合体验和测试）

适用场景：你有一台 Windows 10 或 Windows 11 电脑，想在本地快速跑起来体验一下。

3.1 安装 Python

打开浏览器，访问 https://www.python.org/downloads/
页面会自动识别你是 Windows 系统，显示一个大大的黄色下载按钮。点击它，下载最新的 Python 安装包（文件名类似 python-3.12.x-amd64.exe）。
双击下载好的安装包，进入安装界面。
【关键步骤】在安装界面的第一页，务-必-勾-选底部的复选框 “Add Python to PATH”（把 Python 添加到系统环境变量）。不勾选这一步，后续在终端里执行 python 命令会提示找不到。
勾选后，点击 “Install Now”（立即安装）。等待进度条走完。
安装完成后，点击 “Disable path length limit”（如果有这个选项的话），然后关闭安装程序。

验证 Python 是否安装成功：

按键盘上的 Win + R 组合键，输入 cmd，回车。会弹出一个黑色背景的命令提示符窗口。
在窗口中输入：python --version，回车。
如果看到类似 Python 3.12.0 的输出，说明安装成功。

3.2 下载 AstrBot 源代码

打开浏览器，访问 https://github.com/Soulter/AstrBot
在页面右侧，找到绿色的 “Code” 按钮。
点击这个按钮，在弹出的菜单中点击 “Download ZIP”。
浏览器会下载一个 ZIP 压缩包。
下载完成后，找到这个 ZIP 文件（通常在“下载”文件夹中），右键点击 → 选择“全部解压缩”。
解压到一个你方便找到的位置，比如桌面。解压后会生成一个名为 AstrBot-main 或 AstrBot-x.x.x 的文件夹。
进入这个文件夹，点击地址栏，复制这个文件夹的完整路径（类似 C:\Users\你的用户名\Desktop\AstrBot-main）。

3.3 安装项目依赖

打开命令提示符（Win + R → 输入 cmd → 回车）。
输入 cd 你刚才复制的文件夹路径，回车。例如：cd C:\Users\张三\Desktop\AstrBot-main
输入 pip install -r requirements.txt，回车。
此时终端会开始下载并安装项目所需的所有第三方库。这个过程可能需要 3-10 分钟，取决于你的网络速度。你会看到大量的下载进度条在滚动。
等待直到出现 Successfully installed ... 这样的提示，说明依赖安装完成。

如果安装过程中出现红色的报错信息，常见原因及解决方案：

pip 版本过旧：执行 python -m pip install --upgrade pip 升级 pip 后再重新安装依赖。
缺少 C++ 构建工具：某些依赖需要编译，去 https://visualstudio.microsoft.com/visual-cpp-build-tools/ 下载安装 Microsoft C++ Build Tools。
网络超时：切换 pip 镜像源为国内源：pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

3.4 启动 AstrBot

在同一个命令提示符窗口中，输入 python main.py，回车。
如果是第一次启动，AstrBot 会自动在项目文件夹下生成默认配置文件。
等待终端出现类似 管理面板地址: http://127.0.0.1:6185 的提示。这说明 AstrBot 已经成功启动。
打开浏览器，在地址栏输入 http://127.0.0.1:6185（或 http://localhost:6185），回车。
你会看到 AstrBot 的 Web 管理后台登录页面。默认用户名和密码通常是 admin / admin（具体以页面提示或项目文档为准，首次登录后建议修改密码）。

注意：命令提示符窗口不要关闭。关闭窗口就等于关闭了 AstrBot 服务。保持这个窗口打开，AstrBot 就会一直运行。

3.5 后续配置（所有平台共用）

Windows 部署到这里就完成了。接下来的配置步骤（设置 AI 模型、登录 QQ 机器人）在所有平台上都是相同的，请跳到第五节“配置 AstrBot”继续阅读。

四、部署方式二：Linux 云服务器部署（适合长期运行）

适用场景：你买了一台云服务器（阿里云/腾讯云/华为云），希望机器人 24 小时在线，不依赖自己的电脑。

本教程以阿里云 + Ubuntu 22.04 系统为例。其他云服务商（腾讯云、华为云）和 CentOS 系统的操作大同小异。

4.1 购买并连接到云服务器

购买服务器（如果你已经有了服务器，跳过这一步）：

登录阿里云官网（aliyun.com），搜索“云服务器 ECS”。
选择最低配置：1 核 CPU、1GB 内存、40GB 云盘。地域选离你最近的（如华东 1-杭州）。
系统镜像选择 Ubuntu 22.04 64 位。
设置 root 用户的登录密码，记牢这个密码。
完成购买。

连接到服务器：

Windows 用户：

下载并安装 FinalShell（免费的服务器管理工具，国内下载方便）或 PuTTY。
打开 FinalShell，点击左上角的“新建连接”。
填写：主机（你的服务器公网 IP，在阿里云控制台可以看到）、用户名 root、密码（购买时设置的密码）。点击确定并连接。

Mac 用户：

打开“终端”应用。
输入 ssh root@你的服务器公网IP，回车。
提示输入密码时，粘贴或输入 root 密码，回车。输入密码时屏幕不会显示任何字符，这是正常的安全机制。

连接成功后，终端提示符会变成 root@xxx:~#，表示你已经登录到了云服务器。

4.2 在服务器上安装 Docker

我们使用 Docker 来部署 AstrBot，因为 Docker 会自动处理所有环境依赖，不需要手动安装 Python、手动安装依赖。

依次执行以下命令（一行一行复制粘贴，每行回车）：

# 1. 更新系统包列表
sudo apt update

# 2. 安装必要的工具
sudo apt install -y ca-certificates curl

# 3. 添加 Docker 的官方 GPG 密钥
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# 4. 添加 Docker 软件源
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# 5. 再次更新并安装 Docker
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

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

# 7. 验证安装
docker --version

如果最后一步输出了 Docker 版本号，说明安装成功。

4.3 用 Docker 部署 AstrBot

# 1. 创建数据目录（用来持久化保存配置）
mkdir -p ~/astrbot/data

# 2. 拉取镜像并启动容器
docker run -d \
  --name astrbot \
  --restart unless-stopped \
  -p 6185:6185 \
  -v ~/astrbot/data:/AstrBot/data \
  soulter/astrbot:latest

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

如果看到一行包含 astrbot 的记录，且 STATUS 显示 Up，说明容器启动成功。

访问管理后台：打开浏览器，输入 http://你的服务器公网IP:6185。如果页面打不开，说明云服务器的安全组没有放行 6185 端口。去阿里云控制台 → 安全组 → 添加规则：协议 TCP、端口 6185、允许所有 IP 访问。

4.4 Docker 常用管理命令

# 查看日志（排查问题时使用）
docker logs astrbot

# 重启容器（修改配置后使用）
docker restart astrbot

# 停止容器
docker stop astrbot

# 更新到最新版
docker pull soulter/astrbot:latest
docker stop astrbot
docker rm astrbot
# 然后重新执行上面的 docker run 命令

4.5 直接部署（不使用 Docker）

如果你不想使用 Docker，也可以在服务器上直接安装 Python 并运行：

# 1. 安装 Python 3.10+
sudo apt update
sudo apt install -y python3 python3-pip git

# 2. 克隆项目
cd ~
git clone https://github.com/Soulter/AstrBot.git
cd AstrBot

# 3. 安装依赖
pip3 install -r requirements.txt

# 4. 启动
python3 main.py

这种方式在关闭终端窗口后程序会停止。可以用 nohup python3 main.py & 让它在后台运行，或者用 screen、tmux 等工具保持会话。

五、部署方式三：macOS 部署

适用场景：你用的是 Mac 电脑（MacBook、iMac、Mac mini 等）。

5.1 安装 Python

macOS 自带 Python，但版本通常较旧。推荐用 Homebrew 安装最新版：

# 1. 安装 Homebrew（如果还没装）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 2. 用 Homebrew 安装 Python
brew install python@3.12

# 3. 验证
python3 --version

5.2 下载并运行 AstrBot

# 1. 克隆项目到本地
cd ~/Desktop
git clone https://github.com/Soulter/AstrBot.git
cd AstrBot

# 2. 安装依赖
pip3 install -r requirements.txt

# 3. 启动
python3 main.py

访问 http://127.0.0.1:6185 进入管理后台。

六、配置 AstrBot——让机器人“活”起来

无论你用哪种方式部署，部署完成后都需要在 Web 管理后台中进行配置。以下是所有平台通用的配置步骤。

6.1 登录管理后台

浏览器访问管理后台地址。Windows/Mac 本地部署是 http://127.0.0.1:6185，云服务器是 http://服务器IP:6185。
使用默认用户名密码登录（通常是 admin/admin，以页面提示为准）。

6.2 配置 AI 大模型

在左侧菜单中找到“模型配置”或“大模型”相关选项。
选择你要使用的模型提供商，比如 DeepSeek。
在 API Key 输入框中粘贴之前准备好的 sk-xxxxxxxx 密钥。
如果有模型版本选择（如 deepseek-chat），选择一个即可。
点击保存。

6.3 配置 QQ 机器人登录

在左侧菜单中找到“消息平台”或“平台管理”。
选择 QQ（个人号）。
填写机器人的 QQ 号和密码。
选择登录协议。建议先尝试默认协议，如果登录失败再切换到其他协议。
点击保存，然后点击“登录”按钮。
观察日志输出，如果显示“登录成功”，说明 QQ 机器人已上线。

QQ 机器人登录常见问题：

提示“密码错误”：确认密码是否正确。注意 QQ 密码不要包含特殊字符导致转义问题。
提示“滑块验证”或“需要验证”：这是 QQ 的反机器人机制。尝试在配置中切换登录协议，或者在同一台电脑上先用普通 QQ 客户端登录这个机器人号一次，然后再尝试用 AstrBot 登录。
一直显示“登录中”：检查服务器网络是否能正常访问 QQ 服务器。有些海外服务器可能被屏蔽，需要换国内服务器。

6.4 测试机器人

用你日常使用的 QQ 号，添加机器人为好友，或者把机器人拉进一个测试群。
在群聊中 @机器人说一句话，或者在私聊中直接发送消息。
机器人应该会用 AI 生成的内容回复你。

七、配置其他聊天平台

AstrBot 不仅支持 QQ，还支持以下平台。在管理后台的“消息平台”中可以进行配置。

7.1 QQ 频道（官方机器人）

QQ 频道是腾讯官方提供的机器人接入方式，比个人号登录更稳定，但需要注册成为开发者。步骤如下：

访问 QQ 开放平台（q.qq.com），注册开发者账号。
创建机器人应用，获取 AppID 和 Token。
在 AstrBot 管理后台选择“QQ 频道”，填入 AppID 和 Token。
保存并启用。

7.2 Telegram

在 Telegram 中搜索 @BotFather，创建一个新的 Bot。
BotFather 会给你一个 Token（格式类似 1234567890:ABCdef...）。
在 AstrBot 管理后台选择“Telegram”，填入 Token。
保存并启用。

7.3 微信（个人号）

⚠️ 警告：微信个人号的机器人接入违反微信用户协议，有极高概率被封号。不推荐使用。如果你确实需要，AstrBot 社区有相关插件，但风险自负。

7.4 飞书 / 钉钉

AstrBot 同样支持飞书和钉钉。在管理后台的“消息平台”中选择对应平台，根据提示填写应用的 AppID、AppSecret 等信息即可。具体获取方式请参考各平台的官方开发者文档。

八、常见问题汇总

Q1：启动报错“ModuleNotFoundError: No module named ‘xxx’”

依赖没有安装完整。重新执行 pip install -r requirements.txt。如果某个特定库反复安装失败，尝试单独安装它：pip install 库名。

Q2：管理后台能打开，但机器人不发消息

检查 AI 模型配置是否正确，API Key 是否有效。
检查 AI 平台账户是否还有余额或额度。
在管理后台查看“日志”页面，看有没有红色的报错信息。

Q3：云服务器部署后访问不了 6185 端口

去云服务商的控制台，找到安全组设置，添加入站规则：协议 TCP、端口 6185、来源 0.0.0.0/0（允许所有 IP）。保存后刷新页面即可。

Q4：如何更新 AstrBot 到最新版

Docker 部署：docker pull soulter/astrbot:latest && docker stop astrbot && docker rm astrbot，然后重新执行 docker run 命令。
直接部署：进入项目目录，执行 git pull && pip install -r requirements.txt，然后重启。

九、总结

到这里，你应该已经拥有一个能正常工作的 AI 聊天机器人了。回顾一下整个过程：

准备好三样东西：运行环境（电脑/服务器）、AI API Key、机器人 QQ 号。
选择合适的部署方式：Windows 直接跑、Linux Docker、macOS 直接跑。
启动后进入 Web 管理后台，配置 AI 模型和 QQ 机器人。
@机器人发消息，测试对话。

AstrBot 是一个活跃的开源项目，功能在不断更新。部署过程中如果遇到问题，可以去 GitHub 仓库提 Issue，或者加入项目的 QQ 群/社区寻求帮助。项目地址：https://github.com/Soulter/AstrBot

官方网站：https://docs.astrbot.app/what-is-astrbot.html

分享是一种美德！

THE END

AstrBot 全平台零基础部署教程