Skip to content

aki66938/XHS_RS_TOOLS

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

26 Commits
doc
doc
 
 
docker
docker
 
 
examples
examples
 
 
scripts
scripts
 
 
src
src
 
 
.gitignore
.gitignore
 
 
Cargo.lock
Cargo.lock
 
 
Cargo.toml
Cargo.toml
 
 
LICENSE
LICENSE
 
 
README.md
README.md
 
 
client_demo.py
client_demo.py
 
 
docker-compose.yml
docker-compose.yml
 
 

Repository files navigation

XHS-RS-TOOLS

License Language

[仅供学习研究使用 / For Educational Purposes Only]

⚠️ 免责声明 (Disclaimer)

  1. 学习用途: 本项目仅供编程爱好者学习 Rust 与 Python 混合开发、逆向分析思路及浏览器自动化技术使用。
  2. 严禁商用: 严禁将本项目用于任何商业用途、黑灰产或其他非法目的。
  3. 后果自负: 使用本项目产生的任何后果（包括但不限于账号封禁、法律责任）由使用者自行承担。开发者不对任何衍生作品或使用行为负责。
  4. 接口变动: 项目基于特定时间点的目标网站状态开发，不保证长期有效性。

📖 项目概述

本项目是一个基于 Rust (后端 API) 和 undetected-chromedriver (前端采集) 的小红书 API 逆向与自动化工具集。

核心实现逻辑 (The "Secret Sauce")

小红书 Web 端接口的风控机制极为严格，核心在于：Cookie、Request Header 与 X-S 签名强绑定。 简单的签名生成往往无法通过校验，因为服务端会校验签名的生成环境（Cookie、Canvas 指纹等）是否与请求发起者一致。

本项目采用 Pure Algorithm (纯算法签名) 策略：

  1. 访客 Cookie 获取: 使用 Docker 容器化的 undetected-chromedriver 获取合法的访客 Cookie。
  2. 纯 Rust 登录流程: QR 码创建、轮询、登录确认全部由 Rust 通过官方 API 完成。
  3. 实时签名: Python Agent 提供 xhshow 算法签名服务，无需浏览器捕获。
  4. 持久化会话: 登录成功后 Cookie 自动存储到本地 JSON 文件。
  5. 架构优势: 浏览器仅在首次获取访客 Cookie 和登录同步时运行（极低频率），日常请求完全由 Rust 处理。

🛠️ 源码启动 (Source Code Setup)

如果您希望以开发者身份运行源码，请按以下步骤操作：

1. 基础环境准备

  • Rust: 安装最新版 Rust (及 Cargo)。
  • Python: 安装 Python 3.10+（仅本地运行 Agent 时需要）。
  • Docker (推荐): 安装 Docker Desktop，用于容器化运行 Python Agent。

2. 快速启动 (Docker 方式 - 推荐)

# 启动 Python Agent 容器
docker compose up -d --build

# 启动 Rust 服务 (设置环境变量跳过本地 Agent)
set SKIP_LOCAL_AGENT=true && cargo run

# 运行测试 (新终端)
python client_demo.py

3. 本地启动 (无 Docker)

# 安装 Python 依赖
cd scripts
pip install -r requirements.txt
cd ..

# 启动服务 (自动启动 Python Agent)
cargo run

# 运行测试 (新终端)
python client_demo.py

🚀 当前功能 (v1.10.1)

以下均为目前已实现并验证的功能：

  • 🎨 创作者中心: 全新支持 创作者服务平台 登录流程，包含 Guest 初始化、二维码生成及状态轮询 (v1.10.0 新增)。
  • 🐳 Docker 容器化: Python Agent 支持 Docker 部署，基于 selenium/standalone-chrome 镜像，开箱即用。
  • 🍪 Cookie 同步优化: 登录后智能合并 API cookies 与浏览器 cookies，尝试解决偶发性 461 风控问题。
  • 🎬 媒体采集: 解析 视频笔记 (多画质 CDN) 和 图文笔记 (无水印/有水印)，支持服务端 通用下载。
  • 🔐 纯 Rust 登录流程: QR 码创建、状态轮询、登录确认全部 API 化，无需浏览器子进程。
  • 🔍 全套搜索接口: 支持搜索笔记(综合/视频/图文筛选)、搜索建议、OneBox、筛选器元数据、用户搜索。
  • 📰 全频道 Feed 采集: 支持首页推荐及所有 10 个子频道（穿搭、美食、彩妆、影视、职场、情感、家居、游戏、旅行、健身）。
  • 🔔 通知页采集: 获取评论/@、新增关注、赞和收藏，及其分页数据。
  • 📝 笔记详情: 获取指定笔记的完整内容（标题、正文、图片、标签）。
  • 💬 笔记评论: 获取指定笔记的评论列表，支持分页。
  • ✍️ 实时签名: Python Agent 提供 xhshow 算法实时签名。

📅 开发日志 (Dev Log)

