文件在线预览神器 kkFileView：基于 Spring Boot 的开源解决方案
在企业应用开发中文件在线预览是一个高频需求。无论是 OA 系统中的公文查看、网盘中的文件预览还是在线教育平台的课件展示用户都希望“点一下就能看”而不是先下载再打开。今天给大家推荐一款开源的“万能文件预览”解决方案——kkFileView。 kkFileView 是什么kkFileView 是一款基于Spring Boot构建的文件文档在线预览解决方案。它可以作为独立的预览服务部署通过 HTTP/REST API 与业务系统对接实现松耦合集成。简单来说kkFileView 就是一个开箱即用的文件预览中间件。你只需要把文件 URL 传给它它就能把各种格式的文件转换成可在浏览器中直接查看的页面。在开源社区kkFileView 的热度相当高——Gitee 上收获 17.2K StarGitHub 上也有 9.9K Star。官方将其定位为“开源的万能文件预览系统”。✨ 核心特性kkFileView 之所以被称为“万能”是因为它几乎覆盖了你能想到的所有常见文件类型分类支持的常见格式Office 办公文档doc、docx、xls、xlsx、ppt、pptx、csv、tsv、wps、dps、et 等PDF / OFD / 邮件pdf、ofd、rtf、eml、msg、epub 等纯文本与代码txt、xml、md渲染、java、php、py、js、css 等所有纯文本压缩包zip、rar、7z、tar、gzip 等图片与设计jpg、png、gif、svg、psd、eps 等CAD / 3D 模型dwg、dxf、obj、3ds、stl、fbx、ifc 等音视频mp3、wav、mp4 等其他xmind思维导图、bpmn工作流、drawio 等目前 kkFileView 支持超过20 种文件大类、上百种文件后缀覆盖了日常办公和设计的绝大多数场景。除了格式支持广泛kkFileView 还有以下特点部署简便基于 Spring Boot 开发开箱即用灵活接入支持 URL、FTP 等多种预览源独立部署预览服务与业务系统解耦方便集成开源免费采用 Apache 2.0 协议可自由使用和二次开发 部署方式kkFileView 提供了多种部署方式你可以根据实际环境选择。方式一Linux 物理机/虚拟机部署推荐生产环境这是最经典的部署方式适合对服务器有完全控制权的场景。1. 环境准备Java 1.8LibreOffice 或 OpenOffice用于 Office 文档转换关于 LibreOffice在 Windows 下已内置CentOS 或 Ubuntu 下启动脚本会自动下载安装。你无需手动安装直接运行startup.sh即可。2. 下载与解压从 Gitee 发行版下载最新安装包# Linux/MacOS 使用 .tar.gz 包wgethttps://gitee.com/kekingcn/file-online-preview/releases/download/v4.4.0/kkFileView-4.4.0.tar.gztar-zxvfkkFileView-4.4.0.tar.gz3. 启动服务进入解压后的bin目录执行启动脚本cdkkFileView-4.4.0/bin ./startup.sh首次启动时脚本会自动检测并安装 LibreOffice。如果网络环境良好整个过程会自动完成。4. 验证浏览器访问http://你的服务器IP:8012看到 kkFileView 的演示首页即表示部署成功。5. 解决中文乱码问题可选如果在预览时出现中文乱码通常是字体缺失导致的。可以将中文字体文件上传至/usr/share/fonts目录并赋予权限chmod-R755*.TTF *.ttf *.ttcsource/etc/profile# 重启 kkFileView方式二Docker 部署最便捷如果你熟悉 Docker这是最快上手的方式。拉取并运行镜像# 拉取镜像dockerpull keking/kkfileview:4.1.0# 运行容器映射 8012 端口dockerrun-it-p8012:8012 keking/kkfileview:4.1.0浏览器访问http://127.0.0.1:8012即可看到演示首页。⚠️注意事项官方镜像keking/kkfileview已约两年未更新建议使用社区维护的镜像如wangbowen/kkfileview:5.1.0。方式三源码运行适合二次开发如果你想对 kkFileView 进行定制开发可以从源码运行gitclone gitgithub.com:kekingcn/kkFileView.gitcdkkFileView/server mvn spring-boot:run或在 IDEA 中打开server模块直接运行ServerMain类。 项目集成与使用kkFileView 部署完成后你的业务系统只需通过 HTTP 接口调用即可实现文件预览。预览接口地址http://{kkFileView服务器IP}:8012/onlinePreview?url{base64编码的文件URL}核心参数只有一个url——需要预览文件的访问地址且必须经过 Base64 编码。前端集成示例在前端页面中可以通过 JavaScript 打开预览窗口!-- 引入 Base64 编码库 --scriptsrchttps://cdn.jsdelivr.net/npm/js-base643.6.0/base64.min.js/scriptscript// 要预览的文件地址varfileUrlhttp://your-server.com/files/report.docx;// 拼接预览URL并打开window.open(http://127.0.0.1:8012/onlinePreview?urlencodeURIComponent(Base64.encode(fileUrl)));/script在 iframe 中嵌入预览如果希望将预览页面嵌入到自己的页面中可以使用 iframeiframesrchttp://127.0.0.1:8012/onlinePreview?url你的Base64编码URLwidth100%height600px/iframeSpring Boot 集成示例在 Spring Boot 项目中可以封装一个工具方法ServicepublicclassFilePreviewService{privatestaticfinalStringPREVIEW_URLhttp://kkfileview-server:8012/onlinePreview;publicStringgetPreviewUrl(StringfileUrl){StringencodedBase64.getEncoder().encodeToString(fileUrl.getBytes(StandardCharsets.UTF_8));returnPREVIEW_URL?urlURLEncoder.encode(encoded,StandardCharsets.UTF_8);}}这样业务系统只需调用getPreviewUrl()获取预览地址返回给前端即可。与 MinIO 对象存储结合kkFileView 与 MinIO 等对象存储服务配合使用非常常见。流程如下文件上传到 MinIO 存储桶获取文件的访问 URL将 URL 进行 Base64 编码后传给 kkFileViewkkFileView 拉取文件并渲染预览 常见问题与解决方案1. 启动时报“找不到 office 组件”Linux 系统首次启动时脚本会自动安装 LibreOffice。如果自动安装失败如网络不通可以手动安装# Ubuntu/Debiansudoaptupdatesudoaptinstalllibreoffice# CentOS/RHELsudoyuminstalllibreoffice2. 预览中文出现乱码参考上文“解决中文乱码问题”章节安装中文字体即可。3. Docker 容器无法访问检查端口映射是否正确确保防火墙开放了 8012 端口。4. 官方镜像版本过旧建议使用社区维护的wangbowen/kkfileview:5.1.0镜像。 总结kkFileView 是一个功能全面、部署简便、社区活跃的开源文件预览解决方案。它能够以极低的成本为你的应用快速补齐几乎所有常见文件格式的在线预览能力。适用场景推荐方案快速体验 / 开发测试Docker 一键部署生产环境物理机/虚拟机Linux startup.sh 部署二次开发 / 定制需求源码编译运行无论你是个人开发者、中小企业还是需要快速实现文件预览功能的企业级项目kkFileView 都是一个非常值得考虑的选择。项目地址官网https://kkview.cnGiteehttps://gitee.com/kekingcn/file-online-previewGitHubhttps://github.com/kekingcn/kkFileView发布日期2026-08-08
