企业官网建设流程全解析

上周帮一个做内部知识库的团队排了个不大不小的问题：他们要把系统里的 Word、Excel、PPT、PDF 甚至工程图纸直接在浏览器里打开，不想让用户先下载再用本机软件看。第一反应是用浏览器原生预览能力，结果 Office 系列几乎全军覆没，PDF 勉强能用，一套业务四种表现，维护成本直接上天。最后落地的方案就是kkfileview——一个用 Java 写的开源文件在线预览服务，部署完只暴露一个端口、一个接口，把几十种常见格式统一转成网页能渲染的样子。

本文讲的是 kkfileview 在 Linux 上的安装部署，重点覆盖 CentOS 和 Debian 两条线的差异。这不是一篇"复制三条命令就完事"的教程，因为我自己在两个发行版上各踩过一轮坑：LibreOffice 版本不一致导致转换结果不同、中文字体缺失导致整页方块、进程残留导致预览一直转圈。所以下面会把"为什么要装这个""这个参数为什么这么配""出问题怎么一步步倒推"都讲清楚。适合谁看？适合需要在私有环境里自建文件预览能力的后端、运维，也适合只是想在自己服务器上跑一个预览服务试试水的同学。

1. 先搞清楚 kkfileview 干的是哪一段活

1.1 一次"打开文件"，在它内部被拆成了三步

很多人第一次接触 kkfileview，会以为它是个"网盘预览插件"。其实它的定位很纯粹：接收一个文件地址，返回一个可以在浏览器里看的页面。这个过程在内部被拆成三步走。

第一步是取文件。你通过 URL 参数把文件的访问地址传进来，它自己去下载或者读取。注意这一步是服务端发起的，也就是说 kkfileview 所在的机器必须能访问到那个文件地址，这一点后面会反复提到，很多"预览 404"的根因都在这里。

第二步是转换。这一步是它真正的核心价值所在。如果目标文件是 PDF、图片、视频、音频这类浏览器原生就能渲染的格式，它可以几乎零成本地直接吐出来；但如果是docx、xlsx、pptx、wps、dwg这类浏览器不认识的格式，就需要一个"翻译器"把它转成 PDF 或者 HTML。这个翻译器就是 LibreOffice（早期也支持 OpenOffice，现在基本都推荐 LibreOffice）。

第三步是渲染与缓存。转出来的 PDF 会交给前端用 PDF.js 之类的库按页渲染，或者后端直接转成一张张图片返回。转好的结果通常会缓存起来，同一个文件第二次打开就走缓存，避免反复调用 LibreOffice 这个重量级进程。缓存策略是可配置的，这是后面性能调优的主要抓手。

理解了这三步，你就会明白：kkfileview 本身其实不重，重的是它背后的 LibreOffice。所以运维上真正要操心的是 LibreOffice 的进程、字体、内存和超时，而不是 Java 应用本身。

1.2 什么场景值得上它，什么场景别硬上

先说值得上的场景。典型的是私有化部署 + 格式杂 + 用户不想装软件。比如企业内部的知识库、合同管理系统、OA 审批附件、教学资料平台。这些场景通常文件格式五花八门，用户又分布在各种终端上，手机上根本没有对应的阅读器，服务端统一转换是最省事的路子。

再说别硬上的场景，这也是我经常劝退别人的地方。如果你只需要预览 PDF 和图片，那完全没必要上 kkfileview，浏览器<iframe>直接加载 PDF、<img>直接加载图片就够了，部署一个 Java 服务的成本远高于收益。如果你的文件量级非常大、并发很高，比如一天几十万次预览，那要评估的就不是"能不能装"，而是"要几台机器、每台放多少个 LibreOffice 转换槽位"，这是完全不同的工程量级。还有一种情况是文件全部在用户本地、需要"上传即预览"，那也得先想清楚临时目录的清理策略，不然磁盘会被悄悄吃满。

至于常被拿来对比的方案，无非几类：前端纯 JS 的文档渲染库（对格式支持有限，复杂排版还原度堪忧）、商业化的文档转换服务（效果好但要花钱、且数据要出域）、自己用 LibreOffice 命令行 + 自研渲染层（可控但开发量大）。kkfileview 的定位是开箱即用、私有可控、格式覆盖够广，把它当成"省掉自研转换层"的脚手架，心态就对了。

