企业官网建设流程全解析

XERJ 上线前安全配置实操：密钥、TLS、回环绑定一次配齐

【免费下载链接】xerjXERJ is the new way for AI to search data. Its autoindex capability activates agents to know your data without the token waste of grep and sed. One command indexes code, docs, logs and PDFs for search, RAG, security audits and agent memory, using 40x fewer tokens than grep. Elasticsearch compatible, so existing clients just work.项目地址: https://gitcode.com/GitHub_Trending/xe/xerj

搜索引擎这类常驻服务一旦裸奔上线，最典型的翻车现场不是功能缺失，而是"端口开了、密钥忘了、流量明文"——API 密钥和每条文档内容在网络里裸奔，curl还能照常返回 200，没有任何告警。XERJ 的应对思路与多数项目不同：它把安全兜底直接做进了默认值和启动流程里——回环绑定、自动生成密钥、跨网暴露即拒绝启动。本文结合仓库源码（engine/crates/xerj-server、engine/crates/xerj-common、engine/xerj.default.toml）逐项拆解这套"上线前安全配置"，给出可直接照抄的实操步骤。

默认配置解读：回环绑定 + 自动密钥，开箱即"对外隐身"

XERJ 的默认配置模板定义在 engine/xerj.default.toml，其中与安全直接相关的三个默认值分别是：

配置文件里对回环默认值的原因写得很直白：TLS 默认关闭，如果节点开箱就绑定所有网卡，管理密钥和文档正文就会以明文出现在网络上，而且一个能正常工作的curl根本不会暴露这一点。因此默认"先隐身"，想暴露必须显式修改配置——并且会被引擎拦一道（见下文 fail-closed）。

bind_address只接受 IP 字面量（127.0.0.1、0.0.0.0、::1），主机名在启动早期直接被拒绝，避免同一个名字在不同机器上解析到不同网卡导致暴露判定失真。这一校验在 engine/crates/xerj-server/src/main.rs 启动步骤 3a 中完成，先于任何数据目录、密钥或证书的创建。

密钥生成：32 字节随机、0600 权限、重启复用

[auth] enabled = true是默认值，意味着即使你没写任何配置文件，首次启动也会自动铸造管理密钥。核心逻辑在ensure_admin_key（engine/crates/xerj-server/src/main.rs）：

• 生成 32 个随机字节 → 64 位十六进制字符串；
• 打印在启动横幅里，并写入<data_dir>/admin.key，权限0600（仅属主可读写）；
• 密钥不落地到配置文件；重启时复用已有文件而非重新生成——避免每次重启都迫使 Kibana、MCP 配置、脚本重新指向新值；
• 文件里若是一段无法识别的非 64 位十六进制内容，会被视为损坏并自动重新生成。

请求头携带方式：Authorization: ApiKey <key>（也兼容Bearer <key>与Basic base64(user:<key>)，认证实现见 engine/crates/xerj-api/src/auth.rs，401 响应会附带WWW-Authenticate: ApiKey realm="xerj"质询头）。CLI 客户端不读服务端配置文件，两种方式任选其一：

# 方式一：环境变量 export XERJ_API_KEY="$(cat ./data/admin.key)" # 方式二：显式参数 xerj autoindex ~/my-project --api-key "$(cat ./data/admin.key)"

针对回环地址的 URL，xerj autoindex还会自动回退读取<data_dir>/admin.key并打印用了哪个文件，本地使用更省心。

值得单独一提的是低权限metrics_token：在[auth]段单独给监控组件（如 Prometheus）发一把令牌，持有它只能抓取GET /v1/metrics这一个端点，读不到任何索引数据——权限最小化的典型用法，与管理员密钥职责分离。

跨网络访问前的 TLS 开启步骤

回环绑定只保证"本机安全"，一旦要让其他机器访问节点，TLS 就是必选项。配置模板[tls]段给出标准写法：

[tls] enabled = true cert_path = "/etc/xerj/certs/xerj.crt" key_path = "/etc/xerj/certs/xerj.key"

生产环境应使用受信任 CA 签发的证书。如果你只想先在内网验证流程，XERJ 在ensure_tls_cert（engine/crates/xerj-server/src/main.rs）里提供了自签名兜底：当[tls] enabled = true且证书/密钥路径缺失时，会用rcgen自动生成一张localhost自签名证书，写入<data_dir>/xerj.crt和<data_dir>/xerj.key，其中私钥同样以0600权限创建，并打出一条明确警告：self-signed certificate generated — replace with a real cert for production。

如果 TLS 由前置的反向代理/负载均衡终结，则不需要在进程内开 TLS，但必须显式声明信任边界：

[server] allow_insecure_network_bind = true trusted_proxies = ["10.0.0.7", "10.1.0.0/16"]

trusted_proxies的作用是把客户端身份（按 IP 限流桶、审计日志源地址）从 TCP 对端改读代理头——不把代理列入白名单，所有用户会共享同一个限流桶；而列入白名单的代理可以声称自己是任意客户端，所以只应列入你自己运维的代理。

一个隐蔽的坑：gRPC 端口不随[tls]加密

