用途:说明 Xberg 如何解析配置,以及在多层配置同时存在时的覆盖顺序。
CLI 模式优先级(由高到低):单个 CLI 标志(如 --ocr、--output-format、--chunk);内联 JSON 配置(--config-json 或 --config-json-base64);配置文件(--config path.toml);自动发现的配置(当前目录及父目录的 xberg.toml,然后是用户配置目录);默认值。CLI 标志始终覆盖配置文件。
Server/MCP 模式优先级:CLI 参数(--host、--port);环境变量(XBERG_HOST、XBERG_PORT);配置文件 [server] 段;默认值(127.0.0.1:8000)。
配置发现:ExtractionConfig::discover() 先逐级向上查找 xberg.toml,首个命中即采用;未找到则回退到用户全局配置目录(dirs::config_dir()/xberg),按 xberg.toml、xberg.yaml、xberg.yml、xberg.json 顺序探测。因此项目内的 xberg.yaml 不会被自动发现,需用 --config 指定。
内联 JSON 为字段级合并,而非整对象替换;merge_json_into_config 将 JSON 字段并入基础配置。shell 转义场景可用 --config-json-base64。TOML、YAML、JSON 结构等价,例如 use_cache、[ocr] 的 backend 与 languages、[security_limits] 的 max_archive_size。
两处静默失效:一是 TesseractConfig 存在公开与内部两份定义、各有自己的 Default,改一处只影响对应路径;修改默认值前应搜索裸类型名并确认是否存在第二份定义。二是除 ExtractionConfig 与 UrlExtractionConfig 外,嵌套配置均忽略未知键,拼错的键会静默通过,建议按 serde 线上名(如 max_chars)编写测试,并断言解析结果与默认值不同。