企业官网建设流程全解析

ketch是一个快速、无状态的命令行工具，专为 AI Agent 提供网页搜索（search）与网页抓取（scrape）能力。它的配置体系只有两个入口：一份 JSON 配置文件config.json，以及一组KETCH_*环境变量。两者按CLI flag > KETCH_环境变量 > 配置文件 > 内置默认值* 的 4 级优先级叠加，让你既能在本地持久化设置，又能在容器和 CI 中"不落盘"注入 API 密钥。

📍 配置文件在哪里？

想确认当前生效的完整配置（含所有后端可用列表），只需运行：

ketch config

它会以 JSON 输出"发现式配置"：每个后端是否已配置密钥（只报*_api_key_set布尔值，从不打印密钥本身）、当前后端、缓存 TTL，以及哪些值来自环境变量（env_overrides字段）。

🚀 一键初始化：ketch config init

首次使用，一条命令生成默认配置文件：

ketch config init

默认值开箱即用（源码见 Defaults()）：

💡 没有配置任何密钥时，auto后端会自动走免密钥提供商链，ketch search照样能出结果。

⚙️ 用 ketch config set 持久化配置

所有配置项都能用config set <key> <value>写入文件，无需手写 JSON：

ketch config set backend searxng # 指定搜索后端 ketch config set brave_api_key <key> # 配置 Brave API 密钥 ketch config set searxng_url http://my-searxng:8080 # 自建 SearXNG 实例 ketch config set browser chrome # 启用浏览器兜底渲染 JS 页面 ketch config set limit 10

几个实用细节：

• 多密钥轮换：brave_api_keys等复数字段接受 JSON 数组，每次请求随机选一把，自动摊平限流。
• 只写文件，不混入环境变量：config set内部走 LoadFile()（只读文件、不叠加环境变量），因此KETCH_*注入的值永远不会被误写进config.json。
• 坏文件拒写：如果现有配置 JSON 损坏或类型错误，config set会拒绝覆盖，避免把你的其他设置冲掉——需要手工修复。

🔑 KETCH_* 环境变量：容器与 CI 的免文件配置

每个标量配置项都有对应的环境变量，命名规则是机械映射：KETCH_+ 配置键名的大写下划线形式（实现见 config/env.go）：

典型用法：

KETCH_BRAVE_API_KEY=<key> ketch search "query" # 密钥不落盘 KETCH_BACKEND=ddg KETCH_LIMIT=10 ketch search "query" KETCH_CONFIG=/etc/ketch/config.json ketch config # 指向另一份配置文件

环境变量同样支持多密钥轮换——复数池没有*_API_KEYS变量，单数变量直接接受逗号分隔列表并整体替换该提供商的密钥池：

KETCH_BRAVE_API_KEY=key1,key2 ketch search "query"

⚠️刻意不提供环境变量覆盖的例外（见 ADR-0001）：

• url_rewrites、spa_markers：正则/HTML 子串在 shell 引号里无法安全转义，只能在配置文件里写；
• github_token：它有专门的解析链KETCH_GITHUB_TOKEN> 配置文件 >$GITHUB_TOKEN/$GH_TOKEN>gh auth token，不走通用覆盖以免优先级倒挂。

🏆 4 级优先级机制详解

这是整个配置系统的核心，也是排查"为什么我的设置没生效"的第一站：

CLI flag > KETCH_* 环境变量 > config.json 文件 > 内置默认值

两个让机制透明化的设计：

1. 来源可追溯：ketch config输出中的env_overrides会列出每个被环境变量覆盖的键、对应的变量名和被替换的原值（密钥自动打码），一眼看懂"生效配置"和"文件配置"的差异从何而来。
2. 空值 = 未设置：环境变量设为空字符串时视为未设置，不会把配置清空。

🛡️ 密钥安全与错误处理

• 永不外泄：ketch config、ketch doctor、错误信息中都不打印 API 密钥与http_headers的值；派生的子进程（无头浏览器、外部 PDF 转换器）环境也会被 ScrubbedEnviron() 剥离所有KETCH_*密钥变量。
• 坏值响亮失败：KETCH_LIMIT=abc这样的非法值会在命令报错时点名该变量；坏的配置 JSON 同样会报出"哪个键、需要哪种类型"（退出码 2），且整份文件不被部分应用。
• 关键命令不受坏环境影响：ketch version、ketch config set/path等不消费配置的命令在坏环境下依然可用。

📂 相关源码与文档

掌握config.json、KETCH_*环境变量与这 4 级优先级后，你就掌握了 ketch 配置的全部：本地用config set落盘，容器用环境变量注入，临时实验用 CLI flag，一切生效情况用ketch config随时验证。