AstrBot/docs/zh/startup.md

项目启动指南

本文档详细介绍 AstrBot 项目的启动流程、初始化步骤以及相关配置。

环境要求

• Python 3.10 - 3.13
• uv 包管理器（推荐）

安装方式

方式一：使用 uv 一键安装（推荐）

# 安装 AstrBot
uv tool install astrbot

# 初始化项目（仅首次需要）
astrbot init

# 启动项目
astrbot run

方式二：开发模式安装

# 克隆项目
git clone https://github.com/AstrBotDevs/AstrBot
cd AstrBot

# 安装开发版本
uv tool install git+https://github.com/AstrBotDevs/AstrBot@dev

# 初始化
astrbot init

# 启动
astrbot run

方式三：从源码运行

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 设置
• 代理设置

常见问题

端口被占用

如果启动时提示端口被占用：

# 查看占用端口的进程
lsof -i :8000

# 或使用其他端口启动
astrbot run --port 8080

多个实例冲突

AstrBot 使用锁文件机制防止同时运行多个实例。如需强制启动：

# 删除锁文件
rm astrbot.lock

# 重新启动
astrbot run

Dashboard 无法访问

1. 确认 ASTRBOT_DASHBOARD_ENABLE 为 True
2. 检查防火墙设置
3. 确认端口未被阻止

查看日志

# 以调试模式启动查看详细日志
astrbot run --debug --log-level DEBUG

下一步

• 配置模型提供商
• 安装插件
• 使用技能
• 部署到服务器