kkFileView 文件在线预览实战教程：快速部署与接入-育师

kkFileView 文件在线预览实战教程：快速部署与接入

【免费下载链接】kkFileViewUniversal File Online Preview Project based on Spring-Boot项目地址: https://gitcode.com/GitHub_Trending/kk/kkFileView

kkFileView 是基于 Spring Boot 的开源文件在线预览项目，支持 Office、PDF、CAD、压缩包、图片、音视频等二十余种格式。部署后只需给它一个文件地址，就能得到一个浏览器直接渲染的预览页。本文面向需要把文件在线预览能力嵌入自己系统的开发者和运维同学，带你走完部署、验证、关键配置、接口接入和常见坑。

kkFileView 是什么 📄

它是一个只管"看"不管"编"的预览服务端：接收文件的 http(s) 或 FTP 地址，在服务端完成格式转换，再把浏览器能渲染的网页吐出来。Office 文档走内置的 LibreOffice 转换引擎，压缩包走解压组件，文本类直接进高亮模板，音视频交给 HTML5 播放器，最终页面由 Freemarker 模板渲染。xlsx 虽然有前端解析模式，但定位是查看和基本操作，别把它当在线办公套件。

能力清单如下：

能力	说明	适合谁
Office 文档预览	doc、docx、xls、xlsx、ppt 等，默认转 PDF 呈现	办公文档密集型业务系统
专业格式解析	CAD、3D 模型、Visio、xmind、bpmn、dcm 医疗影像等	设计、工程、影像类场景
压缩包目录树预览	展示 zip、rar、7z 内部结构，点击包内文件即可就地预览	需要快速审阅打包内容的系统
图片与多媒体预览	图片缩放翻转、音视频直接播放	素材库与内容管理平台
纯文本与渲染类	txt、md、xml、json、代码文件，带语法高亮	内部工具与代码相关系统

它是怎么工作：从文件 URL 到浏览器渲染 ⚙️

用大白话说：浏览器从头到尾不碰源文件。请求带着文件 URL 打到 kkFileView 服务端，先过一层信任源校验，再按扩展名分发给对应处理器——Word 交给 LibreOffice 转成 PDF，压缩包解到本地磁盘并生成目录树，文本文件直接套模板高亮。转换产物会写进本地缓存，同一路径第二次访问就不用再转。整个过程有点像打印店：收进原稿，印成客户看得懂的版本再寄出，原件始终留在服务端。

最快速的启动方式：Docker 一键部署 🐳

官方镜像已经打包好 JDK 和转换引擎，不用自己装任何依赖。下面两条命令先拉取镜像，再把宿主机的 8012 端口映射进容器并后台启动：

docker pull keking/kkfileview docker run -d -p 8012:8012 --name kkfileview keking/kkfileview

命令	作用
docker pull keking/kkfileview	拉取官方镜像，内含转换引擎，4.4.0 起提供 ARM64 架构镜像
docker run -d -p 8012:8012	将容器内服务端口 8012 映射到宿主机并后台运行

启动完成后访问 http://127.0.0.1:8012/ 即可看到首页。端口冲突时给 docker run 追加 -e KK_SERVER_PORT=8013 换端口，配置项同样支持 KK_ 前缀的环境变量覆盖。

首次访问与验证：部署后检查清单 ✅

服务起来之后，建议按下面顺序逐项确认功能真的可用：

打开 http://127.0.0.1:8012/，首页应显示文件目录，上传入口默认处于禁用状态。
把一个 PDF 放到任意外部静态服务器，通过预览接口打开，应默认以 PDF 模式渲染且缩略图侧栏展开。
预览一个 Word 文档，5.0.0 默认走 PDF 模式，页面不再显示图片/PDF 切换按钮。
预览一个 zip 压缩包：左侧出现目录树，点击包内文件在右侧内嵌预览，无需先解压。
访问 /actuator/health 端点，确认返回健康检查信息，说明监控接口可用。

