353 lines
8.6 KiB
Markdown
353 lines
8.6 KiB
Markdown
|
# 小红书数据采集器使用指南
|
|||
|
|
|
|||
|
|
## 系统概述
|
|||
|
|
|
|||
|
|
这是一个基于 FastAPI + Playwright 的小红书数据采集器，具有 Web 可视化监控界面，支持多线程采集、实时进度展示和持久化日志记录。
|
|||
|
|
|
|||
|
|
## 系统特点
|
|||
|
|
|
|||
|
|
- 🌐 **Web 可视化界面**：实时监控采集进度和状态
|
|||
|
|
- 🔐 **真实扫码登录**：打开小红书官方登录页面，扫码登录后验证状态
|
|||
|
|
- 👥 **账号管理**：支持添加、删除用户账号
|
|||
|
|
- 📊 **实时日志**：分类显示操作日志，支持过滤和搜索
|
|||
|
|
- 🔄 **多线程采集**：支持单线程/多线程模式切换
|
|||
|
|
- 🐳 **Docker 部署**：容器化部署，支持自动更新
|
|||
|
|
- 📁 **数据持久化**：所有数据本地存储，重启不丢失
|
|||
|
|
|
|||
|
|
## 快速开始
|
|||
|
|
|
|||
|
|
### 1. Docker 部署（推荐）
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# 克隆或下载项目
|
|||
|
|
cd /path/to/demo
|
|||
|
|
|
|||
|
|
# 构建并启动容器（使用18085端口）
|
|||
|
|
docker-compose up -d --build
|
|||
|
|
|
|||
|
|
# 查看容器状态
|
|||
|
|
docker-compose ps
|
|||
|
|
|
|||
|
|
# 查看日志
|
|||
|
|
docker-compose logs -f
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 2. 本地运行
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# 安装依赖
|
|||
|
|
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. 首次使用
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# 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. 配置采集参数
|
|||
|
|
|
|||
|
|
1. 选择采集模式：
|
|||
|
|
- **单线程**：稳定但速度慢，适合少量账号
|
|||
|
|
- **多线程**：速度快，适合大量账号（推荐 3-5 个线程）
|
|||
|
|
|
|||
|
|
2. 设置线程数（多线程模式）：
|
|||
|
|
- 建议：3-5 个线程
|
|||
|
|
- 过多线程可能触发风控
|
|||
|
|
|
|||
|
|
### 3. 开始采集
|
|||
|
|
|
|||
|
|
1. 确保已添加至少一个用户账号
|
|||
|
|
2. 确保已登录（显示绿色状态）
|
|||
|
|
3. 点击"启动采集"
|
|||
|
|
4. 系统会：
|
|||
|
|
- 检查登录状态
|
|||
|
|
- 读取用户列表
|
|||
|
|
- 开始采集并实时显示进度
|
|||
|
|
|
|||
|
|
### 4. 监控采集
|
|||
|
|
|
|||
|
|
采集过程中可以：
|
|||
|
|
- 查看实时进度和状态
|
|||
|
|
- 监控日志输出
|
|||
|
|
- 观察各线程工作状态
|
|||
|
|
- 随时停止采集（点击"停止"）
|
|||
|
|
|
|||
|
|
### 5. 数据导出
|
|||
|
|
|
|||
|
|
采集完成后可以：
|
|||
|
|
- 查看每个用户的数据文件：`data/{用户ID}.json`
|
|||
|
|
- 下载所有日志：点击"导出数据"
|
|||
|
|
- 下载错误截图（如有）
|
|||
|
|
|
|||
|
|
## 用户 ID 获取方法
|
|||
|
|
|
|||
|
|
### 方法1：浏览器地址栏
|
|||
|
|
|
|||
|
|
1. 打开小红书网页版
|
|||
|
|
2. 访问目标用户主页：https://www.xiaohongshu.com/user/profile/用户名
|
|||
|
|
3. 从浏览器地址栏复制用户 ID：
|
|||
|
|
```
|
|||
|
|
https://www.xiaohongshu.com/user/profile/5ef74296000000000100003a
|
|||
|
|
```
|
|||
|
|
复制 `5ef74296000000000100003a` 部分
|
|||
|
|
|
|||
|
|
### 方法2：开发者工具
|
|||
|
|
|
|||
|
|
1. 在用户页面按 F12 打开开发者工具
|
|||
|
|
2. 切换到 Network（网络）标签
|
|||
|
|
3. 刷新页面
|
|||
|
|
4. 查找包含 "user" 或 "profile" 的请求
|
|||
|
|
5. 从请求 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
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 数据格式示例
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
// 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 小时后会自动过期，请：
|
|||
|
|
1. 点击"模拟登录"重新登录
|
|||
|
|
2. 检查 `data/auth_state.json` 文件是否存在
|
|||
|
|
|
|||
|
|
### Q2: 采集速度很慢怎么办？
|
|||
|
|
|
|||
|
|
A: 可以尝试：
|
|||
|
|
1. 使用多线程模式（建议 3-5 线程）
|
|||
|
|
2. 检查网络连接
|
|||
|
|
3. 避免在高峰期采集
|
|||
|
|
|
|||
|
|
### Q3: 如何避免被封禁？
|
|||
|
|
|
|||
|
|
A: 系统已内置防护措施：
|
|||
|
|
1. 拟人化延迟（随机 2-60 秒）
|
|||
|
|
2. 平滑滚动加载
|
|||
|
|
3. 多线程错开启动
|
|||
|
|
4. 风控检测自动截图
|
|||
|
|
5. 建议不要设置过多线程
|
|||
|
|
|
|||
|
|
### Q4: 数据采集不全怎么办？
|
|||
|
|
|
|||
|
|
A: 可能原因：
|
|||
|
|
1. 网络不稳定导致加载失败
|
|||
|
|
2. 笔记数量过多，滚动加载不完整
|
|||
|
|
3. 小红书页面结构变化
|
|||
|
|
|
|||
|
|
### Q5: Docker 容器无法启动？
|
|||
|
|
|
|||
|
|
A: 检查：
|
|||
|
|
1. Docker 是否运行
|
|||
|
|
2. 端口 18080 是否被占用
|
|||
|
|
3. Docker Compose 配置是否正确
|
|||
|
|
|
|||
|
|
## 配置说明
|
|||
|
|
|
|||
|
|
### 环境变量
|
|||
|
|
|
|||
|
|
```env
|
|||
|
|
# Web 服务器配置
|
|||
|
|
PORT=18080
|
|||
|
|
HOST=0.0.0.0
|
|||
|
|
|
|||
|
|
# 浏览器配置
|
|||
|
|
HEADLESS=false # 是否无头模式
|
|||
|
|
SCREENSHOT_ON_ERROR=true # 错误时截图
|
|||
|
|
|
|||
|
|
# 多线程配置
|
|||
|
|
MAX_CONCURRENT_THREADS=5 # 最大并发线程数
|
|||
|
|
THREAD_MIN_DELAY=2 # 线程间最小间隔（秒）
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 配置文件位置
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
# app/config.py
|
|||
|
|
DATA_DIR = "data" # 数据目录
|
|||
|
|
SCREENSHOT_DIR = "data/screenshots" # 截图目录
|
|||
|
|
MAX_CONCURRENT_THREADS = 5 # 最大并发线程数
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 更新和维护
|
|||
|
|
|
|||
|
|
### 1. 自动更新（Docker）
|
|||
|
|
|
|||
|
|
系统支持 Git 自动更新：
|
|||
|
|
1. 代码提交到远程仓库
|
|||
|
|
2. 系统自动拉取最新代码
|
|||
|
|
3. 检测到 Python 代码变化时建议重启容器
|
|||
|
|
|
|||
|
|
### 2. 手动更新
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# 拉取最新代码
|
|||
|
|
git pull origin master
|
|||
|
|
|
|||
|
|
# 重新构建容器
|
|||
|
|
docker-compose build
|
|||
|
|
|
|||
|
|
# 重启服务
|
|||
|
|
docker-compose up -d
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 3. 数据备份
|
|||
|
|
|
|||
|
|
重要数据请定期备份：
|
|||
|
|
```bash
|
|||
|
|
# 备份数据目录
|
|||
|
|
tar -czf backup-$(date +%Y%m%d).tar.gz data/
|
|||
|
|
|
|||
|
|
# 备份特定用户数据
|
|||
|
|
cp data/*.json backup-$(date +%Y%m%d)/
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 技术支持
|
|||
|
|
|
|||
|
|
如果遇到问题：
|
|||
|
|
1. 查看 Web 界面的日志面板
|
|||
|
|
2. 检查 Docker 容器日志：`docker-compose logs`
|
|||
|
|
3. 查看 `data/logs.json` 文件
|
|||
|
|
4. 确保网络连接正常
|
|||
|
|
|
|||
|
|
## 版本更新日志
|
|||
|
|
|
|||
|
|
### v1.0.0 (2025-01-12)
|
|||
|
|
- ✅ 实现基础采集功能
|
|||
|
|
- ✅ Web 可视化界面
|
|||
|
|
- ✅ 多线程支持
|
|||
|
|
- ✅ 实时日志系统
|
|||
|
|
- ✅ 账号管理功能
|
|||
|
|
- ✅ 模拟登录系统
|
|||
|
|
- ✅ Docker 部署支持
|
|||
|
|
- ✅ 数据导出功能
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
**注意**：本工具仅供学习和研究使用，请遵守小红书的使用条款和相关法律法规。
|