SearXNG 搜索源 rogerdigital/dsh-searxng

dsh-searxng

dsh-vet

一个 DeepSeek Harness（dsh）插件，它将一个由 SearXNG 支持的搜索提供程序注册到 web 能力接缝（ctx.web）中，通过一个免费、自托管、无需密钥的元搜索实例为你的 agent 提供 web_search —— 而不是付费的 Exa/Perplexity API。

快速开始

要求：Node.js 20 或更高版本、dsh、Docker Engine 或 Docker Desktop，以及 Docker Compose v2。

setup 命令会安装 dsh-searxng 并将其附加到所选 profile，因此无需单独的插件安装步骤。

npx dsh-searxng setup
dsh --profile web

setup 会创建一个仅限回环、版本固定的 SearXNG Docker 部署，等待 JSON API 就绪，通过 SearXNG 和最终的 DSH 提供程序配置运行一次真实搜索，然后才会激活该 profile。重复执行该命令会复用同一个自有容器、端口、配置和密钥。

在需要时使用其他 DSH profile 或端口：

npx dsh-searxng setup --profile research --port 9080
dsh --profile research

包安装和 DSH 插件激活绝不会启动 Docker。只有显式的 dsh-searxng setup 或 dsh-searxng remove --service 命令才会更改 Docker。

现有 SearXNG

现有的本地、远程、需认证或独立管理的 SearXNG 实例是一等路径：

npx dsh-searxng setup --profile web --url https://search.example.com

该端点必须是 HTTP(S)，不包含凭据、查询或片段，并启用 JSON 搜索。
DSH profile 中现有的提供程序选项（如 authHeader、language、engines 和 categories）会被保留并用于验证。外部模式绝不会调用 Docker。

手动安装插件

如果你自行管理 DSH profile 补丁，并且不希望 setup 命令附加它，可以只安装插件包：

dsh plugin add dsh-searxng

使用具名 profile 时，请使用 dsh plugin --profile add dsh-searxng。

运维

快速健康检查结果；在第一个失败处停止。
npx dsh-searxng status --profile web

有序的环境、Docker、所有权、HTTP、JSON、搜索、profile 和提供程序检查，以及本地隐私态势及其明确的超出范围限制。
npx dsh-searxng doctor --profile web

只读的引擎健康探测组合：每个引擎报告的失败及原因、结果贡献和证据限制。不写入任何内容。
npx dsh-searxng tune --profile web

为受管部署规划并执行所有权安全的修复。
npx dsh-searxng repair --profile web

将受管部署迁移到打包版本，并带有经验证的回滚。
npx dsh-searxng update --profile web
分离配置文件并从该配置文件中移除插件包。
npx dsh-searxng remove --profile web

同时停止并移除所拥有的服务；保留其数据和本地状态。
npx dsh-searxng remove --profile web --service

永久删除确切拥有的数据卷和受管目录。
npx dsh-searxng remove --profile web --service --purge-data

永久删除会在交互式终端上提示确认。自动化必须添加 --yes。--json 在 setup、status、doctor、repair、update 和 remove 上可用。破坏性 Docker 操作仅在容器、网络和卷标签与此 DSH home 匹配后才运行；同名的外部资源会被拒绝。

恢复语义

repair 和 update 在第一次变更与验证完成之间，将其进度记录在 $DSH_HOME/dsh-searxng/journal.json 下；setup 和 remove 会读取该日志，以便在中断期间拒绝执行或在中断后进行清理。

- 当记录到中断的操作时，setup 会拒绝运行并指向 repair。当记录到匹配的部署但不健康时，它会重启卡住的运行时，或者——如果容器已消失而记录的 bundle 仍然存在（未使用 --purge-data 的 remove --service 的残留，或手动
docker compose down）——则从该 bundle 重新创建运行时。
- 当日志存在时，repair 会接管：它在任何普通修复之前从磁盘重新计算恢复决策（清除日志、验证目标或恢复回滚），并且还会移除死进程留下的隔离的过期锁。doctor 会报告中断操作的 id、kind、phase 和 age。
- update 是事务性的：当前部署保持权威，直到目标通过就绪、真实搜索和提供方验证。第一次 Docker 变更之后的任何失败都会回滚到先前的镜像和配置并重新验证它们；同版本更新会以 E_DEPLOYMENT_UNSUPPORTED 被拒绝。
- 一旦部署消失，remove --service 会清除日志，因此后续的 setup 不会被拒绝。它还会通过从状态中记录的 bundle 推导出 compose 文件，来移除无容器部署的带标签残留。

提供方配置

setup 命令管理 $DSH_HOME/profiles//cordis.patch.yml 中的 web-search-searxng 行。可以将这些可选值添加到该行：

| 键 | 默认值 | 含义 |
| baseURL | 受管或 --url 端点 | SearXNG 基础 URL。 |
| baseURLs | 无 | SearXNG 基础 URL 的故障转移池；第一项为主项，非空列表优先于 baseURL。 |
| language | 无 | SearXNG 语言，例如 zh-CN 或 en-US。 |
| engines | 无 | 逗号分隔的引擎允许列表。 |
| categories | 无 | 逗号分隔的类别过滤器。 |
| authHeader | 无 | 用于受保护外部实例的 Authorization 头。 |
| cacheTtlMs | 600000 | 缓存查询结果的存活时间（毫秒）；0 禁用缓存。 |
| minIntervalMs | 1500 | 网络请求之间的最小间隔；0 禁用节流。 |
| queueCapacity | 8 | 在提供方以背压拒绝之前，可等待节流槽位的请求数。 |
| totalBudgetMs | 15000 | 单次搜索调用的挂钟时间预算，涵盖节流等待、退避和网络尝试。 |

