diff --git a/README.md b/README.md new file mode 100644 index 0000000..de17d42 --- /dev/null +++ b/README.md @@ -0,0 +1,343 @@ +# Cloudflare Search + +> 基于 Cloudflare Workers 的聚合搜索 API 服务 + +[![Deploy to Cloudflare Workers](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/Yrobot/cloudflare-search) + +## 特性 + +- 🔍 **多引擎聚合** - 同时使用多个搜索引擎（Google、Brave、DuckDuckGo、Bing） +- ⚡ **并行搜索** - 所有搜索引擎同时请求，快速返回结果 +- 🛡️ **容错机制** - 单个引擎失败不影响其他引擎，自动标记无响应引擎 +- ⏱️ **超时控制** - 可配置请求超时时间，避免长时间等待 +- 🌍 **CORS 支持** - 完整的跨域资源共享支持 +- 🎨 **Web 界面** - 提供简洁的搜索界面，方便测试 +- ⚡ **零成本运行** - Cloudflare Workers 免费版每天 10 万次请求 + +## 页面展示 + +![screenshot](./screenshot.png) + +## 安装方式 + +### 方式一：一键部署（推荐） + +点击上方 "Deploy to Cloudflare Workers" 按钮，按照提示完成部署。 + +### 方式二：使用 Wrangler CLI + +```bash +# 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](https://dash.cloudflare.com/) +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） + +使用查询参数进行搜索： + +```bash +# 基本搜索 +curl "https://$YOUR-DOMAIN/search?q=cloudflare" + +# 指定搜索引擎 +curl "https://$YOUR-DOMAIN/search?q=cloudflare&engines=google,brave" +``` + +### 方式 3: API 请求（POST） + +通过 POST 表单提交搜索： + +```bash +curl -X POST "https://$YOUR-DOMAIN/search" \ + -d "q=cloudflare" \ + -d "engines=google,brave" +``` + +## API 接口说明 + +### `/search` 接口 + +用于执行搜索查询并返回聚合结果。 + +#### 请求参数 + +| 参数 | 类型 | 必填 | 说明 | 示例 | +| ------------- | -------- | ---- | ---------------------------- | -------------- | +| `q` / `query` | `string` | yes | 搜索关键词 | `cloudflare` | +| `engines` | `string` | no | 指定搜索引擎，多个用逗号分隔 | `google,brave` | + +**支持的搜索引擎**： + +- `google` - Google 搜索（需要配置 API Key） +- `brave` - Brave 搜索 +- `duckduckgo` - DuckDuckGo 搜索 +- `bing` - Bing 搜索 + +#### 返回值 + +```typescript +{ + query: string; // 搜索关键词 + number_of_results: number; // 结果总数 + enabled_engines: string[]; // 启用的搜索引擎列表 + unresponsive_engines: string[]; // 无响应的搜索引擎列表 + results: Array<{ + title: string; // 结果标题 + description: string; // 结果描述 + url: string; // 结果链接 + engine: string; // 来源引擎 + }>; +} +``` + +#### 请求示例 + +```bash +# GET 请求 +curl "https://$YOUR-DOMAIN/search?q=cloudflare&engines=google,brave" + +# POST 请求 +curl -X POST "https://$YOUR-DOMAIN/search" \ + -H "Content-Type: application/x-www-form-urlencoded" \ + -d "q=cloudflare&engines=google,brave" +``` + +#### 响应示例 + +```json +{ + "query": "cloudflare", + "number_of_results": 15, + "enabled_engines": ["google", "brave", "duckduckgo"], + "unresponsive_engines": [], + "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": "google" + }, + { + "title": "Cloudflare Workers", + "description": "Deploy serverless code instantly across the globe...", + "url": "https://workers.cloudflare.com/", + "engine": "brave" + } + ] +} +``` + +## 搜索引擎说明 + +### 支持的搜索引擎 + +| 引擎 | 说明 | 是否需要配置 | 默认启用 | +| -------------- | ------------------------ | ----------------------------- | --------------- | +| **Google** | Google Custom Search API | 需要 GOOGLE_API_KEY GOOGLE_CX | yes | +| **Brave** | Brave Search API | - | yes | +| **DuckDuckGo** | DuckDuckGo 即时答案 API | - | yes | +| **Bing** | Bing 搜索 | - | no (结果不稳定) | + +### 基本工作方案 + +1. **并行请求**：所有启用的搜索引擎同时发起请求，提高响应速度 +2. **超时控制**：单个引擎超时不影响其他引擎，默认 3 秒超时 +3. **结果聚合**：将所有成功返回的结果合并，标记来源引擎 +4. **容错处理**：记录无响应的引擎，返回部分结果而不是完全失败 + +### 搜索引擎选择建议 + +- **无需配置快速部署**：使用 `brave` + `duckduckgo` +- **高质量结果**：配置 Google API 并使用 `google` + `brave` +- **最大覆盖**：启用所有引擎 `google,brave,duckduckgo,bing` + +## 环境变量配置 + +### 环境变量说明 + +| 变量名 | 类型 | 默认值 | 说明 | +| ----------------- | -------- | -------- | ------------------------------------------------- | +| `DEFAULT_TIMEOUT` | `string` | `"3000"` | 单个搜索引擎的超时时间（毫秒） | +| `GOOGLE_API_KEY` | `string` | `null` | https://console.cloud.google.com/apis/credentials | +| `GOOGLE_CX` | `string` | `null` | https://programmablesearchengine.google.com/ | + +**注意**：Google Custom Search API 免费版每天限制 100 次请求。 + +### 配置方式 + +#### 方式 1: wrangler.toml 文件 + +编辑 `wrangler.toml` 文件中的 `[vars]` 部分： + +```toml +[vars] +GOOGLE_API_KEY = "your-google-api-key" +GOOGLE_CX = "your-google-custom-search-cx" +DEFAULT_TIMEOUT = "5000" +``` + +#### 方式 2: Cloudflare Dashboard + +1. 进入 Worker 设置页面 +2. 找到 **Environment Variables** 部分 +3. 添加变量并保存 + +## 使用场景 + +### 1. 聚合搜索服务 + +构建自己的搜索聚合 API，整合多个搜索引擎结果： + +```javascript +const response = await fetch( + "https://$YOUR-DOMAIN/search?q=javascript&engines=google,brave" +); +const data = await response.json(); +console.log(`找到 ${data.number_of_results} 个结果`); +``` + +### 2. 前端搜索功能 + +为网站或应用添加搜索功能： + +```javascript +async function search(query) { + const response = await fetch( + `https://$YOUR-DOMAIN/search?q=${encodeURIComponent(query)}` + ); + const data = await response.json(); + return data.results; +} +``` + +### 3. 数据采集与分析 + +收集多个搜索引擎的结果进行对比分析： + +```javascript +const engines = ["google", "brave", "duckduckgo"]; +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; +}, {}); +``` + +## 注意与提醒 + +### 🚨 重要提示 + +1. **使用自定义域名** + + - Cloudflare 默认的 `*.workers.dev` 域名在某些地区可能无法访问 + - **强烈建议**绑定自己的域名以获得更好的访问体验 + - 在 Worker 设置中点击 **Triggers** > **Add Custom Domain** 添加自定义域名 + +2. **搜索引擎限制** + + - Google API 免费版每天限制 100 次请求 + - 其他搜索引擎一般没有严格限制，但请合理使用 + - 频繁请求可能导致被临时限制访问 + +3. **超时设置** + - 默认单个引擎超时 3 秒 + - 可通过环境变量 `DEFAULT_TIMEOUT` 调整 + - 建议不要设置过长，避免整体响应时间过长 + +## 常见问题 + +### Q: 为什么有些搜索引擎返回结果为空？ + +A: 可能原因： + +- 搜索引擎 API 临时不可用或响应超时 +- 搜索关键词没有相关结果 +- 搜索引擎限制了访问频率 +- Google 需要配置 API Key 才能使用 + +可以查看返回的 `unresponsive_engines` 字段了解哪些引擎没有响应。 + +### Q: 如何提高搜索速度？ + +A: 建议： + +- 减少启用的搜索引擎数量，只使用需要的引擎 +- 适当调整超时时间（`DEFAULT_TIMEOUT`） + +### Q: Bing 搜索为什么默认禁用？ + +A: Bing 搜索结果目前不够稳定，经常返回空结果或格式不一致。如需使用，可以在请求时手动指定：`engines=bing` 或修改 `envs.js` 中的 `DEFAULT_ENGINES`。 + +## 免责声明 + +本项目仅供学习和研究使用，使用者需遵守以下规定： + +1. **合法使用** - 仅用于合法搜索需求，不得用于违法或侵权用途 +2. **服务条款** - 使用时需遵守 Cloudflare Workers 和各搜索引擎的服务条款 +3. **API 限制** - 遵守各搜索引擎 API 的使用限制和配额 +4. **责任自负** - 使用本服务产生的任何后果由使用者自行承担 +5. **商业用途** - 如需商业使用，请确保符合相关法律法规和服务条款 + +## 贡献 + +欢迎提交 Issue 和 Pull Request！ + +## 许可证 + +[GPL-3 License](LICENSE) + +## 相关链接 + +- [项目 GitHub](https://github.com/Yrobot/cloudflare-search) +- [Cloudflare Workers 文档](https://developers.cloudflare.com/workers/) +- [Google Custom Search API](https://developers.google.com/custom-search/v1/overview) + +--- + +**如果这个项目对你有帮助，请在 [GitHub](https://github.com/Yrobot/cloudflare-search) 上给我们一个 ⭐️** diff --git a/screenshot.png b/screenshot.png new file mode 100644 index 0000000..c625620 Binary files /dev/null and b/screenshot.png differ