USAGE.md

# 小红书稳定采集微服务 (Spider_XHS) 使用说明文档

本文档旨在指导开发者、运维人员及业务方如何快速部署、配置、对接与运维 Spider_XHS 数据采集微服务。

---

## 1. 快速启动与部署

本项目推荐使用 Docker Compose 进行容器化部署，以保证运行环境的一致性。

### 1.1 前置要求
- **环境**：已安装 Docker 和 Docker Compose。
- **配置**：建议在宿主机（如项目根目录）准备 `.env` 文件。
- **数据目录**：宿主机需要预留足够的磁盘空间用于挂载 `./storage` 目录（存放任务状态、结果、回调失败记录、日志及 HTML 快照）。

### 1.2 启动步骤
在项目根目录执行以下命令，构建并以后台模式启动服务：
```bash
docker compose up -d --build
```
启动成功后，FastAPI 服务默认监听宿主机的 `8000` 端口。你可以通过访问 `http://localhost:8000/docs` 查看 Swagger UI 接口文档。

### 1.3 运营控制台前端（frontend/，可选）
项目内置一个运营控制台前端（Vite + React），用于在浏览器中查看健康状态、任务列表、任务详情与监控指标。

在项目根目录执行：
```bash
cd frontend
npm install
export VITE_API_BASE_URL=/api/v1
npm run dev
```

访问地址：`http://localhost:5173/`

页面路由：
- `/dashboard`：服务健康概览
- `/tasks`、`/tasks/:id`：任务中心与任务详情
- `/rpa`：RPA 回传（Chrome 插件）
- `/errors`：错误中心
- `/resources/accounts`、`/resources/sessions`、`/resources/proxies`：资源池中心
- `/content/raw-notes`、`/content/cleaned-notes`：内容库
- `/metrics`：监控指标

本地联调建议同时启动 FastAPI：
```bash
python -m uvicorn Spider_XHS.service.app:app --host 0.0.0.0 --port 8000 --reload
```

---

## 2. 核心配置说明 (环境变量)

服务的大部分行为通过环境变量进行控制，建议将敏感信息（如 Cookie）通过环境注入，切勿硬编码。

| 环境变量名 | 默认值 | 作用与说明 |
|---|---|---|
| `ENGINE_STRATEGY` | `auto` | 采集引擎调度策略（服务端自动执行的只有 A/B 两个引擎）。可选值：<br>- `auto`: 优先使用 API 引擎，遇风控自动降级到浏览器引擎<br>- `api`: 仅使用极速协议级引擎 (Spider_XHS)<br>- `browser`: 仅使用自动化浏览器引擎 (MediaCrawler) |
| `COOKIES` / `XHS_COOKIES` | 无 | 小红书登录后的 Cookie 字符串。支持多账号，可通过 `COOKIES_LIST` 等按逗号/换行分隔配置。 |
| `ACCOUNT_COOLDOWN_SECONDS` | `900` | 当账号遇到严重风控 (rate/risk) 时，自动进入冷却状态的时长（秒）。 |
| `SERVICE_PROXY` | 无 | 单一代理服务器地址（如 `http://127.0.0.1:7890`）。 |
| `SERVICE_PROXY_POOL` | 无 | 代理列表（逗号分隔）。浏览器引擎在重试时会按次数轮询；同时会与 `SERVICE_PROXY` 合并去重。 |
| `PROXY_API_URL` | 无 | 动态代理池提取 API（单个地址，向后兼容）；建议使用 `PROXY_API_URLS`。 |
| `PROXY_API_URLS` | 无 | 动态代理池的提取 API，支持逗号分隔配置多个 Provider，系统将自动定时拉取、验活与打分剔除。 |
| `PROXY_FILE_PATH` | 无 | 静态代理池文件路径（每行一个代理），支持与 API 代理池聚合使用。 |
| `CALLBACK_URL` | 无 | 任务完成后的 Webhook 回调推送地址。若配置，服务将在采集成功/失败后主动推送数据。 |
| `STORAGE_ROOT` | `./storage` | 容器内的本地文件存储路径。 |
| `ORCHESTRATOR_DB_PATH` | `orchestrator/data/mvp.db` | Orchestrator SQLite 路径（内容库接口 `/content/*` 读取，只读打开）。 |
| `RAW_DATA_RETENTION_DAYS` | `7` | 浏览器引擎采集时保留的原始 HTML 快照天数，过期自动清理。 |
| `ERROR_SUMMARY_SCAN_LIMIT` | `1000` | 错误中心默认扫描最近任务数（用于 `/errors/summary` 的默认 `scan_limit`）。 |
| `MEDIACRAWLER_STEALTH` | `1` | 浏览器引擎是否启用 Stealth 脚本注入（`0` 关闭）。 |
| `MEDIACRAWLER_HUMANIZE` | `1` | 浏览器引擎是否启用随机拟人化动作（`0` 关闭）。 |
| `AGENT_LLM_API_KEY` | 无 | **[必填]** 用于驱动 AI Agent 操作浏览器的视觉大模型 API 密钥（如 OpenAI Key）。 |
| `AGENT_LLM_MODEL` | `gpt-4o` | AI Agent 使用的模型名称。必须支持 Vision 多模态能力（如 `gpt-4o`, `claude-3-5-sonnet-20241022`）。 |
| `AGENT_LLM_BASE_URL` | 无 | 大模型 API 的自定义 Base URL（如使用中转代理地址时填写）。 |
| `OPENAI_API_KEY` | 无 | 独立配置：如果 AI 图文生成（`ai_generation.py`）需要使用不同的模型或通道，可在此配置。 |

