shumengya/cloudflare-search
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
cloudflare-search/README.zh.md
shumengya 9e24d85cd0 chore: sync local changes to Gitea
2026-06-24 22:10:22 +08:00

12 KiB
Raw Permalink Blame History

Cloudflare Search

English | 中文

基于 Cloudflare Workers 的聚合搜索 API 服务

支持 MCP (Model Context Protocol)，让 AI 助手（OpenClaw、Claude Code、Codex、OpenCode）拥有实时联网搜索能力

Deploy to Cloudflare Workers

特性

  • 🔍 多引擎聚合 - 同时使用 DuckDuckGo 和 Bing 搜索引擎
  • 🤖 AI 增强 (MCP) - 原生支持 Model Context Protocol，一键为 OpenClaw / Claude Code / Codex 添加搜索工具
  • ⚡ 并行搜索 - 所有搜索引擎同时请求，快速返回结果
  • 🛡️ 容错机制 - 单个引擎失败不影响其他引擎，自动标记无响应引擎
  • ⏱️ 超时控制 - 可配置请求超时时间，避免长时间等待
  • 🔒 Token 鉴权 - 支持 Token 认证，保护服务不被滥用
  • 🌍 CORS 支持 - 完整的跨域资源共享支持
  • 🎨 Web 界面 - 提供简洁的搜索界面，方便测试
  • ⚡ 零成本运行 - Cloudflare Workers 免费版每天 10 万次请求

页面展示

screenshot

MCP 集成， 在 OpenClaw / Claude Code / AI Agent 中使用

通过 MCP (Model Context Protocol) 让 AI 助手直接调用你的搜索服务，获取实时搜索结果。

安装配置

1. 部署服务

先按照文档 部署 Cloudflare Search

2. 添加 MCP 服务器配置

编辑配置文件（配置指南）：

  • OpenClaw: ~/.openclaw/openclaw.json
  • Claude Code: ~/.claude/config.json / ~/.claude.json
  • Claude Desktop macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Claude Desktop Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "cloudflare-search": {
      "command": "npx",
      "args": ["-y", "@yrobot/cf-search-mcp"],
      "env": {
        "CF_SEARCH_URL": "https://your-worker.workers.dev",
        "CF_SEARCH_TOKEN": "your-token-here"
      }
    }
  }
}

环境变量说明：

  • CF_SEARCH_URL: Worker 部署地址（必填）
  • CF_SEARCH_TOKEN: 鉴权 Token（如果 Worker 配置了 TOKEN 则必填）

3. 验证安装

  • OpenClaw: openclaw gateway restart + openclaw mcp list 能看到 cloudflare-search
  • Claude Code:
    • 在 Claude Code 中运行 /mcp 命令，应该能看到 cloudflare-search 工具。
    • 或 使用 claude mcp list, 看到 cloudflare-search: npx -y @yrobot/cf-search-mcp@latest - ✓ Connected 说明配置成功

安装方式

方式一：一键部署（推荐）

点击上方 "Deploy to Cloudflare Workers" 按钮，按照提示完成部署。

方式二：使用 Wrangler CLI

# 1. 安装 Wrangler
npm install -g wrangler

# 2. 登录 Cloudflare
wrangler login

# 3. 克隆仓库
git clone https://github.com/Yrobot/cloudflare-search.git
cd cloudflare-search

# 4. 部署
wrangler deploy

方式三：使用 Cloudflare Dashboard

  1. 登录 Cloudflare Dashboard
  2. 进入 Workers & Pages
  3. 点击 Create Application > Create Worker
  4. 点击 Upload 上传本地代码文件夹
    • 选择克隆的 cloudflare-search 文件夹
    • 或者手动复制 worker.js、envs.js、utils/ 等文件
  5. 点击 Save and Deploy

获取访问地址

部署成功后，你会获得一个 Worker URL：

https://your-worker-name.your-subdomain.workers.dev

注意：这个自带的域名在某些区域可能无法直接访问，建议绑定自己的域名使用。

使用方式

方式 1: Web 界面

直接访问你的 Worker URL，在网页界面输入搜索关键词：

https://$YOUR-DOMAIN/

方式 2: API 请求（GET）

使用查询参数进行搜索：

