karust/openserp

 # OpenSERP [](https://goreportcard.com/report/github.com/karust/openserp) [](https://pkg.go.dev/github.com/karust/openserp) [](https://github.com/karust/openserp/releases) [](https://hub.docker.com/r/karust/openserp) [](https://github.com/karust/openserp/actions/workflows/ci.yml) **OpenSERP** 是一个免费、开源的 SERP API 和 CLI，用于从 **Google, Yandex, Baidu, Bing, DuckDuckGo 和 Ecosia** 获取实时搜索数据。 它可以作为 **LLM、agents 和 RAG pipelines** 的搜索工具，或作为跨 **Google、Yandex、百度等进行 SEO 排名追踪** 的抓取后端。当您的工作流需要覆盖俄罗斯/中国的网络资源，而不是仅仅依赖只支持 Google 的 API 时，它尤其有用。 您可以在本地运行、自行托管，或者当您想要相同的公共 API 结构而无需自行运维服务器时，使用 [云端版本](https://openserp.org/cloud)。 ## 功能 - 🔍 **多搜索引擎** - 专为 Google、Yandex、Baidu、Bing、DuckDuckGo 和 Ecosia 提供的专用 endpoint，可为 SEO 排名 pipelines 提供稳定的 JSON - 🌐 **Megasearch** - `/mega/search` 可在所有选定的引擎中运行单个查询，然后合并并对结果去重 - 📄 **URL 提取** - 一次调用即可返回搜索结果以及干净的 Markdown/文本目标页面内容，适用于内容接入（grounding）和自动化 - ✨ **SERP 特性** - 在响应中包含 AI 摘要、答案框、相关问题（people-also-ask）及相关搜索 - 🖼 **图片** - 同时支持图片搜索 - 🎯 **高级过滤器** - 支持语言、日期范围、文件类型和指定站点的查询 - 📝 **数据格式** - 支持 JSON、Markdown、Text、NdJSON 响应格式 - 🌍 **可配置** - 支持 proxy、cache 和弹性模式 - 🐳 **Docker 就绪** - 支持本地和 container 部署 ## ⚡ 快速开始 ### Docker 预构建的镜像已发布至 [Docker Hub: `karust/openserp`](https://hub.docker.com/r/karust/openserp)。 ``` # 通过预构建镜像运行 API 服务器 docker run --rm -p 127.0.0.1:7000:7000 karust/openserp:latest serve -a 0.0.0.0 -p 7000 # 或者 docker compose up ``` ### Go install ``` go install github.com/karust/openserp@latest openserp search duckduckgo "open source serp api" --format markdown ``` ### 从源码构建 ``` git clone https://github.com/karust/openserp.git cd openserp go build -o openserp . ./openserp serve ``` ### 首次请求 ``` curl "http://127.0.0.1:7000/mega/search?engines=bing,google&text=golang+vs+rust&extract=1&mode=any" ```

JSON 响应示例

``` { "query": { "text": "golang vs rust", "engines_requested": ["bing", "google"] }, "meta": { "request_id": "019ecdc0-a66d-79a4-9d2b-9e9b480d495e", "requested_at": "2026-06-16T00:06:55Z", "took_ms": 720, "engines_responded": ["bing"], "engines_failed": [], "version": "2.1" }, "results": [ { "id": "s_5a8273f16b19ab64", "rank": 1, "type": "organic", "title": "The Go Programming Language", "url": "https://go.dev/", "display_url": "go.dev", "snippet": "Get Started Playground Tour Stack Overflow Help Packages Standard Library About Go Packages About Download Blog Issue Tracker Release Notes Brand Guidelines Code of Conduct Connect …", "domain": "go.dev", "favicon": "https://go.dev/favicon.ico", "position": { "absolute": 1 }, "engine": "bing", "domain_info": { "tld": "dev", "sld": "go", "category": "" }, "extracted": { "title": "Build simple, secure, scalable systems with Go", "format": "markdown", "content": "## Build simple, secure, scalable systems with Go\n\n\n\n- “At the time, no single team member knew Go, but **within a month, everyone was writing in Go** and we were building out the endpoints. It was the flexibility, how easy it was to use, and the really cool concept behind Go (how Go handles native concurrency, garbage collection, and of course safety+speed.) that helped engage us during the build. Also, who can beat that cute mascot!”\n ........", "mode_used": "fast", "fetched_at": "2026-06-16T00:06:56Z" } }, { "id": "s_1a364ebcb3035539", "rank": 2, "type": "organic", "title": "Go (programming language) - Wikipedia", "url": "https://en.wikipedia.org/wiki/Go_(programming_language)", "display_url": "en.wikipedia.org › wiki › Go_(programming_language)", "snippet": "In Go's package system, each package has a path (e.g., \"compress/bzip2\" or \"golang.org/x/net/html\") and a name (e.g., bzip2 or html). By default other packages' definitions must always be prefixed with …", "domain": "en.wikipedia.org", "favicon": "https://en.wikipedia.org/favicon.ico", "position": { "absolute": 2 }, "engine": "bing", "domain_info": { "tld": "org", "sld": "wikipedia", "category": "" }, "classification": { "content_type": "article", "source_hint": "encyclopedia" } }, ... ], "serp_features": [], "pagination": { "page": 1, "has_more": false, "next_start": 10 }, "clusters": [ { "id": "c_f20b23a020101dce", "canonical_url": "https://go.dev/", "domain": "go.dev", "title": "The Go Programming Language", "occurrences": [ { "engine": "bing", "rank": 1, "result_id": "s_5a8273f16b19ab64" } ], "engines_count": 1, "best_rank": 1, "score": 0.5 }, ... ] } ```