[tls] enabled = true只覆盖 REST 与 ES-compat 两个监听器，不覆盖gRPC 端口（默认 8081）。xerj-server/src/grpc.rs构建 tonic 时没有启用tlsfeature，因此该端口无论配置如何都讲明文 h2c。启动横幅里 gRPC 一行永远标注[h2c — plaintext, no TLS]，且注释明确说明"绝不把 TLS 字样插进去"，防止给操作员一个错误的"全加密"暗示。

Fail-closed 三连：配错了就拒绝启动，绝不带病上线

这是 XERJ 安全设计中最值得学习的一点：暴露检查不是"警告后照常启动"，而是直接拒绝启动、非零退出、且不留下任何数据目录痕迹。三道检查都在 engine/crates/xerj-server/src/main.rs 启动早期完成，谓词定义在 engine/crates/xerj-common/src/config.rs：

1. 明文网络暴露（issue #228）：cleartext_exposed_off_loopback()为真——TLS 关闭 + 非回环绑定 + 未声明allow_insecure_network_bind——时拒绝启动。错误信息点名每个监听器与后果："API key in every Authorization header, and every document body, would cross the network in cleartext"。
2. gRPC h2c 暴露（issue #229）：TLS 开启 + 非回环绑定 + 未声明tls.allow_insecure_grpc_h2c时拒绝启动。因为"开 TLS 读作全加密"是合理预期，而 gRPC 客户端照常工作会让操作员毫无察觉。
3. TLS 建立失败（issue #200）：[tls] enabled = true但证书环节无法交付（文件缺失、生成失败）时，拒绝以明文 HTTP 绑定同一批端口，而不是"降级 + 继续服务"。测试 engine/crates/xerj-server/tests/tls_fail_closed.rs 用一个占位的xerj.crt目录制造确定性失败，断言进程 60 秒内非零退出且 stderr 包含 "TLS" 与 "refusing to start"。

对应测试还有 engine/crates/xerj-server/tests/cleartext_bind_fail_closed.rs（断言拒绝信息点名具体绑定地址、且被拒的启动"不创建任何东西"）与 engine/crates/xerj-server/tests/grpc_h2c_fail_closed.rs。

注意--insecure绕不过这些检查：它同时关闭 TLS 与认证，而关闭 TLS 恰好就是触发明文暴露检查的条件，所以在0.0.0.0上加--insecure一样会非零退出，除非显式声明暴露。这个标志只适合纯本地开发。

上线前安全清单逐项勾选

综合以上机制，一张可直接对照执行的清单：

密钥轮换：三步完成

密钥在启动时读取，因此轮换 = 重启：

# 1. 删除旧密钥（或写入你自己的 64 位十六进制密钥） rm /var/lib/xerj/admin.key # 2. 重启服务 systemctl restart xerj # 3. 在启动日志里找 First-run 横幅，同步给所有客户端 journalctl -u xerj | grep -A4 'First-run'

若写入的文件内容无法识别，会被视为损坏并自动重新生成，无需人工修复。官方安全文档 landing/docs/security.html 完整记载了这套流程。

控制台入口：passkey 取代密码

如果你使用 XERJ 控制台（Web 界面，挂在 ES-compat 端口下），首次启动会引导注册 passkey（平台安全密钥），之后登录只认 passkey——没有"密码"这种可被钓鱼、爆破或明文存储的凭据，管理入口与 API 密钥走的是两条独立认证路径：

注册成功后自动完成首次登录，服务器即被"认领"：

启动横幅就是你的安全体检报告

每次启动，XERJ 都会打印一块部署姿态横幅，逐行对应安全项的状态（engine/crates/xerj-server/src/main.rs 中print_startup_banner）：

• ✓ Bind: 127.0.0.1 — loopback only; nothing off this host can reach the listeners（回环绑定）
• ✓ TLS: in-process rustls termination active (REST + ES-compat)（进程内 TLS）
• ⚠ gRPC: :8081 is NOT covered by TLS — cleartext h2c（gRPC 明文提示）
• ✓ Auth: single API-key（认证开启）
• ✓ Audit: hash-chained log of writes + searches + API-key ops, kept in <data_dir>/audit.jsonl（哈希链审计日志）
• ⚠ Encryption-at-rest: not engine-level — use OS FDE or S3 SSE for now（静态加密边界）

上线前对照这块横幅逐项确认，比翻文档高效得多——它把"回环是否绑定、TLS 是否生效、认证是否开启、审计是否落盘"一次性呈现在你面前。

小结

XERJ 的安全思路可以浓缩为三句话：密钥自动生成且不进配置文件、回环绑定让新节点对外隐身、跨网不加密就拒绝启动。对准备上线的人，记住"本地用默认、对外先开 TLS、密钥只放 0600 权限的文件"这三条，再对照启动横幅和清单勾一遍，就能避开绝大多数 API 密钥与数据泄漏风险——无论是把它当 RAG 底座、日志分析引擎，还是 Agent 记忆仓库。

【免费下载链接】xerjXERJ is the new way for AI to search data. Its autoindex capability activates agents to know your data without the token waste of grep and sed. One command indexes code, docs, logs and PDFs for search, RAG, security audits and agent memory, using 40x fewer tokens than grep. Elasticsearch compatible, so existing clients just work.项目地址: https://gitcode.com/GitHub_Trending/xe/xerj