【技术底稿 18】FTP 文件处理 + LibreOffice Word 转 PDF 在线预览 + 集群乱码终极排查全记录

一、前言

本文为生产环境实战复盘技术底稿，聚焦后端通用文件处理场景，完整实现基于 LibreOffice 的 Word 转 PDF 在线预览接口。全文完整复盘 FTP 底层连接污染问题、分布式集群交替乱码玄学问题，沉淀可复用的生产开发规范与运维经验，适合 Java 后端开发者参考避坑。

业务需求：实现 FTP 存储 Word 文档在线预览能力，前端通过 iframe 直接引用 URL 预览，无需下载文件。

响应模式：支持预览 inline、下载 attachment 两种独立模式。

转换工具：采用LibreOffice跨平台开源免费文档转换工具，无版权风险，支持命令行自动化 Word 转 PDF。

环境部署：本地 Windows 开发环境、Linux 生产集群环境均已部署对应版本 LibreOffice。

架构原则：完全复用现有 FTP 文件下载能力，不改造底层 FTP 服务，最小侵入式开发。

接口直接返回 PDF 在线流，前端通过 src 引入 iframe 即可完成预览。动态设置 Content-Disposition 响应头，预览使用 inline、下载使用 attachment。统一异常处理，覆盖文件不存在、FTP 连接异常、文档转换失败等全部异常场景。

开发时误将setContentType写成getContentType，导致编译报错。修复：修正方法名，对齐 Servlet 响应规范即可解决。

现象：本地 Windows 环境完全正常，Linux 服务器出现一次正常、一次乱码交替不稳定现象。

根因：FTP 流未完整读完、未执行completePendingCommand收尾命令，连接未正常释放，造成连接池污染复用异常。

解决方案：严格遵循 FTP 开发规范，完整读取文件流 → 执行收尾命令 → try-with-resources 自动关闭资源，连接污染问题彻底解决。

现象：本地 Windows 环境 LibreOffice 转换预览永远正常；生产 2 台服务器 Nginx 轮询负载均衡，请求落到机器 1 正常，落到机器 2 文字全部方框乱码，现象交替无规律。

排查过程：依次排除网络、Nginx、代码问题，最终定位乱码来源于 LibreOffice 文档渲染环节。

根因：LibreOffice 渲染 PDF 文字完全依赖系统底层中文字体；机器 1 已安装中文字体，机器 2 未安装，无字体直接渲染方框乱码。

根治方案：

修复后乱码彻底解决。

⚠️ 遗留优化：两台机器字体版本细微差异，导致文字粗细、大小略有区别，属于非上线阻塞问题，后续统一字体版本即可微调。

LibreOffice 是生产环境优选跨平台免费文档转换方案，无版权风险，Windows/Linux 双环境适配稳定。
FTP Commons Net 铁则：流必须完整读完 → 必须执行 completePendingCommand → 必须释放连接，否则必然出现玄学不稳定 BUG。
LibreOffice Word 转 PDF 完全依赖系统字体，本地 Windows 自带字体 ≠ Linux 服务器环境正常。
分布式集群第一原则：所有节点 LibreOffice 版本、字体、配置必须 100% 对齐，否则负载均衡必出现本地正常、服务器间歇性异常无头 BUG。
PDF 乱码排查优先级：优先排查 LibreOffice 生成渲染字体问题，90% 乱码并非网络、Nginx、传输导致。建议：将中文字体库纳入集群初始化脚本，避免人工遗漏安装。

📚 系列导航：