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

一、前言本文为生产环境实战复盘技术底稿聚焦后端通用文件处理场景完整实现基于 LibreOffice 的 Word 转 PDF 在线预览接口。全文完整复盘 FTP 底层连接污染问题、分布式集群交替乱码玄学问题沉淀可复用的生产开发规范与运维经验适合 Java 后端开发者参考避坑。二、核心需求与技术选型业务需求实现 FTP 存储 Word 文档在线预览能力前端通过 iframe 直接引用 URL 预览无需下载文件。响应模式支持预览 inline、下载 attachment 两种独立模式。转换工具采用LibreOffice跨平台开源免费文档转换工具无版权风险支持命令行自动化 Word 转 PDF。环境部署本地 Windows 开发环境、Linux 生产集群环境均已部署对应版本 LibreOffice。架构原则完全复用现有 FTP 文件下载能力不改造底层 FTP 服务最小侵入式开发。三、在线预览接口开发实现3.1 接口设计思路接口直接返回 PDF 在线流前端通过 src 引入 iframe 即可完成预览。动态设置 Content-Disposition 响应头预览使用 inline、下载使用 attachment。统一异常处理覆盖文件不存在、FTP 连接异常、文档转换失败等全部异常场景。3.2 开发落地流程接收 FTP 文件唯一标识调用现有 FTP 工具读取远程 Word 文件流调用 LibreOffice 命令行能力完成 Word 异步转换 PDF设置响应头Content-Type: application/pdf动态区分预览 / 下载模式输出 PDF 流至前端完成在线预览完整闭环四、实战踩坑问题与完整排查方案4.1 开发阶段低级问题修复开发时误将setContentType写成getContentType导致编译报错。修复修正方法名对齐 Servlet 响应规范即可解决。4.2 FTP Commons Net 底层连接污染坑现象本地 Windows 环境完全正常Linux 服务器出现一次正常、一次乱码交替不稳定现象。根因FTP 流未完整读完、未执行completePendingCommand收尾命令连接未正常释放造成连接池污染复用异常。解决方案严格遵循 FTP 开发规范完整读取文件流 → 执行收尾命令 → try-with-resources 自动关闭资源连接污染问题彻底解决。4.3 分布式集群负载均衡交替乱码终极 BUG现象本地 Windows 环境 LibreOffice 转换预览永远正常生产 2 台服务器 Nginx 轮询负载均衡请求落到机器 1 正常落到机器 2 文字全部方框乱码现象交替无规律。排查过程依次排除网络、Nginx、代码问题最终定位乱码来源于 LibreOffice 文档渲染环节。根因LibreOffice 渲染 PDF 文字完全依赖系统底层中文字体机器 1 已安装中文字体机器 2 未安装无字体直接渲染方框乱码。根治方案两台集群服务器统一安装同款中文字体统一 LibreOffice 版本保证字体、运行环境完全一致修复后乱码彻底解决。⚠️ 遗留优化两台机器字体版本细微差异导致文字粗细、大小略有区别属于非上线阻塞问题后续统一字体版本即可微调。五、生产可复用技术经验沉淀LibreOffice 是生产环境优选跨平台免费文档转换方案无版权风险Windows/Linux 双环境适配稳定。FTP Commons Net 铁则流必须完整读完 → 必须执行 completePendingCommand → 必须释放连接否则必然出现玄学不稳定 BUG。LibreOffice Word 转 PDF 完全依赖系统字体本地 Windows 自带字体 ≠ Linux 服务器环境正常。分布式集群第一原则所有节点 LibreOffice 版本、字体、配置必须 100% 对齐否则负载均衡必出现本地正常、服务器间歇性异常无头 BUG。PDF 乱码排查优先级优先排查 LibreOffice 生成渲染字体问题90% 乱码并非网络、Nginx、传输导致。建议将中文字体库纳入集群初始化脚本避免人工遗漏安装。六、最终落地成果LibreOffice Word 转 PDF 转换能力稳定可用iframe 在线预览接口开发完成预览 / 下载双模式正常支持FTP 连接污染问题全部修复集群负载均衡交替乱码 BUG 彻底根治沉淀完整通用文件处理开发运维规范 系列导航【人生底稿 01】农村少年1995–2005【技术底稿】0137岁老码农用4台机器搭了套个人DevOps平台【产品底稿01】37 岁 Java 老码农用 Java 搭了个 AI 写作助手把自己 14 年技术文章全喂给了 AI