当前位置：首页 > news >正文

本地能跑，上线就崩：文件预览服务的五个隐蔽坑与排障实录

news 2026/6/27 7:49:26

本期敖行客研发实战日记，邀请传奇后端人物——GGB,分享文件预览服务上线踩过的一堆阴间大坑，完整复盘生产环境 5 个藏到离谱的疑难 bug 排坑全过程。解决本地跑丝滑、一部署上线直接原地翻车的诡异问题，深挖病根同时附上落地解法。帮各位后端同行躲开中间件、容器部署里防不胜防的隐形坑，以后再遇上玄学报错，也能从容上手排查，告别排查 bug 熬秃脑袋的日子

GGB 江湖人称“后端补刀位”。常年与服务端、容器和各种诡异 bug 为伍，信奉“日志不会骗人，骗人的是写日志的人”。
最大的爱好是把别人眼里的“玄学问题”一层层扒到根因，再用最少的改动把它摁死。找不到他的时候，他大概率正盯着一段堆栈发呆.......

文件预览服务（基于开源的 kkFileView），就是把 Office、PDF、图片、代码等各种格式在浏览器里直接预览。听起来是“拿来即用”，真正接入生产后才发现，坑一个接一个，而且大多在网上搜不到现成答案。下面按踩坑顺序复盘。

一、最隐蔽的坑：多副本部署下“第一次打开必 404，第二次就好了”

现象很妖：

同一个文件、同一个地址，第一次预览报 404，过几分钟再点就正常。后台日志却明明白白写着“转换成功”，而且只花了几百毫秒。

排查了一圈编码、缓存、前端时序，最后靠时间戳锁定真相——404 返回的时间，正好是转换完成时间往后推 120 秒（等待超时）。也就是说：文件确实转出来了，但请求它的那个进程一直没找到。

真相：

服务是 K8s 多副本部署，转换后的 PDF 只落在“产生它的那个 Pod”的本地磁盘上。负载均衡把预览请求发给 Pod A 完成转换，下一个取文件的请求却被转发到 Pod B，Pod B 本地根本没有这个文件，于是 404。

为什么第二次就好了？纯属运气，负载均衡又把我扔回A了😅

经验：凡是“先转换、再按 URL 取产物”的服务，多副本部署必须用共享存储（NFS/NAS）挂载产物目录，否则本地磁盘 + 内存状态天然不一致，本地单实例永远复现不出来，最容易被忽略。

二、本地能跑、上线就崩：环境差异集中爆发

#1. office.home 配置

LibreOffice 的安装路径，本地是 Windows 的 C:/Program Files/LibreOffice，服务器容器里是 /usr/lib/libreoffice。代码里如果写死了路径，上线直接找不到。

办法：用环境变量占位符 ${KK_OFFICE_HOME:默认值} 兼容两端：有环境变量用环境变量，没有用默认值，一份配置两边通用。

#2. 编译打包的 JDK 版本

项目要求 Java 21，但 maven-compiler-plugin 的 release=21 参数，在旧版 Maven 上会触发“不支持发行版本 21”的假报错，错误信息还被 fork 模式藏起来。去掉 release、改用 source/target 后顺利打包。

一句话：报错信息看不全时，先想办法把它逼出来，别盲改。

三、带批注的 Word 一转就崩

带批注（comments）的 docx 转 PDF 时，容器里的 LibreOffice 直接 abort 崩溃（Signal 6），堆栈指向构建批注 UI 部件时找不到资源。本地完整版 LibreOffice 没问题，容器里的精简版缺了 UI 资源文件。

一度以为关掉“导出批注”就行，结果没用——只要文档带批注，LibreOffice打开时就要构建那个UI部件，跟导不导出无关。

最终结论是：治本要在容器里补装完整的 LibreOffice +中文字体。

经验：第三方组件的崩溃，先分清是“调用方用法”问题还是“组件自身安装不完整”问题，方向错了白费力气。

四、Excel 预览中文全乱码变天书

xlsx 转成 HTML 后，中文全变成“é¡¹ç›®åˆ—è¡¨”这种乱码。典型的 UTF-8 被当成别的编码处理。

根因藏得很深：代码用了一个“自动嗅探编码”的工具去读 LibreOffice 转出的 HTML，这个工具自作聪明，结果把本来是 UTF-8 的文件误判成了 Latin1，用错编码读进内存就把中文读坏了，再写回文件，乱码就永久固化了——文件头声明的还是 utf-8，所以浏览器也救不回来。

改法：不再瞎猜，直接读取文件头里自己声明的字符集（LibreOffice 明确写了 charset=utf-8），按它正确读取。