202 lines
6.9 KiB
Markdown
202 lines
6.9 KiB
Markdown
# CLAUDE.md
|
||
|
||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
||
## 项目概述
|
||
|
||
这是一个短视频解析平台，聚合多家短视频解析接口（抖音、TikTok、哔哩哔哩），提供用户系统、限流控制、队列管理和管理后台。
|
||
|
||
技术栈：Python + Flask + MySQL + Redis
|
||
|
||
## 常用命令
|
||
|
||
### 开发环境设置
|
||
|
||
```bash
|
||
# 安装依赖
|
||
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
|
||
```
|
||
|
||
### 运行应用
|
||
|
||
```bash
|
||
# 开发模式
|
||
python app.py
|
||
|
||
# 生产模式（使用Gunicorn）
|
||
gunicorn -w 4 -b 0.0.0.0:5000 app:app
|
||
```
|
||
|
||
### 测试和调试
|
||
|
||
```bash
|
||
# 测试数据库连接
|
||
python test_db.py
|
||
|
||
# 检查环境配置
|
||
python check_env.py
|
||
|
||
# 测试邮件发送功能
|
||
python test_email.py
|
||
|
||
# 单独运行定时任务（健康检查）
|
||
python scheduler.py
|
||
```
|
||
|
||
### Redis 服务
|
||
|
||
```bash
|
||
# 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)` 方法，返回统一格式：
|
||
```python
|
||
{
|
||
"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` 表中，可通过管理后台动态启用/禁用
|