2. 装之前先把三样依赖备齐：JDK、LibreOffice、中文字体

2.1 JDK 版本与 JAVA_HOME 的坑

第一个依赖是 JDK。kkfileview 是 Spring Boot 应用，主流版本对JDK 1.8的兼容性最好，用 11 或 17 大概率也能跑，但如果你手上的版本比较老，别冒险，直接上 8。

CentOS 7 上装起来很直接：

yum install -y java-1.8.0-openjdk java-1.8.0-openjdk-devel java -version

Debian 系则是：

apt update apt install -y openjdk-8-jdk # 如果源里没有 8，用 11 也行，装完确认下版本 java -version

这里有个我踩过的坑：java -version能跑，不代表JAVA_HOME配对了。有些发行版的 JDK 装完不会自动设置环境变量，而 LibreOffice 在某些版本下会依赖JAVA_HOME来加载 Java 相关的组件。表现是：kkfileview 能启动，但转换xlsx里带宏或者复杂公式的文件时会直接失败。排查方式很简单：

echo $JAVA_HOME # 空的话手动补上，路径按实际装的位置改 export JAVA_HOME=/usr/lib/jvm/java-1.8.0-openjdk export PATH=$JAVA_HOME/bin:$PATH

要长期生效就写进/etc/profile.d/java.sh，然后source一下。这一步花两分钟，能省掉后面半小时的排查。

2.2 LibreOffice 为什么不能省，Office 转换全靠它

第二个依赖是 LibreOffice，而且是必须装在 kkfileview 同一台机器上，不是可选组件。原因就是前面说的"翻译器"角色：所有 Office 系文件都得靠它把二进制格式翻译成 PDF。

CentOS 上装：

# CentOS 7 yum install -y libreoffice libreoffice-headless libreoffice-langpack-zh-Hans # CentOS 8 / 9 Stream dnf install -y libreoffice libreoffice-headless libreoffice-langpack-zh-Hans

Debian 上：

apt install -y libreoffice libreoffice-writer libreoffice-calc \ libreoffice-impress libreoffice-java-common

有两个细节值得说。第一，libreoffice-headless这个包很关键。它提供的正是无界面模式，服务端转换靠的就是这个模式。有些精简系统默认只装了基础包，缺了 headless 的话，转换会报找不到模块。第二，libreoffice-java-common在 Debian 上别省，它会带上一些 Java 相关的桥接组件，处理 ODF 格式和部分文档时更靠谱。

安装完验证一下：

libreoffice --version # 或者 soffice --version

能打印出版本号说明命令可用。接下来要决定office.home这个配置怎么填：

我个人的建议是：如果你需要控制版本，就用官网 tar.gz 解压到/opt下，然后在配置里显式写死office.home。为什么？因为系统源里的 LibreOffice 版本往往偏老，CentOS 7 自带的是 5.x，对某些新版docx的排版还原会打折扣；而且系统升级时版本可能被悄悄换掉，转换效果就莫名其妙变了。解压式安装版本固定、升级可控，出问题也容易回滚。

2.3 中文字体：90% 的"乱码方块"都出在这里

第三个依赖是最容易忽略、但出问题最多的：中文字体。

原理很简单：LibreOffice 在转换文档时，需要找到文档里指定的字体来渲染文字。如果服务器上没装对应字体，它只能用一个默认字体去"顶"，而很多精简版 Linux 的默认字体不含中文字形，结果就是满屏的方块或者问号。你在 Word 里看着好好的文档，转成 PDF 就变成"口口口"，根因就在这。

装字体的标准流程是：把 TTF/TTC 字体文件丢进系统字体目录，然后刷新字体缓存。

mkdir -p /usr/share/fonts/chinese # 把字体文件复制进去，比如从其他机器拷贝 cp /path/to/*.ttf /usr/share/fonts/chinese/ cp /path/to/*.ttc /usr/share/fonts/chinese/ chmod 644 /usr/share/fonts/chinese/* # 安装 fontconfig（精简系统可能没装） # CentOS: yum install -y fontconfig # Debian: apt install -y fontconfig # 刷新缓存 fc-cache -fv # 验证中文（或西文）字体已经生效 fc-list :lang=zh | wc -l

最后那条命令会输出检测到的中文字体数量。如果结果是 0，那你的乱码问题基本就跑不掉了，请务必让它大于 0 再继续。