版本 日期 更新内容
v1.10.1 2026-01-26 创作者中心信息接口
- 📊 创作者数据: 新增 /api/galaxy/user/info (用户信息) 和 /api/galaxy/creator/home/personal_info (主页信息)
- 📖 文档升级: Swagger UI 更新相关接口文档
- 🚦 CLI 优化: client_demo.py 集成创作者接口测试功能
v1.10.0 2026-01-24 创作者中心登录
- 🎨 创作者中心: 新增 /api/creator/auth 模块，支持创作者 Guest 模式及二维码登录
- 📖 文档同步: Swagger UI 同步更新创作者中心相关接口文档
- 🖥️ 交互式终端: client_demo.py 重构为交互式 CLI，支持 User/Creator 模式切换
- 🤖 Agent 升级: Python Agent 服务更新，兼容创作者中心请求签名
v1.9.0 2026-01-23 Docker 容器化 & Cookie 同步优化
- 🐳 Agent 容器化: 基于 selenium/standalone-chrome:4.16.1 镜像，使用 undetected-chromedriver + Xvfb 实现容器内 headed 模式
- 🍪 Cookie 深度优化: 登录后智能合并 API cookies (含 id_token) 与浏览器 cookies (含 a1, webId)，尝试解决 461 问题
- 🔑 search_id 格式修正: 统一使用 2fvzx 前缀 + 16位随机字符的仿真格式
- 📦 代理配置: 支持通过 HTTP_PROXY/HTTPS_PROXY 环境变量配置容器网络代理构建容器
v1.8.0 2026-01-22 存储轻量化 & 搜索风控突破
- 💾 去数据库化: 彻底移除 MongoDB 依赖，改用本地 JSON 文件存储 Cookie，实现开箱即用
- 🔓 461 修复: 引入浏览器 Cookie 同步机制，解决 Search/OneBox 接口风控问题
v1.7.0 2026-01-21 媒体采集功能 (视频+图片)
- 🎬 视频采集: 新增 /api/note/video 解析视频笔记，返回多画质 CDN 直链
- 🖼️ 图片采集: 新增 /api/note/images 解析图文笔记，返回有水印/无水印两个版本
- 📥 通用下载: 新增 /api/media/download 下载视频/图片到服务端本地
- 📄 测试更新: test_media.py 新增视频和图片采集测试用例
v1.6.2 2026-01-20 Notification 分页支持 & Note Comment 分页文档
- 🔧 Notification 分页: mentions、connections、likes 三个接口支持 num/cursor 分页参数
- 📄 分页指南: 新增 comment_pagination.md、likes_pagination.md、mentions_pagination.md、connections_pagination.md
- 🔧 406 修复: 新增 get_with_query 方法，修复 Notification 接口签名问题
- 📝 Swagger 精简: 移除冗余的 /api/feed/homefeed/recommend 端点
v1.6.1 2026-01-20 Search Notes/Onebox 461 报错修复 & 分页指南
- 🔧 461 修复: 移除多余 headers、调整 payload 字段顺序、修复 session 关联
- 📄 分页指南: 新增 search_pagination.md、usersearch_pagination.md
v1.6.0 2026-01-20 Homefeed 分页参数规则补充
- 📄 分页文档: 新增 doc/homefeed_pagination.md 详细说明分页机制
- 🔧 参数更新: homefeed 接口支持用户自定义 cursor_score、note_index 等分页参数
- 📄 测试更新: 测试用例重构，更新测试用例client_demo.py，选取【穿搭】接口进行分页参数请求测试
v1.5.0 2026-01-18 模块化重构 & Note API 完善
- 🏗️ Server 模块化: server.rs 精简，将 handlers 按领域拆分为 5 个模块
- 📝 Note API: 新增 note/detail 获取笔记详情，修正 note/page 为笔记评论
- 📦 OpenAPI 独立: 抽离 openapi.rs 管理 API 文档
v1.4.0 2026-01-17 Search API Suite 完整实现
- 🔍 搜索全家桶: 新增 search/notes, recommend, onebox, filter ,usersearch
- 📝 Swagger 更新: 新增 Search 聚合分组，完善 Request/Response 模型
v1.3.1 2026-01-17 纯 Rust 登录流程重构
- 🚀 登录 API 化: 新增 /api/auth/guest-init、/qrcode/create、/qrcode/status
- 🔧 Playwright 职责简化: 仅用于获取初始访客 Cookie，无需浏览器子进程
- 🔄 重试机制: 访客 Cookie 获取支持最多 3 次重试，超时容错增强
v1.3.0 2026-01-16 架构重构与接口补全
- 🏗️ 纯算法架构迁移: 移除 Playwright 签名依赖，全面转向 Python Agent 实时签名
- 🐛 修复 406 错误: 修正 Notifications 接口的签名参数处理逻辑
- 🎉 新增接口: 赞和收藏通知 (/api/notification/likes)
- 🤖 Agent 管理: Rust 服务自动管理 Python Agent 生命周期
v1.2.0 2026-01-16 新增端点与代码优化
- 🎉 新增 /api/auth/qrcode-status
- 🐛 修复 Python 脚本 UTF-8 编码问题
v1.1.0 2026-01-15 新增接口与模块重构
- ✨ 新增通知页采集: /api/notification/mentions 和 /connections
- ✨ 新增图文详情: /api/note/page
- ♻️ 重构 API 公共模块，统一请求处理逻辑