## 部署选项 - **自托管（本仓库）** - 免费、基于 MIT 许可证，可完全控制 runtime、proxy、cache 和扩展。 - **[OpenSERP Cloud](https://openserp.org/cloud)** - 由项目维护者提供的可选托管版本，具有相同的 API 结构。 该托管 API 有助于为开源项目的持续开发提供资金。拥有相同的 endpoint、相同的响应 schema，并且客户端代码可以双向无缝迁移。 ## API 文档 服务器运行后，即可在本地访问交互式文档： - Swagger UI: `http://127.0.0.1:7000/docs` - OpenAPI YAML: `http://127.0.0.1:7000/openapi.yaml` 要在不运行服务器的情况下浏览规范，请参阅 [docs/openapi.yaml](./docs/openapi.yaml)。有关 OpenSERP 内部工作原理的更高层次概述，请参阅 [架构文档](https://openserp.org/docs/architecture/)。 ## SDK 与示例 官方客户端包。每一个都可以针对您的自托管服务器（设置 `baseUrl`）或 [托管 API](https://openserp.org/cloud)（设置 `apiKey`）工作： | 类型 | Package | 安装 | | --------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------- | | JavaScript / TypeScript SDK | [`@openserp/sdk`](https://www.npmjs.com/package/@openserp/sdk) | `npm install @openserp/sdk` | | Python SDK | [`openserp`](https://pypi.org/project/openserp/) | `pip install openserp` | | MCP server (AI agents) | [`@openserp/mcp`](https://www.npmjs.com/package/@openserp/mcp) | `npx @openserp/mcp` | | n8n community node | [`@openserp/n8n-nodes-openserp`](https://www.npmjs.com/package/@openserp/n8n-nodes-openserp) | 通过 n8n 社区节点安装 | 有关涵盖搜索、AI 接入（grounding）、SEO、内容提取和图片搜索的 JavaScript 和 Python 小型用例，请参阅 [**示例**](./examples)。 ``` import { OpenSERP } from "@openserp/sdk"; // Use your self-hosted server const client = new OpenSERP({ baseUrl: "http://localhost:7000" }); const { results } = await client.search({ engine: "google", text: "openserp", limit: 5 }); ``` ## 搜索 Endpoint 可用的引擎名称：`google`, `yandex`, `baidu`, `bing`, `duckduckgo`, `ecosia`。 专用引擎 endpoint： ``` curl "http://127.0.0.1:7000/google/search?text=golang&limit=10" ``` 图片搜索： ``` curl "http://127.0.0.1:7000/bing/image?text=golang+logo&limit=10" ``` Megasearch： ``` curl "http://127.0.0.1:7000/mega/search?text=golang&limit=10" ``` | 模式 | 最适用场景 | 行为 | | ---------- | ------------------------------------ | ---------------------------------------------- | | `balanced` | 大多数多引擎 SERP 工作流 | 并行查询多个引擎并合并结果 | | `fast` | 最低延迟 | 使用最快的可用引擎 | | `any` | 回退式的可用性检查 | 依次尝试引擎，直到有一个响应 |

