Initial commit: 百家号文章采集系统

TASKWORKER_TROUBLESHOOTING.md

@@ -0,0 +1,179 @@
+# TaskWorker 卡住问题解决方案
+
+## 问题现象
+线上部署时，所有任务都在"等待中"状态卡住，无法被处理。
+
+## 根本原因
+在使用 Gunicorn 部署时，TaskWorker 可能因为以下原因未能正常启动或中途崩溃：
+1. **多进程竞争**：多个 worker 进程同时启动导致冲突
+2. **锁文件失效**：进程异常退出后锁文件未清理
+3. **线程崩溃**：工作线程因异常而停止
+
+## 解决方案
+
+### 方案1：使用诊断工具（推荐）
+
+已创建专门的诊断和修复工具 `check_taskworker.py`
+
+#### 检查状态
+```bash
+python check_taskworker.py
+```
+
+#### 自动修复
+```bash
+python check_taskworker.py --fix
+```
+
+### 方案2：手动重启服务
+
+```bash
+# 停止 Gunicorn
+kill -TERM $(cat gunicorn.pid)
+
+# 清理锁文件
+rm -f data/taskworker.lock
+
+# 重新启动
+gunicorn -c gunicorn_config.py app:app
+```
+
+### 方案3：使用自动监控守护进程（生产环境推荐）
+
+启动自动监控程序，会定期检查并自动修复：
+
+```bash
+# 后台运行
+nohup python taskworker_monitor.py > logs/monitor.out 2>&1 &
+
+# 或使用 systemd 管理（推荐）
+sudo systemctl start baijiahao-monitor
+```
+
+## 预防措施
+
+### 1. 优化的 Gunicorn 配置
+已更新 `gunicorn_config.py`，使用文件锁（fcntl）替代简单的存在性检查，避免竞争条件。
+
+### 2. 添加健康检查
+在 `app.py` 中添加健康检查接口：
+
+```python
+@app.route('/health/taskworker')
+def health_taskworker():
+    """TaskWorker 健康检查"""
+    try:
+        from task_worker import get_task_worker
+        worker = get_task_worker()
+        alive_threads = sum(1 for t in worker.worker_threads if t and t.is_alive())
+        
+        return jsonify({
+            'status': 'healthy' if worker.running and alive_threads > 0 else 'unhealthy',
+            'running': worker.running,
+            'alive_threads': alive_threads,
+            'current_workers': worker.current_workers,
+            'processing_tasks': len(worker.processing_tasks)
+        })
+    except Exception as e:
+        return jsonify({'status': 'error', 'message': str(e)}), 500
+```
+
+### 3. 使用 Supervisor 管理（可选）
+
+创建 `supervisor.conf`：
+
+```ini
+[program:baijiahao]
+command=/path/to/venv/bin/gunicorn -c gunicorn_config.py app:app
+directory=/path/to/ai_baijiahao
+user=www-data
+autostart=true
+autorestart=true
+redirect_stderr=true
+stdout_logfile=/path/to/ai_baijiahao/logs/supervisor.log
+
+[program:baijiahao-monitor]
+command=/path/to/venv/bin/python taskworker_monitor.py
+directory=/path/to/ai_baijiahao
+user=www-data
+autostart=true
+autorestart=true
+redirect_stderr=true
+stdout_logfile=/path/to/ai_baijiahao/logs/monitor_supervisor.log
+```
+
+## 日常维护
+
+### 查看日志
+```bash
+# TaskWorker 日志
+tail -f logs/gunicorn_error.log | grep TaskWorker
+
+# 监控日志
+tail -f logs/taskworker_monitor.log
+```
+
+### 定期清理
+```bash
+# 清理旧的任务结果（保留最近30天）
+find data/results -name "*.xlsx" -mtime +30 -delete
+
+# 清理旧日志
+find logs -name "*.log" -mtime +30 -delete
+```
+
+## 监控告警
+
+可以结合监控系统（如 Prometheus + Grafana）监控以下指标：
+
+1. **TaskWorker 运行状态**：`/health/taskworker`
+2. **待处理任务数**：通过 API 获取队列统计
+3. **处理中任务数**
+4. **平均任务处理时间**
+
+## 常见问题
+
+### Q1: 重启后任务会丢失吗？
+**A**: 不会。所有任务都存储在 SQLite 数据库中，重启后会自动继续处理。
+
+### Q2: 如何调整并发数？
+**A**: 修改 `task_worker.py` 中的 `TaskWorker` 初始化参数：
+```python
+worker = TaskWorker(min_workers=1, max_workers=3)  # 调整这两个参数
+```
+
+### Q3: 监控程序占用资源吗？
+**A**: 极低。监控程序每60秒检查一次，几乎不占用 CPU 和内存。
+
+## 升级说明
+
+本次更新包含以下改进：
+
+1. ✅ **更健壮的文件锁机制**：使用 `fcntl` 替代简单的文件存在性检查
+2. ✅ **状态验证**：启动后验证 TaskWorker 是否真正运行
+3. ✅ **诊断工具**：`check_taskworker.py` 快速定位问题
+4. ✅ **自动监控**：`taskworker_monitor.py` 自动检测和修复
+5. ✅ **详细日志**：记录启动过程和异常信息
+
+## 联系支持
+
+如果问题仍然存在，请提供以下信息：
+
+1. `logs/gunicorn_error.log` 的最近日志
+2. `python check_taskworker.py` 的输出
+3. 数据库中待处理任务的数量和状态
+
+```bash
+# 快速诊断命令
+echo "=== Gunicorn 进程 ==="
+ps aux | grep gunicorn
+
+echo "=== TaskWorker 锁文件 ==="
+ls -lh data/taskworker.lock
+
+echo "=== 任务统计 ==="
+python check_taskworker.py
+
+echo "=== 最近日志 ==="
+tail -n 50 logs/gunicorn_error.log
+```