XERJ环境变量速查:XERJ_*全部变量与配置优先级完整清单

原创2026-10-18 18:58:442,230 阅读
文章标签:搜索引擎全文检索向量数据库数据库后端MCP 服务Agent 记忆人工智能日志分析dsh-plugin

XERJ环境变量速查:XERJ_*全部变量与配置优先级完整清单

XERJ 是一款面向 AI Agent 的数据搜索引擎:一条命令即可对代码、文档、日志和 PDF 建立索引,用于全文检索、RAG、安全审计与 Agent 记忆,兼容 Elasticsearch API。本文整理 XERJ 全部 XERJ_* 环境变量速查清单与配置优先级规则,帮你快速定位「哪个变量该在哪里设置、谁覆盖谁」,5 分钟完成正确配置。

XERJ 环境变量速查:终端中对已索引的 ndjson 日志执行检索与聚合验证

一、配置优先级:先记住 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

XERJ 配置内存上限后控制台展示的查询量与延迟监控面板

四、嵌入与 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 向量索引控制台:嵌入空间 UMAP 投影展示 6 个语料聚类

五、安全密钥与认证变量 🔐

变量 说明
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

XERJ 控制台展示的 Agent 记忆规模与语义记忆聚类面板

💡 最后提醒:环境变量只在启动时读取一次——改完配置请重启节点。所有 134 个用户设置的完整定义可查阅 engine/crates/xerj-common/src/config.rs。

登录后查看全文
xerj