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. 克隆项目

cd demo

2. 安装依赖

pip install -r requirements.txt

3. 安装 Playwright 浏览器

playwright install chromium

使用

1. 启动服务

python main.py

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

2. 添加用户 ID

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

5ef74296000000000100003a
5b6c1f9e0000000001000388

3. 配置采集模式

在 Web 界面中选择：

• 单线程模式: 一次采集一个用户，更安全
• 多线程模式: 同时采集多个用户，更快

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

4. 启动采集

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

登录成功后，采集器会自动开始工作，你可以在 Web 界面实时查看：

• 整体进度
• 用户状态
• 线程监控（多线程模式）
• 实时日志

配置

环境变量

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

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

采集参数

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

# 延迟配置（秒）
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)

{
  "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（推荐）

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

# 查看日志
docker-compose logs -f

# 停止服务
docker-compose down

方式二：使用 Docker 命令

构建镜像

docker build -t xiaohongshu-scraper .

运行容器

# 本地开发模式（可以看到浏览器窗口）
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

管理容器

# 查看日志
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 中添加环境变量：

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 手动触发更新：

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

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

4. 重启容器

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

# 使用 Docker Compose
docker-compose restart

# 使用 Docker 命令
docker restart xiaohongshu-scraper

注意事项

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

许可证

MIT License