kkFileView 部署指南：tar.gz 包搭建在线文档预览服务与避坑

简介：kkFileView是一款成熟且开源的文档在线预览解决方案，可部署在服务器上为业务系统提供统一的文档预览入口。这份4.4.0版本的Linux部署包面向需要快速搭建预览环境的开发者与运维人员，解压后即可使用，内容包含可执行jar包、启动/停止/安装/日志查看脚本、properties配置、ftl模板及README说明，压缩包约285.23MB，共8个文件。部署依赖JDK1.8，包内脚本可自动下载所需组件，并支持便捷启停与配置调整，帮助用户省去源码编译和手动部署的繁琐流程。针对中文显示异常的现象，官方FAQ给出了字体安装指引，可有效改善Office、PDF等文档的预览效果。该资源已有2671人学习下载，适合需要评估免费方案与付费产品差距或快速自建在线预览能力的团队参考，是一套开箱即用的文档预览基础包。部署后即可获得一个可独立运行的预览服务，适用于知识库、OA、网盘等场景。

1. 一个 tar.gz 包解决什么：kkFileView-4.4.0-SNAPSHOT 到底能干什么

拿到 kkFileView-4.4.0-SNAPSHOT.tar.gz，先别急着解压，它是目前开源社区里用得比较多的一套在线文档预览中间件。它解决的是业务系统里再常见不过的诉求：用户上传的 Word、Excel、PPT、PDF、图片，甚至音视频，能不能像打开网页一样直接在浏览器里看，不要求用户本机装 Office，也不逼用户先把文件下载到本地再打开。kkFileView 本身是一个 Spring Boot 服务，这个 tar.gz 包是它的完整部署包，工具链里还包括本机上的一个外部文档转换服务。它的典型坑不在 kkFileView 自身，而在外围：转换服务装没装、字体缺不缺、缓存磁盘够不够。下面就从拆包开始，把它怎么跑起来、怎么接进现有系统、哪个环节最容易翻车，一条线说完。

2. 部署前先搞懂：kkFileView 的转换链路与三个前置检查

2.1 先搞懂 kkFileView 的转换链路：谁在处理 Office 转 PDF

kkFileView 的设计思路是：预览不直接读原文件，而是先把原文件转换成一个浏览器能稳定渲染的中间格式，再交给前端渲染。Office 三件套默认转成 PDF，PDF 再交给浏览器原生 PDF 插件或内置的 pdf.js 展示；图片直接输出；音视频走 HTML5 的 video/audio 标签；txt、markdown 这类文本文件走代码高亮。所以它对外看起来是一个 HTTP 预览服务，对内其实藏着一条完整的转换链。

这条链的起点是一个外部程序：LibreOffice 或 OpenOffice。kkFileView 通过 jodconverter 这类桥接库去调用它的 headless（无界面）模式，完成 Office 文档到 PDF 的转换。于是你能观察到的现象是：请求进来后，服务器上先冒出一个 soffice 进程，等 PDF 生成完，预览页才出来。这也解释了为什么很多人的部署失败都发生在同一个环节——LibreOffice 没装、路径给错、或者系统缺中文字体导致转出来的 PDF 是乱码。kkFileView 本身只是调度者，真正干重活的是外部转换程序。

要特别提醒：kkFileView 启动时不会自动帮你装 LibreOffice，它只按配置找到 office.home 指向的路径，找不到就只在日志里记一行错误，页面却一直转圈。所以正确的部署顺序是先把转换程序装好，并且手动验证一次转换命令，之后再去启动 kkFileView 主程序。跳过这一步，后面排查问题会非常痛苦。

2.2 版本选型：4.4.0-SNAPSHOT 与 tar.gz 包适合什么环境

4.4.0-SNAPSHOT 是快照版本，对应的是修复了一批小问题、功能相对齐全的中间版本。SNAPSHOT 的意思是这包还会持续演进，并不是最终发布版。想要快速拿到新功能的团队，它会比同期的 release 更值得试；但如果是给核心业务链路做底座，我建议先在测试环境完整跑一周再上生产，这个选择本身不复杂，别被版本号里的 SNAPSHOT 吓住。

为什么优先考虑 tar.gz 而不是其它打包格式？因为 tar.gz 是免安装的编译产物，解压即用，不需要处理系统包管理器里的依赖关系，也不会有 rpm 安装时把旧版本覆盖掉的风险。部署时把它放在独立目录，启停都靠自带脚本，升级时直接换目录，回滚也快。常见部署环境是 x86_64 的 Linux 服务器，JDK 要求 1.8 及以上。这个 tar.gz 包里的脚本按 Linux 习惯写好，Windows 上跑要另改配置，而且 Linux 上的转换进程更干净，没有注册表和系统服务的干扰。

