wigolo 故障排查完全指南：从 doctor 诊断到 blocked_by_challenge、平台差异与网络问题修复-平芜编程栈

wigolo 故障排查完全指南：从 doctor 诊断到 blocked_by_challenge、平台差异与网络问题修复

【免费下载链接】wigoloThe go-to web for your AI coding agent — local-first search, fetch, crawl & research over MCP. No API keys, no cloud, $0/query. Public beta.项目地址: https://gitcode.com/GitHub_Trending/wi/wigolo

本篇指南以 wigolo 官方 Troubleshooting 文档（docs/troubleshooting.md）为主体骨架，逐条讲解最常见的故障症状、对应的修复命令、组件下载失败后的真实影响边界，以及 Windows / Linux / macOS / ARM 各平台的行为差异。读完你能够熟练使用wigolo doctor与wigolo warmup定位并修复安装问题，理解blocked_by_challenge标签背后的抓取层级与 IP 信誉现实，并在代理、离线等受限网络环境中完成模型的预下载与迁移。

排查的第一步永远是`wigolo doctor`

遇到任何异常，第一条命令不是去看日志、不是重装，而是运行内置诊断：

wigolo doctor # 指出哪个组件损坏，以及修复它所需的环境变量 / 命令 wigolo doctor --fix # 自动修复已知的失败类别

doctor是一个纯本地的快照式体检：它检查数据目录可写性、Python 与 Docker（仅搜索侧车需要）、浏览器引擎是否可启动、TLS 抓取层级、ML reranker 与 embeddings 模型缓存、各 LLM provider 的密钥配置（密钥永远只显示掩码）、搜索后端模式与各搜索引擎的健康状态。从源码看，其核心体检项位于 src/cli/doctor.ts 的runDoctorColdChecks：浏览器、embeddings、searxng 侧车、熔断器（breaker）与数据目录逐一给出ok / failed / skipped状态，且全部是"存在性快照"，不会触发任何模型下载或浏览器启动。

两点值得注意的细节：

浏览器检查不是看文件在不在，而是真实启动。checkPlaywright复用与 warmup 完全一致的probeBrowser探针做一次无头启动——在裸 Linux 上二进制存在但缺系统库时，existsSync会误报"健康"，而真实启动会立刻暴露缺失的库。这正是 src/cli/doctor.ts 里注释强调"doctor 不能与 warmup 对浏览器健康判断不一致"的原因。
--fix只修有明确修复路径的项：installBrowser('chromium')、installEmbeddings()、searxng 状态清理、熔断器重置（含向运行中 daemon 的/admin/reset-breakers下发）。数据目录不可写这类权限问题无法自动修复，doctor 会明确报告但保持degraded。退出码契约是：0 = 全部必要组件 OK（可选组件缺失不扣分）；1 = 任一必要组件降级。

诊断输出里还有个"隐藏技能"：wigolo doctor的搜索引擎表格会逐行显示每个引擎的状态——ok、needs-key (set WIGOLO_GITHUB_TOKEN ...)、disabled (set BRAVE_API_KEY ...)，并附带熔断器状态与已知的不可修复限制说明（src/cli/doctor.ts 的formatEngineHealthLines）。所以当搜索结果变薄时，先跑 doctor 看是哪个引擎"变暗"了、它想要什么。

症状 → 修复对照表

下表完整覆盖官方文档列出的全部症状与修复路径，并补充了底层依据：