# 基本搜索
curl "https://$YOUR-DOMAIN/search?q=cloudflare"

# 指定搜索引擎
curl "https://$YOUR-DOMAIN/search?q=cloudflare&engines=duckduckgo,bing"

# 使用 token 鉴权（如果配置了 TOKEN 环境变量）
curl "https://$YOUR-DOMAIN/search?q=cloudflare&token=$YOUR-TOKEN"

方式 3: API 请求（POST）

通过 POST 表单提交搜索：

curl -X POST "https://$YOUR-DOMAIN/search" \
  -d "q=cloudflare" \
  -d "engines=duckduckgo,bing"
  -d "token=$YOUR-TOKEN" # 如果配置了 TOKEN 环境变量

API 接口说明

/search 接口

用于执行搜索查询并返回聚合结果。

请求参数

参数 类型 必填 说明 示例
q / query string yes 搜索关键词 cloudflare
engines string no 指定搜索引擎，多个用逗号分隔 duckduckgo,bing
token string no/yes 访问令牌（当配置了 TOKEN 环境变量时必填） $YOUR-TOKEN

支持的搜索引擎：

  • duckduckgo - DuckDuckGo 搜索
  • bing - Bing 搜索

返回值

{
  query: string;                    // 搜索关键词
  number_of_results: number;        // 结果总数
  enabled_engines: string[];        // 启用的搜索引擎列表
  unresponsive_engines: string[];   // 无响应的搜索引擎列表
  empty_engines: string[];          // 响应成功但无结果的搜索引擎列表
  engine_errors: Record<string, string>; // 各搜索引擎错误信息
  results: Array<{
    title: string;                  // 结果标题
    description: string;            // 结果描述
    url: string;                    // 结果链接
    engine: string;                 // 来源引擎
  }>;
}

请求示例

# GET 请求
curl "https://$YOUR-DOMAIN/search?q=cloudflare&engines=duckduckgo,bing"

# POST 请求
curl -X POST "https://$YOUR-DOMAIN/search" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "q=cloudflare&engines=duckduckgo,bing"

响应示例

{
  "query": "cloudflare",
  "number_of_results": 15,
  "enabled_engines": ["duckduckgo", "bing"],
  "unresponsive_engines": [],
  "empty_engines": [],
  "engine_errors": {},
  "results": [
    {
      "title": "Cloudflare - The Web Performance & Security Company",
      "description": "Cloudflare is on a mission to help build a better Internet...",
      "url": "https://www.cloudflare.com/",
      "engine": "duckduckgo"
    },
    {
      "title": "Cloudflare Workers",
      "description": "Deploy serverless code instantly across the globe...",
      "url": "https://workers.cloudflare.com/",
      "engine": "bing"
    }
  ]
}

搜索引擎说明

支持的搜索引擎

引擎 说明 是否需要配置 默认启用
DuckDuckGo DuckDuckGo HTML 搜索 - yes
Bing Bing 搜索 - no (结果不稳定)

基本工作方案

  1. 并行请求：所有启用的搜索引擎同时发起请求，提高响应速度
  2. 超时控制：单个引擎超时不影响其他引擎，默认 3 秒超时
  3. 结果聚合：将所有成功返回的结果合并，标记来源引擎
  4. 容错处理：记录无响应的引擎，返回部分结果而不是完全失败

环境变量配置

环境变量说明

变量名 类型 默认值 说明
DEFAULT_TIMEOUT string "3000" 单个搜索引擎的超时时间（毫秒）
TOKEN string null 访问令牌，配置后启用鉴权，保护服务不被滥用

注意：

  • TOKEN 配置后，所有请求都需要提供有效的 token

配置方式

方式 1: wrangler.toml 文件

编辑 wrangler.toml 文件中的 [vars] 部分：

[vars]
DEFAULT_TIMEOUT = "3000"
TOKEN = "your-secret-token-here"

方式 2: Cloudflare Dashboard

  1. 进入 Worker 设置页面
  2. 找到 Environment Variables 部分
  3. 添加变量并保存

使用场景

1. 聚合搜索服务

构建自己的搜索聚合 API，整合多个搜索引擎结果：

const response = await fetch(
  "https://$YOUR-DOMAIN/search?q=javascript&engines=duckduckgo,bing",
);
const data = await response.json();
console.log(`找到 ${data.number_of_results} 个结果`);

