USAGE.md

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

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

---

1. 快速启动与部署

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

1.1 前置要求

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

1.2 启动步骤

在项目根目录执行以下命令，构建并以后台模式启动服务：

docker compose up -d --build

启动成功后，FastAPI 服务默认监听宿主机的 8000 端口。你可以通过访问 http://localhost:8000/docs 查看 Swagger UI 接口文档。

1.3 运营控制台前端（frontend/，可选）

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

在项目根目录执行：

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：

python -m uvicorn Spider_XHS.service.app:app --host 0.0.0.0 --port 8000 --reload

---

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

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

环境变量名	默认值	作用与说明
ENGINE_STRATEGY	auto	采集引擎调度策略（服务端自动执行的只有 A/B 两个引擎）。可选值： - auto: 优先使用 API 引擎，遇风控自动降级到浏览器引擎 - api: 仅使用极速协议级引擎 (Spider_XHS) - 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：

   python cli.py login pc-qrcode --save-cookies --write-env
   

   运行后会弹出真实的浏览器界面供你扫码登录，登录成功后会自动将完整的 Cookie 和浏览器状态（包含 storage_state.json）更新到 .env 文件中。这是解决 auth 风控拦截的最佳方案。

2. 执行抓取命令：

   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 格式：

{
  "code": 200,          // 200 为成功，100xx 为特定业务错误
  "msg": "success",
  "data": { ... }       // 具体业务数据
}

4.2 场景一：异步轮询拉取 (推荐)

最简单且稳定的对接方式。上游（如 Java 服务）发起任务后，定期查询结果。

步骤 1：创建任务

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：轮询获取结果

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:

{
  "task_id": "...",
  "result": {
    "raw": {...},
    "normalized": {...},
    "meta": {"ok": true, ...}
  }
}

如果回调失败（网络抖动或上游返回 5xx），服务会自动使用指数退避算法重试最多 5 次。

4.4 场景三：离线数据兜底导入

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

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。

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 接口：

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) 作为主数据库，首次使用前需初始化：

# 生成 14 张核心业务表
python orchestrator/db_init.py

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

7.2 核心业务流转脚本

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

1. 采集同步：读取关键词并请求爬虫微服务，将 JSON 数据落库。

   python orchestrator/crawl_sync.py
   

2. 数据清洗：从原始快照中清洗提取标题、互动量等结构化字段。

   python orchestrator/note_cleaner.py
   

3. AI 图文生成：利用大模型对爆款笔记进行分析、仿写与原创配图生成。

   python orchestrator/ai_generation.py
   

4. AI 自动发布：唤醒基于 browser-use 的 AI 浏览器代理，自动操控小红书创作者中心进行真实发帖。

   python orchestrator/publish_tracker.py
   

5. AI 自动私信触达：筛选出高意向互动用户，利用 AI Agent 自动打开私信窗口进行获客留资话术的回复。

   python orchestrator/lead_service.py
   

6. 飞书同步与告警（Mock）：将获取的线索同步至上游 CRM（如飞书多维表格）。

   python orchestrator/feishu_sync.py