如果你手头没有商用字体授权的顾虑，可以直接装开源的方案，Debian 系一行搞定：

apt install -y fonts-wqy-zenhei fonts-wqy-microhei fonts-noto-cjk

这几套字体对中文的覆盖都挺全，用来兜底完全够用。有个经验：别只装一套字体。文档里可能指定宋体、可能指定黑体、也可能指定楷体，装得越全，被"顶字体"导致排版跑偏的概率就越低。真要追求还原度，就把常见的几套中文字体都补齐。

3. CentOS 上的落地流程（7.9 与 8/9 差异要分开看）

3.1 系统层面的包与源

CentOS 这条线最大的特点是版本分化严重。CentOS 7.9 和 8/9 Stream 在包管理器、默认软件版本、甚至 glibc 上都不同，混着抄命令很容易卡在第一步。

CentOS 7.9 用的是yum，软件源里 LibreOffice 是 5.x。如果你不介意版本，直接：

yum install -y epel-release yum install -y fontconfig java-1.8.0-openjdk libreoffice libreoffice-headless

CentOS 8 之后换成了dnf，命令基本兼容：

dnf install -y epel-release dnf install -y fontconfig java-1.8.0-openjdk libreoffice libreoffice-headless

如果你要的是新版 LibreOffice，两个版本都可以走官网 tar.gz：

# 下载后解压到 /opt tar -zxvf LibreOffice_7.6.x_Linux_x86-64.tar.gz -C /opt/ cd /opt/libreoffice7.6/program ./soffice --version # 依赖缺的话，用自带脚本补 cd /opt/libreoffice7.6 ./install --help

有个细节要提醒：tar.gz 版本的 LibreOffice 打包方式和系统包不一样，它不一定往系统字体目录找字体，但会读 fontconfig 的缓存。所以 2.3 那一步的fc-cache -fv在 tar.gz 场景下同样不能省。

3.2 kkfileview 的解压、目录结构与配置改动

依赖备齐后，下载 kkfileview 的发行包。它官方提供两种形式：tar.gz压缩包和docker镜像。这里先讲压缩包。

cd /opt tar -zxvf kkfileview-4.x.x.tar.gz mv kkfileview-4.x.x kkfileview cd /opt/kkfileview ls -lh

解压完你会看到一个比较规整的目录结构，大致是这么几块：

启动脚本里本质就是拼一条java -jar命令。关于 JVM 参数，我建议一开始就改，而不是等出问题再回头改：

# 在 bin/startup.sh 里 java 命令那一行加入 -Xms1g -Xmx2g -Dfile.encoding=UTF-8 -Dsun.jnu.encoding=UTF-8

为什么是这两个编码参数？因为文件名字里带中文、文件内容里有中文在这个场景下太常见了，编码没设对，轻则日志乱码，重则读文件路径就报错。-Xms和-Xmx建议设成一样大（比如都是 2G），避免运行过程中堆反复伸缩带来的额外开销。

配置文件里至少要确认这几项：

server.port=8012 base.url=http://你的服务器IP:8012 office.home=/opt/libreoffice7.6

base.url这个容易被忽略，但它很重要：kkfileview 生成预览页面里的一些内部链接是以它为基准拼的。如果填的是127.0.0.1，而你从外网访问，页面里的部分资源就会指向本机、加载失败，表现是"页面出来了但样式全丢"。

3.3 用 systemd 把它变成开机自启的服务

用bin/startup.sh手动启动，关掉终端或者断开 SSH 之后服务就没了，这显然不适合生产。标准做法是写一个 systemd 单元：

[Unit] Description=kkfileview file preview service After=network.target [Service] Type=forking User=root WorkingDirectory=/opt/kkfileview ExecStart=/opt/kkfileview/bin/startup.sh ExecStop=/opt/kkfileview/bin/showdown.sh Restart=on-failure RestartSec=15 LimitNOFILE=65535 [Install] WantedBy=multi-user.target

存成/etc/systemd/system/kkfileview.service，然后：

systemctl daemon-reload systemctl enable kkfileview systemctl start kkfileview systemctl status kkfileview