内存方面，kkFileView 的 JVM 进程给 512MB 到 1GB 就够用，LibreOffice 每次转换会再起一个进程，吃几十到一两百 MB。单机 2GB 内存跑一个小团队的内网预览服务完全没问题。如果公司有条件，把 kkFileView 放一台机器，文件存储放另一台，中间走对象存储的 HTTP 地址，这也是常见的解耦方式。反过来只有 1GB 的小机器也能跑，只是并发预览超过三五个会明显变慢，这一点心里有数就行。

2.3 部署前三个前置检查：JDK、转换程序、端口与磁盘

动手解压之前，我习惯先跑三个检查命令，避免后面问题混在一起难以排查。第一个查 Java，第二个查文档转换程序，第三个查端口和磁盘空间。

# 1. 检查 JDK 版本，kkFileView 4.x 依赖 1.8+ java -version # 2. 检查 LibreOffice 是否已安装，未安装时此命令不会输出版本信息 soffice --version # 3. 检查 8012 端口是否被占用，以及 /opt 分区剩余空间 ss -lntp | grep 8012 df -h /opt

java -version 看到 1.8 及以上就通过；soffice --version 如果提示 command not found，下面必须先装 LibreOffice；8012 是 kkFileView 默认预览端口，如果被占用，后面需要改 server.port 或者停掉占用进程。磁盘空间建议至少留 20GB，因为转换后的缓存文件会堆积在 file.dir 目录下，不清理就会慢慢吃光系统盘，这是很多生产事故的起点。

提示：三个检查命令只要有一个不通过，就不要继续解压启动，先把前置环境补齐，后面会省很多事。

3. 用 tar.gz 包在 Linux 上跑通第一个预览：从解压到出画面

3.1 解压与目录结构：先看清压缩包里有什么

拿到 tar.gz 包，我一般会在 /opt 下新建一个目录再解压，避免文件散落在 root 家目录里，后续维护时路径也清晰。

mkdir -p /opt/kkfileview tar -zxvf kkFileView-4.4.0-SNAPSHOT.tar.gz -C /opt/kkfileview cd /opt/kkfileview ls -l

tar 的 -C 参数指定解压目标目录，-z 表示 gzip 压缩，-x 解包，-v 打印解压过程。解压后你会看到典型的 Spring Boot 部署结构：bin 目录是启停脚本，config 目录里有 application.properties，lib 目录是一堆依赖 jar。有些版本会把主程序打成独立 jar 放在根目录或 lib 下，这都不影响使用，关键是后续改配置只改 config/application.properties 这一个文件。

bin 目录里通常会看到 startup.sh 和 shutdown.sh，分别对应启动和停止。如果执行时提示没有权限，先给脚本加执行权限：