更多 Megasearch 示例

``` # Fast 模式 curl "http://127.0.0.1:7000/mega/search?text=golang&mode=fast&engines=google,bing,yandex" # Any 模式 curl "http://127.0.0.1:7000/mega/search?text=golang&mode=any&engines=google,yandex,bing" # 带有 aggregation 控制的 Balanced 模式 curl "http://127.0.0.1:7000/mega/search?text=golang&mode=balanced&dedupe=true&merge=true" # 高级过滤 curl "http://127.0.0.1:7000/mega/search?text=golang&engines=google,bing&limit=20&date=20250101..20251231&lang=EN®ion=US" # 图片 megasearch curl "http://127.0.0.1:7000/mega/image?text=golang+logo&limit=20" ```

列出引擎： ``` curl "http://127.0.0.1:7000/mega/engines" ``` URL 提取： ``` # 提取单个 URL 为 JSON curl "http://127.0.0.1:7000/extract?url=https://example.com&mode=auto" # 返回干净的页面 markdown curl "http://127.0.0.1:7000/extract?url=https://example.com&format=markdown" # 将提取的内容嵌入到顶部搜索结果下 curl "http://127.0.0.1:7000/google/search?text=llm+observability&extract=2&format=markdown" ``` ## 🖥 CLI 搜索 无需服务器 - 直接从终端查询引擎。CLI 与 API 共享相同的引擎、格式和过滤器。 ``` openserp search duckduckgo "free open source serp" --format markdown ```

CLI 输出及更多示例

``` # “free open source serp”的搜索结果 **Query:** free open source serp - **Engines:** duckduckgo - **Took:** 1794ms ## 结果 ### 1. OpenSERP：开源、自托管且免费的 SERP API **openserp.org** - organic OpenSERP is a free, open-source and self-hosted SERP API for Google, Bing, Yandex, Baidu, DuckDuckGo and Ecosia, with an optional managed Cloud path. -> https://openserp.org/ ### 2. GitHub - karust/openserp：适用于 AI、SEO 和自动化的开源 SERP API ... **github.com › karust › openserp** - organic OpenSERP is a free, open-source API and CLI for accessing normalized search engine results from Google, Yandex, Baidu, Bing, DuckDuckGo, and Ecosia. Run it locally, self-host it, or use the optional hosted API when you do not want to manage infrastructure. -> https://github.com/karust/openserp ``` 更多 CLI 示例： ``` # JSON 是默认格式 openserp search google "golang generics" --limit 20 # 纯文本，德国结果 openserp search yandex "wetter berlin" --format text --lang DE --region DE # 限制到单个站点并 stream NdJSON openserp search bing "release notes" --site github.com --format ndjson # 嵌入来自前 2 个结果的干净页面内容 openserp search google "llm observability" --extract 2 --format markdown # 通过 proxy 的 Browserless（原始 HTTP）模式 openserp search duckduckgo "free open source serp" --raw --proxy http://user:pass@127.0.0.1:8080 ```

运行 `openserp search --help` 获取完整的 flag 列表。引擎名称：`google`, `yandex`, `baidu`, `bing`, `duckduckgo`, `ecosia`。 ## 🔍 查询参数 常用参数： | 参数 | 描述 | 示例 | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------ | | `text` | 搜索查询 | `golang programming` | | `lang` | 语言代码 | `EN`, `DE`, `RU`, `ES` | | `region` | 市场/地区提示。国家/地区代码在各引擎中通用；Google 还通过 `uule` 接受城市名称；Yandex 接受数字形式的 `lr`。 | `DE`, `en-GB`, `Berlin`, `213` | | `date` | 日期范围 | `20250101..20251231` | | `file` | 文件扩展名 | `pdf`, `doc`, `xls` | | `site` | 指定站点搜索 | `github.com` | | `limit` | 自然结果数量，最大 100。如果省略或 `<=10`，则仅解析第一个 SERP 页面。 | `25`, `50` | | `start` | 分页偏移量 | `0`, `10`, `20` | | `format` | 输出格式 | `json`, `markdown`, `text`, `ndjson` | | `extract` | 获取并为排名靠前的网页结果嵌入目标页面内容。布尔值或整数深度：`0`/`false` 关闭，`true`/`1` 取第一个结果，`N` 取前 N 个 (1-5)。除非设为 `extract=0`，否则 `extract_mode`/`min_runes` 将隐式设为 `extract=true` | `1`, `3`, `true` | | `extract_mode` | 提取策略：优先原始 HTTP、仅原始内容、或浏览器渲染 | `auto`, `fast`, `rendered` | 特定引擎参数： | 参数 | 支持的引擎 | 备注 | | ---------- | ----------------- | ---------------------------------------------------------------------- | | `filter` | `google` | 重复过滤器：`true` 隐藏相似结果，`false` 包含相似结果。 | | `features` | 浏览器 `Search` | 从实时页面填充 `serp_features[]`。默认值为 `true`。 | ## 搜索响应示例