症状	修复
`init`期间某个组件下载失败	`wigolo warmup --all`重跑全部下载（也可用`--browser`/`--reranker`/`--embeddings`只补一个）。失败不会阻塞 wigolo 其他部分——组件会在首次使用时惰性重试。
Linux 上浏览器引擎无法启动	`wigolo warmup --browser`会安装浏览器引擎所需的操作系统库（必要时用 sudo 提权）；装不了时，错误信息会打印出你可以自己执行的精确安装命令，执行后再重跑`wigolo warmup`。
`wigolo serve`退出：端口被占用	daemon 刻意不做自动换绑。错误信息会给出一个空闲端口供重试，例如`wigolo serve --port 3334`。src/cli/daemon.ts 中明确写着 "Not auto-rebinding — retry with a free port"——这是设计行为而非缺陷，避免守护进程在无人知晓的情况下漂移端口导致既有调用方全部失联。
`wigolo serve`拒绝在非回环主机上启动	符合设计（fail-closed）。设置`WIGOLO_API_TOKEN`/`WIGOLO_API_TOKEN_FILE`，或显式传`--allow-unauthenticated`。详见绑定回环之外。
Fetch 结果返回`blocked_by_challenge`	见下文 blocked_by_challenge 专节。
搜索结果变薄 / 某个引擎像"死了"	降级引擎是被报告而非被隐藏——检查响应中的`engine_warnings`、`engine_telemetry`、`engine_pool`，以及`wigolo doctor`的逐引擎表格（引擎只是缺 key 时它会点名所需环境变量，如`WIGOLO_GITHUB_TOKEN`、`BRAVE_API_KEY`）。熔断器处于 open/half-open 的引擎会以`[breaker open — 上游错误摘要]`的形式显示在 doctor 表格里，让你知道它为何不派发请求。
结果陈旧	传`force_refresh: true`（适合新闻、价格、changelog），或清除指定条目：`wigolo cache clear --url-pattern="example.com"`。缓存寿命可调：`CACHE_TTL_SEARCH`（默认 86400 秒/1 天）、`CACHE_TTL_CONTENT`（默认 604800 秒/7 天），完整配置见 docs/configuration.md。
在企业代理后面一切请求都失败	设置`USE_PROXY=true`和`PROXY_URL`（凭据存入操作系统钥匙串，不落盘）。见 fetch 与浏览器引擎配置。
某个原本正常的域名开始出问题	wigolo 会学习每个域名的抓取路由；站点改版可能使其学到的路由失效。`wigolo tune show <domain>`查看，`wigolo tune reset <domain>`重新学习。
watch 任务从不触发	watch 检查只在 daemon（`wigolo serve`）或 MCP 会话存活期间运行——一次性 CLI 调用只能注册任务，无法调度它们。从 src/watch/scheduler.ts 的结构看，调度循环依附于常驻进程的生命周期。
浏览器引擎下载缓慢或超时	常见于被限速或地域受限的网络。重跑`wigolo warmup --browser`——它会重试并断点续传。若默认下载 CDN 在你所在地区很慢，可在 warmup 前设置`PLAYWRIGHT_DOWNLOAD_HOST=<mirror-url>`指向镜像。底层实现里，浏览器安装有 300 秒超时和 2 次尝试的预算（`BROWSER_INSTALL_TIMEOUT_MS = 300_000`），超时被识别为网络受限并给出镜像提示而非无限重试（src/cli/warmup.ts）。
embeddings 模型下载失败（`TAR_BAD_ARCHIVE`/ "unrecognized archive"）	截断或损坏的下载。wigolo 现在会自动清除不完整文件并重新下载一次；若仍失败，`wigolo config --cleanup`后再跑`wigolo warmup --embeddings`。
排序模型下载失败（`fetch failed`）	一次瞬时网络抖动。重跑`wigolo warmup --reranker`——它会带退避重试。
下载报`self signed certificate in certificate chain`	你在做 TLS 检查的（企业）代理后面。把 Node 指向组织 CA 包——`NODE_EXTRA_CA_CERTS=/path/to/corp-ca.pem`——然后重跑 warmup。
`npm install`编译原生依赖失败（常见于 Windows）	你的 Node 版本没有预编译二进制，npm 回退到源码编译。请使用有预编译产物的受支持 LTS——Node 20、22 或 24——或在 Windows 上安装 C/C++ 工具链（Visual Studio Build Tools）。
磁盘空间低导致下载停滞或失败	组件需要约 1 GB 空闲。释放空间、把`WIGOLO_DATA_DIR`指向更大的卷，或`wigolo config --cleanup`回收上次安装的残留。

关于`wigolo tune`：域名级路由的查看与重置

tune是上述"域名曾经正常、现在异常"症状的直接工具。它是对缓存库中域名路由投影的一层薄 CLI（src/cli/tune.ts），支持：

wigolo tune list # 列出所有已学习路由的域名 wigolo tune show <domain> # 查看单个域名的路由 wigolo tune reset <domain> # 清除单个域名的已学习路由 wigolo tune reset --all # 清除全部 wigolo tune ... --json # 输出单一 JSON 文档（人类可读行走 stderr，JSON 走 stdout）

表格列包含DOMAIN / TLS / BROWSER / TLS_HITS / HTTP_FAILS / BACKOFF / CLEARANCE，直接对应 wigolo 自调优的四类行为：TLS 模拟层级提升、浏览器引擎升级、已解反爬挑战的 clearance 复用、以及被反复拦截后的礼貌退避窗口。站点改版导致路由失效时，reset让 wigolo 重新学习。

组件安装失败——wigolo 坏了吗？

没有。init即使有下载失败也会以退出码 0 结束，而且核心功能（搜索、HTTP fetch、crawl、extract、cache）完全不需要模型和浏览器。失败的组件会优雅降级——具体代价如下：

