ts

2026-01-12 19:07:00 +08:00
parent f2dcc4c0cf
commit 9b3b5c8329
11 changed files with 362 additions and 7 deletions
@@ -72,13 +72,15 @@ templates = Jinja2Templates(directory=os.path.join(config.BASE_DIR, "templates")

@app.on_event("startup")
 async def on_startup():
-    # 启动 Playwright + Browser（长期复用，减少反复启动带来的抖动）
-    app_state.playwright = await async_playwright().start()
-    app_state.browser = await app_state.playwright.chromium.launch(
-        headless=config.HEADLESS,
-        args=config.BROWSER_ARGS,
-    )
-    log_manager.append("INFO", f"Browser launched (headless={config.HEADLESS})")
+    """
+    只做轻量初始化，不在启动时强制拉起浏览器。
+    原因：
+    - 很多环境首次运行未执行 `playwright install chromium`，如果启动即 launch，会导致 Web 直接起不来（你看到的“打不开”）。
+    - 浏览器改为按需启动：第一次需要登录/解析/采集时再启动，失败也能在 UI 里看到明确错误。
+    """
+    app_state.playwright = None
+    app_state.browser = None
+    log_manager.append("INFO", "App started (browser will be launched lazily on demand)")


@app.on_event("shutdown")
@@ -0,0 +1,353 @@
+# 小红书数据采集器使用指南
+
+## 系统概述
+
+这是一个基于 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. 账号管理区域
+
+![账号管理](./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. 真实扫码登录
+# 点击"打开登录页"按钮，会在新窗口打开小红书官方登录页面
+# 在打开的页面中使用小红书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 部署支持
+- ✅ 数据导出功能
+
+---
+
+**注意**：本工具仅供学习和研究使用，请遵守小红书的使用条款和相关法律法规。