README.md

---
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. 安装依赖

```bash
npm install
```

### 2. 安装 Playwright 浏览器

```bash
npx playwright install chromium
```

**国内用户加速:**
```powershell
# PowerShell
$env:PLAYWRIGHT_DOWNLOAD_HOST="https://npmmirror.com/mirrors/playwright/"
npx playwright install chromium
```

### 3. 启动 Web 服务

```bash
npm run serve
```

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

---

## 📡 API 使用指南

### 1. 健康检查

**请求:**
```bash
curl http://localhost:7860/health
```

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

### 2. 执行爬取任务

**请求:**
```bash
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` |

**响应示例:**
```json
{
  "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小时无访问自动休眠

### 使用示例

```bash
# 测试健康检查
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 并添加测试用例