# CrawlerPlan

**Repository Path**: lmrybc49/crawler-plan

## Basic Information

- **Project Name**: CrawlerPlan
- **Description**: 情报搜集各方案调研
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-10
- **Last Updated**: 2026-07-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CrawlerPlan — 多平台情报收集爬虫系统

从知乎、小红书、豆瓣、微博、Twitter、Facebook 等平台爬取热搜和关键词搜索内容的后端系统。

**当前阶段：技术调研 + MVP 实现** — 已针对知乎完成 5 条技术路线的调研，其中 3 条已完整实现并通过验证，2 个通用搜索/抓取模块已可用。

---

## 快速开始

```bash
# 1. 安装依赖
uv sync
# 或: pip install -r requirements.txt

# 2. 安装浏览器（使用浏览器方案的模块需要）
playwright install chromium

# 3. 配置环境变量
cp .env.example .env
# 编辑 .env 填入你的 OPENAI_API_KEY（AI Agent 模块需要）

# 4. 启动服务（任选一个模块）
python main.py --zhihu_cloakBrowser          # 推荐：反检测浏览器方案
python main.py --zhihu_cloakBrowser_BrowserUse  # 融合方案
python main.py --zhihu_browser_use           # AI Agent 方案
python main.py --searxng_search              # 元搜索引擎
python main.py --crawl_search                # 网页抓取
```

服务启动后访问 http://localhost:8000/docs 查看 Swagger API 文档。

---

## 项目结构

```
CrawlerPlan/
├── main.py                 # FastAPI 统一入口
├── pyproject.toml          # 项目元数据与依赖
├── requirements.txt        # pip 依赖清单
├── .env.example            # 环境变量模板
├── crawlers/               # 爬虫模块目录
│   ├── __init__.py         # 模块注册表 CRAWLER_REGISTRY
│   ├── zhihu_http/         # HTTP 直接请求方案（占位）
│   ├── zhihu_playwright/   # Playwright 浏览器方案（占位）
│   ├── zhihu_browser_use/  # browser-use + AI Agent ✅
│   ├── zhihu_cloakBrowser/ # CloakBrowser 反检测方案 ⭐ 推荐
│   └── zhihu_cloakBrowser_BrowserUse/
│                           # CloakBrowser + browser_use 融合方案 ✅
├── searxng_search/         # SearXNG 元搜索引擎模块 ✅
├── crawl_search/           # Crawl4AI 网页抓取模块 ✅
├── shared/                 # 公共工具
│   ├── config.py           # 配置管理（python-dotenv）
│   ├── logger.py           # 统一日志
│   └── models.py           # Pydantic v2 数据模型
├── docs/
│   ├── plan.md             # 技术调研方案文档（含方案对比）
│   └── CloakBrowser+Browser_use方案分析.md
├── browser_data/           # 浏览器持久化数据（Cookie/Profile，gitignored）
└── tests/                  # 测试目录
```

---

## 模块总览

| 模块 | 技术栈 | 反检测 | 状态 | 适用场景 |
|------|--------|:---:|:---:|------|
| `zhihu_http` | httpx 异步请求 | ❌ | 占位 | API 结构稳定的平台 |
| `zhihu_playwright` | Playwright 浏览器 | ⭐ | 占位 | 基础浏览器采集 |
| `zhihu_browser_use` | browser-use + LLM Agent | ⭐⭐ | ✅ 已实现 | 复杂页面、快速原型 |
| **`zhihu_cloakBrowser`** ⭐ | **CloakBrowser + CSS 选择器** | **⭐⭐⭐⭐⭐** | ✅ 已实现 | **生产环境主力** |
| `zhihu_cloakBrowser_BrowserUse` | CloakBrowser CDP + browser_use | ⭐⭐⭐⭐⭐ | ✅ 已实现 | 反爬 + AI 自适应 |
| `searxng_search` | SearXNG API + httpx | — | ✅ 已实现 | 聚合多搜索引擎结果 |
| `crawl_search` | Crawl4AI + Playwright/CloakBrowser | ⭐⭐⭐ | ✅ 已实现 | 网页内容抓取 + Markdown |

---

## API 端点

| 方法 | 路径 | 参数 | 说明 |
|------|------|------|------|
| GET | `/health` | — | 健康检查 |
| GET | `/hot` | `platform` (必填) | 获取平台热搜/热榜 |
| GET | `/search` | `platform` (必填), `keyword` (必填) | 关键词搜索，返回前 10 条 |