chmod +x bin/*.sh

不要直接删除 config 目录里的任何文件，kkFileView 的端口、缓存路径、水印、转换组件路径全部由这个文件控制。改完配置要重启进程才会生效，这一点和大多数配置型中间件一样。如果你是从旧版本升级过来的，升级前记得备份 config 目录和 file.dir 目录，这两个目录一个装了配置，一个装了缓存，都是不能丢的。

3.2 装好 LibreOffice 并验证转换命令

这是整篇里我最强调的一步。常见做法是直接用系统包管理器装 LibreOffice 的无界面版本，CentOS 系命令类似这样：

yum install -y libreoffice-headless libreoffice-writer libreoffice-calc libreoffice-impress

Ubuntu/Debian 系则换成 apt install libreoffice-core libreoffice-writer libreoffice-calc libreoffice-impress。这里的 writer、calc、impress 分别对应 Word、Excel、PPT 的转换支持，headless 或 core 是精简运行环境，不装桌面那一套。如果公司内网有软件源镜像，就配置成内网源，几十 GB 的安装量走外网会很痛苦。

装完立刻验证，不要等 kkFileView 起来后再试。验证命令很简单：

cd /tmp echo "hello kkfileview" > hello.txt soffice --headless --convert-to pdf --outdir /tmp /tmp/hello.txt ls -l /tmp/hello.pdf

能看到生成的 hello.pdf，说明转换程序本身可用。--headless 表示无界面模式，--convert-to pdf 指定输出格式，--outdir 指定输出目录，最后的 /tmp/hello.txt 是输入文件。如果这一步报缺库、缺字体，先解决掉再往下走。还有一个细节：LibreOffice 在系统缺少中文字体时不会报错，只会悄悄用默认字体替代，转出来的 PDF 中文全变方块。因此装完 LibreOffice 后，我还要顺手装一组中文字体包，没有中文字体的转换环境后面一定翻车。

这一步是整个部署中最容易“当时不报错、事后预览乱码”的地方，务必手动转换一次再启动 kkFileView。

3.3 启动 kkFileView：startup 脚本与日志观察

解压完成、LibreOffice 验证通过后，进 bin 目录启动主程序：

cd /opt/kkfileview/bin ./startup.sh

启动后不要急着访问页面，先看日志。日志一般在 log 目录下，名称类似 kkFileView.log，用 tail 盯着看几秒：

tail -f /opt/kkfileview/log/kkFileView.log

看到 Tomcat started on port(s): 8012 或者 Started 这类关键字，进程才算真正起来。如果报端口占用，改配置文件里的 server.port 再启；如果报内存不足，调启动脚本里的 JVM 参数，这个后面专门讲。日志里最常出现的假象是：首页能打开、引导页正常显示，但一点预览就转圈。此时根因几乎都在转换服务或 office.home 配置上，不在 kkFileView 进程本身。

启动脚本 startup.sh 里默认设了 Java 运行参数，里面有 -Xms 和 -Xmx。小内存机器建议把 -Xmx 压到 512m 或 1g，不要任由默认值跑到 2g，否则物理内存不够时进程会被系统直接杀掉，现象就是启动后过一会儿进程消失。确认进程活着可以用：

ps -ef | grep kkFileView

只要能 grep 到 java 进程并且没有立刻退出，主程序这关就算过了。

3.4 预览第一份文档：URL 参数怎么拼

服务跑起来后，浏览器访问 http://服务器IP:8012，会看到 kkFileView 自带的引导页，上面有一个文件路径输入框。可以直接填服务器本地路径，也可以填一个 http 开头的文件地址。先拿本地文件跑通最简单，假设文件放在 /data/demo.docx，那么浏览器地址栏输入下面这个完整地址：

http://192.168.1.10:8012/onlinePreview?url=http%3A%2F%2F127.0.0.1%3A8012%2FgetCorsFile%3Furl%3Dfile%3A%2F%2F%2Fdata%2Fdemo.docx

这个地址本质上是在让 kkFileView 去访问 http://127.0.0.1:8012/getCorsFile?url=file:///data/demo.docx，其中 file:// 协议表示读本机文件。如果文件不在预览服务器上，而在另一台业务服务器，把 getCorsFile 那一段换成业务系统的真实下载地址即可。

新手最容易懵的是这个地址为什么编码了三层。其实规则不复杂：onlinePreview 的 url 参数本身要做 URL 编码，而 getCorsFile 的 url 参数也是一个需要编码的地址。真正排查时不要凭肉眼猜，先拆开看每一层的实际值，再逐层解码验证。如果只是想快速看到效果，把文件放到 kkFileView 安装目录下的提示位置，用引导页的相对路径输入，先出画面再研究 API 拼接，心理压力会小很多。

4. 配置与集成：把预览能力接到自己的系统里

4.1 application.properties 里的六个必改项

kkFileView 的配置集中在 config/application.properties。生产环境我一般会改下面六处，它们决定端口、缓存、转换组件和水印这些直接影响部署行为的参数。

office.home 如果留空，程序会尝试从 PATH 里找 soffice 命令；如果机器上装了多个版本，建议显式指到要用的那个，避免随机选到一个不兼容的版本。file.dir 指向的目录要提前建好，并给运行用户写权限，否则缓存写不进去，预览会失败。cache.enabled 我建议始终开 true，因为关闭后每份文件每次预览都要重新转换，机器很快会被拖垮。

改完配置文件要重启进程，并且只改自己关心的项，不要在里面加一段格式混乱的自定义内容。Spring Boot 的 properties 文件对行间空格敏感，多一个空格或空行都可能导致解析异常，启动时半天找不出原因。改之前先 cp 一份备份，这是运维习惯，能让你随时反悔。

4.2 用 iframe 与 API 接入业务系统

kkFileView 接入业务系统，最常见的姿势就是 iframe。业务系统里拿到文件下载地址后，拼出预览地址塞进 iframe 的 src：

<iframe src="http://192.168.1.10:8012/onlinePreview?url=http%3A%2F%2Flocalhost%3A8012%2FgetCorsFile%3Furl%3Dfile%3A%2F%2F%2Fdata%2Fdemo.docx" style="width:100%;height:800px;border:0;"></iframe>

iframe 的 src 就是第 3 章那个拼接好的 URL。业务系统在生成这个 src 时，后端一定要做 URL 编码，尤其是文件名带空格、中文、括号时，直接字符串拼接会得到 404 或白屏。预览页面入口固定在 /onlinePreview，启动后访问 /index 可以看到引导页和接口说明。

另一种常见做法是反向代理。把 kkFileView 放到 nginx 的内网路径下，比如 /preview/，业务系统只需要拼相对路径。代理时要特别注意路径保留，location /preview/ 里 proxy_pass 末尾的斜杠写法会影响 /onlinePreview 的静态资源定位，配置不对会出现页面框架出来、样式全部 404 的问题。同时 url 参数里的文件地址也必须是代理后可达的地址，否则预览服务器从自己的视角访问不到业务文件，出现“业务系统能下载，预览服务器却 404”的怪问题。

4.3 水印、缓存、访问权限：生产环境要关心的配置

生产环境最常加的是水印。在 application.properties 里配置 watermark.txt，预览页面的 PDF 渲染层上会叠一层文字水印，不修改原始文件。水印文字建议用团队或系统名，不要放个人名字。同样的，中文字体缺失时水印会显示成方框，和 5.2 里中文乱码是同一个根因，需要在服务器上先把字体补好。

缓存要定时清理。kkFileView 会把转换后的 PDF、图片缩略图都落到 file.dir 下，长期不清理会越堆越大。我一般会在 crontab 里放一条每周清理任务：

0 3 * * 1 find /data/kkfileview/cache -type f -mtime +30 -delete

这条任务删除 30 天前生成的缓存文件，避免误删正在使用的近期文件。执行前先确认 /data/kkfileview/cache 路径确实是缓存目录，别拿根目录开刀。访问控制方面，kkFileView 自身没有账号系统，如果预览服务暴露在办公网，建议前面加一层 nginx basic auth 或按 IP 限定，裸奔到外网的风险不可控。预览服务尽量只对内网开放，文件内容等于变相公开，这个边界在设计网络时要提前想清楚。

5. kkFileView 部署避坑：5 个高频问题与排查记录

5.1 预览 Office 一直转圈，控制台报 connection refused

现象：引导页能打开，传一个 docx 进去后一直转圈，预览不出来，控制台日志出现 connection refused 或转换组件相关异常。

原因：office.home 没配对，或 LibreOffice 根本没装，kkFileView 调不到转换程序；也有可能是转换进程启动后因为权限或系统依赖崩溃。

解决：先手动执行一次 soffice 转换命令，确认转换程序本身可用：

soffice --headless --convert-to pdf --outdir /tmp /tmp/hello.txt

如果这条命令失败，说明问题出在 LibreOffice 安装上；如果成功，再检查 application.properties 里的 office.home 路径是不是指向了 soffice 可执行文件所在目录的上一级，这个路径经常写错一层。改完重启，再看日志里有没有重新触发 soffice 的记录。connection refused 在这里更多是 jodconverter 去连本机某个服务端口发现没起来，优先查本地转换程序，而不是去查防火墙规则。

5.2 Word 转 PDF 后中文乱码或版式错乱

现象：英文数字正常，中文变成方块或乱码，或者行距、页边距和 Word 里完全不一样。

原因：系统缺少中文字体，LibreOffice 用默认字体替代，Latin 字符正常，中文就乱；版式错乱大多是字体被替换成不同字宽和行高的字体导致的。

解决：安装中文字体。常见做法是把 Windows 系统里的 simsun.ttc、simhei.ttf 拷贝到 /usr/share/fonts/chinese/ 目录下，然后刷新字体缓存：

mkdir -p /usr/share/fonts/chinese cp simsun.ttc simhei.ttf /usr/share/fonts/chinese/ fc-cache -f

装完重启 kkFileView，重新预览一次。这个坑在启动阶段不会报任何错，只能靠转换后的 PDF 目检发现，所以部署完成后一定拿一份真实中文文档做验收，不要只传一个英文 Test 文档就认为大功告成。字体文件的版权在自己公司内部使用时一般没人在意，但如果做成对外 SaaS，字体授权是另一个要单独考虑的问题。

5.3 视频预览黑屏、音频播放没声音

现象：mp4 预览黑屏，或者打开音频显示播放器但没有声音。

原因：浏览器对视频编码有硬性要求，H.264 + AAC 组合基本全能放，但 HEVC、某些设备拍出来的 MP4 无法走浏览器原生解码。kkFileView 本身不转码视频，它只是套一个 HTML5 video 标签，原视频编解码不支持就是黑屏。

解决：预览前统一转码，或在源头限制上传格式。另一个容易被忽略的点是响应头：服务器返回时必须带正确的 Content-Type，例如 video/mp4。有些对象存储把扩展名信息丢了，浏览器识别不出视频流，也会黑屏。音频同理，检查返回头是不是 audio/mpeg 或 audio/mp4。这类问题定位时要先分清是编码问题、协议问题还是文件本身损坏，不要一上来就怀疑 kkFileView。

5.4 启动失败：内存不足与端口占用

现象：startup.sh 执行后进程马上退出，日志里出现 OutOfMemoryError 或 BindException。

原因：小机器或容器里物理内存不够，JVM 默认参数把 -Xmx 设太高；或者 8012 端口被其它程序占用。

解决：修改 bin 目录下启动脚本里的 JVM 参数，把 -Xmx 调到 512m 到 1g 之间。端口占用用刚才提到过的命令定位：

ss -lntp | grep 8012

拿到占用进程的 PID 后，确认是否可以停掉，或者直接改 server.port 换成 8013。改完 JVM 参数后，用 ps -ef | grep kkFileView 查看进程参数里有没有带上新的 -Xmx，很多人在脚本里改了但没重启，或重启时用了旧的进程号，这种低级错误在赶时间时最容易犯。

5.5 中文文件名与特殊字符的 URL 编码问题

现象：文件名是“项目方案 v2（终稿）.docx”，点预览 404，或者预览页白屏。

原因：业务系统把原始文件名直接拼进 url 参数，没做 URL 编码，空格、括号在传输中被截断或转义错误。

解决：拼接前用 URLEncoder.encode 处理整个文件地址。Java 后端常见写法是这样：

String fileUrl = "http://file-server/data/项目方案 v2（终稿）.docx"; String encoded = URLEncoder.encode(fileUrl, "UTF-8"); String previewUrl = "http://preview-server:8012/onlinePreview?url=" + encoded;

URLEncoder 会把空格变成 + 或 %20，中文变成 %XX，kkFileView 拿到后会自己解码一次。真正容易出怪问题的地方在网关卡：如果 nginx 或网关层又解了一次码，到达后端时地址就成了半成品。排查时把拼接前、编码后、到达后端后的三段字符串分别打出来对比，看到底是哪一层动了手脚。文件名里有空格和括号的预览需求很常见，这个问题在测试阶段不会遇到，一上线就会集中爆发。

6. 让预览服务跑得更稳：缓存迁移与内存参数调优

6.1 把文件缓存迁到独立数据盘

默认 file.dir 在系统盘，预览量大之后缓存文件会占满根分区，这大概是我见过运行半年后最常见的事故源。我一般坚持在部署当天就把缓存迁到数据盘：

mkdir -p /data/kkfileview/cache chown -R runuser:runuser /data/kkfileview

然后改 application.properties 里的 file.dir 指向这个目录。如果旧缓存里已有转好的文件，直接把原目录 mv 过去，可以省下重新转换的时间。迁移后观察半小时日志，确认程序确实在往新路径写文件，不要只改配置不验证，否则等到缓存写满才反应过来就晚了。

6.2 JVM 堆内存与并发转换参数怎么调

内存调优的原则是：小机器先把 -Xmx 压下来，大机器不要盲目加堆。我一般在 4GB 物理内存的服务器上用 -Xms512m -Xmx1g，已经能支撑十几个人的团队日常预览。转换并发强依赖 CPU，不是堆越大越快，堆太大反而会增加 GC 停顿。kkFileView 的转换任务是排队处理的，给 2 到 4 个并发转换线程就够，再多会把 CPU 打满，页面响应反而变慢。调完参数确认生效后，再用一段时间的日志观察转换耗时变化，比拍脑袋调参可靠。

6.3 用 curl 与日志做一次健康的验收

验收时先看端口和首页，再走一次真实文件预览，不要只打开浏览器点两下就结束：

# 检查服务是否正常响应 curl -I http://127.0.0.1:8012/index # 触发一次预览并观察返回内容 curl -s "http://127.0.0.1:8012/onlinePreview?url=..." | head -20

然后翻日志看转换耗时，单份几页的 docx 在 5 到 10 秒内出预览算正常，超过 30 秒就要查是转换进程问题还是磁盘 IO 慢。我第一次部署就栽在没装 LibreOffice 上，页面转圈半小时，后来把“先验证 soffice，再启动 kkFileView”写进自己的部署清单，再没因为这种低级问题翻过车。希望帮到你。

本文还有配套的精品资源，点击获取