搜索响应示例

``` { "query": { "text": "golang", "engines_requested": ["google"] }, "meta": { "request_id": "019dc6c1-da45-706e-a57c-d671fa2862ee", "requested_at": "2026-04-25T22:27:52Z", "took_ms": 6410, "engines_failed": [], "version": "2.1" }, "results": [ { "id": "s_78341aa47c336101", "rank": 1, "type": "organic", "title": "Documentation - The Go Programming Language", "url": "https://go.dev/doc/", "display_url": "go.dev > doc", "snippet": "Official Go documentation, tutorials, references, and release notes.", "domain": "go.dev", "favicon": "https://go.dev/favicon.ico", "position": { "absolute": 1 }, "engine": "google", "domain_info": { "tld": "dev", "sld": "go", "category": "" } } ], "pagination": { "page": 1, "has_more": true, "next_start": 25 } } ```

## Mega 响应说明 `/mega/search` 返回相同的信封结构（envelope）以及 `clusters`。结果通过规范化的 URL 进行去重；clusters 会保留每个引擎的出现情况。

Cluster 示例

``` { "id": "c_a1b2c3d4e5f6a1b2", "canonical_url": "https://go.dev/", "domain": "go.dev", "title": "The Go Programming Language", "occurrences": [ { "engine": "google", "rank": 1, "result_id": "s_78341aa47c336101" }, { "engine": "bing", "rank": 2, "result_id": "s_20f9f15f0c3d9f6d" } ], "engines_count": 2, "best_rank": 1, "score": 0.75 } ```

## 图片响应示例

图片结果示例

``` { "id": "i_a1b2c3d4e5f6a1b2", "rank": 1, "type": "image", "title": "Go Gopher Logo", "image": { "url": "https://example.com/images/go-logo.png", "thumbnail": "https://example.com/images/go-logo-thumb.png", "width": 1200, "height": 800 }, "source": { "page_url": "https://go.dev/brand/", "domain": "go.dev" }, "engine": "bing" } ```

## 错误响应 `400 Bad Request`： ``` { "error": "bad_request", "code": 400, "message": "EMPTY_QUERY: query cannot be empty: provide text, site, or file parameter", "reason": "EMPTY_QUERY" } ``` `503 Service Unavailable`： ``` { "error": "service_unavailable", "code": 503, "message": "captcha found, please stop sending requests for a while: captcha detected" } ``` ## 健康检查与统计 ``` curl -i "http://127.0.0.1:7000/health" curl "http://127.0.0.1:7000/ready" curl "http://127.0.0.1:7000/stats" curl "http://127.0.0.1:7000/stats/cache" curl "http://127.0.0.1:7000/stats/proxy" curl "http://127.0.0.1:7000/stats/cb" ``` ## 许可证 本项目基于 MIT 许可证授权。详情请见 [LICENSE](LICENSE)。 ## 反馈与更新 - [GitHub Issues](https://github.com/karust/openserp/issues) - Bug、功能建议以及可复现的问题。 - [feedback@openserp.org](mailto:feedback@openserp.org) - 私人反馈、较长的建议，或任何不适合发布在 GitHub Issues 中的内容。 - [Telegram 频道](https://t.me/+RJEKspw3mUlhZDMy) - OpenSERP 新闻、版本说明和项目更新。私信功能开放，用于快速反馈和有关托管 API 的问题。

标签：BeEF, EVTX分析, Go, RAG, Ruby工具, SEO, SERP API, 搜索引擎, 日志审计, 爬虫, 网络调试, 自动化, 请求拦截