这里有几个点值得解释。Type=forking是必须的，因为startup.sh内部是nohup ... &的方式把进程甩到后台，systemd 需要知道它是"派生型"服务，否则会误判服务已经退出。Restart=on-failure加上RestartSec是为了应对偶发的启动失败——比如 LibreOffice 第一次调用要初始化用户配置目录，偶尔会拖慢启动。LimitNOFILE是因为预览服务会同时打开不少文件句柄，默认上限在大文件并发时容易触顶。

还有一点，ExecStop一定要配上。kkfileview 提供的停止脚本会顺带清理它拉起来的 LibreOffice 进程。如果没有这一步，重启服务时旧的soffice进程可能还在，新进程再拉一个，几个来回下来机器上就是一堆僵尸进程，内存悄悄被吃掉。

4. Debian / Ubuntu 的差异点在哪里

4.1 apt 装 LibreOffice 与字体包的组合

Debian 这条线整体比 CentOS 顺，因为 apt 的依赖处理更"聪明"，LibreOffice 的打包也更完整。一条命令基本能把主力组件拉齐：

apt update apt install -y fontconfig openjdk-8-jdk \ libreoffice libreoffice-writer libreoffice-calc libreoffice-impress \ libreoffice-java-common \ fonts-wqy-zenhei fonts-noto-cjk

注意libreoffice这个元包在 Debian 上会拉一大堆东西，包括图形界面相关的组件。如果你的服务器是最小化安装、不想装一堆桌面依赖，可以换成分模块装：

apt install -y libreoffice-core libreoffice-writer libreoffice-calc \ libreoffice-impress libreoffice-java-common

libreoffice-core本身就包含了无界面转换需要的能力，实测足够支撑 kkfileview 的转换需求。

Debian 还有一个特点是包管理器的交互提示。某些版本装字体或 JDK 时会弹配置界面，在自动化脚本里会卡住。提前设好非交互模式：

export DEBIAN_FRONTEND=noninteractive apt install -y ...

这个小技巧在写部署脚本时特别救命，不然 CI 流水线会莫名其妙挂在那里等人按回车。

4.2 Debian 上常见的路径与权限问题

Debian 系的 LibreOffice 装在/usr/lib/libreoffice，而不是 CentOS 的/usr/lib64/libreoffice。大多数情况下 kkfileview 能自动探测到，但如果你遇到"启动正常、转换报错找不到 soffice"，就要在配置里显式指一下：

office.home=/usr/lib/libreoffice

另一个 Debian 上更常见的问题是运行用户和文件权限。如果你用非 root 用户跑服务（这其实是更好的做法），要确保这个用户对几个目录有写权限：

chown -R kkfile:kkfile /opt/kkfileview/log chown -R kkfile:kkfile /opt/kkfileview/file chmod -R 755 /opt/kkfileview/bin

还有 LibreOffice 自己的用户配置目录。它默认会写到$HOME/.config/libreoffice，如果运行用户的 HOME 不存在或者不可写，转换会直接失败。稳妥的做法是在 systemd 单元里显式指定：

[Service] User=kkfile Environment=HOME=/home/kkfile

这个坑不常被提到，但一旦撞上，报错信息非常隐晦——日志里只有一句"转换失败"，没有任何细节。我当时查了挺久才定位到是 HOME 目录不可写。

4.3 一个通用的启动脚本检查清单

不管是哪个发行版，服务装完后我都会跑一遍这个检查清单。它帮我省下过至少三次线上救火：

最后一条尤其重要。服务能不能用，不看curl返回码，看日志里有没有"启动完成"和后续的转换记录。kkfileview 的日志写得还算清楚，转换耗时、缓存命中、异常堆栈都能看到，排查时优先看它。

5. Docker 部署：省事的路线，以及它藏起来的两件事

5.1 单容器跑起来的完整命令

如果服务器上已经有 Docker 环境，用镜像是更省事的路径，因为它把 JDK 和 LibreOffice 都打进去了，不用你自己纠结版本。

docker pull keking/kkfileview:latest docker run -d \ --name kkfileview \ --restart=unless-stopped \ -p 8012:8012 \ -e JAVA_OPTS="-Xms1g -Xmx2g" \ -v /opt/kkfileview/config:/opt/kkfileview/config \ -v /opt/kkfileview/log:/opt/kkfileview/log \ -v /opt/kkfileview/file:/opt/kkfileview/file \ keking/kkfileview:latest

