企业文件在线预览服务：技术架构与选型实践——BaseMetas FileView设计复盘

一、为什么需要单独建设预览服务？

1.1 问题本质

文件预览看似简单：图片、PDF、纯文本浏览器可直接打开；Word、Excel、CAD、OFD 则不能。

在企业业务系统中，“不能直接打开”带来的连锁反应远超预期。最直接的是终端依赖——每个用户都需要安装 Office、CAD Reader 等客户端，IT 运维成本居高不下。更棘手的是安全失控：文件一旦下载到本地，复制、打印、截屏便脱离管控，审计形同虚设。此外，OA 系统往往涉及 20 多种文件格式，逐个适配成本极高；而每个业务系统各自实现一套预览逻辑，更是造成了人力与维护的重复浪费。 1.2 服务化的核心价值

预览服务的本质不是“找一个能打开文件的工具”，而是将“文件查看”能力从业务系统中解耦，变成可独立演进、水平扩展、安全管控的平台服务。

一套预览服务可以同时支撑 OA、BPM、合同、档案等多个业务系统，实现能力复用。近 300 种格式由平台统一覆盖，业务系统零成本扩展。水印、防下载、防复制等安全策略集中执行，不再依赖各业务系统的独立实现。更重要的是，转换引擎升级、性能优化等底层变化对上层业务系统完全透明。

二、核心架构：API + Worker 分离

2.1 架构图

2.2 为什么采用 API + Worker 分离？

三、关键技术决策：哪些文件需要转换？

3.1 文件分类处理策略

3.2 转换路径选择

3.3 缓存与复用策略

• 缓存键：内容哈希（SHA-256），相同文件 + 相同参数 → 复用结果
• 缓存分级：Redis（元数据）+ 对象存储（转换结果）
• 缓存有效期：可配置，默认永久（源文件变更时主动失效）

性能数据：缓存命中时 API 响应 < 10ms，QPS ≥ 5000+；缓存未命中时 API 仍保持 < 50ms 返回。

四、大规模业务接入

4.1 多租户隔离

4.2 水平扩展能力

4.3 降级与熔断

五、安全架构

5.1 分层安全模型

5.2 权限控制模型

业务系统通过 previewOptions 透传控制策略，预览服务只执行策略，不定义策略：

{
  "permissions": {
    "download": false,
    "print": true,
    "copy": false,
    "watermark": {
      "text": "张三 2026-06-09",
      "opacity": 0.3
    }
  }
}

5.3 预览 URL 安全设计

• 签名 + 时效（默认 3600s 过期）
• 支持 IP 绑定（预览 IP 需与获取 URL 时的请求 IP 一致）

六、性能与运维

6.1 性能指标（8C16G 单 Worker 节点，内部压测）

6.2 可观测性

6.3 常见运维问题与应对

6.4 部署形态

推荐：Kubernetes 部署，利用 HPA 自动扩缩 API 和 Worker。

七、技术选型总结

八、总结

回顾本文讨论的核心技术决策：

为什么单独建设预览服务？ 因为开源工具解决的是“能不能打开”的问题，而企业场景需要解决的是“规模化、可运维、可管控”的问题——多租户隔离、水平扩展、安全审计、可观测性，这些都是工具级方案无法直接提供的。

为什么采用 API + Worker 架构？ 同步 API 保障响应速度，异步 Worker 处理重量级转换任务。职责分离后，两者可以独立扩展、独立演进，互不干扰。

为什么有些文件直接预览、有些需要转换？ 浏览器原生支持的格式直接返回，减少不必要的转换开销。需要转换的格式根据场景选择 PDF、图片、SVG 或 HTML 等不同目标，在时延、质量、功能之间做取舍。

如何支撑大规模接入？ 通过无状态 API、MQ 削峰填谷、水平扩展、多租户隔离和降级熔断机制，保障系统在高压下的稳定运行。

如何保证安全？ 分层安全模型覆盖网络、API、文件、转换、数据五个层级，每层独立防护。权限策略由业务系统定义，预览服务只负责执行。

如何运维？ 可观测性三支柱（指标、日志、追踪）配合容器化部署和自动化扩缩容，常见问题有成熟的应对方案。

核心价值：不是重新发明“转换轮子”，而是把转换能力服务化、标准化、可治理，让上层业务系统只关心“要预览哪个文件”，不关心“怎么预览这个文件”。

本文基于 BaseMetas IDP 文件预览服务真实架构设计整理，性能数据来自内部压测环境，实际数据可能因部署规模、硬件配置、文件类型分布有所差异。

相关资料

商业版

BaseMetas 预览产品商业版介绍

BaseMetas 预览体验（企业网盘入口）

社区版

• BaseMetas Fileview 产品介绍：https://fileview.basemetas.cn/docs/product/summary
• BaseMetas Fileview 在线体验：https://file.basemetas.cn
• BaseMetas Fileview GitHub：https://github.com/basemetas/fileview

​