mirror of https://github.com/AstrBotDevs/AstrBot synced 2026-07-15 17:30:13 +08:00

Files

LIghtJUNction e1ac6733e8 docs: 新增 openspec 规范文档

- abp.md: ABP (AstrBot Plugin) 插件协议规范
- api.md: API 规范
- agent-message.md: Agent 消息格式规范
- config.md: 配置系统规范 (含 GPG 安全配置)
- env.md: 环境变量规范
- path.md: XDG 路径规范

2026-03-27 00:15:37 +08:00

8.6 KiB

Raw Blame History

环境变量规范

概述

本文档定义 AstrBot 环境变量的规范，所有环境变量以 ASTRBOT_ 为前缀。

变量分类

分类	前缀	说明
实例标识	`ASTRBOT_INSTANCE_*`	实例相关配置
核心配置	`ASTRBOT_*`	核心功能配置
网络配置	`ASTRBOT_NET_*`	网络相关配置
SSL/TLS	`ASTRBOT_SSL_*`	安全连接配置
代理配置	`*_PROXY`	代理相关配置
平台配置	平台特定	第三方平台集成

实例标识 / Instance Identity

`ASTRBOT_INSTANCE_NAME`

属性	值
说明	实例名称，用于日志和服务名
类型	string
默认	`AstrBot`

核心配置 / Core Configuration

`ASTRBOT_ROOT`

属性	值
说明	AstrBot 根目录路径
类型	path
默认	当前工作目录

特殊路径：

桌面客户端：~/.astrbot
服务器：/var/lib/astrbot/<instance>/

`ASTRBOT_LOG_LEVEL`

属性	值
说明	日志等级
类型	enum
默认	`INFO`
可选值	`DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`

`ASTRBOT_RELOAD`

属性	值
说明	启用插件热重载
类型	boolean (0/1)
默认	`0` (禁用)

`ASTRBOT_DISABLE_METRICS`

属性	值
说明	禁用匿名使用统计
类型	boolean (0/1)
默认	`0` (启用统计)

`ASTRBOT_PYTHON`

属性	值
说明	覆盖 Python 可执行文件路径（用于本地代码执行）
类型	path
示例	`/usr/bin/python3`, `/home/user/.pyenv/shims/python`

`ASTRBOT_DEMO_MODE`

属性	值
说明	启用演示模式（可能限制部分功能）
类型	boolean
默认	`False`

`ASTRBOT_TESTING`

属性	值
说明	启用测试模式（影响日志和部分行为）
类型	boolean
默认	`False`

`ASTRBOT_DESKTOP_CLIENT`

属性	值
说明	标记是否通过桌面客户端执行（内部使用）
类型	boolean (0/1)
默认	`0`

`ASTRBOT_SYSTEMD`

属性	值
说明	标记是否通过 systemd 服务执行
类型	boolean (0/1)
默认	`0`

管理面板 / Dashboard

`ASTRBOT_DASHBOARD_ENABLE`

属性	值
说明	启用或禁用 WebUI 管理面板
类型	boolean
默认	`True`

国际化 / Internationalization

`ASTRBOT_CLI_LANG`

属性	值
说明	CLI 界面语言
类型	enum
默认	`zh` (跟随系统 locale)
可选值	`zh` (中文), `en` (英文)

网络配置 / Network

`ASTRBOT_HOST`

属性	值
说明	API 绑定主机
类型	string
示例	`0.0.0.0` (所有接口), `127.0.0.1` (仅本地)

`ASTRBOT_PORT`

属性	值
说明	API 绑定端口
类型	integer
示例	`3000`, `6185`, `8080`

API 服务器配置 / API Server

`ASTRBOT_API_ENABLE`

属性	值
说明	启用 HTTP API 服务器
类型	boolean
默认	`true`

`ASTRBOT_API_TIMEOUT`

属性	值
说明	API 请求超时时间（秒）
类型	integer
默认	`60`

`ASTRBOT_API_MAX_BODY_SIZE`

属性	值
说明	API 最大请求体大小（MB）
类型	integer
默认	`100`

`ASTRBOT_API_KEY`

属性	值
说明	默认 API Key（用于开发环境）
类型	string
注意	建议通过 secrets.yaml 配置

`ASTRBOT_CALLBACK_API_BASE`

属性	值
说明	Webhook 回调基础 URL
类型	url
示例	`https://your-server.com/callback`

`ASTRBOT_CALLBACK_SECRET`

属性	值
说明	Webhook 回调签名密钥
类型	string
注意	用于验证回调请求签名

SSL/TLS 配置

`ASTRBOT_SSL_ENABLE`

属性	值
说明	启用 SSL/TLS
类型	boolean
默认	`false`

`ASTRBOT_SSL_CERT`

属性	值
说明	SSL 证书路径（PEM 格式）
类型	path
示例	`/etc/astrbot/certs/myinstance/fullchain.pem`

`ASTRBOT_SSL_KEY`

属性	值
说明	SSL 私钥路径（PEM 格式）
类型	path
示例	`/etc/astrbot/certs/myinstance/privkey.pem`

`ASTRBOT_SSL_CA_CERTS`

属性	值
说明	SSL CA 证书链路径（可选，用于客户端验证）
类型	path
示例	`/etc/ssl/certs/ca-certificates.crt`

