# 存储文件预览开源选型 核实日期: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`。