Files
order-notification-automation/docs/storage-preview-open-source-research-2026-10-17.md
T

4.9 KiB
Raw Blame History

存储文件预览开源选型

核实日期:2026-10-17。需求:为当前已经托管的 SMB 服务器增加 PDF、图片、文本及 Word/Excel 文件预览,保持服务器、账号与目录可配置。

已核实的候选

项目 当前状态与许可 与本项目的关系
OpenList 最新稳定版 v4.2.7(2026-10-15),后端 AGPL-3.0 原生 SMB 驱动,完整目录管理及文件预览;作为完整服务接入会增加一个 Go 服务及权限对接
OpenList Frontend v4.2.7,前端独立 MIT 许可 可复用其开源预览组件与依赖,适配当前存储 API,保留现有 SMB 托管与工作台账号
FileBrowser Quantum v2.0.1-stable(2026-10-13),Apache-2.0 完整文件管理服务,提供多种预览;另有用户与存储源管理,需要额外对接
kkFileView v5.0.3(2026-10-08),LICENSE 为 Apache-2.0 适合需要 doc/xls/ppt 等旧格式及高保真办公预览的场景,依赖 Java 与 LibreOffice/OpenOffice
经典 File Browser GitHub API 显示仓库已归档 本次不作为新增集成的首选

版本、归档状态及发行时间来自 GitHub 官方仓库 API;许可同时核对实际 LICENSE。kkFileView 的 GitHub 元数据未识别 SPDX,但仓库 LICENSE 原文为 Apache License 2.0。

已采用的内嵌路线

现有项目已有 SMB 加密托管、逐段目录校验、工作台权限和归档记录;可以将 OpenList Frontend 的预览逻辑适配到现有文件列表,在文件旁加入“预览”。无需让同事再次维护一套 SMB 账号。适配时保留 OpenList Frontend MIT 版权文本,明确上游版本及修改。

已核实 OpenList Frontend v4.2.7 的实际实现:

  • PDF 组件:采用 MIT 许可的 @embedpdf/snippet 2.15.1,提供完整 PDF 阅读界面和 PDFium WASM;支持普通 HTML 页面,不要求整个工作台迁移前端框架。
  • Word 组件:采用 docx-preview 与 JSZip;npm 当前 docx-preview 为 0.4.1、Apache-2.0。对应现代 DOCX,不应据此声称已支持旧 DOC 格式。
  • Excel 组件:采用 MIT 许可的 ExcelJS,实际调用 workbook.xlsx.load。npm ExcelJS 为 4.4.0;不能把组件文件名 xls.tsx 当作旧 XLS 格式已经支持的证据。
  • 图片、文本可在当前页面的受限预览容器内展示;图片缩放可采用 MIT 许可的 PhotoSwipe 5.4.4。

上游 useCDN.ts 的 Office 预览依赖默认从资源 CDN 加载。本项目接入时应将选用的脚本和 WASM 固定版本并在本机提供;读取文件仍经受工作台认证的存储 API。

接入行为

  1. 已启用托管服务器的目录中,支持的文件显示“预览”;继续复用原服务器 ID 和共享根目录限制。
  2. PDF 提供翻页、搜索与缩放;图片可缩放;文本保留换行;DOCX 和 XLSX 使用相应开源组件读取。
  3. 预览使用工作台登录态,SMB 密码不进入浏览器;预览文件不发送至公网 Office 在线服务。
  4. 图片和文档在独立预览区域渲染,文本文字不作为 HTML 执行;未知格式明确显示无法预览并保留原有可用下载能力。
  5. DOC/XLS 等旧格式若为后续实际必需,可通过配置内网 kkFileView 等转换服务扩展,单独完成部署和实际格式验收。

已实现本地组件接入、工作台鉴权传递文件字节、独立 opaque-origin iframe 沙箱与目录内预览/下载入口;服务器地址、共享目录与凭据继续使用现有配置。不部署第二套文件服务。PDF 采用组件官方支持的 direct engine 模式(worker:false),在 opaque-origin 沙箱中本地初始化 PDFium;避免该环境下 Blob Worker 初始化停滞,主工作台 CSP 不变。

限制:单文件 64 MiB;文本预览 2 MiB;Office 包最多 4096 条目和 64 MiB 展开内容,同时校验实际受限解压结果,拒绝伪造展开大小。XLSX 每张表预览前 500 行、50 列,明确显示原始数值及保存的公式结果,不重新计算公式或模拟 Office 全部格式。PDF 界面使用系统字体,不访问公网补充字体/印章库;未内嵌字体的 PDF 可能有字体替代。

验证使用本地临时目录模拟 SMB 文件边界;真实服务器地址、账号及网络条件尚未提供,不能据此宣称完成真实 SMB 联调。完整许可及适配范围见 licenses/storage-preview-NOTICES.md。