跳转到主要内容
可以通过环境变量对系统各项参数进行控制。社区版 Docker 部署以 docker/.env.example 为参考；如果已经进入 docker/ 目录，执行 cp .env.example .env 并按需修改即可。 部分参数说明如下：
环境变量说明
API_BASE_URLAPI 服务地址（需修改）
CLIENT_BASE_URLWeb 客户端基础地址（服务端部署时建议一并修改）
WEB_PORT网站端口号
DB_NAME数据库名称
DB_USER数据库用户名
DB_PASS数据库密码
DB_PORT数据库端口
DB_HOST数据库地址
REDIS_PASSWORD缓存服务密码
NODE_ENV运行环境: development or production
LOG_LEVEL日志级别
DEFAULT_LATITUDE默认纬度
DEFAULT_LONGITUDE默认经度
DEFAULT_CURRENCY默认货币
DEMO演示系统

​
组织初始化与模板

以下变量主要在“创建新组织”时生效，用于初始化组织默认工作区、分析模型和模板 xpert：
环境变量作用如何配置
ORG_DEFAULT_XPERT_TEMPLATE_KEYS在新组织创建后，自动把指定模板导入该组织的默认工作区填写模板 ID，多个值使用英文逗号分隔；留空表示不自动导入
ORG_ANALYTICS_BOOTSTRAP_MODE控制新组织的 analytics 初始化模式支持 semantic-only 或 full-demo；未设置或填写其他值时会回退到 semantic-only
XPERT_TEMPLATE_DIR指定外部 xpert 模板目录建议配置为持久化目录；首次启动时系统会把缺失的基线模板文件补齐到该目录
示例配置： 
ORG_DEFAULT_XPERT_TEMPLATE_KEYS=af7133cb-32b3-47ff-90c1-b144c4d4887e,af7133cb-32b3-47ff-90c1-b144c4d48872
ORG_ANALYTICS_BOOTSTRAP_MODE=semantic-only
XPERT_TEMPLATE_DIR=/var/lib/xpert/data/xpert-template
补充说明：
  • ORG_DEFAULT_XPERT_TEMPLATE_KEYS 使用模板 ID，而不是模板名称。上面的两个示例模板分别对应 ChatBI with Sales Analysis Expert 和 Text2SQL-ChatDB。
  • ORG_ANALYTICS_BOOTSTRAP_MODE=semantic-only 只初始化语义模型运行所需数据；full-demo 会额外导入 demo indicators 和 demo story。
  • XPERT_TEMPLATE_DIR 未设置时会回退到默认数据目录；在 Docker 环境下通常对应 /var/lib/xpert/data/xpert-template。
  • 这组配置不会回溯修改已有组织，只影响后续新创建的组织。

​
权限与 Handoff 路由

环境变量作用如何配置
ALLOW_SUPER_ADMIN_ROLE是否允许 SUPER_ADMIN 直接通过租户级和组织级权限守卫默认 true；仅当显式设置为 false 时，才会关闭该权限旁路
HANDOFF_ROUTING_CONFIG_PATH指向 handoff 路由 YAML 配置文件可填写绝对路径或相对路径；相对路径会按 API 服务根目录解析
示例配置： 
ALLOW_SUPER_ADMIN_ROLE=true
HANDOFF_ROUTING_CONFIG_PATH=/var/lib/xpert/data/config/handoff-routing.yaml
对应的路由文件可参考 Xpert 源码中的 docker/handoff-routing.example.yaml，最小示例如下： 
version: 1
defaultQueue: handoff
defaultLane: main
routes:
  - match:
      typePrefix: channel.lark.
    target:
      queue: integration
      lane: normal
补充说明：
  • ALLOW_SUPER_ADMIN_ROLE 不会删除或创建角色，它控制的是 SUPER_ADMIN 是否自动跳过部分租户/组织权限检查。
  • HANDOFF_ROUTING_CONFIG_PATH 未设置时，系统会记录告警并回退到内置默认路由。
  • handoff 路由配置在模块初始化时加载一次，修改 YAML 文件后需要重启 API 服务。

​
插件与默认技能仓库

环境变量作用如何配置
PLUGINS在部署时向系统追加全局插件包多个插件包名使用英文逗号或分号分隔；该变量会追加到系统内置的全局插件列表，而不是替换内置列表
AI_DEFAULT_SKILL_REPOSITORIES在新租户创建时自动注册默认技能仓库传入 JSON 字符串；推荐使用 { "repositories": [...] } 结构；每项至少包含 name 和 provider，可选 options、credentials
示例配置： 
PLUGINS=@xpert-ai/plugin-openrouter,@xpert-ai/plugin-gemini
AI_DEFAULT_SKILL_REPOSITORIES={"repositories":[{"name":"anthropics/skills","provider":"github","options":{"url":"https://github.com/anthropics/skills","branch":"main"}},{"name":"acme/internal-skills","provider":"github","options":{"url":"https://github.com/acme/internal-skills","path":"skills","branch":"main"},"credentials":{"token":"<github-token>"}}]}
补充说明：
  • PLUGINS 在服务启动阶段读取，修改后需要重启 API 服务。
  • AI_DEFAULT_SKILL_REPOSITORIES 也支持直接传 JSON 数组，但推荐与 docker/.env.example 一样使用 repositories 包装结构，便于扩展。
  • AI_DEFAULT_SKILL_REPOSITORIES 中的 provider 需要填写系统支持的技能仓库提供方，例如 github 或 clawhub。
  • 如果 JSON 格式不合法，系统会记录告警并忽略该配置。
  • 这组默认技能仓库仅在“新租户创建”时自动注册；已有租户如需补充，请通过技能仓库接口手动注册并同步。

​
邮件相关配置

自定义 smtp 邮件服务器配置， 需要配置以下环境变量：
环境变量说明
MAIL_FROM_ADDRESS发件人邮件地址
MAIL_HOST邮箱服务主机
MAIL_PORT邮箱服务端口号
MAIL_USERNAME邮箱账号
MAIL_PASSWORD邮箱密码

​
文件存储

自定义文件存储提供商
环境变量说明
FILE_PROVIDER文件存储提供商（LOCAL | S3 | OSS）
ALIYUN_ACCESS_KEY_ID阿里云 Access Key ID
ALIYUN_ACCESS_KEY_SECRET阿里云 Access Key Secret
ALIYUN_REGION阿里云地区
ALIYUN_OSS_ENDPOINT阿里云 OSS Endpoint
ALIYUN_OSS_BUCKET阿里云 OSS Bucket
AWS_ACCESS_KEY_ID亚马逊云 Access Key ID
AWS_SECRET_ACCESS_KEY亚马逊云 Secret Access Key
AWS_REGION亚马逊云地区
AWS_S3_BUCKET亚马逊云 S3 Bucket