重复查询由作用域限定在提供方实例的进程内缓存提供服务（不会写入磁盘）；缓存命中不会发起网络请求。
并发搜索通过令牌桶（突发 2，之后每 minIntervalMs 一个请求），队列满时立即以可重试错误拒绝，而不是阻塞调用方。失败的响应和空结果页永远不会被缓存——缓存的空页面会在整个 TTL 内掩盖上游恢复——并且空结果页会按原样返回：engines/categories 允许列表绝不会为了追逐结果而被静默放宽。当实例返回 HTTP 429 时，提供方会遵循 Retry-After，并在剩余预算内最多重试一次。

多实例故障转移

在 baseURLs 中列出两个或更多端点（最多 8 个，重复项会合并），以将搜索路由到它们之间——例如先本地托管实例，再远程实例： yaml web-search-searxng: baseURLs:
- http://127.0.0.1:8080
- https://searxng.example.net

第一个条目是主端点。当某次尝试因网络错误、超时或 HTTP 502/503/504/429 失败时，该端点的健康惩罚会上升，下一次尝试（以及后续搜索的首次尝试）会转到最健康的端点；惩罚以 30 秒半衰期衰减，因此主端点会在最后一次失败约一分钟后恢复第一个槽位，或在成功搜索后立即恢复。格式错误的响应（contract 失败）和其他 4xx 状态码永远不会触发故障转移——这些是该端点上的配置问题，切换会静默掩盖它们。缓存以整个池为键，节流桶按端点划分，并且 totalBudgetMs 截止时间跨越每个端点的尝试；空结果页是有效答案，永远不会触发故障转移。setup --url 仍会为每个配置文件记录单个外部端点——在 CLI 后续功能发布之前，配置池需要手动编辑配置文件。

按查询控制

SearXNG 支持在查询字符串本身中进行按查询路由；提供方会原样传递查询语法：

- :zh-CN / :en — 为此查询选择结果语言（: 前缀）。
- !bing / !news — 为此查询选择一个引擎或类别（! 前缀）。
- site:example.com — 将结果限制到一个域（支持情况取决于引擎）。

例如，查询 :zh-CN 大模型 排行榜 会以中文搜索，无论配置文件的 language 是什么，而 !github compose network mapping 仅使用 GitHub 引擎。请根据你的实例的引擎列表验证引擎名称。
如果有多个 DSH 搜索提供程序可用，请使用
DSH_WEB_SEARCH_PROVIDER=searxng 或相应的 searchProvider DSH Web 配置选择此提供程序。

故障排除

- E_DOCKER_MISSING / E_DOCKER_OFFLINE：安装或启动 Docker。
- E_COMPOSE_UNSUPPORTED：启用 Docker Compose v2。
- E_JSON_DISABLED：将 json 添加到 SearXNG 的 search.formats。
- E_AUTH_FAILED：检查外部实例的 authHeader 配置。
- E_TLS_FAILED：端点的 TLS 证书验证失败；检查证书链并重试。
- E_RATE_LIMITED：调整实例限流器或上游引擎选择。
- E_RESOURCE_FOREIGN：同名 Docker 资源不带有此安装的所有权标签；它绝不会被自动修改。
- E_BUNDLE_DAMAGED：生成的配置包不完整或不匹配；repair 会从打包的资产中重建它，同时保留现有密钥。
- E_DEPLOYMENT_UNSUPPORTED：打包的部署目录无法满足请求（请求了未知或相同版本，或某个条目与当前状态不兼容）；请升级 dsh-searxng 或选择一个可用版本。
- E_PROFILE_CONCURRENT_MODIFICATION：DSH 配置文件在操作期间发生了更改；请检查它并重试。

doctor --json 返回完整的已脱敏检查列表和可操作的错误代码。

运行时支持

- Node.js：20 及更高版本。
- CLI、测试、构建和打包产物：已在 CI 中的 Linux、macOS 和 Windows 上验证。
- 托管 Docker 流程（包括修复和更新回滚）以及 Docker 适配器集成：已在选择启用的 Linux CI 中使用 Docker Engine 和 Compose v2 验证。发布认证运行器也在那里进行了演练；CI 不提供 Docker Desktop 并使用桩 dsh，因此它不是正式认证。
- 每个版本的已认证 Docker 环境：仅限那些在 docs/release-certification.md 中具有来自发布 tarball 的完整通过报告的环境——分别来自 macOS + Docker Desktop、Windows + Docker Desktop + WSL2 和 Linux + Docker Engine + Compose v2 各一个。
- macOS 上的 Docker Desktop 已针对 0.4.0 认证（docs/certification/v0.4.0-darwin-arm64.json）；Windows 上的 Docker Desktop 兼容（相同引擎、相同 Compose v2 插件），但在给定版本存在其报告之前未认证。
- 外部 SearXNG 模式不需要 Docker，可在任何使用 Node.js 20+ 的平台上运行。
- 托管路径不支持 Podman 和 Podman Compose。

setup 从打包的部署目录中选择要安装的部署（与当前状态 schema 兼容的最新条目），并复用仍列在目录中的健康现有部署；使用 update 在部署版本之间切换。

dsh 处于开发者预览阶段，预计会有破坏性变更。版本 0.4.0 支持
@deepseek-ai/dsh-web >=0.1.0-rc.6 =0.0.1-rc.3 .tgz

许可证

MIT