xhs_crawler_claude/README.md

# 小红书数据采集器

一个带 Web 可视化监控界面的小红书批量数据采集器，支持多账号增量采集、实时进度展示、持久化日志追踪、单/多线程切换。

## 功能特性

- **Web 可视化界面**: 实时监控采集进度和日志
- **单/多线程模式**: 支持切换单线程或多线程采集，可配置线程数
- **增量采集**: 自动识别已采集内容，仅采集新增笔记
- **持久化日志**: 日志保存到文件，重启后可查看历史记录
- **风控策略**: 拟人化延迟、平滑滚动、风控检测
- **云部署友好**: 支持 Docker 部署

## 项目结构

```
demo/
├── app/
│   ├── __init__.py
│   ├── config.py          # 配置文件
│   ├── log_manager.py     # 日志管理器
│   ├── scraper.py         # 核心采集逻辑
│   └── web.py             # Web API
├── data/
│   ├── users.txt          # 用户 ID 输入文件
│   ├── logs.json          # 持久化日志
│   └── {user_id}.json     # 采集数据
├── templates/
│   └── index.html         # 前端页面
├── static/
│   ├── style.css          # 样式
│   └── app.js             # 前端逻辑
├── main.py                # 程序入口
├── requirements.txt       # 依赖列表
└── README.md
```

## 安装

### 1. 克隆项目

```bash
cd demo
```

### 2. 安装依赖

```bash
pip install -r requirements.txt
```

### 3. 安装 Playwright 浏览器

```bash
playwright install chromium
```

## 使用

### 1. 启动服务

```bash
python main.py
```

服务将在 `http://localhost:18080` 启动。

### 2. 添加用户 ID

在 `data/users.txt` 中添加要采集的用户 ID，每行一个：

```
5ef74296000000000100003a
5b6c1f9e0000000001000388
```

### 3. 配置采集模式

在 Web 界面中选择：
- **单线程模式**: 一次采集一个用户，更安全
- **多线程模式**: 同时采集多个用户，更快

多线程模式下可设置线程数（1-10）。

### 4. 启动采集

点击「启动采集」按钮，在弹出的浏览器窗口中扫码登录。

登录成功后，采集器会自动开始工作，你可以在 Web 界面实时查看：
- 整体进度
- 用户状态
- 线程监控（多线程模式）
- 实时日志

## 配置

### 环境变量

创建 `.env` 文件配置以下参数：

```env
HOST=0.0.0.0
PORT=18080
HEADLESS=false
SCREENSHOT_ON_ERROR=true
MAX_THREADS=5
```

### 采集参数

修改 `app/config.py` 中的参数：

```python
# 延迟配置（秒）
PAGE_LOAD_DELAY = (2, 5)        # 页面加载后等待
NOTE_READ_DELAY = (3, 8)        # 笔记详情页停留
NOTE_INTERVAL_DELAY = (3, 6)    # 采集笔记间隔
USER_SWITCH_DELAY = (30, 60)    # 切换用户间隔

# 多线程配置
THREAD_MIN_DELAY = 2            # 线程间最小间隔
THREAD_OFFSET = 5               # 线程启动偏移
```

## 数据格式

### 输入文件 (data/users.txt)

```
5ef74296000000000100003a
5b6c1f9e0000000001000388
```

### 输出文件 (data/{user_id}.json)

```json
{
  "user_id": "5ef74296000000000100003a",
  "last_updated": "2025-01-12T10:30:00",
  "total_notes": 12,
  "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/..."
    }
  ]
}
```

## Docker 部署

### 方式一：使用 Docker Compose（推荐）

```bash
# 构建并启动
docker-compose up -d

# 查看日志
docker-compose logs -f

# 停止服务
docker-compose down
```

### 方式二：使用 Docker 命令

#### 构建镜像

```bash
docker build -t xiaohongshu-scraper .
```

#### 运行容器

```bash
# 本地开发模式（可以看到浏览器窗口）
docker run -d \
  -p 18080:18080 \
  -v $(pwd)/data:/app/data \
  -e HEADLESS=false \
  --name xiaohongshu-scraper \
  xiaohongshu-scraper

# 云服务器模式（无头模式）
docker run -d \
  -p 18080:18080 \
  -v $(pwd)/data:/app/data \
  -e HEADLESS=true \
  --name xiaohongshu-scraper \
  xiaohongshu-scraper
```

#### 管理容器

```bash
# 查看日志
docker logs -f xiaohongshu-scraper

# 停止容器
docker stop xiaohongshu-scraper

# 启动容器
docker start xiaohongshu-scraper

# 删除容器
docker rm xiaohongshu-scraper

# 进入容器
docker exec -it xiaohongshu-scraper bash
```

### Docker 环境变量

| 变量 | 默认值 | 说明 |
|------|--------|------|
| HOST | 0.0.0.0 | 监听地址 |
| PORT | 18080 | 监听端口（范围 10000-50000）|
| HEADLESS | false | 是否无头模式（云服务器设为 true）|
| SCREENSHOT_ON_ERROR | true | 错误时截图 |
| MAX_THREADS | 5 | 最大线程数 |
| ENABLE_GIT_PULL | false | 启用 Git 自动更新 |
| GIT_REPO_URL | - | Git 仓库地址 |
| GIT_BRANCH | main | Git 分支 |
| AUTO_PULL_INTERVAL | 3600 | 自动拉取间隔（秒）|

### 数据持久化

通过挂载 `./data` 目录到容器的 `/app/data`，确保以下数据持久化：

- `users.txt` - 用户 ID 列表
- `{user_id}.json` - 采集数据
- `logs.json` - 运行日志
- `auth_state.json` - 登录状态（Cookie）
- `screenshots/` - 错误截图

### Git 自动更新

支持通过 Git 自动更新代码（适用于云部署）：

#### 1. 配置 Git 自动更新

在 `docker-compose.yml` 中添加环境变量：

```yaml
environment:
  - ENABLE_GIT_PULL=true
  - GIT_REPO_URL=https://github.com/yourusername/xiaohongshu-scraper.git
  - GIT_BRANCH=main
  - AUTO_PULL_INTERVAL=3600
```

#### 2. 工作原理

- 容器启动后，会定期从 Git 仓库拉取最新代码
- 如果检测到 Python 文件变化，会提示需要重启容器
- 静态文件（HTML/CSS/JS）变化会立即生效，无需重启

#### 3. 手动更新

通过 API 手动触发更新：

```bash
# 检查 Git 状态
curl http://your-server:18080/api/git/status

# 拉取最新代码
curl -X POST http://your-server:18080/api/git/pull
```

#### 4. 重启容器

如果 Python 代码有变化，需要重启容器：

```bash
# 使用 Docker Compose
docker-compose restart

# 使用 Docker 命令
docker restart xiaohongshu-scraper
```

## 注意事项

1. **风控风险**: 本工具仅供学习交流使用，请遵守小红书的使用条款
2. **采集频率**: 建议使用单线程模式，多线程模式可能增加风控风险
3. **登录状态**: 首次登录后会保存 Cookie，后续无需重新登录
4. **页面结构**: 小红书页面结构可能变化，如遇采集失败请检查 CSS 选择器

## 许可证

MIT License