🔌 已验证 API 列表 (Implemented APIs)

Category Endpoint Status Description
Auth /api/auth/guest-init ✅ 获取访客 Cookie
Auth /api/auth/qrcode/create ✅ 创建登录二维码
Auth /api/auth/qrcode/status ✅ 轮询登录状态
Creator /api/creator/auth/guest-init ✅ 创作者中心访客初始化
Creator /api/creator/auth/qrcode/create ✅ 创建创作者登录二维码
Creator /api/creator/auth/qrcode/status ✅ 轮询创作者登录状态
Creator /api/galaxy/user/info ✅ 创作者基础信息
Creator /api/galaxy/creator/home/personal_info ✅ 创作者主页数据 (粉丝/获赞)
User /api/user/me ✅ 获取当前用户信息
Search /api/search/trending ✅ 获取热搜推荐词
Search /api/search/notes ✅ 笔记搜索 (📖 分页指南)
Search /api/search/recommend ✅ 搜索建议
Search /api/search/onebox ✅ OneBox 聚合
Search /api/search/usersearch ✅ 用户搜索 (📖 分页指南)
Search /api/search/filter ✅ 筛选器元数据
Feed /api/feed/homefeed/{category} ✅ 11 个垂直频道 (📖 分页指南)
Notification /api/notification/mentions ✅ 获取评论和 @ 通知 (📖 分页指南)
Notification /api/notification/connections ✅ 获取新增关注通知 (📖 分页指南)
Notification /api/notification/likes ✅ 获取赞和收藏通知 (📖 分页指南)
Note /api/note/page ✅ 获取笔记评论列表 (📖 分页指南)
Note /api/note/detail ✅ 获取笔记完整内容
Media /api/note/video ✅ 视频笔记地址解析（多画质 CDN 直链）
Media /api/note/images ✅ 图文笔记地址解析（有水印/无水印）
Media /api/media/download ✅ 通用媒体下载（视频/图片到本地）

📚 接口文档 (API Docs)

本项目内置 Swagger UI，启动服务后即可访问：

  • 地址: http://localhost:3005/swagger-ui/
  • 使用: 可在网页上直接发起请求测试接口。

👨‍💻 作者自述 (Author's Note)

项目起源与转型

本项目的灵感来源于我对 RPA (Robotic Process Automation) 技术及浏览器自动化控制的深入研究。 在前作 xhs_tools (1.1k stars) 的维护过程中，我深刻体会到单纯依赖 Python 脚本进行自动化操作的局限性。随着 AI 技术（特别是像 Google Gemini 这样具备强大浏览器理解能力的模型）的崛起，传统的硬编码自动化正在被智能代理所取代。

因此，我决定暂停旧项目的更新，转向探索通过纯后端API实现的服务端解决方案：

  • 架构变更: 核心网络层采用 Rust 重写，确保极高的并发性能与类型安全。
  • 自动化基座: 保留 Python (Playwright) 作为浏览器控制层，专注于处理登录二维码的获取。
  • API 化: 将所有功能封装为标准 HTTP 接口，为未来接入 AI Agent 或其他上层应用提供坚实基础。

法律/合规声明 (Legal Statement)

请务必仔细阅读：

  1. 技术研究性质: 本项目本质上是一个 浏览器自动化框架 的实践案例。所有的“采集”行为均基于模拟真实用户的常规浏览操作（点击、滚动、网络请求）
  2. 数据安全: 本项目不提供任何现成的账号或 Cookie。用户必须通过官方渠道（扫码）进行合法登录。项目仅作为数据的本地处理工具，不收集、不上传任何用户敏感信息。
  3. 合规使用: 请使用者严格遵守《中华人民共和国网络安全法》及目标网站的《用户服务协议》。严禁将本项目用于数据爬取（Scraping）、批量账号控制（Botting）或任何侵犯他人隐私/知识产权的商业行为。
  4. 免责条款: 开源作者不对任何因使用本项目而导致的法律纠纷或账号损失承担责任。代码仅作为技术交流用途，下载后请于 24 小时内删除。

🙏 致谢 (Acknowledgements)

特别感谢以下开源项目为本项目提供的技术支持与灵感：

  • xhshow by Cloxl: 本项目中的 Python Agent 签名服务部分深度借鉴并集成了 xhshow 的核心算法实现。xhshow 是一个优秀的开源项目，提供了可靠的小红书 Web 端签名生成方案。

    Standing on the shoulders of giants.

以技术探索为名，行守法合规之事。

📄 开源协议

MIT License

About

xhs_toolkit for rust

Resources

Readme

License

MIT license
Activity

Stars

145 stars

Watchers

1 watching

Forks

36 forks
Report repository

Releases

1 tags

Packages

 
 
 

Contributors

Languages