**示例请求：**

```bash
# 知乎热榜
curl "http://localhost:8000/hot?platform=zhihu_cloakBrowser"

# 知乎搜索
curl "http://localhost:8000/search?platform=zhihu_cloakBrowser&keyword=Python"

# 聚合搜索
curl "http://localhost:8000/search?platform=searxng_search&keyword=AI"

# 网页抓取（SearXNG 搜索 + Crawl4AI 抓取第一个结果）
curl "http://localhost:8000/search?platform=crawl_search&keyword=机器学习"
```

---

## 爬虫模块开发规范

### 模块接口约定

每个模块必须在 `crawler.py` 中导出：

```python
async def crawl(keyword: str | None = None) -> list[dict]:
    """
    keyword=None → 返回热点/热搜内容
    keyword=str  → 返回关键词搜索的前 10 条结果

    返回格式：
    [{"title": str, "url": str, "summary": str, "platform": str, "score": float}, ...]
    """
```

### 新增模块步骤

1. 在 `crawlers/` 下创建目录：`crawlers/<模块名>/`
2. 创建 `crawler.py`，实现 `crawl` 函数
3. 创建 `README.md` 说明技术路线
4. 在 `crawlers/__init__.py` 的 `CRAWLER_REGISTRY` 中注册
5. 启动：`python main.py --<模块名>`

---

## 知乎方案选择建议

```
主力方案（生产环境定时任务）:
  → zhihu_cloakBrowser          反检测最强、速度快(~15s)、稳定可预测

辅助方案（探索性爬取 / 页面频繁改版）:
  → zhihu_cloakBrowser_BrowserUse  反检测 + AI 自适应
  → zhihu_browser_use              AI 自适应、快速原型

共享基础设施:
  → Cookie 持久化（Chrome 锁文件清理）
  → 密码登录（JS 文本匹配定位 + Playwright 原生键盘输入）
  → 验证码处理（Cookie 持久化规避，首次人工）
```

详细方案对比见 [docs/plan.md](docs/plan.md)。

---

## 环境变量

核心配置（完整列表见 `.env.example`）：

| 变量 | 必填 | 说明 |
|------|:---:|------|
| `OPENAI_BASE_URL` | * | LLM API 地址（AI Agent 模块需要） |
| `OPENAI_API_KEY` | * | LLM API Key |
| `BROWSER_USE_MODEL` | | Agent 使用的模型（默认 `gpt-4o`） |
| `ZHIHU_ACCOUNT` | | 知乎登录手机号（CloakBrowser 模块） |
| `ZHIHU_PASSWORD` | | 知乎登录密码 |
| `SEARXNG_BASE_URL` | | SearXNG 服务地址（默认 `http://localhost:9999`） |
| `FORMATTER_MODEL` | | 兜底格式化模型（Agent JSON 解析失败时） |
| `CLOAK_CDP_PORT` | | CloakBrowser CDP 端口（默认 `9242`） |

---

## 技术栈

| 类别 | 选型 |
|------|------|
| Web 框架 | FastAPI (Python 3.11+) |
| 包管理器 | uv / pip |
| 爬虫引擎 | CloakBrowser / Playwright / browser-use / Crawl4AI / SearXNG |
| AI Agent | OpenAI 兼容格式（DeepSeek v4-pro 等） |
| 配置管理 | python-dotenv（`.env` 文件） |
| 数据校验 | Pydantic v2 |
| 异步 HTTP | httpx |

---

## 约束与注意事项

- **NEVER** 硬编码 API Key、Token、密码
- **NEVER** 违反目标平台的 robots.txt 或服务条款
- **NEVER** 将 `.env` 文件提交到版本控制
- 添加新依赖后需同步更新 `requirements.txt` 和 `pyproject.toml`
- 模块间禁止循环依赖
- 始终使用异步 HTTP 客户端（`httpx.AsyncClient`）
- 使用 `os.getenv()` 读取所有配置

---

## 相关文档

- [技术调研方案](docs/plan.md) — 各方案的详细技术分析、对比、踩坑记录
- [CloakBrowser 生产部署指南](crawlers/zhihu_cloakBrowser/PRODUCTION.md)
- [browser_use 错误排障手册](crawlers/zhihu_browser_use/errorLog/error-handbook.md)
- [browser_use 项目总结](crawlers/zhihu_browser_use/SUMMARY.md)
- [融合方案分析](docs/CloakBrowser+Browser_use方案分析.md)