几个参数的实际意义：--restart=unless-stopped保证宿主机重启后容器能自动拉起，等价于前面 systemd 的enable；JAVA_OPTS是给容器内 JVM 传参；三个-v分别把配置、日志、缓存目录挂出来，这样容器重建时你的配置和缓存不会丢，日志也能在宿主机上直接看。这三个挂载强烈建议一个都别省。

启动完成后访问http://服务器IP:8012应该能看到首页。

5.2 挂载字体与配置目录的正确姿势

Docker 路线第一个藏着的问题是字体。镜像里通常只带了几套基础字体，中文覆盖不一定完整。如果你发现预览出来的中文是方块，别急着怀疑配置，先往字体上想。解决办法是把宿主机的字体目录挂进去：

-v /usr/share/fonts:/usr/share/fonts:ro

以只读方式挂载，容器里直接复用宿主机的字体资源。这样你在宿主机上按 2.3 的方式装好字体、刷好缓存，容器重新拉起后就能直接用了。注意宿主机上也要装fontconfig并执行过fc-cache -fv，否则挂进去的字体的缓存信息是缺的，容器里同样认不出来。

第二个藏着的问题是文件源的网络可达性。容器有自己的网络命名空间，"容器能不能访问到那个文件地址"和"宿主机能不能"是两回事。如果你传的是内网域名或者宿主机本地路径，容器里很可能解析不到。两种处理方式：一是用--network host让容器直接复用宿主机网络栈，二是把文件源配置成容器可达的地址（比如用宿主机的内网 IP 而不是127.0.0.1）。127.0.0.1在容器里指的是容器自己，这个是最容易犯的错。

5.3 什么时候反而不推荐 Docker

Docker 省事，但不是万能。有两种情况我更倾向裸机部署。

一种是需要精细控制 LibreOffice 版本的场景。企业里对文档转换效果的要求有时很具体，比如某个版本的 LibreOffice 对某种表格样式的还原更好，而镜像里的版本你没得选。这时候裸机部署、自己装指定版本的 tar.gz 反而更自由。

另一种是要求极致性能的场景。容器化会带来一点点额外的开销，而且容器内进程数量、文件描述符上限的控制链路更长。高并发转换场景下，裸机 + systemd 的调优空间更大，也更容易做进程级别的资源隔离。当然，这两种情况的差异在日常量级下基本感知不到，除非你的预览量真的很大，否则别为了"性能"这个理由放弃 Docker 的便利。

6. application.properties 里真正需要你动的那几行

6.1 端口、上下文路径与 base.url

server.port默认是8012，一般不用改，除非端口冲突。真要改的话记两件事：改完配置文件，别忘了同步改防火墙规则和任何前置转发层的配置。

base.url前面提过，这里再强调一次它的判断标准：你在浏览器地址栏里输入的那个前缀，就是它该填的值。比如你最终是通过http://preview.内网域名/kkfileview/访问的，那base.url就应该填这个，而不是http://127.0.0.1:8012。

如果你的服务前面有一层 Web 服务器做统一入口，还要注意上下文路径的一致性。假设你把请求路径收敛到/kkfileview/下，那么配置里的上下文路径和转发层的前缀要能对上，同时base.url也要带上这个前缀。这三处只要有一处不一致，典型现象就是"首页能开，点预览就 404"，因为首页是静态资源能兜住，但预览接口的拼装路径错了。

6.2 缓存类型的选择：default、jdk 还是 redis

缓存这块是决定性能上限的关键配置。常见的取值有这么几种，用途差别挺大：

单机小规模，用default最省事，它是内存加磁盘的混合策略，大文件落在磁盘上不占堆。但你要记得配一个缓存清理任务，否则磁盘是温水煮青蛙式的被吃满：

cache.clean.enabled=true cache.clean.cron=0 0 3 * * ?

多实例部署就必须上redis，否则每台机器各缓存一份，用户刷新几次可能落到不同实例上，缓存命中率惨不忍睹：

cache.type=redis spring.redisson.address=redis://127.0.0.1:6379

jdk这个选项我要多说一句：它快，但也危险。纯内存缓存意味着一个大文件转出来的中间产物全在堆里，几十兆的文件叠加上并发，OutOfMemoryError就是几分钟的事。除非你的文件都确定很小，否则别选它。

6.3 转换超时、水印与下载开关

超时配置是另一个必须调的项。默认值往往偏保守，遇到大文档、复杂排版的表格，转换时间很容易超出，表现就是"页面一直转圈最后报超时"。可以适度放宽：

