README.md

metadata

title: Smart Search Crawler
emoji: 🕷️
colorFrom: blue
colorTo: indigo
sdk: docker
pinned: false

Smart Search Crawler - 多平台商品爬虫系统

基于 Crawlee + Playwright 的高性能商品数据抓取工具，采用 TypeScript 编写，支持动态扩展多个电商平台。

✨ 核心特性

• 🚀 高性能并发: 支持多线程并发爬取，智能资源拦截加速
• 🛡️ 防封禁策略: 三种预设模式（快速/稳定/隐蔽）应对不同场景
• 🔌 动态路由架构: 通过 source 参数自动选择对应平台爬虫，易于扩展
• 📊 灵活配置: 集中化 CSS 选择器管理，支持运行时切换
• 💾 多格式输出: 支持 JSON 和 CSV 格式导出
• 🔧 类型安全: 完整的 TypeScript 类型定义
• 🌐 REST API: 简洁的 HTTP 接口，支持批量爬取
• ☁️ 多云部署: 支持 Hugging Face Spaces、Render.com、VPS 等多种部署方式

---

🚀 快速开始

1. 安装依赖

npm install

2. 安装 Playwright 浏览器

npx playwright install chromium

国内用户加速:

# PowerShell
$env:PLAYWRIGHT_DOWNLOAD_HOST="https://npmmirror.com/mirrors/playwright/"
npx playwright install chromium

3. 启动 Web 服务

npm run serve

服务将在 http://localhost:7860 启动。

---

📡 API 使用指南

1. 健康检查

请求:

curl http://localhost:7860/health

响应:

{
  "status": "ok",
  "service": "smart-search-crawler",
  "timestamp": "2024-04-20T14:00:00.000Z",
  "supportedSources": ["Otto"]
}

2. 执行爬取任务

请求:

curl -X POST http://localhost:7860/crawl \
  -H "Content-Type: application/json" \
  -d '{
    "source": "Otto",
    "urls": [
      "https://www.otto.de/p/product-url-1",
      "https://www.otto.de/p/product-url-2"
    ],
    "preset": "stable"
  }'

参数说明:

参数	类型	必填	说明
source	string	✅	爬虫源标识（如 "Otto"），系统根据此值动态路由到对应爬虫
urls	string[]	✅	待爬取的商品 URL 数组
preset	string	❌	预设模式：fast / stable（默认）/ stealth

响应示例:

{
  "success": true,
  "source": "Otto",
  "count": 2,
  "data": [
    {
      "url": "https://www.otto.de/p/product-url-1",
      "crawledAt": "2024-04-20T14:00:00.000Z",
      "price": "279,99 €",
      "rating": "4.5",
      "reviews": "(434)",
      "title": "Samsung Galaxy S23...",
      "imageUrl": "https://..."
    }
  ]
}

---

⚙️ 配置详解

预设模式对比

模式	并发数	超时	重试次数	适用场景
fast	20	30s	1	快速测试、少量 URL
stable	5	90s	1	生产环境（✅ 推荐）
stealth	3	180s	1	大规模爬取、防封禁

---

☁️ Hugging Face Spaces 部署说明

本 Space 已配置为 Docker 部署模式，具有以下特点：

环境配置

• 服务器位置: 欧洲（访问 Otto.de 等欧洲网站速度快）
• 端口: 7860（HF 强制要求）
• 内存: 16GB RAM
• CPU: 2 vCPU

性能建议

• 推荐并发数: 1-2（避免 OOM）
• 超时设置: 120秒（适应跨国网络）
• 休眠策略: 48小时无访问自动休眠

使用示例

# 测试健康检查
curl https://sky5678-crawler.hf.space/health

# 执行爬取任务
curl -X POST https://sky5678-crawler.hf.space/crawl \
  -H "Content-Type: application/json" \
  -d '{
    "source": "Otto",
    "urls": ["https://www.otto.de/p/example-product/"],
    "preset": "stable"
  }'

---

🏗️ 项目结构

crawler/
├── src/
│   ├── config.ts              # 全局配置（选择器、预设模式）
│   ├── otto-crawler.ts        # Otto 平台核心爬虫实现
│   └── batch-crawler.ts       # 批量处理与文件 I/O
├── examples/
│   └── usage-examples.ts      # 代码集成示例
├── server.ts                  # Express REST API 服务
├── quick-start.ts             # 交互式命令行工具
├── Dockerfile                 # Docker 容器化配置
└── .github/workflows/         # GitHub Actions CI/CD

---

⚠️ 注意事项

1. 遵守 robots.txt: 请尊重目标网站的爬虫政策
2. 控制频率: 建议使用 stable 或 stealth 模式
3. 网络优化: HF Spaces 位于欧洲，访问欧洲电商网站延迟低
4. 选择器维护: 网站结构变更可能导致选择器失效

---

📄 许可证

MIT License

---

🤝 贡献

欢迎提交 Issue 和 Pull Request！

扩展新平台的步骤:

1. 在 src/ 下创建新的爬虫文件
2. 实现统一的 ProductData[] 返回接口
3. 在 server.ts 的 crawlerMap 中注册
4. 提交 PR 并添加测试用例