kami_apple_exchage/backend/docs

分布式Playwright爬虫系统

基于Playwright的分布式爬虫系统，支持多副本部署和Kubernetes环境，具备高可用性和数据一致性保障。

🚀 核心特性

• 🔒 Redis分布式锁: 解决多副本任务竞争问题
• ⚡ Celery任务队列: API服务与爬虫逻辑完全解耦
• 📊 分布式状态管理: 基于Redis的状态存储和同步
• 🔄 自动故障恢复: 智能检测和恢复异常任务
• 💾 持久化存储: 支持错误截图的持久化保存
• 🎯 多副本部署: 支持Kubernetes水平扩缩容
• 📈 监控告警: 完整的健康检查和指标收集

🏗️ 系统架构

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   API Service   │    │  Worker Service │    │  Recovery Svc   │
│   (FastAPI)     │    │   (Celery)      │    │   (Monitor)     │
│   Replicas: 3   │    │   Replicas: 5   │    │   Replicas: 1   │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         ▼                       ▼                       ▼
┌─────────────────────────────────────────────────────────────────┐
│                     Message Queue (Redis)                       │
└─────────────────────────────────────────────────────────────────┘
         │
         ▼
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   PostgreSQL    │    │   File Storage  │    │   Redis Cache   │
│   (Database)    │    │  (PV/Volumes)   │    │  (State Mgmt)   │
└─────────────────┘    └─────────────────┘    └─────────────────┘

🛠️ 技术栈

• 后端框架: FastAPI
• 任务队列: Celery + Redis
• 浏览器自动化: Playwright
• 数据库: PostgreSQL
• 缓存: Redis
• 容器化: Docker
• 编排: Kubernetes

🚀 快速开始

开发环境

1. 克隆项目

git clone <repository-url>
cd backend

2. 使用Docker Compose启动

docker-compose up -d

3. 访问服务

• API服务: http://localhost:8000
• 健康检查: http://localhost:8000/health
• API文档: http://localhost:8000/docs

生产环境

1. 部署到Kubernetes

kubectl apply -f k8s/

2. 检查部署状态

kubectl get pods -l app=crawler

📁 项目结构

详细的项目结构说明请参考 PROJECT_STRUCTURE.md

🔧 配置说明

环境变量

变量名	描述	默认值
REDIS_URL	Redis连接URL	redis://localhost:6379/0
DATABASE_URL	PostgreSQL连接URL	postgresql://user:pass@localhost/db
SERVICE_TYPE	服务类型 (api/worker/recovery)	api
LOG_LEVEL	日志级别	INFO

Redis配置

# Redis分布式锁配置
LOCK_TIMEOUT=30
LOCK_RETRY_DELAY=1
MAX_LOCK_RETRIES=5

# 任务恢复配置
RECOVERY_INTERVAL=60
MAX_RECOVERY_ATTEMPTS=3

🧪 测试

运行所有测试

pytest

运行集成测试

pytest tests/integration/

运行单元测试

pytest tests/unit/

📊 监控

健康检查端点

• /health - 基础健康检查
• /health/ready - 就绪检查（包含依赖服务）
• /health/extended - 扩展健康检查

指标收集

系统提供Prometheus格式的指标：

• 任务执行计数
• 任务执行时间
• 活跃任务数量
• 错误率统计

🔍 故障排查

常见问题

1. Redis连接失败

# 检查Redis服务状态
kubectl get pods -l app=redis
kubectl logs -l app=redis

2. Worker任务堆积

# 检查任务队列状态
# Arq使用不同的队列命名方式，可通过Redis查看具体队列
# 增加Worker副本
kubectl scale deployment crawler-worker --replicas=10

3. 存储空间不足

# 检查PV使用情况
kubectl get pv
# 清理过期文件
kubectl exec -it crawler-worker-xxx -- python -m app.tasks.cleanup_tasks

📚 文档

• 分布式架构文档
• 项目结构说明
• API文档 (启动服务后访问)

🤝 贡献

1. Fork 项目
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 打开 Pull Request

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

🆘 支持

如果您遇到任何问题或有疑问，请：

1. 查看 文档
2. 搜索 Issues
3. 创建新的 Issue

---

注意: 这是一个生产就绪的分布式系统，请确保在部署前仔细阅读文档并进行充分测试。