---

## 3. 数据抓取实战操作指南

系统提供了多种灵活的抓取方式，以适应本地测试、运营操作和系统集成等不同场景。

### 3.1 方式一：命令行工具 (CLI) 本地抓取（推荐测试与获取 Cookie）
适合开发者在本地快速测试抓取效果，并获取最新、最完整的防风控 Cookie。
1. **扫码登录并保存 Cookie**：
   ```bash
   python cli.py login pc-qrcode --save-cookies --write-env
   ```
   > 运行后会弹出真实的浏览器界面供你扫码登录，登录成功后会自动将完整的 Cookie 和浏览器状态（包含 `storage_state.json`）更新到 `.env` 文件中。这是解决 `auth` 风控拦截的最佳方案。
2. **执行抓取命令**：
   ```bash
   python cli.py search --query "小红书架构设计" --num 10
   ```
   > 支持的子命令包括 `search` 等，结果会默认保存到项目目录下的 `datas/excel_datas/` 文件夹中。

### 3.2 方式二：前端运营控制台 (Web UI) 可视化抓取
适合运营人员或无需编写代码的用户进行可视化交互操作。
1. **启动服务**：确保后端 FastAPI 和前端 Vite 服务已正常启动（参考文档 1.2 和 1.3 节）。
2. **访问控制台**：在浏览器中打开 `http://localhost:5173/tasks` 进入任务中心。
3. **创建任务**：
   - **task_type**：填写 `search`（搜索）、`note_url`（单篇笔记）或 `user_profile`（用户主页）。
   - **target**：填写对应的关键词、笔记链接或用户主页链接。
   - 点击 **创建任务**。
4. **查看结果**：任务创建后会在列表中显示，点击列表中的任务 ID 即可进入详情页，实时查看轮询状态、Raw（原始快照数据）和 Normalized（清洗后标准数据）。

### 3.3 方式三：API 接口调用 (上游业务集成)
适合将数据采集能力集成到 Java/Go/Python 等后端微服务中。
- **操作步骤**：通过发送 HTTP POST 请求发起任务，再通过 GET 请求轮询结果，或配置 Webhook 接收自动回调。
- **详细说明**：请参考本文档第 **4. 对接指南 (上游业务调用)** 节。

### 3.4 方式四：离线兜底与插件 RPA 回传
当线上自动化引擎均遭遇极严格风控拦截时的人工兜底方案。
- **操作步骤**：利用小红书数据助手导出 Excel 或使用 Chrome 插件在真实浏览器中抓取，随后调用对应的导入接口将数据回传至服务端。
- **详细说明**：请参考本文档 **4.4 场景三：离线数据兜底导入** 及 **4.5 浏览器插件 RPA 回传**。

---

## 4. 对接指南 (上游业务调用)

### 4.1 接口规范
所有 API 请求路径前缀为 `/api/v1`。
所有响应统一为 JSON 格式：
```json
{
  "code": 200,          // 200 为成功，100xx 为特定业务错误
  "msg": "success",
  "data": { ... }       // 具体业务数据
}
```

### 4.2 场景一：异步轮询拉取 (推荐)
最简单且稳定的对接方式。上游（如 Java 服务）发起任务后，定期查询结果。

