--- title: XHS emoji: 🦀 colorFrom: blue colorTo: purple sdk: docker pinned: false --- Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
# Spider_XHS **专业的小红书数据采集 & 全域运营解决方案 & Agent Skills** [![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/) [![Node.js](https://img.shields.io/badge/nodejs-20%2B-green)](https://nodejs.org/) [![License](https://img.shields.io/badge/license-MIT-orange)](LICENSE)
> **在 AI 大模型爆发的时代，内容运营的竞争本质是效率竞争。** > 本项目封装了小红书平台完整的数据采集与内容发布能力，为开发者构建 AI 运营智能体提供可靠、稳定的底层 API 支撑。 > **本项目已升级为「稳定性大脑 + 三引擎自动降级 + AI Agent 全链路闭环」架构：服务端自动执行 API 协议采集 + Playwright Stealth + 基于大模型视觉的 Agentic Crawler，并支持 AI Agent 全自动发布笔记与自动触达私信线索。** **⚠️ 本项目仅供学习交流使用，禁止任何商业化行为，如有违反，后果自负** --- ## 为什么需要这个项目？ ``` 采集竞品笔记 ──► [Spider_XHS] ──► 你的 AI Agent（改写 / 生成 / 分析）──► 自动上传发布 ▲ │ └──────────── 获取数据 / 管理账号 ◄──────────────────────┘ ``` 小红书没有开放完整的内容运营接口。想要接入 AI 大模型实现内容批量采集、智能改写、一键发布，首先需要能**稳定读写平台数据**。Spider_XHS 解决的正是这个前置问题： - 逆向还原了小红书 PC 端与创作者平台的签名算法（x-s / x-t / x-s-common / x_b3_traceid / sign / q-signature参数） - 封装全部核心 HTTP 接口，签名参数已透明处理 - 同时覆盖 **数据采集**（PC端）、**内容发布**（创作者平台）、**KOL数据**（蒲公英）三大场景 **你负责接 AI 大脑，我们负责打通小红书的神经。** --- ## ⭐ 已实现功能 | 模块 | 功能 | 状态 | |------|------|------| | **小红书 PC 端** | 二维码登录 / 手机验证码登录 | ✅ | | | 获取主页所有频道 & 推荐笔记 | ✅ | | | 获取用户主页信息 / 自己的账号信息 | ✅ | | | 获取用户发布 / 喜欢 / 收藏的所有笔记 | ✅ | | | 获取笔记详细内容（无水印图片 & 视频） | ✅ | | | 搜索笔记 & 搜索用户 | ✅ | | | 获取笔记评论 | ✅ | | | 获取未读消息 / 评论@提醒 / 点赞收藏 / 新增关注 | ✅ | | **创作者平台** | 二维码登录 / 手机验证码登录 | ✅ | | | 上传图集作品 | ✅ | | | 上传视频作品 | ✅ | | | 查看已发布作品列表 | ✅ | | **蒲公英平台** | 获取 KOL 博主列表 & 详细数据 | ✅ | | | 获取博主粉丝画像 & 历史趋势 | ✅ | | | 发起合作邀请 | ✅ | | **千帆平台** | 获取分销商列表 & 详细数据 | ✅ | | | 获取分销商合作品类 / 店铺 / 商品信息 | ✅ | --- ## 🌟 核心特性：稳定性大脑与 AI Agent 多链路容灾 为了解决小红书日益严格的风控（封号、验证码、前端频繁改版）问题，本项目重构了底层的采集架构，全面升级为**三自动引擎 + RPA 回传兜底 + 稳定性大脑 (Stability Controller)** 模式，完美适配生产级高可用业务需求。 ### 1. 稳定性大脑与资源池化 不再将异常写死在爬虫逻辑中，而是引入统一的 `Stability Controller`，并辅以三大资源池，实现防封禁的生命周期管理： - **Account Pool（账号池）**：自动管理多账号风险分，遭遇高频风控时触发防封冷却窗。 - **Session Pool（会话池）**：兼容 API 登录态与浏览器 Storage State，支持失效检测与自动轮换。 - **Proxy Pool（代理池）**：支持多数据源动态拉取 IP，根据网络响应执行同步打分，自动剔除高失败率代理。 - **Agentic Captcha Solver**：智能风控解除。系统在遇到复杂验证码时，会自动唤醒基于 `browser-use` 和视觉大模型的 Agent，自动完成滑块拖动和文字点选。 ### 2. 自动化主采集链路（三引擎容灾） 提供标准的 FastAPI 轻量服务，服务端自动执行三大引擎： - **Engine A (API 协议引擎)**：通过逆向签名算法直接请求接口。极速、并发高、资源占用极小，作为绝对主力。 - **Engine B (Browser 浏览器引擎)**：引入 Playwright 自动化框架，并提供 Stealth 脚本注入与随机拟人化动作（鼠标轨迹、滚动，支持开关）以降低自动化特征。 - **Engine D (Agentic Crawler)**：引入了**基于视觉大模型的自适应页面提取引擎**。当小红书前端 DOM 结构发生变化导致 Engine B 的固定解析规则失效时，系统自动降级唤醒 Engine D，大模型会自己“看”懂页面并提取标题、作者、正文等结构化数据，无视任何前端改版。 ### 3. 人工兜底链路（Chrome 插件 RPA 回传） Chrome 插件并不是服务端“自动执行的第三引擎线程”，而是一个**最后的人工兜底通道**：当所有自动引擎和 AI Agent 都无法突破风控，任务自动进入 `WAITING_RPA` 时，运营人员在真实浏览器环境下采集页面内容/数据后，通过插件调用服务端回传接口完成闭环。 ### 4. 人工兜底采集链路（Excel 导入解析） 在极端情况下（如全网 IP 被封或大面积升级），支持通过**小红书数据助手**或第三方平台导出的 Excel 进行全量解析： - 提供 `/api/v1/import/excel` 接口，自动识别各种变体表头（曝光、阅读、互动、转粉等）。 - 自动完成字段映射、标准化清洗，将离线人工数据无缝对接到自动化流中，确保业务“不断流”。 ### 5. 企业级运维保障 - **防雪崩限流**：内置基于 IP 的滑动窗口限流（Rate Limit），超过阈值返回 `429 Retry-After`。 - **普罗米修斯监控**：暴露 `/api/v1/metrics` 接口，直出 `spider_xhs_tasks_total`、`spider_xhs_recent_failure_rate` 等核心指标。 - **并发与持久化**：采用基于 `fcntl.flock` 的文件锁分片存储，保证跨进程写文件的绝对原子性。 - **回调重试机制**：支持结果 Webhook 推送，内置 `Idempotency-Key` 幂等控制与指数退避重试。 ### 6. AI 自动化获客编排 (Orchestrator MVP) 基于采集服务之上，新增轻量级 Python 编排脚本与 SQLite 本地数据库，提供完整的获客流转： - **采集同步与清洗**：`crawl_sync.py` & `note_cleaner.py` - **AI 批量生成图文**：`ai_generation.py` - **AI 全自动发布笔记**：`publish_tracker.py`（接入 `browser-use`，大模型直接操控创作者中心） - **AI 全自动触达线索**：`lead_service.py`（AI 自动打开小红书网页版私信，向高意向用户发送留资话术） - **飞书同步与告警**：`feishu_sync.py` & `alert.py` (Mock 流转) ### 7. 运营控制台可视化 提供基于 React + Vite 的前端可视化看板（`frontend/`），支持资源池（账号/会话/代理）健康度监控、任务错误聚合扫描以及底层 SQLite 内容库的只读分页检索，实现了前后端数据链路的直观打通。 --- ## 🤖 接入 AI 智能体 Spider_XHS 天然适合作为 AI 运营 Agent 的数据底座，以下是几种典型用法： ### 场景一：竞品笔记采集 + AI 改写 + 自动发布 ```python from apis.xhs_pc_apis import XHS_Apis from apis.xhs_creator_apis import XHS_Creator_Apis pc_api = XHS_Apis() creator_api = XHS_Creator_Apis() # 1. 采集竞品笔记 success, msg, note = pc_api.get_note_info(note_url, cookies_str) # 2. 交给 AI 改写（接入任意大模型） rewritten = your_ai_agent(note['content']) # GPT / Claude / Qwen / 本地模型 # 3. 自动上传到创作者平台 creator_api.post_note({ "title": rewritten['title'], "desc": rewritten['desc'], "media_type": "image", "images": [...], ... }, creator_cookies_str) ``` ### 场景二：关键词监控 + AI 情报分析 ```python # 搜索指定关键词的最新笔记，交给 AI 分析趋势 success, msg, notes = pc_api.search_some_note(query, require_num, cookies_str, ...) analysis = your_ai_agent(notes) ``` ### 场景三：KOL 筛选 + 智能匹配 ```python from apis.xhs_pugongying_apis import PuGongYingAPI pgy = PuGongYingAPI() # 获取目标类目的 KOL 数据，交给 AI 评估匹配度 kol_list = pgy.get_some_user(num=50, cookies=cookies) best_kols = your_ai_agent(kol_list, brand_profile) ``` --- ## 🧩 Skills 支持 当前项目已经支持基于 skills 的能力接入，既可以直接作为 `Spider_XHS` 的底层能力仓库使用，也可以通过标准化 skills 方式被上层 Agent 工具链引入。 如果你希望直接复用已经封装好的 skills，可以直接使用本项目内置的 Agent Skills。该模块目前可被 `Clawbot`、`Claude Code`、`Codex` 等支持 skills 的工具直接引入与集成。 --- ## 🎨 爬虫效果图 ### 处理后的所有用户 ![image](https://github.com/cv-cat/Spider_XHS/assets/94289429/00902dbd-4da1-45bc-90bb-19f5856a04ad) ### 某个用户所有的笔记 ![image](https://github.com/cv-cat/Spider_XHS/assets/94289429/880884e8-4a1d-4dc1-a4dc-e168dd0e9896) ### 某个笔记具体的内容 ![image](https://github.com/cv-cat/Spider_XHS/assets/94289429/d17f3f4e-cd44-4d3a-b9f6-d880da626cc8) ### 保存的 Excel ![image](https://github.com/user-attachments/assets/707f20ed-be27-4482-89b3-a5863bc360e7) --- ## 🛠️ 快速开始 ### ⛳ 环境要求 - Python 3.10+ - Node.js 20+ ### 🎯 安装依赖 ```bash pip install -r requirements.txt npm install ``` ### 🧩 Playwright（必选：用于 Browser 引擎兜底与扫码登录） 如果你希望使用**浏览器引擎 (MediaCrawler) 作为兜底策略**，或使用“内置浏览器扫码登录后自动获取 Cookie 并写回 `.env`”功能，必须安装 Playwright 浏览器内核： ```bash playwright install chromium ``` ### 🎨 配置 Cookie 在项目根目录的 `.env` 文件中填入你的登录 Cookie： ``` COOKIES='' ``` Cookie 获取方式：浏览器登录小红书后，按 `F12` 打开开发者工具 → 网络 → Fetch/XHR → 找任意一个请求 → 复制请求头中的 `cookie` 字段。 ![image](https://github.com/user-attachments/assets/6a7e4ecb-0432-4581-890a-577e0eae463d) ![image](https://github.com/user-attachments/assets/5e62bc35-d758-463e-817c-7dcaacbee13c) > **注意：必须是登录后的 Cookie，未登录状态无效。** ### 🚀 运行项目 ```bash python main.py ``` ### 🧰 CLI（推荐） 项目提供 CLI 方便团队跑批与断点续跑（默认状态文件 `datas/state.json`）： ```bash python cli.py --help ``` #### 扫码登录并自动写回 Cookie（推荐） ```bash python cli.py login pc-qrcode --save-cookies --write-env ``` 成功后会同时写入： - `datas/cookies.json` - `.env` 中的 `COOKIES="..."` #### 抓取示例 ```bash python cli.py note --url 'https://www.xiaohongshu.com/explore/xxxx?...' --save-choice excel --excel-name demo --resume python cli.py user --url 'https://www.xiaohongshu.com/user/profile/xxxx?...' --resume python cli.py search --query 榴莲 --num 50 --resume ``` 如需代理： ```bash python cli.py search --query 榴莲 --num 50 --proxy http://127.0.0.1:7890 ``` --- ## 🧪 FastAPI 服务（对接 Java/任务系统） - 适合场景：把 Spider_XHS 作为“采集/解析微服务”，由上游（Java/Agent/工作流引擎）提交任务并拉取结果；也可配置回调推送。 - 提示：服务端不会要求你把 Cookie 写进代码；推荐通过环境变量或任务 payload 注入，且不要在日志中打印 Cookie。 ### 🚀 启动服务（uvicorn） 在项目根目录执行： ```bash python -m uvicorn Spider_XHS.service.app:app --host 0.0.0.0 --port 8000 ``` 开发调试（热加载）： ```bash python -m uvicorn Spider_XHS.service.app:app --host 0.0.0.0 --port 8000 --reload ``` 启动后： - OpenAPI JSON：`http://localhost:8000/openapi.json` - Swagger UI：`http://localhost:8000/docs` ### 🖥️ 运营控制台前端（frontend/） `frontend/` 提供基于 Vite + React + TypeScript 的运营控制台，用于查看健康状态、任务中心、RPA 回传、错误中心、资源池中心、内容库与监控指标等能力。 页面路由： - `/dashboard`：服务健康概览 - `/tasks`、`/tasks/:id`：任务中心与任务详情 - `/rpa`：RPA 回传（Chrome 插件） - `/errors`：错误中心 - `/resources/accounts`、`/resources/sessions`、`/resources/proxies`：资源池中心（账号/会话/代理） - `/content/raw-notes`、`/content/cleaned-notes`：内容库（原始笔记/清洗笔记） - `/metrics`：监控指标 #### 1) 安装依赖 ```bash cd frontend npm install ``` #### 2) 配置后端地址（VITE_API_BASE_URL） 默认后端地址为 `http://localhost:8000/api/v1`。如需调整，可通过环境变量覆盖： - 推荐本地联调（走 Vite dev proxy，避免 CORS）： ```bash export VITE_API_BASE_URL=/api/v1 ``` - 或指定完整地址（跨域访问，需后端允许 CORS）： ```bash export VITE_API_BASE_URL=http://localhost:8000/api/v1 ``` #### 3) 启动前端（开发模式） ```bash npm run dev ``` 访问地址：`http://localhost:5173/` #### 4) 与 FastAPI 同时启动（本地联调） 终端 A（后端）： ```bash python -m uvicorn Spider_XHS.service.app:app --host 0.0.0.0 --port 8000 --reload ``` 终端 B（前端）： ```bash cd frontend export VITE_API_BASE_URL=/api/v1 npm run dev ``` ### 🧩 API 概览（/api/v1） 服务默认只开放带版本前缀的接口（推荐）： - Base URL：`http://:8000/api/v1` - 统一响应包装：`{ "code": 200, "msg": "success", "data": ... }` - 兼容旧路由（不带 `/api/v1`）可通过 `ENABLE_LEGACY_ROUTES=1` 打开，默认关闭 #### 统一响应格式 所有接口（包括错误）均返回如下结构： ```json { "code": 200, "msg": "success", "data": {} } ``` 常用错误码（节选）： | 场景 | HTTP | code | 说明 | |------|------|------|------| | 鉴权/登录态失效 | 401 | 10001 | auth required | | 单 IP 限流 | 429 | 10002 | rate limited | | 风控/验证码 | 403 | 10003 | risk control | | 参数/路径无效 | 400/404 | 10007 | invalid target | | 任务不存在 | 404 | 10008 | task not found | | 结果未就绪 | 409 | 10009 | task not ready | #### 端点一览 | 方法 | 路径 | 说明 | |------|------|------| | GET | `/tasks` | 分页查询任务列表（过滤/排序） | | POST | `/tasks` | 创建任务 | | GET | `/tasks/{task_id}` | 查询任务状态 | | GET | `/tasks/{task_id}/result` | 获取任务结果 | | POST | `/tasks/{task_id}/callback/retry` | 手动重试回调 | | POST | `/import/excel` | Excel 导入 | | POST | `/import/extension` | Chrome 插件回填 | | GET | `/errors/summary` | 错误聚合统计与失败任务列表 | | GET | `/resources/accounts` | 账号池快照（只读） | | GET | `/resources/sessions` | 会话池轻量检查（只读） | | GET | `/resources/proxies` | 代理池快照（只读） | | GET | `/content/raw-notes` | 内容库 raw_note 列表（SQLite，只读） | | GET | `/content/cleaned-notes` | 内容库 cleaned_note 列表（SQLite，只读） | | GET | `/health` | 健康检查 | | GET | `/metrics` | Prometheus 指标 | #### 运维：GET /api/v1/health 返回字段（节选）： - `queue_length`：当前 `queued` 任务数量 - `engine_usage_counts`：各引擎累计处理任务数（内存计数器，随进程重启清零） - `success_count` / `fail_count`：累计成功/失败任务数（内存计数器，随进程重启清零） - `recent_failure_rate`：近期失败率（滑动窗口） - `recent_failure_window_seconds` / `recent_failure_total` / `recent_failure_failed`：失败率窗口与分子分母 #### 监控：GET /api/v1/metrics Prometheus 文本格式（`text/plain; version=0.0.4`），核心指标（节选）： - `spider_xhs_queue_length` - `spider_xhs_tasks_total{engine,status}` - `spider_xhs_tasks_succeeded_total` / `spider_xhs_tasks_failed_total` - `spider_xhs_recent_failure_rate` #### 错误中心：GET /api/v1/errors/summary 用途：聚合最近 N 条任务的 `error_kind` 分布，并返回失败任务列表（可分页/过滤）。 Query 参数（节选）： - `scan_limit`：扫描最近任务数量（默认取 `ERROR_SUMMARY_SCAN_LIMIT`，未配置则 1000） - `status`：逗号分隔过滤（例如 `failed,waiting_rpa`） - `error_kind`：逗号分隔过滤（例如 `auth,rate`） #### 资源池中心：GET /api/v1/resources/* - `/resources/accounts`：账号池快照（risk_score/cooldown 等） - `/resources/sessions`：会话池轻量检查结果（ok/reason） - `/resources/proxies`：代理池快照（规模/均分/失败原因分布等） #### 内容库：GET /api/v1/content/* 说明：内容库从编排层 SQLite 读取数据，数据库路径由 `ORCHESTRATOR_DB_PATH` 指定（默认 `orchestrator/data/mvp.db`）。 - `/content/raw-notes`：raw_note 列表（author/url/content 模糊搜索） - `/content/cleaned-notes`：cleaned_note 列表（cleaned_content + 关联 raw_note 信息） #### 日志字段（结构化） 服务日志会在 `extra` 中附带结构化字段（示例字段）： - `task_id` / `task_type` / `engine` / `status` 不要把 Cookie、回调签名、Authorization 等敏感信息写入日志；错误信息会对 URL token/cookies 等做脱敏。 #### 1) 创建任务：POST /api/v1/tasks 用途：提交一个采集/解析任务，立即返回 task_id，服务端后台执行。 请求体（JSON）： - `task_type`：`note_url` / `search` / `user_profile` - `target`：采集目标（URL/关键词/用户ID），推荐使用；会自动写入 payload（向后兼容） - `payload`：任务参数（见下方示例） - `engine`：可选，`auto` / `api` / `browser`（不传则使用环境变量 `ENGINE_STRATEGY`） 示例（抓取笔记详情）： ```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?xsec_token=yyyy", "engine": "auto", "payload": { "operator": "demo" } }' ``` 说明： - API 引擎（Spider_XHS）Cookie 来源优先级：`payload.cookies`/`payload.cookie`/`payload.cookies_str` > 环境变量 `COOKIES`/`XHS_COOKIES` - 代理来源优先级：`payload.proxies`（对象）> `payload.proxy`/`payload.proxies`（字符串）> 环境变量 `SERVICE_PROXY`；浏览器引擎可额外配置 `SERVICE_PROXY_POOL` 做简单轮换 不同 task_type 的 payload 约定： - `note_url` - `note_url`：笔记链接（必填） - `cookies`：可选（推荐从环境变量注入，避免透传到上游日志） - `search` - `query` 或 `keyword`：关键词（必填） - `require_num` 或 `limit`：期望条数（默认 20） - `sort_type_choice` / `note_type` / `note_time` / `note_range` / `pos_distance` / `geo`：可选（与 CLI/现有 API 对齐） - `user_profile` - `user_id` 或 `uid`：用户 id（必填其一） - 或 `user_url`/`url`：用户主页链接（可由 URL 自动解析 user_id） #### 2) 查询任务状态：GET /api/v1/tasks/{task_id} ```bash curl "http://localhost:8000/api/v1/tasks/" ``` 返回字段（节选）： - `task.status`：`queued` / `running` / `succeeded` / `failed` - `task.engine`：实际执行引擎（例如 `spider_xhs` / `mediacrawler`） - `task.callback`：回调状态（配置了回调才会出现） #### 3) 获取任务结果：GET /api/v1/tasks/{task_id}/result - 若任务仍在 `queued/running`，会返回 `409`（result not ready）。 - 任务结束后返回： - `raw`：引擎原始返回（结构可能随上游接口变化） - `normalized`：标准化后的关键字段（便于入库/检索） - `meta`：任务元信息与错误分类 ```bash curl "http://localhost:8000/api/v1/tasks//result" ``` `meta` 常用字段： - `ok`：是否成功 - `error_kind`：失败类型（如 `auth` / `rate` / `risk` / `parse` / `timeout` / `missing_dependency`） - `primary_engine` / `final_engine`：自动策略下的主引擎与最终引擎 - `fallback_reason`：触发兜底的原因（如阈值触发、鉴权/风控失败等） #### 4) 回调失败手动重试：POST /api/v1/tasks/{task_id}/callback/retry 仅当配置了回调地址且结果已生成时可用。服务端会： - 使用 `Idempotency-Key` 请求头进行幂等控制 - 最多尝试 5 次（指数退避 + 抖动） - 若仍失败，会把失败请求落盘，供后续重试 ```bash curl -X POST "http://localhost:8000/api/v1/tasks//callback/retry" ``` #### 5) Excel 导入（人工兜底）：POST /api/v1/import/excel 用途：当线上采集受风控/验证码影响，可用人工导出的 Excel 进行导入与标准化。 请求（multipart/form-data）： - `file`：Excel 文件 - `operator`：操作者/来源标识（必填） - `source_name`：可选，来源名称（如“运营同学A导出”） ```bash curl -X POST "http://localhost:8000/api/v1/import/excel" \ -F "file=@/path/to/demo.xlsx" \ -F "operator=ops" \ -F "source_name=manual_export" ``` 模板识别（自动）： - `xhs_data_assistant`：命中“曝光/阅读/浏览/互动/转粉”等数据助手指标列，并同时包含“笔记标题/笔记链接/作者昵称”等识别列 - `fixed_template`：兜底模板（任意表头），会尝试从行内提取 URL/关键词等信息 `xhs_data_assistant` 支持的常见列（中英文均可，大小写/空格不敏感）： - 识别列：`笔记链接`/`笔记url`/`作品链接` → `note_url`，`笔记标题` → `title`，`作者昵称` → `author` - 时间列：`发布时间`/`上传时间` → `publish_time` - 互动指标：`点赞` → `like`，`评论` → `comment`，`收藏` → `collect`，`分享`/`转发` → `share` - 流量指标：`曝光` → `exposure`，`阅读` → `read`，`浏览` → `view`，`互动` → `interact`，`转粉` → `follow` - 内容类型：`内容类型`/`笔记类型` → `content_type` 标准化输出（`records[].normalized`）： - 基础：`kind`（note/user/search/url）、`note_url`/`note_id`/`user_url`/`user_id`/`query` - 补充：`title`、`author`/`nickname`、`publish_time`、`like_count`、`comment_count`、`collect_count`、`share_count`、`exposure`、`read`、`view`、`interact`、`follow`、`content_type` 溯源信息（`records[].meta`）： - `import_id`、`operator`、`source_name`、`row_number`、`dedup_key`、`parser`、`filename`、`sheet` ### ⚙️ 环境变量配置（建议仅在部署环境注入，不要写入代码/仓库） > 下表仅展示变量名与用途；不要在日志/报错里输出真实 Cookie、回调签名、账号信息等敏感数据。 | 变量 | 默认值 | 说明 | |------|--------|------| | `ENABLE_LEGACY_ROUTES` | `0` | 是否兼容旧接口（不带 `/api/v1` 前缀）；建议生产关闭 | | `STORAGE_ROOT` / `SERVICE_STORAGE_ROOT` / `SERVICE_STORAGE_DIR` | `./storage` | 服务落盘根目录（任务/结果/回调失败/原始快照/日志） | | `SERVICE_CONCURRENCY` | `4` | 任务执行并发度（建议和上游并发一起收敛） | | `SERVICE_PROXY` | 空 | 代理（同时影响 API 引擎与浏览器引擎） | | `SERVICE_PROXY_POOL` | 空 | 代理池（逗号分隔多个代理，浏览器引擎按重试次数轮换；会与 `SERVICE_PROXY` 合并去重） | | `ENGINE_STRATEGY` | `auto` | `auto`/`api`/`browser` | | `ENGINE_FALLBACK_THRESHOLD` | `3` | `auto` 模式下切换浏览器引擎的失败阈值 | | `RAW_DATA_RETENTION_DAYS` | `7` | 原始 HTML 快照保留天数（启动时清理 + 定时清理） | | `ORCHESTRATOR_DB_PATH` | `orchestrator/data/mvp.db` | Orchestrator SQLite 路径（内容库接口 `/content/*` 读取，只读打开） | | `ERROR_SUMMARY_SCAN_LIMIT` | `1000` | 错误中心默认扫描最近任务数（用于 `/errors/summary` 的默认 `scan_limit`） | | `CALLBACK_URL` / `SERVICE_CALLBACK_URL` | 空 | 任务完成后回调推送地址（可选） | | `MEDIACRAWLER_STORAGE_STATE_PATHS` | 空 | 浏览器引擎登录态文件路径（逗号分隔多个候选） | | `MEDIACRAWLER_STORAGE_STATE_PATH` | 空 | 同上（单路径兼容） | | `MEDIACRAWLER_MOCK` | `0` | 浏览器引擎 mock 模式（不依赖 Playwright，可用于自测/验证脚本） | | `MEDIACRAWLER_RETRY_MAX` | `3` | 浏览器引擎页面访问重试次数（含首次） | | `MEDIACRAWLER_RETRY_BASE_S` | `0.8` | 浏览器引擎重试指数退避基准秒数 | | `MEDIACRAWLER_RETRY_CAP_S` | `12` | 浏览器引擎重试指数退避上限秒数 | | `MEDIACRAWLER_DELAY_MIN_S` | `0.4` | 浏览器引擎随机延迟下限（秒） | | `MEDIACRAWLER_DELAY_MAX_S` | `1.2` | 浏览器引擎随机延迟上限（秒） | | `COOKIES` / `XHS_COOKIES` | 空 | API 引擎登录 Cookie（敏感：建议仅在服务侧注入，不要写入镜像/仓库） | | `LOG_LEVEL` | `INFO` | 日志级别 | | `LOG_ROTATION` | `1 day` | 日志切分策略（loguru rotation） | | `LOG_RETENTION` | `14 days` | 日志保留策略（loguru retention） | | `LOG_COMPRESSION` | `zip` | 压缩策略（loguru compression） | `MEDIACRAWLER_STORAGE_STATE_PATHS` 示例： ```bash export MEDIACRAWLER_STORAGE_STATE_PATHS="/data/xhs/storage_state.json,/app/datas/state.json" ``` ### 🐳 Docker Compose 部署（推荐） 项目根目录已提供 `docker-compose.yml`，默认把宿主机 `./storage` 挂载到容器 `/app/storage`： ```bash docker compose up -d --build ``` 建议做法： - 使用单独的环境文件（例如 `.env.local`）注入 `COOKIES`/`CALLBACK_URL` 等敏感变量，并确保不提交到仓库 - 生产环境用反向代理（Nginx/Traefik）提供 TLS，并设置 `x-forwarded-for` 以获得真实 IP（限流按 IP 生效） ### ☕ Java 对接示例 #### 模式 A：拉取（推荐，最简单稳定） 流程： 1) Java 调用 `POST /api/v1/tasks` 创建任务拿到 task_id 2) Java 轮询 `GET /api/v1/tasks/{task_id}` 或直接轮询 `GET /api/v1/tasks/{task_id}/result` 3) 拿到 `normalized/meta` 入库；`raw` 可按需归档 OkHttp 示例（精简版）： ```java import okhttp3.*; import java.util.concurrent.TimeUnit; public class SpiderXhsClient { private final OkHttpClient http = new OkHttpClient.Builder() .connectTimeout(5, TimeUnit.SECONDS) .readTimeout(30, TimeUnit.SECONDS) .build(); public String createTask(String baseUrl, String noteUrl) throws Exception { String json = "{" + "\"task_type\":\"note_url\"," + "\"engine\":\"auto\"," + "\"payload\":{\"note_url\":\"" + noteUrl + "\",\"operator\":\"java\"}" + "}"; Request req = new Request.Builder() .url(baseUrl + "/api/v1/tasks") .post(RequestBody.create(json, MediaType.parse("application/json"))) .build(); try (Response resp = http.newCall(req).execute()) { if (!resp.isSuccessful()) throw new RuntimeException("createTask http=" + resp.code()); return resp.body().string(); } } } ``` 生产环境请解析 JSON 响应，读取 `task.id` 作为 task_id。 建议： - `GET /tasks/{task_id}/result` 返回 409 时，说明结果未就绪；可退避重试（例如 0.5s/1s/2s 递增）。 - 如果 `meta.ok=false` 且 `meta.error_kind=risk/auth`，通常需要人工处理验证码或更新 Cookie/登录态。 #### 模式 B：回调推送（可选） 配置： - 在 Spider_XHS 服务侧设置 `CALLBACK_URL`（或 `SERVICE_CALLBACK_URL`） 回调行为： - 服务完成任务后会 `POST CALLBACK_URL` - 请求头：`Idempotency-Key: ` - 请求体：`{"task_id":"...","result":{...}}` Spring Boot 接收示例（示意，需自行实现幂等去重存储）： ```java import org.springframework.web.bind.annotation.*; import java.util.Map; @RestController public class SpiderXhsCallbackController { @PostMapping("/spider-xhs/callback") public Map callback( @RequestHeader(value = "Idempotency-Key", required = false) String idemKey, @RequestBody Map body ) { return Map.of("ok", true); } } ``` 生产环境建议使用 `Idempotency-Key` 做幂等去重（例如落库或 Redis SETNX），同时避免把任何敏感字段写入日志。 回调失败处理： - 服务会自动重试（最多 5 次），仍失败会落盘记录 - 上游可调用 `POST /api/v1/tasks/{task_id}/callback/retry` 触发再次推送 ### 🛡️ 风控/验证码/封号风险建议（务必阅读） - 限速：控制 QPS 与随机抖动（尤其是搜索/批量详情），避免固定频率与高峰期密集请求。 - 并发：客户端线程数与服务端并发同时收敛；建议从小并发开始（例如 1~3）逐步压测。 - 代理：优先稳定的住宅/独享代理；按账号/会话做粘性，避免频繁切换出口；异常时再切换。 - 人工验证码：当出现验证码/风控（`meta.error_kind=risk/auth`），建议人工在浏览器完成验证并更新 Cookie 或 Playwright storage_state。 - 账号隔离：不同业务/环境使用不同账号与独立存储目录；避免共享 Cookie 造成互相踢下线。 ### 🧰 运维说明（日志/清理/迁移） - 日志目录：`/logs/`，默认文件 `service.log`（按 `LOG_ROTATION` 轮转，保留 `LOG_RETENTION`，按需压缩） - 原始快照：浏览器引擎可能会将 HTML 快照写入 `/raw/`，由 `RAW_DATA_RETENTION_DAYS` 控制保留天数（启动时清理 + 定时清理） - 存储迁移：若检测到旧版 `tasks.json`，服务启动时会自动迁移到 `/tasks/{task_id}.json`，并将旧文件重命名为 `tasks.json.migrated` - 备份建议：按目录整体备份 `` 即可（包含任务、结果、回调失败、快照与日志） ### ✅ 合规红线（务必遵守） - 仅在获得授权、符合平台协议与当地法律法规前提下使用本项目 - 不要采集/存储/传播敏感个人信息，避免长期留存可识别数据（PII） - Cookie、storage_state、回调签名等属于敏感凭证，严禁写入仓库、镜像、公开日志与错误回传 - 如需留存数据，建议最小化采集字段、设置保留期、建立审计与删除机制 --- ## 📁 项目结构 ``` Spider_XHS/ ├── main.py # 主入口：爬虫调用示例 ├── apis/ │ ├── xhs_pc_apis.py # 小红书PC端完整API（采集） │ ├── xhs_creator_apis.py # 创作者平台API（上传发布） │ ├── xhs_pc_login_apis.py # PC端登录（二维码/手机验证码） │ ├── xhs_creator_login_apis.py # 创作者平台登录 │ ├── xhs_pugongying_apis.py # 蒲公英平台API（KOL数据） │ └── xhs_qianfan_apis.py # 千帆平台API（分销商数据） ├── xhs_utils/ │ ├── common_util.py # 初始化工具（读取.env配置） │ ├── cookie_util.py # Cookie解析 │ ├── data_util.py # 数据处理（Excel保存、媒体下载） │ ├── xhs_util.py # PC端签名算法封装 │ ├── xhs_creator_util.py # 创作者平台签名算法封装 │ ├── xhs_pugongying_util.py # 蒲公英平台工具 │ └── xhs_qianfan_util.py # 千帆平台工具 ├── static/ │ ├── xhs_main_260411.js # PC端签名核心JS（最新版） │ ├── xhs_creator_260411.js # 创作者平台签名核心JS（最新版） │ └── ... ├── .env # Cookie配置（不要提交到git） ├── requirements.txt ├── Dockerfile └── package.json ``` --- ## 🗝️ 注意事项 - `main.py` 是爬虫入口，可根据需求修改调用逻辑 - `apis/xhs_pc_apis.py` 包含所有 PC 端数据接口 - `apis/xhs_creator_apis.py` 包含创作者平台发布接口 - Cookie 有时效性，失效后需重新获取 - 建议配合代理（proxies 参数）使用，降低封号风险 --- ## 🍥 更新日志 | 日期 | 说明 | |------|------| | 23/08/09 | 首次提交 | | 23/09/13 | API 更改 params 增加两个字段，修复图片无法下载，修复部分页面无法访问报错 | | 23/09/16 | 修复较大视频编码问题，加入异常处理 | | 23/09/18 | 代码重构，加入失败重试 | | 23/09/19 | 新增下载搜索结果功能 | | 23/10/05 | 新增跳过已下载功能，获取更详细的笔记和用户信息 | | 23/10/08 | 上传至 PyPI，可通过 pip install 安装 | | 23/10/17 | 搜索下载新增排序方式（综合 / 热门 / 最新） | | 23/10/21 | 新增图形化界面，上传至 release v2.1.0 | | 23/10/28 | Fix Bug：修复搜索功能隐藏问题 | | 25/03/18 | 更新 API，修复部分问题 | | 25/06/07 | 更新 search 接口，区分视频和图集下载，新增创作者平台 API | | 25/07/15 | 更新 xs version56 & 小红书创作者接口 | | 26/04/11 | 重构创作者平台 API（图集 / 视频上传），新增蒲公英 KOL 数据 API，新增千帆分销商 API，签名算法升级至最新版 | | 26/04/16 | **架构升级**：全面升级为“稳定性大脑 + 双自动引擎 + RPA 回传兜底”架构（Spider_XHS + MediaCrawler兜底 + Extension 回传），新增 FastAPI 微服务、Webhook 回调、数据助手 Excel 解析、Prometheus 监控与 IP 级限流机制 | | 26/04/16 | **业务闭环（样例级）**：新增 `orchestrator` 编排层，基于 SQLite 搭建 14 张核心业务表，提供“采集同步 -> 基础清洗 -> Mock 飞书同步/告警落库”的最小闭环样例 | | 26/04/16 | **稳定性增强**：引入 **Stability Controller** 大脑与资源池（Account/Session/Proxy Pool），升级为**双自动引擎 + RPA 回传兜底**，增强浏览器引擎拟人化 Stealth，任务状态机升级为多阶段容灾流转 | | 26/04/16 | **可视化控制台**：新增基于 React + Vite 的前端可视化看板，落地资源池中心（账号/会话/代理状态）、错误中心（失败任务聚合分析）与内容库基础页的可视化闭环 | --- ## 🧸 额外说明 1. 欢迎 PR 和 Issue。 2. 项目会持续更新，致力于提供更稳定的数据采集服务。