mirror of
https://github.com/AstrBotDevs/AstrBot
synced 2026-07-17 01:49:15 +08:00
236 lines
5.2 KiB
Markdown
236 lines
5.2 KiB
Markdown
# 项目启动指南
|
||
|
||
本文档详细介绍 AstrBot 项目的启动流程、初始化步骤以及相关配置。
|
||
|
||
## 环境要求
|
||
|
||
- Python 3.10 - 3.13
|
||
- uv 包管理器（推荐）
|
||
|
||
## 安装方式
|
||
|
||
### 方式一：使用 uv 一键安装（推荐）
|
||
|
||
```bash
|
||
# 安装 AstrBot
|
||
uv tool install astrbot
|
||
|
||
# 初始化项目（仅首次需要）
|
||
astrbot init
|
||
|
||
# 启动项目
|
||
astrbot run
|
||
```
|
||
|
||
### 方式二：开发模式安装
|
||
|
||
```bash
|
||
# 克隆项目
|
||
git clone https://github.com/AstrBotDevs/AstrBot
|
||
cd AstrBot
|
||
|
||
# 安装开发版本
|
||
uv tool install git+https://github.com/AstrBotDevs/AstrBot@dev
|
||
|
||
# 初始化
|
||
astrbot init
|
||
|
||
# 启动
|
||
astrbot run
|
||
```
|
||
|
||
### 方式三：从源码运行
|
||
|
||
```bash
|
||
git clone https://github.com/AstrBotDevs/AstrBot
|
||
cd AstrBot
|
||
|
||
# 创建虚拟环境
|
||
uv venv --seed
|
||
source .venv/bin/activate # Linux/macOS
|
||
# 或: .venv\Scripts\activate # Windows
|
||
|
||
# 安装依赖
|
||
uv pip install -e .
|
||
|
||
# 初始化
|
||
astrbot init
|
||
|
||
# 启动
|
||
astrbot run
|
||
```
|
||
|
||
## 初始化详解
|
||
|
||
`astrbot init` 命令执行以下操作：
|
||
|
||
1. **创建 `.astrbot` 标记文件** - 标识 AstrBot 根目录
|
||
2. **创建数据目录结构**：
|
||
- `data/` - 主数据目录
|
||
- `data/config/` - 配置文件目录
|
||
- `data/plugins/` - 插件目录
|
||
- `data/temp/` - 临时文件目录
|
||
- `data/skills/` - 技能目录
|
||
3. **生成配置文件** `data/cmd_config.json`
|
||
4. **生成环境变量文件** `.env`（从 `config.template` 模板）
|
||
5. **安装 Dashboard**（可选，非服务器模式）
|
||
|
||
### 初始化参数
|
||
|
||
| 参数 | 说明 |
|
||
|------|------|
|
||
| `-y, --yes` | 跳过确认提示 |
|
||
| `-b, --backend-only` | 仅初始化后端，不安装 Dashboard |
|
||
| `-u, --admin-username` | 设置 Dashboard 管理员用户名 |
|
||
| `--root` | 指定 AstrBot 根目录 |
|
||
|
||
## 启动详解
|
||
|
||
`astrbot run` 命令启动 AstrBot 服务。
|
||
|
||
### 启动参数
|
||
|
||
| 参数 | 说明 |
|
||
|------|------|
|
||
| `-H, --host` | Dashboard 绑定地址 |
|
||
| `-p, --port` | Dashboard 绑定端口 |
|
||
| `-r, --reload` | 启用插件自动重载 |
|
||
| `-b, --backend-only` | 仅启动后端，不启动 WebUI |
|
||
| `-l, --log-level` | 日志级别（DEBUG, INFO, WARNING, ERROR） |
|
||
| `--ssl-cert` | SSL 证书路径 |
|
||
| `--ssl-key` | SSL 私钥路径 |
|
||
| `--ssl-ca` | SSL CA 证书路径 |
|
||
| `--debug` | 调试模式 |
|
||
| `-c, --service-config` | 服务配置文件路径 |
|
||
|
||
### 启动输出
|
||
|
||
启动成功后会显示：
|
||
|
||
```
|
||
AstrBot is running...
|
||
Visit the dashboard at : https://dash.astrbot.men/
|
||
Backend Requests : localhost or based on https
|
||
```
|
||
|
||
## 环境变量
|
||
|
||
### 核心配置
|
||
|
||
| 变量 | 说明 | 默认值 |
|
||
|------|------|--------|
|
||
| `ASTRBOT_ROOT` | AstrBot 根目录 | 自动检测 |
|
||
| `ASTRBOT_LOG_LEVEL` | 日志级别 | INFO |
|
||
| `ASTRBOT_RELOAD` | 启用插件热重载 | - |
|
||
| `ASTRBOT_DISABLE_METRICS` | 禁用指标上传 | - |
|
||
|
||
### Dashboard 配置
|
||
|
||
| 变量 | 说明 | 默认值 |
|
||
|------|------|--------|
|
||
| `ASTRBOT_DASHBOARD_ENABLE` | 启用 Dashboard | True |
|
||
| `ASTRBOT_HOST` | Dashboard 绑定地址 | 0.0.0.0 |
|
||
| `ASTRBOT_PORT` | Dashboard 绑定端口 | 8000 |
|
||
|
||
### SSL 配置
|
||
|
||
| 变量 | 说明 |
|
||
|------|------|
|
||
| `ASTRBOT_SSL_ENABLE` | 启用 SSL |
|
||
| `ASTRBOT_SSL_CERT` | SSL 证书路径 |
|
||
| `ASTRBOT_SSL_KEY` | SSL 私钥路径 |
|
||
| `ASTRBOT_SSL_CA_CERTS` | CA 证书路径 |
|
||
|
||
### 代理配置
|
||
|
||
| 变量 | 说明 |
|
||
|------|------|
|
||
| `http_proxy` | HTTP 代理地址 |
|
||
| `https_proxy` | HTTPS 代理地址 |
|
||
| `no_proxy` | 不使用代理的地址列表 |
|
||
|
||
### 平台集成
|
||
|
||
| 变量 | 说明 |
|
||
|------|------|
|
||
| `DASHSCOPE_API_KEY` | 阿里云 DashScope API Key（用于 Rerank） |
|
||
| `COZE_API_KEY` | Coze API Key |
|
||
| `COZE_BOT_ID` | Coze Bot ID |
|
||
| `BAY_DATA_DIR` | Computer Use 数据目录 |
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
AstrBot/
|
||
├── .astrbot # AstrBot 根目录标记
|
||
├── .env # 环境变量配置
|
||
├── data/ # 数据目录
|
||
│ ├── config/
|
||
│ │ └── cmd_config.json # 主配置文件
|
||
│ ├── plugins/ # 插件目录
|
||
│ ├── skills/ # 技能目录
|
||
│ └── temp/ # 临时文件目录
|
||
├── astrbot/ # 核心代码
|
||
│ ├── cli/ # 命令行工具
|
||
│ ├── core/ # 核心模块
|
||
│ ├── dashboard/ # Dashboard 前端
|
||
│ └── ...
|
||
└── ...
|
||
```
|
||
|
||
## 配置文件
|
||
|
||
主配置文件位于 `data/cmd_config.json`，包含：
|
||
|
||
- LLM 提供商配置
|
||
- 平台适配器配置
|
||
- 插件设置
|
||
- Dashboard 设置
|
||
- 代理设置
|
||
|
||
## 常见问题
|
||
|
||
### 端口被占用
|
||
|
||
如果启动时提示端口被占用：
|
||
|
||
```bash
|
||
# 查看占用端口的进程
|
||
lsof -i :8000
|
||
|
||
# 或使用其他端口启动
|
||
astrbot run --port 8080
|
||
```
|
||
|
||
### 多个实例冲突
|
||
|
||
AstrBot 使用锁文件机制防止同时运行多个实例。如需强制启动：
|
||
|
||
```bash
|
||
# 删除锁文件
|
||
rm astrbot.lock
|
||
|
||
# 重新启动
|
||
astrbot run
|
||
```
|
||
|
||
### Dashboard 无法访问
|
||
|
||
1. 确认 `ASTRBOT_DASHBOARD_ENABLE` 为 `True`
|
||
2. 检查防火墙设置
|
||
3. 确认端口未被阻止
|
||
|
||
### 查看日志
|
||
|
||
```bash
|
||
# 以调试模式启动查看详细日志
|
||
astrbot run --debug --log-level DEBUG
|
||
```
|
||
|
||
## 下一步
|
||
|
||
- [配置模型提供商](providers/llm.md)
|
||
- [安装插件](use/plugin.md)
|
||
- [使用技能](use/skills.md)
|
||
- [部署到服务器](./deploy/astrbot/docker.md)
|