Spaces:

luoleyuan
/

XHS

Sleeping

App Files Files Community

XHS / PRD.md

Trae Bot

Upload Spider_XHS project

c481f8a 30 days ago

preview code

raw

history blame contribute delete

14 kB

小红书稳定采集微服务 (Spider_XHS) - 产品需求文档 (PRD)

1. 产品概述

1.1 产品名称

小红书稳定采集微服务 (Spider_XHS Stability Data Service)

1.2 产品定位

一款面向企业级大模型（AI Agent）、数据分析、内容运营等上游业务，提供高可用、抗风控、全链路可溯源的小红书数据采集基础设施。本产品将底层的反爬对抗与数据清洗封装为标准 RESTful API，使得上游业务无需关注账号、风控及底层协议细节，即可稳定获取所需数据。

1.3 背景与痛点

风控严苛：小红书针对协议级 API 采集有着极强的反爬策略（封号、IP 限流、滑动验证码）。单一的协议破解（如逆向 x-s 签名）往往在遭遇强风控时全线崩溃。
效率与稳定性的博弈：传统的浏览器自动化方案（Playwright/Selenium）虽能较好地模拟真人绕过风控，但并发低、极其消耗 CPU/内存资源，无法满足大规模跑批需求。
业务不能断流：对于上游的内容生成和监控业务，数据的断流意味着业务停滞，必须拥有 100% 可用的兜底机制。

1.4 核心解决方案

“稳定性调度大脑 (Stability Controller) + 三引擎自动降级 + RPA 回传兜底 + AI Agent 自动化获客闭环”：

主链路（三引擎自动降级）：
- 引擎 A (Spider_XHS): 协议逆向极速采集（高并发、低成本）
- 引擎 B (MediaCrawler): Playwright Stealth 增强页面采集（含拟人化）
- 引擎 D (AgenticCrawler): 基于大模型视觉的智能自适应页面解析引擎（抗前端 DOM 改版）
统一调度与资源池：前置 Stability Controller 负责基于错误策略（auth/rate/risk/captcha/timeout 等）对 Account Pool（账号冷却池）、Session Pool（会话轮换）和 Proxy Pool（动态代理评分与剔除）进行资源分配、重试与引擎降级决策。在遇到复杂验证码时，主动唤醒 AI Agentic Captcha Solver 智能解除风控。
兜底链路（Chrome 插件 RPA 回传）：当所有自动引擎和 AI 解除验证码均失效，任务进入 WAITING_RPA 时，由人工在真实浏览器环境中通过插件采集并调用 POST /api/v1/import/extension 回传结果。
离线导入链路（人工离线导入）：支持运营人员导出的 Excel（小红书数据助手等）格式化导入。
AI 编排脚本（Orchestrator）：提供基于 SQLite 的业务编排闭环，包含数据清洗、AI 智能生成图文内容、基于 AI Agent（browser-use）的全自动真实发布与高意向线索自动私信触达。
**运营控制台 (Ops Console)**：提供基于 React + Ant Design 的前端看板，实现资源池（账号/会话/代理）监控、错误分析聚合与内容库的只读可视化。

2. 核心架构设计

2.1 系统架构图概览

上游业务 (Java/Agent) ──► [ OpenAPI / Webhook ] ──► (Spider_XHS FastAPI 微服务)
                                                          │
   ┌──────────────────────────────────────────────────────┤
   ▼                                                      ▼
[ 稳定性大脑: Stability Controller ]                 [ 兜底链路：数据导入 (Importer) ]
   ├─► 资源分配：Account Pool + Session Pool + Proxy Pool    ├─► 解析器: xhs_data_assistant
   ├─► AI Agent 风控解除 (Captcha Solver)                    ├─► 解析器: fixed_template
   ▼                                                      │
[ 多引擎执行链路 (Runner) ]                                  └─► 字段标准化、元数据注入
   ├─► 引擎 A (Spider_XHS): 协议逆向、极速并发                │
   │   └─ 遇 timeout/rate/auth/risk/captcha ─重试/降级─┐     │
   │                                                    ▼    │
   ├─► 引擎 B (MediaCrawler): Stealth 防抖模拟人行为          │
   │   └─ DOM 解析失效/改版 ─降级─┐                          │
   │                             ▼                           │
   └─► 引擎 D (Agentic Crawler): AI 视觉自动解析 ───────────┤
       └─ 若仍被验证码拦截 → 状态 WAITING_RPA（等待人工回传） │
   ┌──────────────────────┴───────────────────────────────┘
   ▼
[ 持久化与监控 ]
   ├─► 文件存储 (JSON + HTML快照) 带有 fcntl 进程锁
   ├─► 限流拦截 (IP 滑动窗口 RateLimit)
   └─► Prometheus 指标监控 (/metrics)
   │
   ▼
