docs/hf_optimization_plan.md

HF Space 部署优化方案

根据HF Space部署约束，本方案旨在对现有系统进行重构优化，以提高性能、降低资源消耗并增强可维护性。

1. 内存缓存设计

• 目标：将后端 FastAPICache 从 RedisBackend 切换到基于内存的LRU缓存，并为现有内存缓存（如 backend/data/data_service_memory.py 中的 data_cache）设置上限和自动清理机制，以更好地支持新华财经数据的高效处理。
• 具体步骤：
  • 评估现有缓存使用情况：
    • 检查 backend/app/main.py 中 FastAPICache 的使用范围，确定哪些API端点使用了缓存。
    • 检查 backend/data/data_service_memory.py 中 data_cache 的使用情况，了解其存储的数据类型和访问模式。
  • 引入LRU缓存库：
    • 对于Python后端，考虑使用 functools.lru_cache 或第三方库（如 cachetools）来实现LRU缓存。
  • 修改 FastAPICache 配置：
    • 在 backend/app/main.py 中，将 FastAPICache.init 的后端从 RedisBackend 更改为内存LRU后端。
    • 配置LRU缓存的最大容量，防止内存溢出。
  • 增强现有内存缓存：
    • 在 backend/data/data_service_memory.py 中，如果 data_cache 不是LRU实现，则将其替换为LRU缓存，并设置缓存上限。
    • 实现自动清理机制，例如基于时间或大小的清理策略。

2. 轻量监控方案

• 目标：在不引入额外监控服务的情况下，提供基本的系统健康和性能洞察。
• 具体步骤：
  • 内置健康检查API端点：
    • 在 backend/app/api/v1/api.py 或新建一个 health.py 文件中，添加一个 /health 或 /status API端点。该端点应返回简单的状态信息（如 {"status": "ok"}），并可选择包含内存使用情况、CPU负载等基本指标。
    • 集成 backend/app/services/data_monitor.py 模块，将其提供的 /market-data/status API纳入整体健康检查和状态报告。
  • 实时日志流分析：
    • 确保所有关键操作和错误都通过标准日志库（如Python的 logging 模块）输出到控制台。
    • HF Space会自动捕获这些日志，用户可以通过HF Space界面查看实时日志流。
    • 在日志中包含关键信息，如请求处理时间、缓存命中率等，以便进行简单的日志分析。
  • 简易状态仪表盘（基于内存数据）：
    • 在后端维护一些内存中的统计数据，例如：
      • API请求计数
      • 缓存命中/未命中次数
      • 内存使用峰值
    • 通过一个新的API端点（例如 /metrics）暴露这些内存中的统计数据，供用户或简单的脚本查询。
    • 前端可以开发一个简单的页面来展示这些数据，或者用户可以直接通过 curl 命令获取。

3. 代理池适配

• 目标：优化代理池的使用，使其适应HF Space的资源限制，并增加内存使用监控和动态调整策略。
• 具体步骤：
  • 精简代理池容量：
    • 在 backend/app/core/config.py 中配置 PROXY_POOL，并确保其容量限制在10个以内，以适应HF Space的资源限制。
  • 增加内存使用监控：
    • 在 backend/app/utils/proxy_manager.py 中集成内存使用情况的检查。当代理池的内存使用量接近预设阈值时，触发警告日志。
  • 动态调整策略：
    • 在 backend/app/utils/proxy_manager.py 中实现动态调整机制，例如：
      • 如果代理使用失败率高，则尝试更换代理。
      • 如果系统内存紧张，则暂时减少活跃代理的数量。
      • 利用 tenacity 库的重试机制，增强代理的健壮性。

4. HF构建流程

• 目标：优化Docker镜像大小和HF Space的健康检查配置，并引入内存使用预警机制。
• 具体步骤：
  • 优化Docker镜像大小：
    • 检查 Dockerfile，采用多阶段构建（Multi-stage build）来减小最终镜像大小，并确保正确安装所有必要的依赖（包括新华财经数据集成所需的 httpx, fake_useragent, tenacity, feedparser 等）。
    • 移除不必要的构建依赖和运行时依赖。
    • 使用更小的基础镜像（如 alpine 版本）。
    • 清理缓存和临时文件。
  • 配置HF Space健康检查：
    • 在 Dockerfile 或 HF Space 的配置中，指定上一步创建的健康检查API端点（例如 /health）作为HF Space的健康检查路径。
    • 配置健康检查的频率和超时时间。
  • 内存使用预警机制：
    • 在应用程序启动时，记录初始内存使用量。
    • 定期（例如每隔几分钟）检查当前内存使用量，并与预设的阈值进行比较。
    • 如果内存使用量超过阈值，则通过日志输出警告信息，提示可能存在内存泄漏或资源使用过高。
    • 考虑使用Python的 resource 模块或 psutil 库来获取内存信息。

方案概览图

graph TD
    A[当前系统] --> B{HF Space 部署约束}

    subgraph 内存缓存设计
        B --> C[LRU 内存缓存替代 Redis]
        C --> D[设置缓存上限]
        C --> E[实现自动清理机制]
    end

    subgraph 轻量监控方案
        B --> F[内置健康检查 API]
        F --> G[实时日志流分析]
        F --> H[简易状态仪表盘]
    end

    subgraph 代理池适配
        B --> I[精简代理池容量]
        I --> J[增加内存使用监控]
        I --> K[动态调整策略]
    end

    subgraph HF 构建流程
        B --> L[优化 Docker 镜像大小]
        L --> M[配置 HF Space 健康检查]
        L --> N[内存使用预警机制]
    end

    C & D & E & F & G & H & I & J & K & L & M & N --> O[HF 特化优化方案]