office.task.timeout=60

单位一般是秒，具体看你手上的版本注释。我的经验是：先把超时调到 60 秒跑一段时间，观察日志里的实际转换耗时分布，再决定要不要继续往上调。盲目设成 300 秒的后果是，真卡住的请求会占着转换槽位三分钟，把后面排队的全堵死。

水印是个很实用的安全特性，预览敏感文档时建议打开：

watermark.txt=内部资料 请勿外传 watermark.fontsize=18 watermark.alpha=0.3 watermark.x.space=200 watermark.y.space=200

alpha控制透明度，x.space和y.space控制水印之间的间隔。间隔太小会糊成一片影响阅读，太大又容易被裁掉，我一般用 200 左右。

还有一个容易被忽略的开关是是否允许下载原始文件。预览服务一旦同时提供下载入口，等于把文件通过预览服务"二次暴露"了一遍。如果你的业务本身对文件访问有权限校验，那这个开关最好关掉，把下载能力收回业务系统里。

7. 预览接口怎么调：URL 参数的编码规则

7.1 onlinePreview 的参数拼装

接口本身很简单，核心就一个/onlinePreview，文件地址放在url参数里。但这个url参数不能直接放原始地址，中间要做两重编码，这是新手最容易翻车的地方。

正确的做法是：先把原始文件地址做 Base64，再对整个 Base64 结果做 URL 编码。用 Java 写出来是这样：

String fileUrl = "http://fileserver/contract/2024年合同.docx"; // 第一步：Base64 编码（用 UTF-8，中文路径才不出乱码） String base64 = Base64.getEncoder() .encodeToString(fileUrl.getBytes(StandardCharsets.UTF_8)); // 第二步：URL 编码 String encoded = URLEncoder.encode(base64, "UTF-8"); String previewUrl = "http://127.0.0.1:8012/onlinePreview?url=" + encoded;

为什么第二步不能省？因为 Base64 的结果里会出现+、/、=这三种字符。其中+在 URL 的查询字符串里有特殊含义——它会被解析成空格。如果不做 URL 编码，你的文件地址在服务端解出来就少了一个字符或者多了一个空格，结果就是"文件不存在"或者 404。URLEncoder会把+转成%2B，这个问题就规避了。这段代码看起来简单，但因为+导致的 404 我见过不止一次，排查起来还挺费劲，因为参数看起来"就是对的"。

除了url，还支持一些附加参数，常用的有：

fullfilename这个参数的实际价值在于：当你的文件地址末尾没有扩展名时（比如走的是/api/file/12345这种接口地址），kkfileview 无法从 URL 判断文件类型，这时候就必须靠fullfilename告诉它这是xlsx还是docx。不带这个参数，它就只能按默认逻辑猜，猜错就会走到错误的转换分支。

7.2 文件来源的两种模式：远程 URL 与本地目录

文件来源有两种典型模式，选哪种直接决定了你的部署拓扑。

模式一是远程 URL。业务系统提供文件访问地址，kkfileview 主动去拉。这个模式的优点是解耦，文件和预览服务可以不在同一台机器上。缺点是网络可达性成了前置条件，而且要注意服务端发起请求时的身份问题——如果你的文件接口需要鉴权，kkfileview 拉不到文件，除非你提供一个临时可访问的地址（比如带签名的临时链接）。这里还有个安全点：新版本一般会有可信主机白名单的配置，如果预览远程地址时报"不受信任"之类的错误，先去检查这个白名单有没有把你的文件服务器加进去，这是防止服务被当成任意请求跳板的保护机制，别直接关掉。

模式二是本地目录。配置一个本地目录，把文件放进去或者挂载进去，url传相对路径就能预览。优点是快、安全、不依赖外部网络。缺点也很明显：文件得先落到这台机器上，而且路径处理必须严谨，任何允许"相对路径"的能力都要防住路径穿越，否则一个../../就能读到系统文件。生产环境用这个模式的话，建议单独切一块磁盘挂载到配置的目录下，把权限收窄，只给运行用户读写。

我的建议是：内部小规模、文件本来就在同一台机器上的，用本地目录；文件散落在多个业务系统里的，用远程 URL，但把白名单和临时鉴权地址这两件事做扎实。

8. Nginx 前置转发与访问入口的收口

