JieXi/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

项目概述

这是一个短视频解析平台，聚合多家短视频解析接口（抖音、TikTok、哔哩哔哩），提供用户系统、限流控制、队列管理和管理后台。

技术栈：Python + Flask + MySQL + Redis

常用命令

开发环境设置

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

# 配置环境变量
cp .env.example .env
# 然后编辑 .env 文件配置数据库和Redis连接

# 创建数据库
mysql -u root -p
CREATE DATABASE video_parser CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

# 导入数据库表结构
mysql -u root -p video_parser < database/schema.sql

# 初始化管理员账号（用户名: shihao, 密码: 80012029Lz）
python init_admin.py

# 初始化解析接口数据
python init_data.py

运行应用

# 开发模式
python app.py

# 生产模式（使用Gunicorn）
gunicorn -w 4 -b 0.0.0.0:5000 app:app

测试和调试

# 测试数据库连接
python test_db.py

# 检查环境配置
python check_env.py

# 测试邮件发送功能
python test_email.py

# 单独运行定时任务（健康检查）
python scheduler.py

Redis 服务

# Windows下启动Redis（项目包含Redis-x64-5.0.14.1）
cd Redis-x64-5.0.14.1
redis-server.exe redis.windows.conf

核心架构

解析器工厂模式（parsers/factory.py）

• ParserFactory.create_parser(api_config) - 根据API配置创建对应平台的解析器实例
• ParserFactory.get_parser_for_platform(platform) - 获取指定平台的解析器，支持负载均衡（哔哩哔哩使用加权随机选择）
• ParserFactory.detect_platform(video_url) - 自动检测视频链接所属平台

所有解析器继承自 BaseParser（parsers/base.py），必须实现 parse(video_url) 方法，返回统一格式：

{
    "cover": "封面URL",
    "video_url": "视频URL",
    "title": "标题",
    "description": "简介"
}

添加新平台解析器：

1. 在 parsers/ 目录创建新的解析器文件（如 kuaishou.py）
2. 继承 BaseParser 并实现 parse() 方法
3. 在 parsers/factory.py 的 create_parser() 中添加平台映射
4. 在数据库 parser_apis 表中添加新接口配置
5. 在 ParserFactory.detect_platform() 中添加 URL 检测规则

队列与并发控制（utils/queue.py）

• ParseQueue - 解析任务队列管理器，支持Redis和内存队列双模式

  • add_task() - 添加任务到队列
  • get_task() - 从队列获取任务
  • complete_task() - 完成任务并存储结果
  • get_result() - 获取任务结果
  • 降级机制：Redis 连接失败时自动降级到内存队列（重启后数据丢失）

• ConcurrencyController - 并发控制器

  • can_process() - 检查是否可以处理新任务（基于 max_concurrent 配置）
  • wait_for_slot() - 等待可用槽位

健康检查与定时任务（scheduler.py）

使用 APScheduler 定时检查各平台解析接口的健康状态：

• 根据 health_check_config 表配置的间隔执行检查
• 检查结果记录到 health_check_logs 表
• 更新 parser_apis 表的 health_status 和 fail_count

路由结构

• routes/main.py - 主页路由
• routes/auth.py - 用户认证（注册、登录、验证码、重置密码）
• routes/parser.py - 解析API（/api/parse, /api/task/<task_id>, /api/queue-status）
• routes/admin.py - 管理后台（用户管理、接口管理、配置管理、统计数据）

数据模型（models/init.py）

核心模型：

• User / UserGroup - 用户和分组（支持不同限流策略）
• Admin - 管理员（支持2FA）
• ParserAPI - 解析接口配置（支持权重、健康状态、统计数据）
• SMTPConfig - SMTP配置（支持多配置负载均衡）
• ParseLog / DailyParseStat - 解析日志和统计
• HealthCheckConfig / HealthCheckLog - 健康检查配置和日志

限流机制（utils/limiter.py）

RateLimiter 类实现基于用户分组的每日限流：

• check_limit(user_id, ip_address) - 检查是否超过限制，返回 {allowed, current, limit, remaining}
• increment_count(user_id, ip_address, success) - 增加解析计数

默认限流配置：

• 游客：可通过 site_configs 表的 guest_daily_limit 配置（默认5次/天）
• 普通用户（group_id=2）：10次/天
• VIP用户（group_id=3）：50次/天
• SVIP用户（group_id=4）：200次/天

限流数据存储在 daily_parse_stats 表，按 user_id 或 ip_address 统计。

管理员认证（utils/admin_auth.py）

• @admin_required - 装饰器，保护管理后台路由（API返回401 JSON，页面重定向到登录）
• verify_2fa(admin, code) - 验证TOTP 2FA代码
• generate_2fa_secret() / get_2fa_qrcode_url() - 2FA设置辅助函数

应用初始化流程（app.py）

1. 创建Flask应用并加载配置（config.py）
2. 初始化数据库（Flask-SQLAlchemy）
3. 初始化登录管理器（Flask-Login）
4. 初始化Redis连接（支持降级到内存队列）
5. 注册蓝图（auth, parser, admin, main）
6. 启动定时任务调度器（非调试模式或主进程）

环境变量配置（.env）

必需配置：

• SECRET_KEY - Flask密钥
• DB_HOST, DB_PORT, DB_USER, DB_PASSWORD, DB_NAME - MySQL配置
• REDIS_HOST, REDIS_PORT, REDIS_DB, REDIS_PASSWORD - Redis配置（可选，失败时降级到内存队列）
• MAX_CONCURRENT - 最大并发解析数（默认3）
• SESSION_LIFETIME - 会话过期时间（秒，默认7200）

注意：

• SMTP 配置存储在数据库 smtp_configs 表中，通过管理后台管理
• 站点配置（Logo、标题、公告等）存储在 site_configs 表中
• 首次运行前必须执行 init_admin.py 和 init_data.py 初始化数据

访问地址

• 前台首页：http://localhost:5000
• 管理后台：http://localhost:5000/admin/login（默认账号：shihao / 80012029Lz）
• API文档：参考 API文档.md

常见问题

数据库相关

• 修改数据库表结构后，需手动执行 SQL 更新语句（项目未使用迁移工具）
• 确保数据库字符集为 utf8mb4，避免 emoji 等特殊字符存储问题

Redis 相关

• Windows 环境已包含 Redis 服务端（Redis-x64-5.0.14.1/）
• Redis 不可用时系统会自动降级到内存队列，但重启后队列数据会丢失
• 生产环境建议使用独立的 Redis 服务

邮件发送

• 首次部署需在管理后台配置 SMTP（或使用 开发文档/默认SMPT.md 中的默认配置）
• 使用 python test_email.py 测试邮件发送功能
• 支持多 SMTP 配置负载均衡，提高邮件发送成功率

解析接口

• 哔哩哔哩平台支持 3 个接口负载均衡，通过权重分配流量
• 健康检查失败会发送邮件告警给管理员
• 接口配置在 parser_apis 表中，可通过管理后台动态启用/禁用