**步骤 1：创建任务**
```bash
curl -X POST "http://localhost:8000/api/v1/tasks" \
  -H "Content-Type: application/json" \
  -d '{
    "task_type": "note_url",
    "target": "https://www.xiaohongshu.com/explore/xxxx",
    "engine": "auto"
  }'
```
> 返回值中的 `data.task.id` 即为 `task_id`。

**步骤 2：轮询获取结果**
```bash
curl "http://localhost:8000/api/v1/tasks/<task_id>/result"
```
> **注意**：
> - 如果任务还在执行中，会返回 HTTP `409` (result not ready)，上游应捕获 409 并等待 1~2 秒后重试。
> - 任务结束后返回 200，其中 `data.normalized` 为标准化后的数据字段，`data.meta` 包含采集消耗的引擎与溯源信息。

### 4.3 场景二：Webhook 回调推送
如果上游不希望轮询，可以在环境变量中配置 `CALLBACK_URL`。

服务在任务完成后（无论成功或失败），会自动向该地址发起 POST 请求：
- **Header**: 包含 `Idempotency-Key` (基于 task_id 和内容生成的哈希)，上游应据此做**幂等去重**。
- **Body**: 
```json
{
  "task_id": "...",
  "result": {
    "raw": {...},
    "normalized": {...},
    "meta": {"ok": true, ...}
  }
}
```
> 如果回调失败（网络抖动或上游返回 5xx），服务会自动使用指数退避算法重试最多 5 次。

### 4.4 场景三：离线数据兜底导入
当线上风控极其严格，导致 API 和浏览器双双失效时，业务方可通过“小红书数据助手”导出 Excel，并由上游系统或运营人员调用导入接口，将离线数据平滑注入现有业务流。

```bash
curl -X POST "http://localhost:8000/api/v1/import/excel" \
  -F "file=@/path/to/data_assistant.xlsx" \
  -F "operator=运营人员张三"
```
> 服务会自动识别 Excel 表头（如曝光、阅读、互动等），并返回标准化的 `normalized` 数据数组。

### 4.5 浏览器插件 RPA 回传：POST /api/v1/import/extension
用途：该链路属于**人工兜底通道**（不在服务端自动执行引擎内）。通常用于处于 `waiting_rpa` 的任务：运营人员在真实浏览器环境中完成登录/验证码后，通过 Chrome 插件采集页面并回传；服务端目前只校验 `task_id` 存在性，然后写入结果并将任务更新为 `rpa_imported`。

```bash
curl -X POST "http://localhost:8000/api/v1/import/extension" \
  -H "Content-Type: application/json" \
  -d '{
    "task_id": "...",
    "raw": {...},
    "normalized": {...}
  }'
```

### 4.6 运营控制台只读接口
资源池中心（只读）：
- `GET /api/v1/resources/accounts`
- `GET /api/v1/resources/sessions`
- `GET /api/v1/resources/proxies`

错误中心（聚合统计）：
- `GET /api/v1/errors/summary`
  - `scan_limit`：扫描最近任务数量（默认取 `ERROR_SUMMARY_SCAN_LIMIT`，未配置则 1000）
  - `status` / `error_kind`：逗号分隔过滤

内容库（Orchestrator SQLite，只读）：
- `GET /api/v1/content/raw-notes`（`query` 模糊匹配 author/url/content）
- `GET /api/v1/content/cleaned-notes`（`query` 模糊匹配 cleaned_content/raw_note 字段）

---

## 5. 支持的任务类型 (task_type)

在调用 `POST /api/v1/tasks` 时，支持以下三种主要采集任务：

| task_type | target 含义 | 示例 | 产出数据 (`normalized` 核心字段) |
|---|---|---|---|
| `note_url` | 笔记链接 | `https://www.xiaohongshu.com/explore/xxx` | `note_id`, `title`, `author`, `publish_time` |
| `user_profile` | 用户主页链接或 ID | `https://www.xiaohongshu.com/user/profile/xxx` | `user_id`, `nickname`, `title` (个性签名) |
| `search` | 搜索关键词 | `AI Agent` | 匹配该关键词下的多条笔记基础信息列表 |

---

## 6. 运维与监控

### 6.1 IP 限流防雪崩
服务内置了防雪崩限流机制（默认每个 IP `100次 / 60秒`）。超出阈值的请求会立即被拒绝，并返回 HTTP `429 Too Many Requests` 以及 `Retry-After` Header。
> **建议**：上游业务在收到 429 时，应遵守 `Retry-After` 指定的秒数进行休眠，避免持续轰炸。

