From 41172c9380409be745119d93b3f9c1932d1ce96f Mon Sep 17 00:00:00 2001 From: LIghtJUNction Date: Mon, 23 Mar 2026 02:07:10 +0800 Subject: [PATCH] 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 --- docs/en/startup.md | 235 +++++++++++++++++++++++++++++++++++++++++++++ docs/zh/startup.md | 235 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 470 insertions(+) create mode 100644 docs/en/startup.md create mode 100644 docs/zh/startup.md diff --git a/docs/en/startup.md b/docs/en/startup.md new file mode 100644 index 000000000..ee6e0cda3 --- /dev/null +++ b/docs/en/startup.md @@ -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) diff --git a/docs/zh/startup.md b/docs/zh/startup.md new file mode 100644 index 000000000..1ae054dac --- /dev/null +++ b/docs/zh/startup.md @@ -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)