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

43 lines
4.9 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 存储文件预览开源选型
核实日期:2026-10-17。需求:为当前已经托管的 SMB 服务器增加 PDF、图片、文本及 Word/Excel 文件预览,保持服务器、账号与目录可配置。
## 已核实的候选
| 项目 | 当前状态与许可 | 与本项目的关系 |
|---|---|---|
| [OpenList](https://github.com/OpenListTeam/OpenList) | 最新稳定版 v4.2.7(2026-10-15),后端 AGPL-3.0 | 原生 SMB 驱动,完整目录管理及文件预览;作为完整服务接入会增加一个 Go 服务及权限对接 |
| [OpenList Frontend](https://github.com/OpenListTeam/OpenList-Frontend/tree/v4.2.7) | v4.2.7,前端独立 MIT 许可 | 可复用其开源预览组件与依赖,适配当前存储 API,保留现有 SMB 托管与工作台账号 |
| [FileBrowser Quantum](https://github.com/gtsteffaniak/filebrowser) | v2.0.1-stable(2026-10-13),Apache-2.0 | 完整文件管理服务,提供多种预览;另有用户与存储源管理,需要额外对接 |
| [kkFileView](https://github.com/kekingcn/kkFileView) | v5.0.3(2026-10-08),LICENSE 为 Apache-2.0 | 适合需要 doc/xls/ppt 等旧格式及高保真办公预览的场景,依赖 Java 与 LibreOffice/OpenOffice |
| [经典 File Browser](https://github.com/filebrowser/filebrowser) | 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 组件](https://github.com/OpenListTeam/OpenList-Frontend/blob/v4.2.7/src/pages/home/previews/pdf.tsx):采用 MIT 许可的 `@embedpdf/snippet` 2.15.1,提供完整 PDF 阅读界面和 PDFium WASM;支持普通 HTML 页面,不要求整个工作台迁移前端框架。
- [Word 组件](https://github.com/OpenListTeam/OpenList-Frontend/blob/v4.2.7/src/pages/home/previews/doc.tsx):采用 `docx-preview` 与 JSZip;npm 当前 docx-preview 为 0.4.1、Apache-2.0。对应现代 DOCX,不应据此声称已支持旧 DOC 格式。
- [Excel 组件](https://github.com/OpenListTeam/OpenList-Frontend/blob/v4.2.7/src/pages/home/previews/xls.tsx):采用 MIT 许可的 ExcelJS,实际调用 `workbook.xlsx.load`。npm ExcelJS 为 4.4.0;不能把组件文件名 xls.tsx 当作旧 XLS 格式已经支持的证据。
- 图片、文本可在当前页面的受限预览容器内展示;图片缩放可采用 MIT 许可的 PhotoSwipe 5.4.4。
上游 [useCDN.ts](https://github.com/OpenListTeam/OpenList-Frontend/blob/v4.2.7/src/hooks/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`。