跳转到内容
Escriba Suite Escriba Suite

Searchgirl 文档

Searchgirl 有四张面孔，由同一个二进制文件提供。本页逐一介绍它们、底层的 SearXNG 引擎以及套件（联合）模式。

Web UI

Section titled “Web UI”

http://localhost:8089——带建议的首页、按类别展示的结果（综合、新闻、图片、 视频、科学、IT 等）、语言／日期／SafeSearch 过滤器、直接答案与信息框，以及 浅色／深色主题。缩略图经由 Searchgirl 自己的代理（/thumb）： 你的浏览器永不触碰各引擎的主机。

REST API

Section titled “REST API”
端点作用
GET /api/search?q=...搜索。参数：category、language、time_range（day/week/month/year）、safesearch（0-2）、page、engines。
GET /api/suggest?q=...自动补全。
POST /api/answer带引用的 AI 综合：{"query": "...", "fetch_pages": true}——无 LLM 时返回 503。
POST /api/readURL → Markdown：{"url": "https://..."}。
GET /api/engines · /api/categories引擎／类别目录。
GET /api/config版本、鉴权模式、LLM 可用性。
GET /healthz存活探测。
Terminal window
curl "http://localhost:8089/api/search?q=searxng&category=news&time_range=week"

响应是一个规范化、稳定的结构——按 URL 去重、评分、域名、ISO 日期—— 独立于 SearXNG 的原始 JSON。

MCP（面向 Claude Code、Claude Desktop 或任何 MCP 客户端）

Section titled “MCP（面向 Claude Code、Claude Desktop 或任何 MCP 客户端）”

MCP 服务器运行在 http://localhost:8089/mcp（streamable HTTP 传输）。工具：

  • search——元搜索，参数有 category、language、time_range、max_results。
  • url_read——将公开 URL 抓取为 Markdown（带 SSRF 防护）。
  • answer——搜索 + 综合，带 [n] 引用（仅在配置了 LLM 时出现）。
Terminal window
# Claude Code:
claude mcp add --transport http searchgirl http://localhost:8089/mcp

若你设置了 SEARCHGIRL_MCP_TOKEN，请添加请求头：

Terminal window
claude mcp add --transport http searchgirl https://your-domain/mcp \
  --header "Authorization: Bearer <your token>"

偏好 stdio？同一个二进制文件：searchgirl serve（不带 -http）通过 stdio 提供 MCP——它需要能访问 SearXNG（取消 compose 中 127.0.0.1:8090:8080 映射的注释， 并导出 SEARXNG_URL=http://localhost:8090）。日常使用推荐走 HTTP 的 /mcp。

AI 回答（可选，默认关闭）

Section titled “AI 回答（可选，默认关闭）”

配置模型之后，UI 中会出现 AI 回答按钮，同时启用 POST /api/answer 和 MCP 工具 answer：它先搜索、选取最佳来源，然后写出一段简短的回答并以 [1][2] 引用，来源列表附于末尾。没有模型时，其余一切照常工作。

Terminal window
# Anthropic (native — takes priority if set):
ANTHROPIC_API_KEY=sk-ant-...


# or any OpenAI-compatible endpoint — local Ollama, OpenRouter, DeepSeek:
LLM_BASE_URL=https://openrouter.ai/api/v1
LLM_MODEL=deepseek/deepseek-chat
LLM_API_KEY=sk-or-...

底层的 SearXNG

Section titled “底层的 SearXNG”

引擎的配置位于 searxng/settings.yml：

  • search.formats: [html, json]——必不可少：没有 json 时 API 会返回 403。
  • server.limiter: false——SearXNG 不对外暴露；速率限制由 Searchgirl 提供。
  • autocomplete: duckduckgo——启用 /api/suggest。

SearXNG 默认激活大约 200 个引擎。若要精选它们，在 settings.yml 中添加：

use_default_settings:
  engines:
    remove: [qwant, startpage]   # the ones that keep failing on you

然后执行 docker compose restart searxng。

鉴权、令牌与速率限制

Section titled “鉴权、令牌与速率限制”
  • 本地登录——单用户（SEARCHGIRL_USER/SEARCHGIRL_PASS），标准的 Escriba 界面；登录之前一切均被拦截。
  • Bearer 令牌——SEARCHGIRL_MCP_TOKEN 接受多个具名令牌 （claude:abc...,n8n:def...）；吊销一个就是将它从列表中移除，而无需轮换 其余的。令牌与本地登录和联合模式都可组合——人类登录，智能体使用令牌。
  • 速率限制——API、MCP 和登录上的按 IP 限制（SEARCHGIRL_RATE_RPS / SEARCHGIRL_RATE_BURST）。位于反向代理之后时，请设置 SEARCHGIRL_TRUSTED_PROXIES，让限制通过 X-Forwarded-For 看到真实的客户端 IP。

套件模式（与 Lockatus 联合）

Section titled “套件模式（与 Lockatus 联合）”

在 Escriba 套件的 docker-compose.suite.yml 中，Searchgirl 以端口 8089 加入，并设置 AUTH_MODE=federado：经由 Lockatus 的单点登录（PKCE S256、HMAC Cookie），无本地登录。访问由中枢的矩阵管理（角色 admin/usuario）。关于生产 环境的 SSO 部署——注册 searchgirl 客户端、确切的 redirect_uri 规则与验证—— 请参阅 DEPLOY.md 的联合章节。

在 GitHub 上查看