BaseMetas 文件预览

Appearance

长轮询机制（Preview Polling） ​

总体说明 ​

针对文件下载、格式转换等异步耗时场景，系统在预览模块中内置了一套可配置、可限流、可自适应的长轮询机制。

  • 客户端通过统一的轮询接口查询文件状态
  • 服务端在超时时间内持续检查缓存与任务状态
  • 一旦结果就绪立即返回，避免频繁短轮询带来的资源浪费

长轮询行为由 fileview.preview.polling 统一控制，并与缓存、网络下载、密码安全等机制协同工作。

一、长轮询核心配置：fileview.preview.polling ​

1. 基础参数（超时与频率边界） ​

yaml
fileview:
  preview:
    polling:
      default-timeout: 20      # 默认超时时间（秒）
      max-timeout: 300         # 最大超时时间（秒）
      default-interval: 1000   # 默认检查间隔（毫秒）
      min-interval: 500        # 最小检查间隔（毫秒）
      max-interval: 5000       # 最大检查间隔（毫秒）

2. 设计要点 ​

默认值兜底

  • 客户端未指定参数时，使用系统默认值：
    • default-timeout = 20s
    • default-interval = 1000ms

强制边界约束

即使客户端传入极端参数，系统也会进行裁剪：

  • 超时时间：5s ≤ timeout ≤ 300s
  • 检查间隔：500ms ≤ interval ≤ 5000ms

产品价值

  • 防止恶意或误用请求长时间占用线程
  • 防止过高频率轮询导致 Redis 与 CPU 压力激增
  • 保证长轮询在可控范围内运行

二、智能轮询策略（自适应间隔） ​

1. 配置说明 ​

yaml
fileview:
  preview:
    polling:
      smart-strategy:
        phase1-attempts: 10
        phase1-interval: 1000
        phase2-attempts: 20
        phase2-interval: 2000
        phase3-interval: 5000

2. 三阶段轮询策略 ​

阶段尝试次数范围间隔设计目的
Phase 11 ~ 10 次1s快速响应（大多数文件）
Phase 211 ~ 30 次2s适度放缓（复杂文件）
Phase 331+ 次5s明显降压（大文件 / 慢转换）

实际效果（以 timeout = 60s 为例）：

  • 前 10 秒：高频检查，尽快返回结果
  • 10 ~ 50 秒：降低频率，平衡响应与压力
  • 50 秒后：显著降频，避免持续高压访问缓存

产品价值：

  • 大幅减少无意义的高频 Redis 查询
  • 在不牺牲用户体验的前提下，提升系统整体吞吐能力
  • 对不同文件规模具备“自适应行为”

三、与缓存机制的协同（fileview.preview.cache） ​

1. 缓存配置 ​

yaml
fileview:
  preview:
    cache:
      enabled: true
      conversion:
        success-ttl: 86400   # 转换成功缓存 24 小时
        failed-ttl: 60       # 转换失败缓存 60 秒
      direct-preview-ttl: 86400

2. 长轮询与缓存的关系 ​

  • 长轮询每次循环都会查询 Redis 缓存
  • 一旦命中以下终态之一，立即返回并结束轮询：
    • SUCCESS
    • FAILED
    • NOT_SUPPORTED
    • PASSWORD_REQUIRED

设计要点：

  • ✅ 成功结果缓存 24 小时：
    • 同一文件重复预览可直接命中缓存，无需再次转换
  • ✅ 失败结果仅缓存 60 秒：
    • 避免错误状态被长期放大或“永久失败”

四、与网络文件下载的协同 ​

1. 下载配置 ​

yaml
fileview:
  network:
    download:
      connect-timeout: 3000
      read-timeout: 60000
      max-retry: 3

2. 在长轮询中的表现 ​

对于网络文件预览（URL 文件）：

  1. 预览服务先异步触发下载任务
  2. 长轮询阶段优先检查下载任务状态：
    • DOWNLOADING → 继续等待
    • DOWNLOADED → 进入转换状态检查
    • FAILED → 立即返回失败结果

下载失败不会继续无意义地等待转换。

产品价值：

  • 下载失败能被快速感知并返回
  • 避免“下载失败但仍长时间轮询转换状态”的无效等待

五、与加密文件 / 密码安全的协同 ​

1. 密码安全配置 ​

yaml
fileview:
  preview:
    security:
      password:
        ttlSeconds: 1800

2. 长轮询中的行为 ​

对于加密文件（加密 Office / 压缩包）：

  • 若未解锁或解锁状态已过期
  • 长轮询会直接返回 PASSWORD_REQUIRED
  • 不会返回任何预览 URL

安全设计要点：

  • 密码解锁状态存储在 Redis 中，TTL 为 30 分钟
  • 密码本身加密存储
  • 防止通过轮询接口绕过密码校验获取预览链接

六、典型场景说明 ​

场景 1：本地文件快速转换 ​

  • 默认超时 20s
  • 前期每秒检查一次
  • 3 秒内完成转换，立即返回结果
  • 转换结果缓存 24 小时

场景 2：网络文件 + 慢转换 ​

  • 客户端指定 timeout = 60s
  • 下载阶段 + 转换阶段统一由长轮询感知
  • 前期密集、后期放缓
  • 约 50 秒后返回最终结果

场景 3：加密文件未解锁 ​

  • 长轮询检测到文件已加密
  • 校验解锁状态失败
  • 立即返回 PASSWORD_REQUIRED，终止轮询

七、小结 ​

  • 长轮询机制由统一配置控制，具备默认兜底 + 边界保护
  • 通过三阶段智能轮询策略，实现前快后慢、自动降压
  • 与缓存、下载、密码安全机制深度协同
  • 在保证用户体验的同时，有效控制系统资源消耗

适用场景：

  • 大文件
  • 网络文件
  • 转换耗时不可预期的复杂场景

Copyright © 2025 BaseMetas