mirror of
https://github.com/AstrBotDevs/AstrBot
synced 2026-07-16 01:40:15 +08:00
docs: add project startup guide for zh and en
Document AstrBot startup process including: - Installation methods (uv, dev mode, from source) - Initialization details and options - Startup options and parameters - Environment variables - Directory structure - Troubleshooting guide
This commit is contained in:
LIghtJUNction
235
docs/en/startup.md
Normal file
235
docs/en/startup.md
Normal file
@@ -0,0 +1,235 @@
|
||||
# Project Startup Guide
|
||||
|
||||
This document provides detailed instructions on how to start the AstrBot project, including initialization steps and configuration.
|
||||
|
||||
## Requirements
|
||||
|
||||
- Python 3.10 - 3.13
|
||||
- uv package manager (recommended)
|
||||
|
||||
## Installation
|
||||
|
||||
### Method 1: One-Click Installation with uv (Recommended)
|
||||
|
||||
```bash
|
||||
# Install AstrBot
|
||||
uv tool install astrbot
|
||||
|
||||
# Initialize the project (first time only)
|
||||
astrbot init
|
||||
|
||||
# Start the project
|
||||
astrbot run
|
||||
```
|
||||
|
||||
### Method 2: Development Mode Installation
|
||||
|
||||
```bash
|
||||
# Clone the project
|
||||
git clone https://github.com/AstrBotDevs/AstrBot
|
||||
cd AstrBot
|
||||
|
||||
# Install development version
|
||||
uv tool install git+https://github.com/AstrBotDevs/AstrBot@dev
|
||||
|
||||
# Initialize
|
||||
astrbot init
|
||||
|
||||
# Start
|
||||
astrbot run
|
||||
```
|
||||
|
||||
### Method 3: Run from Source
|
||||
|
||||
```bash
|
||||
git clone https://github.com/AstrBotDevs/AstrBot
|
||||
cd AstrBot
|
||||
|
||||
# Create virtual environment
|
||||
uv venv
|
||||
source .venv/bin/activate # Linux/macOS
|
||||
# or: .venv\Scripts\activate # Windows
|
||||
|
||||
# Install dependencies
|
||||
uv pip install -e .
|
||||
|
||||
# Initialize
|
||||
astrbot init
|
||||
|
||||
# Start
|
||||
astrbot run
|
||||
```
|
||||
|
||||
## Initialization Details
|
||||
|
||||
The `astrbot init` command performs the following operations:
|
||||
|
||||
1. **Creates `.astrbot` marker file** - Identifies the AstrBot root directory
|
||||
2. **Creates data directory structure**:
|
||||
- `data/` - Main data directory
|
||||
- `data/config/` - Configuration files
|
||||
- `data/plugins/` - Plugins directory
|
||||
- `data/temp/` - Temporary files directory
|
||||
- `data/skills/` - Skills directory
|
||||
3. **Generates configuration file** `data/cmd_config.json`
|
||||
4. **Generates environment file** `.env` (from `config.template`)
|
||||
5. **Installs Dashboard** (optional, not recommended for server mode)
|
||||
|
||||
### Initialization Options
|
||||
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| `-y, --yes` | Skip confirmation prompts |
|
||||
| `-b, --backend-only` | Initialize backend only, skip Dashboard |
|
||||
| `-u, --admin-username` | Set Dashboard admin username |
|
||||
| `--root` | Specify AstrBot root directory |
|
||||
|
||||
## Startup Details
|
||||
|
||||
The `astrbot run` command starts the AstrBot service.
|
||||
|
||||
### Startup Options
|
||||
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| `-H, --host` | Dashboard bind address |
|
||||
| `-p, --port` | Dashboard bind port |
|
||||
| `-r, --reload` | Enable plugin auto-reload |
|
||||
| `-b, --backend-only` | Start backend only, skip WebUI |
|
||||
| `-l, --log-level` | Log level (DEBUG, INFO, WARNING, ERROR) |
|
||||
| `--ssl-cert` | SSL certificate path |
|
||||
| `--ssl-key` | SSL private key path |
|
||||
| `--ssl-ca` | SSL CA certificate path |
|
||||
| `--debug` | Debug mode |
|
||||
| `-c, --service-config` | Service configuration file path |
|
||||
|
||||
### Startup Output
|
||||
|
||||
Upon successful startup:
|
||||
|
||||
```
|
||||
AstrBot is running...
|
||||
Visit the dashboard at : https://dash.astrbot.men/
|
||||
Backend Requests : localhost or based on https
|
||||
```
|
||||
|
||||
## Environment Variables
|
||||
|
||||
### Core Configuration
|
||||
|
||||
| Variable | Description | Default |
|
||||
|----------|-------------|---------|
|
||||
| `ASTRBOT_ROOT` | AstrBot root directory | Auto-detected |
|
||||
| `ASTRBOT_LOG_LEVEL` | Log level | INFO |
|
||||
| `ASTRBOT_RELOAD` | Enable plugin hot-reload | - |
|
||||
| `ASTRBOT_DISABLE_METRICS` | Disable metrics upload | - |
|
||||
|
||||
### Dashboard Configuration
|
||||
|
||||
| Variable | Description | Default |
|
||||
|----------|-------------|---------|
|
||||
| `ASTRBOT_DASHBOARD_ENABLE` | Enable Dashboard | True |
|
||||
| `ASTRBOT_HOST` | Dashboard bind address | 0.0.0.0 |
|
||||
| `ASTRBOT_PORT` | Dashboard bind port | 8000 |
|
||||
|
||||
### SSL Configuration
|
||||
|
||||
| Variable | Description |
|
||||
|----------|-------------|
|
||||
| `ASTRBOT_SSL_ENABLE` | Enable SSL |
|
||||
| `ASTRBOT_SSL_CERT` | SSL certificate path |
|
||||
| `ASTRBOT_SSL_KEY` | SSL private key path |
|
||||
| `ASTRBOT_SSL_CA_CERTS` | CA certificate path |
|
||||
|
||||
### Proxy Configuration
|
||||
|
||||
| Variable | Description |
|
||||
|----------|-------------|
|
||||
| `http_proxy` | HTTP proxy address |
|
||||
| `https_proxy` | HTTPS proxy address |
|
||||
| `no_proxy` | Addresses to bypass proxy |
|
||||
|
||||
### Platform Integration
|
||||
|
||||
| Variable | Description |
|
||||
|----------|-------------|
|
||||
| `DASHSCOPE_API_KEY` | Alibaba DashScope API Key (for Rerank) |
|
||||
| `COZE_API_KEY` | Coze API Key |
|
||||
| `COZE_BOT_ID` | Coze Bot ID |
|
||||
| `BAY_DATA_DIR` | Computer Use data directory |
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```
|
||||
AstrBot/
|
||||
├── .astrbot # AstrBot root marker
|
||||
├── .env # Environment configuration
|
||||
├── data/ # Data directory
|
||||
│ ├── config/
|
||||
│ │ └── cmd_config.json # Main configuration file
|
||||
│ ├── plugins/ # Plugins directory
|
||||
│ ├── skills/ # Skills directory
|
||||
│ └── temp/ # Temporary files directory
|
||||
├── astrbot/ # Core code
|
||||
│ ├── cli/ # Command line tool
|
||||
│ ├── core/ # Core modules
|
||||
│ ├── dashboard/ # Dashboard frontend
|
||||
│ └── ...
|
||||
└── ...
|
||||
```
|
||||
|
||||
## Configuration File
|
||||
|
||||
The main configuration file is located at `data/cmd_config.json`, containing:
|
||||
|
||||
- LLM provider configuration
|
||||
- Platform adapter configuration
|
||||
- Plugin settings
|
||||
- Dashboard settings
|
||||
- Proxy settings
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Port Already in Use
|
||||
|
||||
If the port is already in use:
|
||||
|
||||
```bash
|
||||
# Check process using the port
|
||||
lsof -i :8000
|
||||
|
||||
# Or start on a different port
|
||||
astrbot run --port 8080
|
||||
```
|
||||
|
||||
### Multiple Instance Conflict
|
||||
|
||||
AstrBot uses a lock file mechanism to prevent multiple instances. To force start:
|
||||
|
||||
```bash
|
||||
# Remove lock file
|
||||
rm astrbot.lock
|
||||
|
||||
# Restart
|
||||
astrbot run
|
||||
```
|
||||
|
||||
### Dashboard Not Accessible
|
||||
|
||||
1. Verify `ASTRBOT_DASHBOARD_ENABLE` is `True`
|
||||
2. Check firewall settings
|
||||
3. Confirm port is not blocked
|
||||
|
||||
### Viewing Logs
|
||||
|
||||
```bash
|
||||
# Start with debug mode for detailed logs
|
||||
astrbot run --debug --log-level DEBUG
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Configure LLM Providers](../providers/llm.md)
|
||||
- [Install Plugins](../use/plugin.md)
|
||||
- [Use Skills](../use/skills.md)
|
||||
- [Deploy to Server](./deploy/astrbot/docker.md)
|
||||
235
docs/zh/startup.md
Normal file
235
docs/zh/startup.md
Normal file
@@ -0,0 +1,235 @@
|
||||
# 项目启动指南
|
||||
|
||||
本文档详细介绍 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
|
||||
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)
|
||||
Reference in New Issue
Block a user