2. 前端搜索功能

为网站或应用添加搜索功能：

async function search(query) {
  const response = await fetch(
    `https://$YOUR-DOMAIN/search?q=${encodeURIComponent(query)}`,
  );
  const data = await response.json();
  return data.results;
}

3. 数据采集与分析

收集多个搜索引擎的结果进行对比分析：

const engines = ["duckduckgo", "bing"];
const results = await fetch(
  `https://$YOUR-DOMAIN/search?q=AI&engines=${engines.join(",")}`,
);
const data = await results.json();

// 按引擎分组
const byEngine = data.results.reduce((acc, result) => {
  acc[result.engine] = acc[result.engine] || [];
  acc[result.engine].push(result);
  return acc;
}, {});

MCP 集成

通过 MCP (Model Context Protocol) 让 AI 助手直接调用你的搜索服务，获取实时搜索结果。

注意与提醒

🚨 重要提示

  1. 使用自定义域名

    • Cloudflare 默认的 *.workers.dev 域名在某些地区可能无法访问
    • 强烈建议绑定自己的域名以获得更好的访问体验
    • 在 Worker 设置中点击 Triggers > Add Custom Domain 添加自定义域名

  2. 搜索引擎限制

    • 其他搜索引擎一般没有严格限制，但请合理使用
    • 频繁请求可能导致被临时限制访问

  3. 超时设置

    • 默认单个引擎超时 3 秒
    • 可通过环境变量 DEFAULT_TIMEOUT 调整
    • 建议不要设置过长，避免整体响应时间过长

🔒 安全配置

启用鉴权

  1. 配置 TOKEN 环境变量 来保护你的服务不被滥用：
  • 利用 wrangler.toml 配置 TOKEN 环境变量
  • 通过 Cloudflare Worker Dashboard 配置 TOKEN 环境变量
  1. 在请求时传入 token：
# 访问首页
https://$YOUR-DOMAIN?token=$YOUR-TOKEN

# 使用 query/body 的 token 参数 请求 API
curl "https://$YOUR-DOMAIN/search?q=cloudflare&token=$YOUR-TOKEN"

curl -X POST "https://$YOUR-DOMAIN/search" \
  -d "q=cloudflare" \
  -d "token=$YOUR-TOKEN"

常见问题

Q: 为什么有些搜索引擎返回结果为空？

A: 可能原因：

  • 搜索引擎 API 临时不可用或响应超时
  • 搜索关键词没有相关结果
  • 搜索引擎限制了访问频率

可以查看返回的 unresponsive_engines 字段了解哪些引擎没有响应。

Q: 如何提高搜索速度？

A: 建议：

  • 减少启用的搜索引擎数量，只使用需要的引擎
  • 适当调整超时时间（DEFAULT_TIMEOUT）

Q: Bing 搜索为什么默认禁用？

A: Bing 搜索结果目前不够稳定，出现内容与搜索关联度低的情况。如需使用，可以在请求时手动指定：engines=bing 或修改 envs.js 中的 DEFAULT_ENGINES。

Q: 如何保护服务不被滥用？

A: 建议配置 TOKEN 环境变量启用鉴权：

  1. 在 wrangler.toml 中设置 TOKEN = "your-random-token"
  2. 或在 Cloudflare Dashboard 的 Environment Variables 中添加
  3. 配置后所有请求都需要提供有效的 token

鉴权失败会返回 401 错误

免责声明

本项目仅供学习和研究使用，使用者需遵守以下规定：

  1. 合法使用 - 仅用于合法搜索需求，不得用于违法或侵权用途
  2. 服务条款 - 使用时需遵守 Cloudflare Workers 和各搜索引擎的服务条款
  3. API 限制 - 遵守各搜索引擎 API 的使用限制和配额
  4. 责任自负 - 使用本服务产生的任何后果由使用者自行承担
  5. 商业用途 - 如需商业使用，请确保符合相关法律法规和服务条款

贡献

欢迎提交 Issue 和 Pull Request！

许可证

GPL-3 License

相关链接

支持一下

如果这个项目对你有帮助，可以请作者喝杯咖啡 ☕

Reference in New Issue View Git Blame Copy Permalink