AstrBot 教程

官方参考 #

• AstrBot 官方文档
• AstrBot GitHub
• Docker 部署
• 接入消息平台
• 接入 AI
• 插件开发

适用场景 #

AstrBot 更适合这些需求：

Docker Compose 部署 #

先准备 Docker 环境，再拉取官方仓库：

git clone https://github.com/AstrBotDevs/AstrBot
cd AstrBot

使用项目提供的 compose 配置启动：

docker compose up -d

查看容器状态：

docker compose ps

查看日志：

docker compose logs -f

单容器部署 #

如果只想快速启动 AstrBot，可以使用官方镜像并挂载数据目录：

mkdir -p ~/astrbot/data
cd ~/astrbot

docker run -itd \
  -p 6185:6185 \
  -p 6199:6199 \
  -v "$PWD/data:/AstrBot/data" \
  -v /etc/localtime:/etc/localtime:ro \
  --name astrbot \
  soulter/astrbot:latest

常用检查：

docker logs -f astrbot
docker ps --filter name=astrbot

如果部署在服务器上，需要在防火墙、安全组或反向代理中放行对应端口。

接入消息平台 #

AstrBot 的典型接入顺序：

1. 确认 AstrBot 本体和 WebUI 正常运行。
2. 选择消息平台适配器。
3. 在平台侧创建 Bot 或应用。
4. 把平台提供的 Token、Secret、Webhook 或 WebSocket 参数填入 AstrBot。
5. 发送测试消息，确认收发链路正常。

常见平台包括：

接入 AI 服务 #

接入模型时建议先准备一张配置表：

验证方法：

WebUI 中保存模型配置
-> 发送一条简单测试消息
-> 查看 AstrBot 日志
-> 确认模型服务侧是否有请求记录

插件维护 #

插件适合扩展这些能力：

• 自定义指令。
• 监听消息事件。
• 调用外部 API。
• 管理群聊或频道规则。
• 做定时任务或自动回复。

维护插件时建议：

1. 先确认插件是否支持当前 AstrBot 版本。
2. 插件配置只写占位变量，不写真实密钥。
3. 安装或升级后重启 AstrBot。
4. 查看日志确认没有导入错误、依赖错误或权限错误。

日常维护 #

常用命令：

docker compose ps
docker compose logs --tail=120
docker compose pull
docker compose up -d

如果是单容器部署：

docker logs --tail=120 astrbot
docker pull soulter/astrbot:latest
docker restart astrbot

建议定期备份：

• data/ 数据目录。
• 插件配置。
• 平台接入配置。
• 自定义规则和知识库文件。

排障清单 #