多格式文件预览：方案总览与选型
时间：2026-05 · 调研范围：GitHub 开源项目、官方文档、社区博客与 Discussion
1. 需求定义
1.1 预览 vs 编辑
| 能力 | 本次优先级 | 说明 |
|---|---|---|
| 在线预览 | P0 | 浏览器内查看附件，无需下载 |
| 在线编辑 | P2 | OnlyOffice/Collabora 范畴，资源占用高 |
| 格式转换 | P1 | Office → PDF/图片，由预览服务完成 |
| 与 Git 同步 | P0 | 附件随 Gitea 仓库存储，预览服务只读访问 |
1.2 格式矩阵（按常见度）
| 类别 | 典型后缀 | 个人知识库出现频率 |
|---|---|---|
| 文档 | md, txt, pdf | 极高 |
| Office | docx, xlsx, pptx | 高（调研材料、复盘） |
| 图片 | png, jpg, webp, svg | 高 |
| 代码 | py, js, json, yaml | 中 |
| 音视频 | mp4, mp3 | 中 |
| 压缩包 | zip, rar, 7z | 中 |
| 专业 | dwg, xmind, drawio, epub | 低但「有则要有」 |
2. 方案分层
flowchart TB
subgraph L1["L1 独立预览服务"]
KK[kkFileView]
OO[OnlyOffice DS]
CO[Collabora CODE]
end
subgraph L2["L2 文件管理 + 预览"]
AL[AList]
FB[File Browser]
end
subgraph L3["L3 站点 / 前端嵌入"]
MK[MkDocs 插件]
VO[vue-office 等组件]
end
subgraph L4["L4 现有能力"]
GT[Gitea 原生]
MD[MkDocs 静态页]
end
AL -->|iframe 接入| KK
MK -->|Office 外链| KK
MK -->|PDF 内嵌| MK
3. 方案对比总表
| 方案 | Stars* | 部署难度 | 2C4G 可行 | 格式覆盖 | 预览质量 | 与 Gitea/MkDocs 集成 | 推荐度 |
|---|---|---|---|---|---|---|---|
| kkFileView | ~12k+ | 低（Docker） | ✅ 可行 | ⭐⭐⭐⭐⭐ | 中高（LibreOffice 转换） | REST URL 接入 | ⭐⭐⭐⭐⭐ |
| AList | ~49k+ | 低 | ✅ | ⭐⭐⭐（基础）+ 可扩展 | 中 | 独立子域或 WebDAV | ⭐⭐⭐⭐ |
| AList + kkFileView | — | 中 | ✅ | ⭐⭐⭐⭐⭐ | 中高 | iframe 配置 | ⭐⭐⭐⭐⭐ |
| File Browser | ~34k+ | 极低 | ✅ | ⭐⭐ | 低（基础） | 独立服务 | ⭐⭐⭐ |
| vue-office | ~5.5k+ | 需开发 | ✅（无服务端） | ⭐⭐⭐（Office+PDF） | 中高（前端解析） | 需自写页面 | ⭐⭐⭐ |
| vue-files-preview | ~130 | 需开发 | ✅ | ⭐⭐⭐⭐ | 中 | 需自写页面 | ⭐⭐⭐ |
| OnlyOffice DS | 高 | 高 | ⚠️ 紧张 | ⭐⭐⭐⭐ | 高 | WOPI/iframe | ⭐⭐（预览专用不划算） |
| Collabora CODE | 高 | 中 | ⚠️ ~1.3G 基线内存 | ⭐⭐⭐⭐ | 高 | WOPI + Nextcloud 常见 | ⭐⭐ |
| MkDocs mkdocs-pdf | 小 | 极低 | ✅ | PDF only | 高（浏览器原生） | 构建时嵌入 | ⭐⭐⭐⭐（PDF） |
| Gitea 内置 | — | 无 | ✅ | ⭐ | 低 | 已有 | ⭐⭐（仅 raw/图片） |
* Stars 为 2026-05 公开数据量级，随时间变化。
4. 重点方案详解
4.1 kkFileView（首选：万能预览服务）
- 仓库：https://github.com/kekingcn/kkFileView
- 官网/文档：https://kkview.cn
- 协议：Apache-2.0
- 架构：Spring Boot + LibreOffice/OpenOffice 转码 + 多种前端渲染器
支持格式（摘录）
- Office：doc/docx/xls/xlsx/ppt/pptx、WPS、OpenDocument
- 文档：pdf、ofd、rtf、epub、eml
- 文本：md（渲染）、代码、json、xml
- 媒体：图片、音视频（转码预览）
- 其他：zip 目录树、CAD、3D、xmind、bpmn、drawio、dcm 等
接入方式
- 文件须可被预览服务 HTTP/HTTPS 访问（Gitea raw、Nginx 静态目录、AList 直链均可）
- 无后缀的下载流需加
fullfilename=xxx.docx
资源占用（经验值）
| 项 | 估算 |
|---|---|
| 内存 | 512MB～1.5GB（含 LibreOffice 进程） |
| 磁盘 | 镜像 + 转换缓存，建议 ≥5GB |
| CPU | Office 首次转换时 spike，平时低 |
优点：格式最全、Docker 成熟、国内社区大、AList 有现成集成讨论
缺点：旧版 .doc/.ppt 兼容性一般；LibreOffice 转换大文件慢；需维护转换进程
参考博客
4.2 AList（文件列表 + 可扩展预览）
- 仓库：https://github.com/AlistGo/alist
- 文档：https://alistgo.com/zh/config/preview.html
内置预览
- PDF、Markdown、代码、纯文本、图片、音视频
- Office 默认可走 Microsoft Office Online（
view.officeapps.live.com）→ 依赖外网 + 域名 80/443 + 文件大小限制（Word/PPT <10MB，Excel <5MB）
自建 Office 预览（推荐配置）
在「预览 → iframe 预览」中接入 kkFileView：
{
"doc,docx,xls,xlsx,ppt,pptx": {
"kkFileView": "https://preview.example.com/onlinePreview?url=$b_url"
},
"pdf": {
"kkFileView": "https://preview.example.com/onlinePreview?url=$b_url"
}
}
优点：多存储挂载、WebDAV、UI 完整、49k+ stars
缺点：单靠内置 Office 预览不满足「完全本地」；与知识库「写作流」是平行入口
4.3 vue-office / vue-files-preview（前端组件）
| 项目 | 链接 | 特点 |
|---|---|---|
| vue-office | https://github.com/501351981/vue-office | docx/xlsx/pdf/pptx，~5.5k stars，可 CDN 引入 |
| vue-files-preview | https://github.com/VueFilesPreview/vue-files-preview | 聚合 docx/xlsx/pptx/pdf/md/代码/音视频 |
适用：自建一个「附件预览页」，从 Gitea raw URL 或 API 拉文件到浏览器解析。
局限：
- 无 CAD、压缩包、旧 Office 等
- pptx 完整能力可能依赖作者付费组件
- 大 Excel 性能依赖前端算力
优点：零 LibreOffice、纯静态可部署
缺点：需开发；格式覆盖远小于 kkFileView
4.4 OnlyOffice / Collabora（在线 Office 套件）
| 对比项 | OnlyOffice Document Server | Collabora CODE |
|---|---|---|
| 定位 | 编辑 + 预览 | 编辑 + 预览 |
| 内存基线 | ~500MB（宣传）/ 实际部署常更高 | ~1.3GB+ |
| 部署 | Docker 可用但组件多 | 单容器相对简单 |
| 预览接入 | WOPI、iframe | WOPI |
| 2C4G VPS | 与 Gitea+MkDocs+Memos 同机 偏紧 | 同机 更紧 |
结论：若目标仅是「只读预览」，在 2C4G 上不优先；kkFileView 更合适。
若未来 v2 需要「浏览器内改 docx」，再单独立项评估 OnlyOffice。
参考
4.5 MkDocs 侧能力（与现有只读站结合）
| 插件/能力 | 作用 | 格式 |
|---|---|---|
| mkdocs-pdf | Markdown 内嵌 PDF iframe | |
| mkdocs-embed-file | 嵌入笔记片段 / wikilink | md |
| 自定义 HTML | 链接到 kkFileView 预览页 | 任意（跳转） |
MkDocs 不能原生渲染 docx/xlsx；Office 需外链预览服务或预转换为 PDF。
4.6 File Browser
- 仓库：https://github.com/filebrowser/filebrowser
- 特点：单二进制、Go 编写、上传/管理/基础预览
- 预览：图片/文本/PDF 等基础能力，不如 kkFileView 全
- 状态：维护模式（官方说明以维护为主）
- 结论：适合「轻量网盘」，不适合作为多格式预览核心
5. 选型决策树
需要预览 Office/CAD/压缩包等「冷门格式」？
├─ 是 → kkFileView（Docker）
└─ 否 → 只需 PDF/MD/图片？
├─ 是 → MkDocs 内嵌 + Gitea raw 即可
└─ 否 → 还要网盘式浏览附件？
├─ 是 → AList + kkFileView iframe
└─ 否 → vue-office 自建轻量预览页
6. 针对个人知识库的推荐组合
方案 A：最小可行（推荐先做）
kkFileView 单服务 + Gitea/MkDocs 链接跳转
- 新增子域
preview.teacherhome.top（示例） - Docker 跑 kkFileView，Nginx 反代
- MkDocs 笔记里对附件写：
[预览 PDF](https://preview.../onlinePreview?url=...) - 资源：+512MB～1GB 内存
方案 B：附件库体验完整
方案 A + AList
- AList 挂载
/data/attachments或 Gitea 仓内assets/ - iframe 预览走 kkFileView
- 适合 PDF/Office/压缩包混放的「03-素材库」
方案 C：站点内 PDF 无跳转
MkDocs mkdocs-pdf + 方案 A
- PDF 在 notes 站内 iframe 嵌入
- Office 仍跳 kkFileView
7. 风险与规避
| 风险 | 影响 | 规避 |
|---|---|---|
| LibreOffice 转换超时 | 大 PPT/CAD 失败 | 调大 kkFileView 超时；大文件建议本地转 PDF 再入库 |
| 预览 URL 泄露 | 未授权访问附件 | Nginx 鉴权 / 内网 Tailscale / 签名 URL |
| 微软在线预览依赖外网 | 国内不稳定 | 禁用 Microsoft 预览，只用 kkFileView |
| VPS 内存不足 | OOM | 限制 kkFileView 并发；转换缓存定期清理 |
| 二进制进 Git 仓体积膨胀 | clone 变慢 | 大文件放 LFS 或独立 attachments 目录 + AList |
8. 下一步
- Docker Compose 草案（kkFileView + Nginx）
- Gitea raw URL → 预览 URL 拼接规则
- MkDocs 附件链接模板
- 分阶段验收清单