环境变量总表
A2X Registry 读取的全部环境变量。所有变量都在进程启动时读取,运行时修改不生效——改完需要重启 a2x-registry。
本项目不使用 dotenv,没有
.env加载器:变量需要通过 shellexport、systemd 的Environment=/EnvironmentFile=,或容器编排注入。
1. 数据目录
| 变量 | 默认值 | 说明 |
|---|---|---|
A2X_REGISTRY_HOME |
见下方解析顺序 | 数据根目录,database/、llm_apikey.json、cluster_state.json、auth_data/ 都相对它解析 |
A2X_REGISTRY_AUTH_DATA |
<HOME>/auth_data |
鉴权数据(凭据哈希 + 审计日志)目录的显式覆盖。部署到只读包目录时用它把数据落到可写卷。详见 auth_design.md |
A2X_REGISTRY_CLUSTER_STATE |
<HOME>/cluster_state.json |
集群身份文件路径的显式覆盖。同机跑多实例时必须每个实例设不同值 |
A2X_REGISTRY_HOME 的解析顺序见 a2x_registry/common/paths.py:环境变量 → ~/.a2x_registry/ → 当前目录。
2. 分布式同步(cluster/,默认关闭)
| 变量 | 默认值 | 说明 |
|---|---|---|
A2X_REGISTRY_CLUSTER_ADVERTISE |
空 | 对端回连本节点用的 base URL,必须填对端可达的地址(同机调试可用 127.0.0.1)。不设则不启用集群 |
A2X_REGISTRY_CLUSTER_KEEPALIVE_INTERVAL |
10 |
直链保活广播周期(秒) |
A2X_REGISTRY_CLUSTER_HOLD_TIMEOUT |
30 |
直链静默多久断会话并驱逐其记录(秒);失活耗时 ≈ 此值 |
A2X_REGISTRY_CLUSTER_ANTI_ENTROPY_INTERVAL |
20 |
反熵对账 + GC 周期(秒) |
A2X_REGISTRY_CLUSTER_HTTP_TIMEOUT |
5 |
单次对端调用超时(秒) |
A2X_REGISTRY_CLUSTER_BROADCAST_WORKERS |
32 |
并发广播 / 保活线程池上限 |
A2X_REGISTRY_CLUSTER_MERKLE_BUCKETS |
256 |
Merkle 反熵桶数,须全网一致 |
除 ADVERTISE 外,上表其余 6 项由 ClusterConfig.from_env() 按 A2X_REGISTRY_CLUSTER_<字段大写> 自动派生(见 a2x_registry/cluster/config.py)——给 ClusterConfig 新增字段就会自动多一个变量,改动时记得同步本表。非法值会打 warning 并回落默认。
部署步骤与拓扑示例见 README_forDistributed.md,机制设计见 cluster_design.md。
3. 并发度调优
| 变量 | 默认值 | 说明 |
|---|---|---|
A2X_REGISTRY_SEARCH_WORKERS |
4 |
/api/search 请求处理线程池上限 |
A2X_REGISTRY_DATASET_WORKERS |
2 |
/api/datasets CRUD / build 请求处理线程池上限 |
A2X_REGISTRY_LLM_WORKERS |
20 |
A2X 递归导航并发调用 LLM 的线程数。受 LLM 供应商速率限制约束,免费额度建议调小 |
A2X_REGISTRY_AGENT_CARD_WORKERS |
10 |
注册时并发抓取 agent card URL 的线程数 |
前两个是模块级线程池,在 import 时创建,因此必须在启动 server 前设好。非法值会打 warning 并回落默认。
4. 前端
| 变量 | 默认值 | 说明 |
|---|---|---|
A2X_FRONTEND_DIST_DIR |
无 | 前端构建产物目录。设置后 backend 用 StaticFiles 挂载它。ui/launcher.py 在检测到 ui/frontend/dist/ 时会自动设置,一般无需手工配置 |
5. 第三方 / 系统变量
| 变量 | 说明 |
|---|---|
HF_HOME |
HuggingFace 缓存目录,影响 [vector] extras 的嵌入模型下载位置。默认 ~/.cache/huggingface |
NO_PROXY |
本机访问(含集群同机调试)需要包含 127.0.0.1,localhost,否则请求会被系统代理拦截 |
6. 一体机模式
一体机(appliance)部署引入的 A2X_REGISTRY_MODE / A2X_REGISTRY_BIND / A2X_REGISTRY_PORT / A2X_REGISTRY_DB_* 系列变量尚未合入本分支,将在后续版本随一体机能力一起提供。