### 6.2 Prometheus 指标监控
服务直接暴露标准的 Prometheus Metrics 接口：
```bash
curl http://localhost:8000/api/v1/metrics
```
**核心监控指标**：
- `spider_xhs_tasks_total{engine="api", status="succeeded"}`：按引擎和状态统计的任务总数。
- `spider_xhs_queue_length`：当前正在排队中的积压任务数。
- `spider_xhs_recent_failure_rate`：近 5 分钟内的实时失败率（可用于配置 Grafana 报警：如 > 20% 时触发风控预警）。
- 代理池指标（若启用 Proxy Pool）：`spider_xhs_proxy_pool_size`、`spider_xhs_proxy_pool_avg_score`、`spider_xhs_proxy_pool_ejected_total`、`spider_xhs_proxy_pool_failures_total{reason}`。

### 6.3 存储与数据清理
所有任务状态、采集结果、失败回调记录以及日志，均持久化存储在宿主机挂载的 `./storage` 目录下。
- **原子落盘 + 进程锁**：写入采用临时文件 + `os.replace` 原子替换；关键更新路径使用 `fcntl.flock` 做跨进程互斥，避免并发更新覆盖。
- **自动清理**：服务后台线程会每天定期扫描 `./storage/raw` 目录，自动清理超过 `RAW_DATA_RETENTION_DAYS`（默认 7 天）的 HTML 页面快照，防止磁盘爆满。

### 6.4 常见错误排查

如果在获取结果时发现 `data.meta.ok = false`，请查看 `data.meta.error_kind`：

- **`auth`**: 鉴权失败。可能是由于 Cookie 失效。**系统策略**：标记为失效并切换 Session Pool，若耗尽则报错。
- **`rate`**: 遭遇频控。**系统策略**：为当前账号设置冷却窗（例如 15 分钟），换号、降频并重试。
- **`risk` / `captcha`**: 触发滑动验证码。**系统策略**：主引擎报错，降级至浏览器引擎；若被验证码拦截，系统会唤醒 **Agentic Captcha Solver**（基于视觉大模型）自动拖动滑块/点选验证码；若 AI 依然失败，则置为 `waiting_rpa`，等待人工借助 Chrome 插件拉取。
- **`parse`**: 页面解析失败。通常发生在小红书前端 DOM 结构发生重大改版时。**系统策略**：自动降级唤醒 **Engine D (Agentic Crawler)**，利用大模型的视觉和推理能力自动寻找并提取页面数据，无视 DOM 结构变化。
- **`timeout` / `proxy_failed`**: 网络超时。**系统策略**：代理池立刻将此 IP 降分或剔除，换新代理并重新请求。

---

## 7. AI 自动化编排模块 (Orchestrator MVP)

本项目在底层采集服务之上，提供了一套基于 Python 脚本的轻量级业务编排样例（位于 `orchestrator/` 目录），演示了借助大模型和 Agentic 技术实现的**获客全链路自动化**。

### 7.1 初始化数据库与测试数据
编排模块依赖 SQLite (`orchestrator/data/mvp.db`) 作为主数据库，首次使用前需初始化：
```bash
# 生成 14 张核心业务表
python orchestrator/db_init.py

# 录入测试用的关键词与竞品账号
python orchestrator/seed_data.py
```

### 7.2 核心业务流转脚本
请确保后台 FastAPI 采集服务已启动，并且在环境变量中配置了 `AGENT_LLM_API_KEY`。可按顺序执行以下脚本体验闭环：

1. **采集同步**：读取关键词并请求爬虫微服务，将 JSON 数据落库。
   ```bash
   python orchestrator/crawl_sync.py
   ```
2. **数据清洗**：从原始快照中清洗提取标题、互动量等结构化字段。
   ```bash
   python orchestrator/note_cleaner.py
   ```
3. **AI 图文生成**：利用大模型对爆款笔记进行分析、仿写与原创配图生成。
   ```bash
   python orchestrator/ai_generation.py
   ```
4. **AI 自动发布**：唤醒基于 `browser-use` 的 AI 浏览器代理，自动操控小红书创作者中心进行真实发帖。
   ```bash
   python orchestrator/publish_tracker.py
   ```
5. **AI 自动私信触达**：筛选出高意向互动用户，利用 AI Agent 自动打开私信窗口进行获客留资话术的回复。
   ```bash
   python orchestrator/lead_service.py
   ```
6. **飞书同步与告警（Mock）**：将获取的线索同步至上游 CRM（如飞书多维表格）。
   ```bash
   python orchestrator/feishu_sync.py
   ```