架构介绍

一、 系统架构概览

1. 整体架构

系统由两个后端服务组成：文件预览服务 和 文件转换服务，对外只暴露预览服务的 HTTP 接口：

• 文件预览服务：
  • 对外提供 /preview/api/** 等 HTTP 接口
  • 负责预览编排、文件下载、权限校验、结果缓存、长轮询响应等
  • 当检测到需要转换的格式时，向消息队列发送转换事件
• 文件转换服务：
  • 不对外开放，仅作为内部服务使用
  • 通过订阅 MQ 事件被动触发
  • 负责实际的文件格式转换，并将结果写回存储与缓存

两者通过 消息队列（MQ）+ Redis + 文件存储 实现预览与转换的异步解耦和高可用能力。

2. 分层结构

接入层 / 前端 UI

• 浏览器或业务系统前端
• 通过 HTTP 调用预览服务统一接口发起预览请求
• 支持本地文件预览、网络文件预览以及长轮询查询等交互

API 层

• 预览接口：
  • 提供本地文件预览接口
  • 提供网络文件预览接口
  • 提供长轮询查询接口，用于查询预览结果或任务状态
• 转换接口：
  • 仅在服务之间调用，不对外开放

服务层

• 预览服务：
  • 负责整个预览流程的编排
  • 处理网络文件下载与格式校验
  • 根据文件类型判断是否需要转换
  • 向 MQ 发送下载任务、转换任务等事件
  • 结合 Redis 实现预览结果缓存与长轮询响应
• 转换服务：
  • 由 MQ 消费者、文件转换上下文接口 以及各类文件转换策略组成
  • 消费下载/转换事件，执行具体的格式转换逻辑
  • 将转换后的结果写入文件存储并更新 Redis 状态

数据与中间件层

• RocketMQ：
  • 作为事件总线承载预览相关事件
  • 负责下载任务和转换任务的异步投递
  • 实现预览服务与转换服务之间的解耦
• Redis：
  • 统一的状态与缓存中心
  • 存储下载任务、转换任务的状态信息
  • 缓存预览结果，支撑长轮询查询和高并发访问
• 文件存储：
  • 通过存储配置管理本地或远程存储路径
  • 存放源文件、下载文件以及转换后的结果文件

运行环境与支撑层

• 基于 Spring Boot 运行于容器环境
• 通过容器挂载提供：字体目录、文件存储路径、日志输出目录等
• 统一配置时区、字符编码和无头图形环境，保障转换与渲染行为稳定
• 使用 Logback 输出日志至控制台与文件，便于跟踪预览流程、下载阶段与转换过程中的关键行为与性能指标

二、 本地文件预览时序

时序说明（本地文件）

本地文件预览时序大致包括以下步骤：

1. 前端通过接口上传或指定本地文件进行预览
2. 预览服务校验参数、解析文件类型，决定是否需要转换
3. 如需转换：
   • 写入任务状态到 Redis
   • 向 RocketMQ 发送转换相关事件
4. 转换服务消费 MQ 事件，执行格式转换，将结果写入文件存储并更新 Redis 状态
5. 预览服务通过轮询或长轮询方式查询任务状态
6. 前端在任务完成后，加载转换或预览结果并展示给用户

三、 网络文件预览时序

时序说明（网络文件）

网络文件预览在本地预览基础上，增加了“网络下载”环节，大致步骤为：

1. 前端传入网络文件 URL，调用网络预览接口
2. 预览服务发起网络下载任务，将下载任务写入 Redis，并向 MQ 投递下载事件
3. 下载任务消费者拉取文件并存入文件存储，更新任务状态
4. 预览服务在检测到下载完成后，继续判断是否需要格式转换
5. 如需转换，则继续通过 MQ 触发转换服务执行转换，并更新 Redis 状态
6. 前端通过长轮询或轮询方式查询任务状态，在预览结果就绪后加载并展示