[ AI 自动化业务编排 (Orchestrator) ]
   ├─► 核心数据库: SQLite (14张业务表: 关键词、生成草稿、线索等)
   ├─► AI Agent 自动操作: 发布图文 (publish_tracker.py)
   ├─► AI Agent 自动操作: 线索私信触达 (lead_service.py)
   └─► 生态协同: 数据清洗、AI 图文生成、飞书同步

[ 运营控制台 (Ops Console) ]
   ├─► 资源池中心 (账号/会话/代理健康快照)
   ├─► 错误中心 (任务失败聚合与异常扫描)
   └─► 内容库看板 (基于 SQLite 数据的全量只读展示)

  (第三兜底链路：Chrome 插件 RPA 回传)
    浏览器插件 ──► POST /api/v1/import/extension ──► 写入任务结果

3. 功能需求说明

3.1 核心采集业务 (Data Scraping)

**笔记详情采集 (note_url)**：输入笔记链接，获取无水印图文、视频信息、正文、点赞/收藏/评论等互动数据。
**用户主页采集 (user_profile)**：输入用户 ID 或主页链接，获取博主基本信息、粉丝数、关注数、获赞与收藏总数。
**关键词搜索采集 (search)**：输入关键词，获取相关笔记列表，支持按综合/最新/热门排序。

3.2 智能引擎调度与稳定性控制 (Stability Controller)

资源池化管理：系统内置账号池 (Account Pool)、会话池 (Session Pool) 和代理池 (Proxy Pool)，所有采集任务通过 Stability Controller 动态获取最佳健康资源。
- 代理打分与剔除：代理池支持多 provider 聚合，根据任务执行结果实时回写分数，自动降权并剔除高失败率代理。
- 账号防封冷却：连续遭遇 rate 或 risk 错误的账号将进入冷却窗口，避免被平台拉黑。
三引擎容灾与降级（服务端自动执行）：
- 任务默认以 auto 策略下发，优先分配给 Spider_XHS 引擎 (Engine A) 以最高效率执行。
- 监听执行异常并按策略表处置：timeout 换代理重试；rate 账号冷却+换账号降频；auth 标记会话失效+换 Session。
- 遇到强风控 (risk/captcha) 时，降级至 **MediaCrawler 引擎 (Engine B)**。
- Engine B 内置 Stealth 脚本与随机拟人化行为。若 Engine B 报 parse 错误（说明 DOM 结构发生变化），任务自动流转至 **Agentic Crawler (Engine D)**，由大模型视觉接管。
- **智能验证码解除 (Captcha Solver)**：遇到复杂滑块或点选验证码时，系统主动实例化基于大模型的 AgenticCaptchaSolver，尝试自动操控浏览器完成过验。若 Agent 仍失败，任务进入 WAITING_RPA 状态。
终极免疫链路（人工 RPA 回传）：处于 WAITING_RPA 的任务可由人工通过 Chrome 浏览器插件拦截并回传数据，完成闭环；该链路属于人工兜底通道，而非服务端自动执行的引擎线程。

3.3 异步任务与状态流转 (Task Lifecycle)

扩展任务状态机：支持 queued -> running -> retrying -> fallback_running -> succeeded / failed / waiting_rpa / rpa_imported / risk_paused 等细粒度状态。
异步拉取：上游业务通过创建任务获取 task_id，并可通过长轮询获取执行结果。
Webhook 回调：支持配置全局 CALLBACK_URL。任务到达终态后自动触发回调推送。
- 回调重试：如遇上游网络抖动，系统自动采用指数退避算法最多重试 5 次，并在头部携带 Idempotency-Key 确保上游幂等消费。

3.4 离线数据人工兜底 (Offline Import)

Excel 文件解析：提供 /api/v1/import/excel 接口，支持上传 Excel 文件。
模板智能识别：自动识别“小红书数据助手”等特定报表格式。
数据标准化：提取“曝光、阅读、互动、转粉”等高阶流量指标，将其与自动化采集的数据结构对齐 (normalized 数据契约)。
全链路溯源：保留 operator (操作人)、source_name (来源)、行号及表名等元数据，便于数据审计。

3.5 运营控制台与可视化 (Ops Console)

资源池中心：直接复用内存池（Account/Session/Proxy Pool）状态快照，提供只读的可视化列表，方便运维人员实时监控风控与资源健康度。
错误聚合分析：基于本地任务文件系统，扫描近期（如近 1000 条）采集任务，并根据错误类别（auth/rate/risk/captcha 等）进行高阶聚合分析，提供失败列表过滤能力。
内容库基础页：对接 Orchestrator 的 SQLite 底座，为业务人员提供原始笔记和标准化笔记的分页查询与模糊检索视图。

