PROGRESS_BAR_TROUBLESHOOTING.md

进度条卡住问题 - 故障排除指南

问题描述

进度条一直卡在 "Waiting for crawler to start..." 状态

已完成的修复

1. WebSocket连接机制

• ✅ 添加了连接等待机制（最多等待3秒）
• ✅ 改进了broadcast函数的日志和错误处理
• ✅ 添加了连接状态检查

2. 消息发送机制

• ✅ 替换所有 asyncio.run 调用为 broadcast_sync
• ✅ 在爬虫开始前发送多次初始消息（确保到达）
• ✅ 添加了详细的调试日志

3. 爬虫错误处理

• ✅ 添加了爬虫启动错误捕获
• ✅ 添加了爬虫执行过程中的错误处理
• ✅ 所有错误都会通过WebSocket发送到前端

诊断步骤

步骤1：检查后端日志

当URL上传后，查看后端日志，应该能看到以下信息：

⏳ [AsyncTask] Starting task: url
⏳ [URL Task] Waiting for WebSocket connection... (0.1s)
✅ [URL Task] WebSocket connection(s) ready: 1
📢 [URL Task] About to send initial progress message...
✅ [Broadcast] Message sent to 1/1 connections: progress
✅ [URL Task] Initial progress message sent
🚀 [URL Task] Starting crawl for: <your-url>
🕸️ Starting recursive crawl: <your-url> (Depth: 8, Max Pages: 1000)
   📢 Initial callback sent
   🔍 Crawling: <your-url>

如果看不到这些日志：

• 后台任务可能没有启动
• 检查FastAPI是否正常运行

如果看到 "⚠️ [Broadcast] No active WebSocket connections"：

• WebSocket连接没有建立
• 检查浏览器控制台是否有WebSocket错误

步骤2：检查浏览器控制台

打开浏览器开发者工具（F12），查看Console标签：

应该看到：

✅ WebSocket connected successfully
WebSocket message received: {type: "progress", task_type: "url", ...}

如果没有看到 "WebSocket connected"：

• WebSocket连接失败
• 检查服务器是否运行在正确的端口
• 检查防火墙设置

如果看到连接但收不到消息：

• 消息可能没有发送
• 检查后端日志中的广播消息

步骤3：检查爬虫是否真正启动

在系统管理器中，爬虫启动会打印：

🕸️ Starting recursive crawl: <url>

如果看到这个消息但之后没有进度更新：

• 爬虫可能在第一个URL就卡住了
• 检查网络连接
• 检查目标URL是否可访问

步骤4：检查数据库

如果启用了 check_db_first=True：

• URL可能已经存在于数据库中
• 爬虫会跳过已存在的URL
• 如果所有URL都已存在，进度可能不会更新

常见问题

Q1: 为什么进度条一直显示 "Waiting for crawler to start..."？

A: 可能的原因：

1. WebSocket消息没有发送成功
2. 前端没有正确处理消息
3. 爬虫没有真正启动

解决方法：

• 检查后端日志中的广播消息
• 检查浏览器控制台是否收到WebSocket消息
• 检查爬虫是否打印了启动日志

Q2: 看到 "No active WebSocket connections" 警告

A: WebSocket连接没有建立

解决方法：

• 刷新页面，确保WebSocket连接建立
• 检查 static/index.html 中的WebSocket初始化代码
• 检查服务器是否正常运行

Q3: 爬虫启动但没有进度更新

A: 可能的原因：

1. URL已经在数据库中，被跳过了
2. 爬虫卡在某个URL上
3. 回调函数没有被调用

解决方法：

• 查看后端日志，确认是否有 "Crawling:" 消息
• 查看是否有 "Progress updated:" 消息
• 检查URL是否可访问

调试技巧

1. 启用详细日志

   • 所有关键步骤都有日志输出
   • 查看后端控制台的完整输出

2. 检查WebSocket连接

   • 在浏览器Network标签中查看WebSocket连接状态
   • 查看是否有错误或断开连接

3. 测试单个URL

   • 先测试一个简单的、已知可访问的URL
   • 确认爬虫基本功能正常

4. 检查网络环境

   • 确保服务器可以访问目标URL
   • 检查是否有防火墙或代理问题

下一步

如果问题仍然存在，请提供：

1. 后端日志的完整输出（从URL上传开始）
2. 浏览器控制台的完整输出
3. 目标URL
4. 服务器环境信息

这些信息将帮助我们进一步诊断问题。