哪个组件失败了	你失去什么	仍然正常工作的
浏览器引擎	JS 渲染页面回退到纯 HTTP fetch（部分 SPA 内容可能缺失）	搜索、HTTP fetch、crawl、extract、cache、模型
embeddings 模型	语义发现——`find_similar`和语义缓存排序回退到关键词匹配	搜索、fetch、crawl、extract、关键词缓存
排序模型	ML 重排环节（多引擎 rank fusion 仍然生效）	其他一切——只是结果排序颗粒度降低
没有 LLM key	`research`/`agent`/`search --format answer`返回结构化证据而非书面散文	所有无 key 工具（这正是默认形态）

任何时候都可以重跑wigolo warmup --all重试下载，或干脆让每个组件在首次使用时惰性加载。

从源码看，这一"永不阻塞"的契约在 src/cli/init.ts 的runFullSetup中被显式保证：warmup 即使抛异常，init 也打印修复提示后继续完成 agent 接线与配置持久化，并输出逐组件报告（✓ ready/○ skipped (lazy)/✗ failed + Fix:），随后附加 doctor 冷检查摘要。浏览器、embeddings、reranker 的失败都被映射为"可修复"项，对应修复命令各不相同（src/cli/init.ts）。

另一个支撑点：warmup 对每个模型都做端到端冒烟测试而非"下载完成即成功"——reranker 下载后会真正跑一次rerank调用，embeddings 会实际embed(['warmup'])并校验向量维度（src/cli/warmup.ts）。所以warmup报告ok的组件，是可以直接用的。

blocked_by_challenge 标签深度解析

这个标签意味着目标站点位于一个在挑战窗口内未被清除的反爬挑战之后。wigolo 会逐级升级抓取层级（纯 HTTP → TLS 模拟层级 → 完整浏览器引擎），像耐心浏览器一样轮询挑战，并按域名复用此前解出的 clearance——而当这一切都无效时，它会如实告诉你，而不是把挑战页面伪装成内容返回。

两个诚实的现实，用来校准预期：

IP 信誉是被评分的。在数据中心 IP（VPS、CI、云主机）上，部分受挑战保护的站点无论如何都不会清除——即使从住宅连接发出完全相同的请求就能成功。这是你的运行位置属性，而不是 wigolo 漏掉了某个旋钮。
可选杠杆是代理，其 IP 信誉要与你的合法研究用途匹配——见数据中心 IP 的现实。凭据存入钥匙串，且礼貌机制（robots.txt、按域名限速）依旧生效。

从源码角度，这个标签有完整的实现支撑：挑战无法清除时，路由层会把它归一化为结构化的blocked_by_challenge阶段错误，浏览器池对该错误有专门映射（src/fetch/browser-pool.ts），fetch 路由层保证"挑战回退变成blocked_by_challenge，绝不把挑战外壳当作内容泄漏出去"（src/fetch/router.ts），REST 错误层把blocked_by_challenge列为标准上游失败原因之一（src/daemon/rest/errors.ts）。相关可调参数见 docs/configuration.md：WIGOLO_CHALLENGE_COMPLETION_MS（默认 15000，浏览器层轮询挑战页多久后快速失败）、WIGOLO_TLS_TIER（off/auto/on）、WIGOLO_STEALTH与WIGOLO_TLS_BROWSER。

平台注意事项

Node 版本。wigolo 运行在Node 20、22 或 24（LTS）上。过新或不常见的 Node 构建可能还没有预编译原生二进制，会尝试从源码编译（需要 C/C++ 工具链）——坚持使用 LTS 即可避免。

Windows。支持 Node 20+。数据目录是%USERPROFILE%\.wigolo。环境变量用你 shell 的语法设置（PowerShell 中$env:WIGOLO_SEARCH="hybrid"）；其他一切——命令、flags、端口——与 Unix 文档完全一致。注意npm install编译原生依赖失败在该平台上最常出现，解决方案就是上文对照表中的 Node LTS 或 Visual Studio Build Tools。

Linux（精简镜像 / 容器）。浏览器引擎需要若干操作系统库；wigolo warmup --browser会安装它们（有 sudo 时提权），否则打印你需要手动执行的精确命令。Python 不是必需的——它只被可选的搜索引擎侧车使用，所以 "Python 3 not found" 提示在核心使用中可以安全忽略。实际上 warmup 对 searxng 阶段的降级路径设计得很细致：无 Python 时报no_python，无python3-venv模块时报no_venv并给出 apt 安装提示、回退到内置 core 搜索后端，而不是用难懂的 traceback 让整个 warmup 失败（src/cli/warmup.ts）。

macOS（Apple Silicon / Intel）。完全支持——模型和浏览器都包含在内。

