华为开发者轮播图API服务

基于FastAPI + Playwright的高性能轮播图数据爬取和API服务，专门用于抓取华为开发者网站的轮播图内容。

特性

• 现代化架构: 基于FastAPI异步框架，支持高并发访问
• 智能爬虫: 使用Playwright移动端模拟，绕过反爬虫机制
• 实时缓存: 内存缓存系统，支持后台更新不影响服务
• 定时任务: 自动定时更新数据，保持数据新鲜度
• 容器化部署: 完整的Docker支持，一键部署
• 监控告警: 内置健康检查和状态监控
• 数据质量: 智能数据验证和过滤机制

系统要求

• Python 3.11+
• Docker & Docker Compose
• 至少 2GB 内存
• 至少 5GB 磁盘空间

快速开始

1. 克隆项目

git clone <repository-url>
cd huawei_carousel_backend

2. 环境配置

# 复制环境配置文件
cp .env.example .env

# 编辑配置文件（可选）
nano .env

3. 一键部署

# 初始化环境
chmod +x deploy.sh
./deploy.sh install

# 启动开发环境
./deploy.sh start dev

# 或启动生产环境
./deploy.sh start prod

4. 验证部署

# 健康检查
./deploy.sh health

# 查看服务状态
./deploy.sh status

# 查看API文档
open http://localhost:8001/docs

API文档

基础端点

• GET / - 服务根路径
• GET /health - 健康检查
• GET /docs - Swagger UI文档
• GET /redoc - ReDoc文档

轮播图API

获取轮播图数据

GET /api/carousel/slides?page=1&page_size=20&with_images_only=false&with_text_only=false

获取单个轮播图

GET /api/carousel/slides/{slide_id}

获取缓存状态

GET /api/carousel/cache/status

手动触发爬取

POST /api/carousel/crawl/manual

管理API

获取调度器状态

GET /api/carousel/scheduler/status

获取爬虫信息

GET /api/carousel/crawler/info

测试爬虫连接

GET /api/carousel/crawler/test

导出缓存数据

POST /api/carousel/cache/export

⚙️ 配置说明

环境变量

变量名	默认值	说明
DEBUG	false	调试模式
HOST	0.0.0.0	服务器绑定地址
PORT	8001	服务器端口
ENABLE_SCHEDULER	true	启用定时任务
CAROUSEL_UPDATE_INTERVAL	21600	更新间隔（秒）
CRAWLER_DELAY	1.0	爬虫请求间隔（秒）
BROWSER_HEADLESS	true	浏览器无头模式

数据库配置

开发环境（默认）

DATABASE_URL=sqlite:///./data/huawei_carousel.db

生产环境

DATABASE_URL=postgresql://user:password@localhost:5432/huawei_carousel

Redis配置（可选）

REDIS_URL=redis://localhost:6379/0

Docker部署

开发环境

# 启动开发环境
docker-compose up -d

# 查看日志
docker-compose logs -f

# 停止服务
docker-compose down

生产环境

# 启动生产环境
docker-compose -f docker-compose.prod.yml up -d

# 查看服务状态
docker-compose -f docker-compose.prod.yml ps

# 查看日志
docker-compose -f docker-compose.prod.yml logs -f app

生产环境配置

生产环境包含以下服务：

• app: 主应用服务
• postgres: PostgreSQL数据库
• redis: Redis缓存
• nginx: 反向代理和SSL终端
• prometheus: 监控（可选）
• grafana: 仪表板（可选）

监控和运维

健康检查

# 内置健康检查
curl http://localhost:8001/health

# 返回示例
{
  "status": "healthy",
  "service": "华为轮播图API",
  "version": "1.0.0",
  "timestamp": 1703123456.789,
  "cache": {
    "status": "ready",
    "cache_count": 10,
    "last_updated": "2025-01-02T10:30:00",
    "update_count": 5
  }
}

日志管理

# 查看应用日志
./deploy.sh logs app

# 查看所有服务日志
./deploy.sh logs all

# 日志文件位置
ls -la logs/

数据备份

# 备份数据
./deploy.sh backup

# 恢复数据
./deploy.sh restore backup_file.tar.gz

开发指南

本地开发

# 创建虚拟环境
python -m venv .venv
source .venv/bin/activate  # Linux/Mac
# 或
.venv\Scripts\activate  # Windows

# 安装依赖
pip install -r requirements.txt

# 安装Playwright浏览器
playwright install chromium

# 启动开发服务器
python run.py --mode dev

项目结构

huawei_carousel_backend/
├── main.py                    # FastAPI应用入口
├── run.py                     # 启动脚本
├── requirements.txt           # Python依赖
├── .env.example              # 环境变量模板
├── Dockerfile                # Docker配置
├── docker-compose.yml        # Docker编排（开发）
├── docker-compose.prod.yml   # Docker编排（生产）
├── deploy.sh                 # 部署脚本
├── core/                     # 核心模块
│   ├── config.py            # 配置管理
│   ├── cache.py             # 缓存系统
│   ├── logging_config.py    # 日志配置
│   └── scheduler.py         # 任务调度
├── api/                      # API路由层
│   └── carousel.py          # 轮播图API
├── models/                   # 数据模型
│   └── carousel.py          # 轮播图模型
├── services/                 # 业务逻辑层
│   └── carousel_service.py  # 轮播图服务
├── nginx/                    # Nginx配置
├── database/                 # 数据库脚本
└── logs/                     # 日志文件

添加新功能

1. 添加新的API端点:

   • 在 models/ 中定义数据模型
   • 在 api/ 中实现路由
   • 在 services/ 中实现业务逻辑

2. 添加新的爬虫源:

   • 在 services/ 中实现新的爬虫服务
   • 在 core/scheduler.py 中添加定时任务

3. 添加新的缓存策略:

   • 在 core/cache.py 中扩展缓存类
   • 更新配置文件

故障排除

常见问题

1. 服务无法启动

# 检查端口占用
netstat -tlnp | grep 8001

# 检查Docker服务
docker ps

# 查看详细日志
docker-compose logs app

2. 爬虫失败

# 测试网络连接
curl -I https://developer.huawei.com/consumer/cn/

# 检查浏览器环境
./deploy.sh logs app | grep -i playwright

# 手动测试爬虫
python -c "from services.carousel_service import get_carousel_service; print(get_carousel_service().test_crawler_connectivity())"

3. 内存不足

# 检查内存使用
docker stats

# 调整资源限制
# 编辑 docker-compose.yml 中的 deploy.resources 配置

4. 数据库连接问题

# 检查数据库状态
docker-compose exec postgres pg_isready

# 查看数据库日志
docker-compose logs postgres

性能优化

1. 爬虫优化

• 调整 CRAWLER_DELAY 减少请求间隔
• 使用代理池避免IP封锁
• 增加重试次数和超时时间

2. 缓存优化

• 调整 CACHE_TTL 延长缓存时间
• 使用Redis替代内存缓存
• 启用数据压缩

3. 数据库优化

• 添加适当的索引
• 定期清理历史数据
• 使用连接池

许可证

本项目基于 Apache License 2.0 许可证开源。

贡献

欢迎提交Issue和Pull Request来改进这个项目。

支持

如有问题，请通过以下方式联系：

• 提交GitHub Issue
• 邮件联系项目维护者

---

注意: 请确保遵守华为开发者网站的robots.txt和使用条款，合理使用爬虫功能。