8.1 转发配置与常见的 404/502

如果你前面有一层 Nginx 之类的 Web 服务器做统一入口，有几个点必须对齐，否则症状都很像"服务没起来"，实际上服务好好的。

第一是路径前缀的一致性。入口前缀、转发目标路径、配置里的base.url，这三者必须是一个闭环。最常见的事故是入口配了/kkfileview/，但没有把前缀剥离，结果转发到后端的路径变成了/kkfileview/onlinePreview，而 kkfileview 只认/onlinePreview，于是 404。

第二是请求头里的 Host 和协议。如果你的入口做了 HTTPS 终止，后端收到的是 HTTP，这时后端拼出来的部分资源链接可能还是 HTTP，在浏览器里就会被拦。处理方式是让转发层把原始协议和 Host 透传过去，应用侧也配置上对应的识别参数。

第三是502 的两种典型来源。一种是后端确实没起来，先去curl http://127.0.0.1:8012确认；另一种是转换耗时超过了转发层的超时时间。后者的特点是首页正常、小文件正常，只有大文件报 502。这时候要调的是转发层的读超时，不是服务本身。

8.2 大文件、长耗时的超时设置

这块我有过很具体的一次经历：一个 40 多页的带图表格xlsx，本地直连 8012 端口预览没问题，走统一入口就必报错。原因就是转换耗时接近 30 秒，而入口层默认超时也是 30 秒，正好卡在边界上。

要调的参数有这么几类：

一个原则：转发层的超时必须大于应用层的转换超时，而且要留出余量。两者相等是最糟糕的配置，因为总有一部分请求正好卡在边界上，表现就是"时好时坏"，这种问题最难排查。

另外提醒一句，如果走 HTTPS 并且是自建证书，别忘了把证书链配对，否则某些客户端会拒绝连接，症状同样是"服务不可用"，但根因完全不在 kkfileview 这边。

9. 上线后高频故障的排查链路（按现象倒推）

9.1 页面转圈不出内容

这是收到最多的报障。不要一上来就重启服务，按下面这条链路走，基本三轮内能定位。

第一步，curl http://127.0.0.1:8012看首页是否正常。首页都不出，问题在服务层，去看log/kkfileview.log的启动日志，重点看端口是否被占、依赖是否缺失。

第二步，首页正常但预览转圈，在服务器上直接curl一下那个文件地址，验证"机器能不能拿到文件"。这一步能排掉一大半问题：DNS 解析不到、防火墙没放行、需要鉴权、容器网络隔离，全在这一步暴露。

第三步，文件能拿到但还是转圈，去看日志里的转换记录。如果日志显示转换已经开始但没有结束，那就是 LibreOffice 卡住了，去看 9.2。如果日志里根本没有转换记录，那是请求没走到转换环节，回头检查 URL 参数的编码对不对——尤其是那个+号的问题。

第四步，日志显示转换完成但页面还是空的，那就是前端渲染或缓存的问题。先清一下缓存目录，再换个浏览器或者无痕窗口试，排除浏览器本地缓存的干扰。

9.2 Office 文件转换失败 / LibreOffice 进程残留

这是 kkfileview 运维里最核心的一类问题，值得单独拿出来说。

LibreOffice 有个特点：当一个转换进程因为文件异常、内存不足或者超时而崩溃时，它不一定能自己清理干净。残留的soffice进程会继续占着资源，而且它可能锁住了用户的配置目录，导致后续新的转换进程启动时直接失败。表现就是：一开始个别文件转换失败，过一段时间全部文件都失败。

排查命令很简单：

ps -ef | grep soffice | grep -v grep

如果看到一堆残留进程，先别急着kill -9。优先用kill让它自己退出，因为强杀可能留下锁文件。杀完之后去清理一下 LibreOffice 的用户配置锁：

# 路径按运行用户的 HOME 来 ls -la /home/kkfile/.config/libreoffice/4/.lock # 确认没有活着的进程后可以删除 rm -f /home/kkfile/.config/libreoffice/4/.lock

根治的办法有两个方向。一是给转换任务配上超时和自动清理，kkfileview 本身有超时机制，但你要确保它真的生效（超时参数别设得太离谱）。二是在部署层面加一个兜底巡检，写个定时任务，发现soffice进程存活时间超过某个阈值就清掉。这个兜底看着"土"，但在实际运行中非常管用，因为总会有那么几个畸形文件能让 LibreOffice 挂住。

