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

## 系统概述

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

## 系统特点

- 🌐 **Web 可视化界面**：实时监控采集进度和状态
- 🔐 **模拟登录系统**：模拟登录成功状态，本地保存，24小时自动过期
- 👥 **账号管理**：支持添加、删除用户账号
- 📊 **实时日志**：分类显示操作日志，支持过滤和搜索
- 🔄 **多线程采集**：支持单线程/多线程模式切换
- 🐳 **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. 账号管理区域

![账号管理](./images/account-management.png)

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

### 2. 控制面板

![控制面板](./images/control-panel.png)

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

### 3. 进度监控

![进度监控](./images/progress.png)

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

### 4. 日志面板

![日志面板](./images/logs.png)

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

### 5. 错误截图

![错误截图](./images/screenshots.png)

如果采集过程中遇到错误（如风控检测），系统会自动截图并保存：
- 截图保存在：`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. 模拟登录
# 点击"模拟登录"按钮，系统会模拟登录成功并记录登录状态
# 注意：这是模拟登录，不是真实的扫码登录
# 登录状态有效期：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 部署支持
- ✅ 数据导出功能

---

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