hs-video-api/CACHE_PERSISTENCE_README.md

缓存和持久化机制说明

概述

本项目实现了完善的任务缓存和持久化机制，确保服务重启后能够恢复任务状态，并提供高效的任务管理功能。

主要特性

1. 分层缓存设计

• 运行中任务缓存 (running_tasks_cache): 存储正在执行的任务（状态为 running 或 queued）
• 已完成任务缓存 (completed_tasks_cache): 存储已完成的任务（状态为 succeeded、failed、cancelled）
• 等待队列 (waiting_queue): 存储等待执行的任务请求

2. 持久化机制

• 文件持久化: 等待队列数据保存到本地JSON文件
• 自动保存: 等待队列变化时自动保存
• 启动恢复: 服务启动时自动从持久化文件恢复等待队列

3. 智能清理策略

• 按时间清理: 自动清理超过TTL的已完成任务
• 按数量限制: 保留最新的N个已完成任务
• 定期执行: 每10次状态更新执行一次清理

4. SDK数据恢复

• 启动时恢复: 从SDK重新加载运行中和已完成的任务
• 状态同步: 定时从SDK更新任务状态
• 缓存更新: SDK数据变化时自动更新本地缓存

配置参数

TaskQueueManager 初始化参数

queue_manager = TaskQueueManager(
    max_running_tasks=5,                    # 最大运行任务数
    update_interval=5,                      # 状态更新间隔（秒）
    persistence_file="task_queue_persistence.json"  # 持久化文件路径
)

缓存配置

# 在 __init__ 方法中设置
self.max_completed_cache_size = 100      # 最多保留100个已完成任务
self.completed_cache_ttl_hours = 24      # 已完成任务缓存保留24小时

工作流程

1. 服务启动流程

1. 创建TaskQueueManager实例
2. 调用start()方法
3. 从持久化文件恢复等待队列 (_load_persistence_data)
4. 从SDK恢复任务缓存 (_load_initial_tasks)
5. 启动状态更新线程 (_start_update_thread)

2. 任务创建流程

1. 检查是否可以创建新任务 (can_create_task)
2. 调用SDK创建任务
3. 根据队列状态决定:
   - 直接加入运行中缓存
   - 或加入等待队列并持久化
4. 返回任务信息和队列状态

3. 状态更新流程

1. 定时查询运行中任务状态
2. 更新任务缓存时间戳
3. 将完成的任务从运行中缓存移到已完成缓存
4. 处理等待队列，将等待任务移到运行中
5. 定期清理过期的已完成任务
6. 定期保存持久化数据

4. 服务停止流程

1. 调用stop()方法
2. 保存等待队列到持久化文件
3. 停止更新线程
4. 清理资源

API接口

获取队列状态

GET /api/video/queue/status

返回详细的队列状态信息：

{
  "success": true,
  "data": {
    "running_tasks_count": 3,
    "completed_tasks_count": 25,
    "waiting_queue_count": 2,
    "total_cache_count": 30,
    "status_counts": {
      "running": 2,
      "queued": 1,
      "succeeded": 20,
      "failed": 3,
      "cancelled": 2,
      "waiting": 2
    },
    "max_running_tasks": 5,
    "max_completed_cache_size": 100,
    "completed_cache_ttl_hours": 24,
    "running_task_ids": ["task1", "task2", "task3"],
    "completed_task_ids": ["task4", "task5", ...],
    "waiting_task_ids": ["task6", "task7"],
    "persistence_file": "task_queue_persistence.json"
  }
}

查询任务结果

GET /api/video/result/<task_id>

优先从缓存查询，缓存未命中时调用SDK：

1. 检查运行中任务缓存
2. 检查已完成任务缓存
3. 检查等待队列
4. 调用SDK查询（如果缓存都未命中）

持久化文件格式

{
  "waiting_queue": [
    {
      "task_id": "task_123",
      "status": "waiting",
      "content": {
        "image_url": "...",
        "prompt": "..."
      },
      "cache_time": "2024-01-01T12:00:00",
      "created_at": "2024-01-01T12:00:00"
    }
  ],
  "timestamp": "2024-01-01T12:00:00"
}

监控和调试

日志级别

• INFO: 重要操作（启动、停止、任务状态变化）
• DEBUG: 详细操作（任务恢复、缓存更新）
• WARNING: 异常情况（任务不存在、清理失败）
• ERROR: 错误情况（API调用失败、持久化失败）

关键日志示例

启动任务队列管理器
从持久化文件恢复了 3 个等待任务
缓存恢复完成: 2 个运行中任务, 15 个已完成任务
任务状态更新: 1 个任务完成
清理了 5 个已完成任务的缓存
保存了 2 个等待任务到持久化文件

测试

运行测试脚本验证缓存和持久化机制：

python test_cache_persistence.py

测试内容包括：

• 持久化机制测试
• 缓存机制测试
• 清理机制测试

性能优化

1. 缓存策略

• 运行中任务优先级最高，实时更新
• 已完成任务按时间和数量双重限制
• 等待队列持久化保证数据安全

2. 更新频率

• 状态更新：每5秒一次
• 缓存清理：每10次更新一次
• 持久化保存：每20次更新一次或队列变化时

3. 内存管理

• 自动清理过期任务
• 限制缓存大小
• 避免内存泄漏

故障恢复

服务意外重启

1. 等待队列恢复: 从持久化文件完全恢复
2. 运行中任务恢复: 从SDK重新加载状态
3. 已完成任务恢复: 从SDK加载最近的任务

持久化文件损坏

1. 服务正常启动，但等待队列为空
2. 记录错误日志
3. 继续正常服务，新任务正常排队

SDK服务异常

1. 缓存继续提供查询服务
2. 记录API调用失败日志
3. 定时重试恢复连接

最佳实践

1. 定期备份: 备份持久化文件
2. 监控日志: 关注缓存清理和恢复日志
3. 合理配置: 根据业务量调整缓存大小和TTL
4. 性能监控: 监控缓存命中率和队列长度
5. 故障演练: 定期测试服务重启恢复能力