关键配置项：最常改的六个参数 🔧

配置文件位于 server/src/main/config/application.properties，几乎所有项都能用 KK_ 前缀的环境变量覆盖，多数项支持不重启动态生效：

参数	默认值	影响什么	何时修改
server.port	8012	服务监听端口	端口被占用或与内网服务冲突
trust.host	default（拒绝全部外部源）	允许预览哪些来源域名的文件	上线后必须显式白名单你的文件域名
office.preview.type	pdf	Office 预览按 PDF 还是逐页图片渲染	需要旧图片体验时设为 image，并关闭 office.preview.switch.disabled
cache.enabled / cache.type	true / jdk	转换结果是否缓存、缓存在内存还是 Redis	集群部署时把 cache.type 切到 redis
kk.key	false	预览接口是否要求密钥参数校验	服务被多方调用时开启，并下发 16 位 aes.key
file.upload.disable	true	首页上传入口是否可用	需要"上传即看"入口时改为 false

上线前的工程建议 🚀

性能：Office、PDF、视频转换默认已是多线程异步执行，想提升并发可调 pdf.max.threads 与 cad.thread，同时给容器分配足够的内存和 CPU。
安全：trust.host 只白名单可信域名，内网网段用 not.trust.host 兜底屏蔽；prohibit 默认禁止 exe、dll、dat，没有明确理由别放宽；对外暴露时建议开启 kk.key 配合 AES 加密，防止别人把你的服务当代理去拉取内网资源。
维护：cache.clean.cron 默认每天凌晨 3 点清理缓存文件，注意 file.dir 目录的磁盘水位；源码方式部署时注意 5.0.0 起强制要求 JDK 21 及以上。
可观测：Actuator 默认开放 health、info、metrics 端点，可直接接进你的监控告警体系。

接入你自己的系统 🧩

kkFileView 以 REST 接口对外提供预览能力：GET /onlinePreview?url=<文件地址>，其中 url 参数要求先 URL 编码、再 Base64 编码，响应是可直接打开或嵌进 iframe 的预览页。前端可以用十几行代码组装预览地址：

function buildPreviewUrl(fileUrl, host) { const encoded = btoa(encodeURIComponent(fileUrl)); return host + '/onlinePreview?url=' + encoded; }

想先在命令行验证接口是否通，可以直接请求预览地址：

curl "http://127.0.0.1:8012/onlinePreview?url=<Base64编码值>"

如果要新增文件格式或改造现有行为，切入口在 server/src/main/java/cn/keking/service/ 目录：实现 FilePreview 接口并交由 FilePreviewFactory 分发即可；页面版式则集中在 server/src/main/resources/web/ 下的 Freemarker 模板里。

容易踩的坑：四个实录 🕳️

现象：预览外部文件 URL 时页面直接提示"非法路径,不允许访问"。原因：trust.host 默认值为 default，等于拒绝所有外部文件源。处理办法：把 trust.host 改成你的文件域名白名单，同时在 not.trust.host 屏蔽 192.168.、10.等内网网段。
现象：升级到 5.0.0 后，Word 预览从逐页图片变成了 PDF，模式切换按钮也消失了。原因：新版本默认策略改为 office.preview.type=pdf 且隐藏切换开关。处理办法：若仍需要图片优先体验，显式设置 office.preview.type=image 和 office.preview.switch.disabled=false。
现象：预览页报"Base64解码失败，请检查你的 url 是否采用 Base64 + urlEncode 双重编码了"。原因：url 参数传了明文地址，没有做双重编码。处理办法：按接入章节的 buildPreviewUrl 写法，先 URL 编码再 Base64 编码。
现象：Word 文档里的中文在预览页显示为方框或乱码。原因：容器或服务器内没有安装中文字体，LibreOffice 转换时找不到对应字形。处理办法：把常用中文字体放入基础镜像提供的 fonts 字体目录后重启容器。