first commit

2026-01-12 12:04:05 +08:00
commit 8b6e431c12
17 changed files with 3358 additions and 0 deletions
@@ -0,0 +1,296 @@
+# 小红书数据采集器
+
+一个带 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