代理配置

通用

`http_proxy` / `HTTP_PROXY`

属性	值
说明	HTTP 代理地址
类型	url
示例	`http://127.0.0.1:7890`, `socks5://127.0.0.1:1080`

`https_proxy` / `HTTPS_PROXY`

属性	值
说明	HTTPS 代理地址
类型	url
示例	`http://127.0.0.1:7890`, `socks5://127.0.0.1:1080`

`no_proxy` / `NO_PROXY`

属性	值
说明	不走代理的主机列表（逗号分隔）
类型	string
示例	`localhost,127.0.0.1,192.168.0.0/16,.local`

第三方集成 / Third-party Integrations

`DASHSCOPE_API_KEY`

属性	值
说明	阿里云 DashScope API 密钥（用于 Rerank 服务）
类型	string
获取地址	https://dashscope.console.aliyun.com/
示例	`sk-xxxxxxxxxxxx`

`COZE_API_KEY`

属性	值
说明	Coze API 密钥
类型	string
获取地址	https://www.coze.com/

`COZE_BOT_ID`

属性	值
说明	Coze Bot ID
类型	string

`BAY_DATA_DIR`

属性	值
说明	计算机控制相关的数据目录（用于截图/文件存储）
类型	path
示例	`/var/lib/astrbot/bay_data`

平台特定配置 / Platform-specific

`TEST_MODE`

属性	值
说明	QQ 官方机器人测试模式开关
类型	enum
默认	`off`
可选值	`on`, `off`

GPG 安全配置 / GPG Security

`ASTRBOT_GPG_ENABLE`

属性	值
说明	启用 GPG 配置签名与验签功能
类型	boolean
默认	`false`

`ASTRBOT_GPG_VERIFY_MODE`

属性	值
说明	验签模式
类型	enum
默认	`warn`
可选值	`none` (不验签), `warn` (仅警告), `enforce` (阻止启动)

`ASTRBOT_GPG_TRUSTED_KEYS`

属性	值
说明	信任的 GPG 公钥指纹列表（逗号分隔）
类型	string
示例	`ABCDEF1234567890...,FEDCBA0987654321...`

`ASTRBOT_GPG_SIGNED_CONFIGS`

属性	值
说明	需要验签的配置文件列表（逗号分隔）
类型	string
示例	`secrets.yaml,agent.yaml,platform.yaml`

`ASTRBOT_GPG_GNUPG_HOME`

属性	值
说明	GPG 主目录路径（默认使用系统配置）
类型	path
示例	`/home/user/.gnupg`

`ASTRBOT_GPG_PRIVATE_KEY`

属性	值
说明	GPG 私钥（ASCII Armor 格式），用于签名
类型	string
注意	建议通过 secrets.yaml 配置，优先使用环境变量

`ASTRBOT_GPG_PASSPHRASE`

属性	值
说明	GPG 私钥密码短语
类型	string
注意	建议通过 secrets.yaml 配置，优先使用环境变量

命名规范

前缀规则

前缀	用途
`ASTRBOT_`	AstrBot 核心配置
`ASTRBOT_SSL_`	SSL/TLS 配置
`ASTRBOT_GPG_`	GPG 安全配置
`ASTRBOT_INSTANCE_`	实例相关
`http_proxy`, `https_proxy`, `no_proxy`	标准代理变量（无前缀）

布尔值

布尔值使用以下格式之一：

格式	示例
整数 (0/1)	`ASTRBOT_RELOAD=0`
字符串 (true/false)	`ASTRBOT_SSL_ENABLE=false`
枚举	`TEST_MODE=on/off`

配置文件优先级

环境变量（最高优先级）
.env 文件
默认值（最低优先级）

特殊变量展开

支持 ${VAR_NAME} 格式的变量展开：

INSTANCE_NAME="my-bot"
ASTRBOT_ROOT="${ASTRBOT_ROOT:-/var/lib/astrbot}"

支持的展开语法

语法	说明
`${VAR}`	展开 VAR 的值
`${VAR:-default}`	如果 VAR 未设置或为空，使用 default
`${VAR:=default}`	如果 VAR 未设置或为空，设置为 default 并展开

8.6 KiB Raw Blame History Unescape Escape

环境变量规范

概述

变量分类

实例标识 / Instance Identity

ASTRBOT_INSTANCE_NAME

核心配置 / Core Configuration

ASTRBOT_ROOT

ASTRBOT_LOG_LEVEL

ASTRBOT_RELOAD

ASTRBOT_DISABLE_METRICS

ASTRBOT_PYTHON

ASTRBOT_DEMO_MODE

ASTRBOT_TESTING

ASTRBOT_DESKTOP_CLIENT

ASTRBOT_SYSTEMD

管理面板 / Dashboard

ASTRBOT_DASHBOARD_ENABLE

国际化 / Internationalization

ASTRBOT_CLI_LANG

网络配置 / Network

ASTRBOT_HOST

ASTRBOT_PORT

API 服务器配置 / API Server

ASTRBOT_API_ENABLE

ASTRBOT_API_TIMEOUT

ASTRBOT_API_MAX_BODY_SIZE

ASTRBOT_API_KEY

ASTRBOT_CALLBACK_API_BASE

ASTRBOT_CALLBACK_SECRET