XERJ环境变量速查:XERJ_*全部变量与配置优先级完整清单
XERJ环境变量速查:XERJ_*全部变量与配置优先级完整清单
XERJ 是一款面向 AI Agent 的数据搜索引擎:一条命令即可对代码、文档、日志和 PDF 建立索引,用于全文检索、RAG、安全审计与 Agent 记忆,兼容 Elasticsearch API。本文整理 XERJ 全部 XERJ_* 环境变量速查清单与配置优先级规则,帮你快速定位「哪个变量该在哪里设置、谁覆盖谁」,5 分钟完成正确配置。
一、配置优先级:先记住 3 条规则
XERJ 的大部分行为由 TOML 配置文件控制,但二进制在启动时同样会读取环境变量。官方明确说明:优先级并非统一规则,每个变量有自己的约定(完整定义见 engine/crates/xerj-server/src/main.rs 与 engine/crates/xerj-rerank/src/judge.rs)。
| 规则 | 优先级顺序 | 典型变量 |
|---|---|---|
| 🅰️ 覆盖型 | CLI 标志 > 环境变量 > 配置文件 | XERJ_BIND_ADDRESS、XERJ_URL、XERJ_EMBED_MODE |
| 🅱️ 后备型(密钥类) | 配置文件 > 环境变量(配置非空时环境变量失效) | XERJ_CLUSTER_AUTH_SECRET、TYPESAFE_API_KEY |
| 🅲 特殊型 | 环境变量 > 配置文件(显式覆盖内存上限) | XERJ_MAX_PROCESS_MEMORY_MB、XERJ_SEGMENT_HYDRATION_CACHE_MB |
⚠️ 另外两点重要前提:
- 所有环境变量只在启动时读取一次,运行中修改不生效,必须重启节点;
- 完整配置参考 engine/xerj.default.toml(134 个用户设置的默认值说明)和官方文档 landing/docs/env.html。
二、配置入口与日志变量
| 变量 | 默认值 | 作用 |
|---|---|---|
XERJ_CONFIG |
未设置 | 指定配置文件路径。若同时设置了 --config,标志获胜;两者都没有则用内置默认值(不会自动查找 ./xerj.toml) |
XERJ_LOG |
info |
日志过滤,支持 tracing_subscriber 语法,例如 xerj_api=debug,info |
RUST_LOG |
— | 后备日志过滤,仅在 XERJ_LOG 未设置时才检查 |
# 只把 API 层调到 debug,其余保持 info
export XERJ_LOG="xerj_api=debug,info"
三、服务端变量:网络、端口与内存 🖥️
| 变量 | 默认值 | 说明 |
|---|---|---|
XERJ_BIND_ADDRESS |
— | 覆盖 server.bind_address,--bind 获胜;空值是启动错误 |
XERJ_AUTO_PORT |
— | 多实例开关(true/false),端口被占用时自动绑定下一个空闲端口 |
XERJ_ALLOW_INSECURE_NETWORK_BIND |
— | 严格布尔(1/true/yes/on、0/false/no/off),其他取值直接拒绝启动 |
XERJ_MAX_PROCESS_MEMORY_MB |
— | 进程内存上限:auto、off、unlimited 或具体 MiB 数值;压过 limits.max_process_memory_mb |
XERJ_SEGMENT_HYDRATION_CACHE_MB |
— | 段水合缓存预算,语法同上;自动钳制为内存的 50% |
XERJ_NUM_CPUS |
— | 指定节点按多少核心数规划线程池,优先于 cgroup 与操作系统探测 |
TOKIO_WORKER_THREADS |
核心数 × 8(64–512) | 异步运行时工作线程数(唯一非 XERJ_ 前缀的变量) |
# 生产环境常见组合:固定绑定地址 + 收紧内存
export XERJ_BIND_ADDRESS=0.0.0.0
export XERJ_ALLOW_INSECURE_NETWORK_BIND=false
export XERJ_MAX_PROCESS_MEMORY_MB=8192
四、嵌入与 AI 相关变量 🧠
| 变量 | 默认值 | 说明 |
|---|---|---|
XERJ_EMBED_MODE |
— | 覆盖 embedding.mode,取值:lexical、neural、proxy、auto、onnx-experimental;--embed-mode 获胜 |
XERJ_EMBEDDING_API_KEY |
— | proxy 嵌入模式的 Bearer 密钥;仅环境变量,没有对应配置项 |
XERJ_ONNX_MODEL / XERJ_ONNX_TOKENIZER |
— | onnx-experimental 模式的模型与分词器路径(CLI 标志获胜) |
XERJ_ONNX_LOG |
warn |
ONNX 运行时日志级别 |
XERJ_NEURAL_LOCAL_DIR |
— | 本地神经嵌入模型的存放目录 |
配置嵌入密钥示例:
# 走 OpenAI 兼容的 proxy 嵌入端点
export XERJ_EMBED_MODE=proxy
export XERJ_EMBEDDING_API_KEY="sk-xxxx"
五、安全密钥与认证变量 🔐
| 变量 | 说明 |
|---|---|
XERJ_CLUSTER_AUTH_SECRET |
集群传输密钥,至少 16 字符;后备型——配置 cluster.auth_secret 非空时以配置为准 |
XERJ_CONSOLE_KEY |
64 位十六进制的 Console 主密钥,压过 .xerj_master_key 文件;格式错误会直接报错 |
XERJ_API_KEY |
客户端子命令(含 autoindex)的 API 密钥,--api-key 获胜 |
XERJ_AUTH |
xerj mcp 的 Authorization 头(如 ApiKey <key>),--auth 获胜 |
启用默认配置([auth] enabled = true)后,首次启动会在 <data_dir>/admin.key 生成管理密钥,客户端这样使用:
export XERJ_API_KEY="$(cat ./data/admin.key)"
xerj autoindex ./my-folder
六、客户端变量:让搜索命令找对节点 🔌
| 变量 | 默认值 | 说明 |
|---|---|---|
XERJ_URL |
http://localhost:9200 |
xerj search / def / code / gain / init / mcp 使用的节点地址,--url 获胜 |
XERJ_CODE_HOME |
~/.xerj-code |
xerj corpus / xerj code 的语料与状态目录 |
XERJ_BROWSER |
BROWSER |
xerj brain 等命令打开浏览器使用的可执行程序 |
XERJ_DISABLE_FEEDBACK |
— | 隐藏反馈提示(与 --disable-feedback 等价) |
AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY、AWS_SESSION_TOKEN、AWS_REGION、AWS_ENDPOINT_URL(_S3) |
— | s3:// / r2:// 数据源与 S3 存储后端的凭证和端点 |
⚠️ 最容易被忽略的坑:xerj autoindex 故意忽略 XERJ_URL(并会打印提示),远程索引时必须显式传 --url:
export XERJ_URL=http://10.0.0.5:9200
xerj search "disk pressure" # 自动使用 XERJ_URL
xerj autoindex ./logs --url "$XERJ_URL" # autoindex 必须显式 --url
七、Hub 变量(语料中心)🌐
| 变量 | 默认值 | 说明 |
|---|---|---|
XERJ_HUB_HOME |
~/.xerj/hub |
Hub 本地状态目录 |
XERJ_HUB_URL |
— | 覆盖 Hub 服务器地址(hub 子命令与 ask 流程使用) |
XERJ_HUB_PUBKEY |
编译时内置 | 覆盖构建内嵌的 Hub 公钥;设为 none 可显式禁用签名校验 |
相关实现见 engine/crates/xerj-hub/src/node.rs 与 engine/crates/xerj-hub/src/catalogue.rs。
八、基准测试与调试开关:生产环境请保持未设置 ⚙️
二进制还内置了一批供基准测试、A/B 实验和性能剖析使用的变量,例如:
| 变量 | 用途 |
|---|---|
XERJ_FLUSH_SIZE_MB / XERJ_FLUSH_DOCS |
强制按大小/文档数触发 flush |
XERJ_MERGE_INTERVAL_SECS / XERJ_MERGE_PARALLELISM(默认 1) |
调整合并节奏与并发合并数 |
XERJ_DISABLE_QUERY_CACHE / XERJ_DISABLE_FAST_AGGS |
关闭查询缓存 / 快速聚合,用于对照实验 |
XERJ_PROF |
性能剖析开关 |
XERJ_SKIP_WAL |
⚠️ 危险:禁用预写日志,崩溃时已确认写入的数据会丢失 |
官方基准脚本可以参考 scripts/bench/ 目录。
九、Rerank 提供商变量(后备型,非 XERJ_ 前缀)
rerank 搜索阶段会把文档文本发给第三方评审服务,因此需要密钥——这里是后备型优先级的典型:配置 [rerank] 中的值非空时获胜,防止环境变量悄悄把文档文本改道。
| 变量 | 默认值 | 说明 |
|---|---|---|
TYPESAFE_API_KEY |
— | 评审提供商密钥;两处都未设置时 rerank 请求返回 HTTP 503;GET /_xerj/rerank 只报告「已设置且来自 env」,永不回显密钥 |
TYPESAFE_ENDPOINT |
https://api.typesafe.ai/v1/systemone |
评审端点,启动时校验:必须是绝对 http/https URL 且不含 user:password@,否则拒绝启动 |
注意:[rerank] enabled = false 会同时压过这两个变量;且仅设置密钥不会自动开启 rerank,请求本身必须携带 rerank 块。
十、按场景速查 📌
| 我想…… | 该设置…… |
|---|---|
| 本地零配置快速体验 | 不用设置,直接 xerj --insecure --data-dir ./data |
| 让客户端连远程节点 | XERJ_URL + XERJ_API_KEY(autoindex 另加 --url) |
| 限制内存、防 OOM | XERJ_MAX_PROCESS_MEMORY_MB(env 优先于配置) |
| 调日志排查问题 | XERJ_LOG="xerj_api=debug,info" |
| 启用本地 ONNX 嵌入 | XERJ_EMBED_MODE=onnx-experimental + XERJ_ONNX_MODEL/_TOKENIZER |
| 对接 S3 数据源 | AWS_ENDPOINT_URL_S3、AWS_ACCESS_KEY_ID 等 |
| 多实例同机部署 | XERJ_AUTO_PORT=true |
💡 最后提醒:环境变量只在启动时读取一次——改完配置请重启节点。所有 134 个用户设置的完整定义可查阅 engine/crates/xerj-common/src/config.rs。



