xinyouhe/xhs_crawler_claude

Fork 0

Files

T

mzl92 9b3b5c8329 ts

2026-01-12 19:07:00 +08:00

8.6 KiB

Raw Blame History

小红书数据采集器使用指南

系统概述

这是一个基于 FastAPI + Playwright 的小红书数据采集器，具有 Web 可视化监控界面，支持多线程采集、实时进度展示和持久化日志记录。

系统特点

🌐 Web 可视化界面：实时监控采集进度和状态
🔐 真实扫码登录：打开小红书官方登录页面，扫码登录后验证状态
👥 账号管理：支持添加、删除用户账号
📊 实时日志：分类显示操作日志，支持过滤和搜索
🔄 多线程采集：支持单线程/多线程模式切换
🐳 Docker 部署：容器化部署，支持自动更新
📁 数据持久化：所有数据本地存储，重启不丢失

快速开始

1. Docker 部署（推荐）

# 克隆或下载项目
cd /path/to/demo

# 构建并启动容器（使用18085端口）
docker-compose up -d --build

# 查看容器状态
docker-compose ps

# 查看日志
docker-compose logs -f

2. 本地运行

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

# 安装浏览器
playwright install chromium

# 创建数据目录
mkdir -p data data/screenshots

# 运行程序
python main.py

3. 访问系统

打开浏览器访问：http://localhost:18085

系统界面说明

1. 账号管理区域

添加账号：点击添加账号按钮，输入小红书用户 ID
刷新账号：重新加载账号列表和状态
登录状态：
- 🔴 红色圆点：未登录
- 🟢 绿色圆点：已登录
- 显示剩余登录时间（小时:分钟）

2. 控制面板

启动采集：开始数据采集任务
停止：停止正在进行的采集任务
清空日志：清空所有历史日志
导出数据：下载采集到的数据文件
模式选择：
- 单线程：逐个处理账号
- 多线程：同时处理多个账号（可配置线程数）
线程数：多线程模式下的并发线程数（1-10）

3. 进度监控

整体进度：显示采集进度条和百分比
活跃线程：多线程模式下显示正在运行的线程数
用户列表：显示每个用户的采集状态
- ✅ 已完成：显示采集的笔记数量
- 🔄 进行中：显示当前处理的笔记数量
- ⏳ 待处理：尚未开始处理的账号
- ❌ 失败：采集失败的账号

4. 日志面板

日志级别过滤：可选择查看 ALL/INFO/SUCCESS/WARNING/ERROR/DEBUG 级别的日志
搜索功能：搜索特定关键词的日志
自动滚动：开启后自动滚动到最新日志
时间戳：显示每条日志的具体时间
线程标识：多线程模式下显示日志来源线程

5. 错误截图

如果采集过程中遇到错误（如风控检测），系统会自动截图并保存：

截图保存在：data/screenshots/ 目录
在界面中显示错误截图缩略图
可点击查看大图或下载所有截图

操作流程

1. 首次使用

# 1. 启动系统
docker-compose up -d --build

# 2. 访问 Web 界面
# 打开 http://localhost:18080

# 3. 添加要采集的用户 ID
# 点击"添加账号"按钮，输入小红书用户 ID
# 格式：长字符串（如 5ef74296000000000100003a）
# 可从浏览器地址栏获取：https://www.xiaohongshu.com/user/profile/用户ID

# 4. 真实扫码登录
# 点击"打开登录页"按钮，会在新窗口打开小红书官方登录页面
# 在打开的页面中使用小红书App扫描二维码完成登录
# 登录成功后，返回本页面点击"验证登录"按钮
# 登录状态有效期：24小时

2. 配置采集参数

选择采集模式：
- 单线程：稳定但速度慢，适合少量账号
- 多线程：速度快，适合大量账号（推荐 3-5 个线程）
设置线程数（多线程模式）：
- 建议：3-5 个线程
- 过多线程可能触发风控

3. 开始采集

确保已添加至少一个用户账号
确保已登录（显示绿色状态）
点击"启动采集"
系统会：
- 检查登录状态
- 读取用户列表
- 开始采集并实时显示进度

4. 监控采集

采集过程中可以：

查看实时进度和状态
监控日志输出
观察各线程工作状态
随时停止采集（点击"停止"）

5. 数据导出

采集完成后可以：