Linux on ARM（arm64）。核心搜索、fetch、crawl、extract 和 cache 正常工作。语义功能目前在 linux-arm64 上不可用——embeddings 模型的 tokenizer 还没有预编译 ARM 二进制，所以find_similar、embeddings 和语义缓存排序回退到关键词匹配。如果今天就需要 Linux 上的语义功能，请运行在 x64 主机上；此事已纳入未来版本计划。doctor 的诊断输出会把这一事实如实展示——checkFastembedCache检测模型缓存目录，而 src/cli/doctor.ts 的注释明确"惰性 ≠ 盲目"：存在但损坏的目录会在首次使用时暴露。

慢速、代理或离线网络

慢速或地域受限的链接。模型和浏览器下载是耗时大头，重跑时可断点续传。wigolo init --no-warmup跳过全部前置下载——每个组件随后在首次使用时惰性加载。浏览器引擎 CDN 被限速时，在 warmup 前设置PLAYWRIGHT_DOWNLOAD_HOST镜像。
企业代理。设置USE_PROXY=true和PROXY_URL（凭据进 OS 钥匙串，不落盘）。在 TLS 检查代理后面，还需设置NODE_EXTRA_CA_CERTS指向你的 CA 包，使下载校验通过。
气隙 / 离线环境。在联网机器上运行wigolo warmup --all，然后把它的~/.wigolo复制到目标机器以预置模型和浏览器。注意：search 和 fetch 在查询时仍然访问实时网络——只有模型/浏览器的下载可以预置。

补充一个磁盘层面的细节：数据目录里模型与缓存的体积是可查、可回收的。wigolo config --storage打印按组件划分的存储使用地图，wigolo config --cleanup cache|embeddings|models|browser|searxng按组件释放空间（src/cli/config.ts 显示释放后输出Cleaned <component>: freed N MB）。wigolo config --cache-stats则给出缓存条目数与体积。

日志都在哪里

wigolo 把全部日志写到 stderr（默认结构化 JSON；LOG_FORMAT=text给人看，LOG_LEVEL=debug提高详细度）。没有隐藏的日志目录：

CLI 运行：日志出现在终端 stderr；用2>wigolo.log重定向。
MCP 宿主：宿主把 server 的 stderr 捕获进它自己的 MCP 日志位置。
systemd / Docker 下的wigolo serve：journal / 容器日志。
wigolo 自己写事件的唯一文件是可选遥测 NDJSON（~/.wigolo/telemetry/），且仅在WIGOLO_TELEMETRY=1时。遥测默认关闭，只写到本地文件，不发送任何数据；只有额外设置WIGOLO_TELEMETRY_ENDPOINT才会 POST 到你自己的端点（docs/configuration.md）。

这个"日志只在 stderr"的设计是有意为之：stdout 被保留给 MCP 协议流量和--json工具输出，日志永远不污染它们（docs/configuration.md）。

常见问题（FAQ）

商业模式是什么？会开始收费吗？wigolo 是免费的开源软件，采用 AGPL-3.0 许可。没有托管层级、没有计费 API、没有需要购买的 key——它是本地软件，你的机器完成工作。这正是它的意义所在。

AGPL 对我意味着什么，直白地说？把 wigolo 当作工具使用——个人、公司内部、接入你运行的每个 agent——零义务。许可证的分享条款只在你修改 wigolo 本身并以网络服务形式为他人运行修改版时生效：那时你需要分享这些修改。构建仅仅调用 wigolo 的产品不属于这种情况。

用它做抓取道德吗？wigolo 的默认配置围绕做一个礼貌客户端构建：默认遵守 robots.txt、按域名限速与抓取延迟、为研究而非批量收割设计的页面预算、以及诚实的失败标注而不是死磕撞墙。这里"可靠性工作"意味着像真实浏览器那样读页面——它不是伪装工具包，文档也不会教你造一个。

它有多稳定？当前为 0.2.0 公开测试版。文档化的功能面由约 7,600 个自动化测试组成的测试套件守护；beta 关乎的是打磨标准和 API 形态的信心，而不是已知的不稳定。真正存在的限制都写在文档里，而不是留到生产环境才被发现——见上文挑战上限一节。

为什么安装包这么大？因为智能在本地。下载体积主要来自设备端 embedding + 排序模型（约 250 MB）和 JS 渲染抓取所需的可选浏览器引擎二进制（约 0.5–1 GB）。这是换取无 key、私有、零按次调用成本运作的代价。init --no-warmup可推迟全部下载；wigolo config --cleanup可回收它们。

wigolo 故障排查完全指南：从 doctor 诊断到 blocked_by_challenge、平台差异与网络问题修复