9.3 内存与磁盘：被忽略的两个瓶颈

转换是吃内存的。LibreOffice 加载一个大pptx或者带大量图片的docx，瞬时内存占用可能到几百兆甚至上 G。如果你同一台机器跑好几个并发转换，内存曲线会非常陡。

内存不够的表现不是"报错"，而是"慢"和"偶发失败"。JVM 堆不够会OOM，LibreOffice 内存不够可能被系统 OOM Killer 干掉，日志里只有一句进程消失。所以别只看 Java 进程的堆，还要留足物理内存给 LibreOffice。经验值是：每个并发转换槽位预留 500M 到 1G 的额外内存，再算上 JVM 的-Xmx。

磁盘的问题更隐蔽。缓存目录会随着预览量持续增长，而缓存清理如果不配，它就是只进不出。定期看一下缓存目录的体积：

du -sh /opt/kkfileview/file/*

如果发现涨得很快，一是检查缓存清理任务有没有真的在跑，二是看看缓存的有效期配置是不是太长了。另外，转换过程中的临时文件也在这块盘上，磁盘满了的直接后果是所有转换都失败，而且报错信息往往指向别处，很容易误判。

10. 多实例与容量规划的几条经验

10.1 共享缓存与文件源

单机扛不住的时候就要上多实例，而多实例最关键的两个词是"共享"。

共享缓存就是前面说的把cache.type换成redis。这不只是为了命中率，还有一个更重要的原因：避免同一份文件在多台机器上重复转换。一份大文档在两台机器上各转一遍，两倍的资源消耗，而用户只点了一次。有了共享缓存，第一台转完写进 Redis，第二台的请求直接命中，成本立刻降一半。

共享文件源也要考虑。如果用的是本地目录模式，多实例下你就得保证每台机器的那个目录内容一致，这个维护成本很高。更现实的方案是统一走远程 URL，让文件服务成为唯一的真相来源。这样新增实例就是纯粹的横向扩容，不需要同步数据。

Redis 这块有两个坑：一是它自己也可能成为单点，生产上至少做主从；二是缓存里的内容会包含文件转换结果，如果文件本身敏感，Redis 的访问控制和持久化策略要及时跟上，别让一个临时的预览缓存变成数据泄露的口子。

10.2 JVM 参数与并发数的估算

最后聊聊参数怎么估。我的做法是先测再定，不靠拍脑袋。

先做单文件基准测试：找几个典型文件（最小的、最大的、最复杂的），在单实例上跑，看日志里的转换耗时。假设最复杂那个文件平均要 8 秒，那理论上一个转换槽位每秒能处理 0.125 个请求。如果业务峰值是每分钟 60 次预览，那就是每秒 1 个请求，需要大概 8 个并发槽位才能不排队。这个数字再乘个 0.7 的安全系数，实际按 10 到 12 个槽位准备。

再根据槽位算内存：JVM 堆 + 槽位数 × 单次转换峰值内存 × 安全系数。这是物理内存的下限。如果算出来的数字超过单机能力，就该考虑拆机器而不是硬堆配置，因为转换这件事本质上是个 CPU 和内存密集型任务，堆配置的边际收益衰减很快。

JVM 参数上，-Xms和-Xmx设成相等是基础操作，-XX:+UseG1GC这类现代 GC 在预览这种"短时高频分配"的场景下表现更好。至于线程池相关参数，不要一上来就调大，先把默认值跑起来，观察日志里排队和拒绝的情况再动，否则很容易调成"看起来并发很高，实际上全在互相争抢"。

最后聊点实在的。我自己在两套环境上跑 kkfileview，一套裸机 CentOS、一套 Docker 在 Debian 上，最大的体会是：这套服务本身的部署难度其实不高，真正花时间的地方全在外围——字体、LibreOffice 进程、缓存目录、以及前面那层转发的时间参数。所以我的习惯是把 4.3 那张检查清单做成一键脚本，每次上新的环境先跑一遍，能省掉大量"服务明明起来了就是不能用"的无效排查。另外强烈建议第一次部署时拿一个带图表的复杂xlsx和一个几十页的docx做验收，别拿一个纯文本文件测试通过就以为搞定了，那两类文件才是暴露问题的主力。