查看每个用户的数据文件：data/{用户ID}.json
下载所有日志：点击"导出数据"
下载错误截图（如有）

用户 ID 获取方法

方法1：浏览器地址栏

打开小红书网页版
访问目标用户主页：https://www.xiaohongshu.com/user/profile/用户名
从浏览器地址栏复制用户 ID：
```
https://www.xiaohongshu.com/user/profile/5ef74296000000000100003a
```
复制 5ef74296000000000100003a 部分

方法2：开发者工具

在用户页面按 F12 打开开发者工具
切换到 Network（网络）标签
刷新页面
查找包含 "user" 或 "profile" 的请求
从请求 URL 中提取用户 ID

数据文件说明

输入文件

data/users.txt     # 用户 ID 列表，每行一个

输出文件

data/
├── auth_state.json    # 登录状态缓存
├── logs.json          # 操作日志历史
├── users.txt          # 用户列表
├── 5ef74296000000000100003a.json  # 用户采集数据
├── 5b6c1f9e0000000001000388.json  # 用户采集数据
└── screenshots/       # 错误截图目录
    ├── error_xxx1.png
    └── error_xxx2.png

数据格式示例

// data/{用户ID}.json
{
  "user_id": "5ef74296000000000100003a",
  "last_updated": "2025-01-12T10:30:00",
  "notes": [
    {
      "title": "笔记标题",
      "publish_time": "2025-01-10 14:30",
      "location": "上海",
      "comment_count": 128,
      "like_count": 5234,
      "collect_count": 892,
      "note_url": "https://www.xiaohongshu.com/explore/xxx"
    }
  ]
}

常见问题

Q1: 为什么提示"未登录"？

A: 登录状态 24 小时后会自动过期，请：

点击"模拟登录"重新登录
检查 data/auth_state.json 文件是否存在

Q2: 采集速度很慢怎么办？

A: 可以尝试：

使用多线程模式（建议 3-5 线程）
检查网络连接
避免在高峰期采集

Q3: 如何避免被封禁？

A: 系统已内置防护措施：

拟人化延迟（随机 2-60 秒）
平滑滚动加载
多线程错开启动
风控检测自动截图
建议不要设置过多线程

Q4: 数据采集不全怎么办？

A: 可能原因：

网络不稳定导致加载失败
笔记数量过多，滚动加载不完整
小红书页面结构变化

Q5: Docker 容器无法启动？

A: 检查：

Docker 是否运行
端口 18080 是否被占用
Docker Compose 配置是否正确

配置说明

环境变量

# Web 服务器配置
PORT=18080
HOST=0.0.0.0

# 浏览器配置
HEADLESS=false          # 是否无头模式
SCREENSHOT_ON_ERROR=true # 错误时截图

# 多线程配置
MAX_CONCURRENT_THREADS=5 # 最大并发线程数
THREAD_MIN_DELAY=2       # 线程间最小间隔（秒）

配置文件位置

# app/config.py
DATA_DIR = "data"                    # 数据目录
SCREENSHOT_DIR = "data/screenshots"  # 截图目录
MAX_CONCURRENT_THREADS = 5           # 最大并发线程数

更新和维护

1. 自动更新（Docker）

系统支持 Git 自动更新：

代码提交到远程仓库
系统自动拉取最新代码
检测到 Python 代码变化时建议重启容器

2. 手动更新

# 拉取最新代码
git pull origin master

# 重新构建容器
docker-compose build

# 重启服务
docker-compose up -d

3. 数据备份

重要数据请定期备份：

# 备份数据目录
tar -czf backup-$(date +%Y%m%d).tar.gz data/

# 备份特定用户数据
cp data/*.json backup-$(date +%Y%m%d)/

技术支持

如果遇到问题：

查看 Web 界面的日志面板
检查 Docker 容器日志：docker-compose logs
查看 data/logs.json 文件
确保网络连接正常

版本更新日志

v1.0.0 (2025-01-12)

✅ 实现基础采集功能
✅ Web 可视化界面
✅ 多线程支持
✅ 实时日志系统
✅ 账号管理功能
✅ 模拟登录系统
✅ Docker 部署支持
✅ 数据导出功能

注意：本工具仅供学习和研究使用，请遵守小红书的使用条款和相关法律法规。

8.6 KiB Raw Blame History Unescape Escape