4. 非功能需求

4.1 并发与数据一致性

无状态服务设计：服务进程应尽量无状态化，数据落盘依赖本地文件系统（./storage）。
并发控制锁：针对单机多进程/多线程场景，写入任务状态时必须使用 fcntl.flock 实现进程间排他锁，配合 .tmp 文件原子替换 (os.replace)，杜绝高并发下的文件写坏或数据覆盖问题。

4.2 限流与防雪崩

IP 级滑动窗口限流：内置轻量级基于内存的 API 限流（如 100 次 / 60 秒），超出阈值立即返回 HTTP 429 状态码与 Retry-After 头，防止恶意或异常流量打垮服务。

4.3 监控与可观测性

Prometheus 集成：暴露标准 /api/v1/metrics 接口，输出以下核心指标：
- spider_xhs_tasks_total{engine, status}：各引擎任务执行计数。
- spider_xhs_queue_length 与 spider_xhs_tasks_inflight：当前排队及在途队列长度。
- spider_xhs_recent_failure_rate：滑动窗口内的实时失败率报警指标。
- 代理池指标：spider_xhs_proxy_pool_size、spider_xhs_proxy_pool_avg_score 及失败原因分布统计。
结构化日志：使用 loguru 输出结构化日志并按天切割；对部分错误日志做基础脱敏处理，但不保证对所有自定义日志字段自动脱敏，敏感凭证应只通过环境变量注入且避免打印。

4.4 部署与兼容性

容器化支持：提供 Dockerfile 与 Docker Compose 编排，支持一键部署。存储目录独立挂载，保障数据持久化。
向后兼容：针对历史未带版本号的旧 API，可通过配置 ENABLE_LEGACY_ROUTES=1 提供兼容层平滑过渡。

5. API 接口契约说明

5.1 全局契约

所有 RESTful API 的响应体均采用标准三段式包装：

{
  "code": 200,          // 业务状态码，200 为成功，100xx 为特定业务错误
  "msg": "success",     // 提示信息
  "data": { ... }       // 载荷数据
}

5.2 核心端点规划

端点路径	Method	用途	核心参数/说明
`/api/v1/tasks`	POST	创建采集任务	必传: `task_type`, `target`; 可选: `engine`, `payload`
`/api/v1/tasks/{id}`	GET	查询任务状态	返回当前状态 (`queued`, `running` 等)
`/api/v1/tasks/{id}/result`	GET	获取任务结果	若未完成返回 409；完成后返回 `raw`, `normalized`, `meta`
`/api/v1/tasks/{id}/callback/retry`	POST	手动重试回调	用于 Webhook 推送彻底失败后的人工介入
`/api/v1/import/excel`	POST	上传并解析 Excel	必传: `file`, `operator`; 输出标准化清洗结果
`/api/v1/import/extension`	POST	插件 RPA 结果回传	必传: `task_id`, `raw`, `normalized`; 更新任务为 `RPA_IMPORTED`
`/api/v1/metrics`	GET	Prometheus 指标	面向监控采集系统 (如 Grafana)，含任务、队列、代理池状态
`/api/v1/health`	GET	健康检查与看板	包含队列长度、在途数、各引擎执行统计及实时失败率

6. 演进规划 (Roadmap)

Phase 1 (V1.0) - 历史版本：完成双引擎双链路架构重构，实现核心采集、容灾降级、IP限流、并发控制与容器化监控交付。
Phase 2 (MVP) - 当前版本：新增轻量级 Orchestrator 编排脚本与 SQLite 核心业务数据库，提供“采集同步→内容清洗→Mock 飞书同步/告警”的最小闭环样例。
Phase 3 (Stability) - 当前版本：完成 Stability Controller (稳定性大脑) 重构，补齐 Account Pool、Session Pool 与 Proxy Pool 的全链路生命周期管理。完成 Chrome 插件回传通道（/api/v1/import/extension + WAITING_RPA 状态机），形成“双引擎自动采集 + 人工 RPA 回传兜底”的可控闭环。新增基于 React 的运营控制台，落地资源池中心、错误中心与内容库基础页的只读可视化。
**Phase 4 (V1.1)**：增加任务优先级队列 (Priority Queue)，支持高优紧急任务插队；集成 Redis 作为分布式存储与分布式锁的选项，支持多节点横向扩容部署。
**Phase 5 (V2.0)**：接入大模型智能提取链路（针对未知格式或乱码的 Excel，通过 LLM 自动提取结构化内容）；提供可视化热更新管理后台（用于账号池、代理池调优）。