近期将 Word 在线预览转 PDF 功能，从内网 FTP 存储迁移至自建内网 S3 对象存储并配套子域名访问。迁移后出现两类典型异常：大体积图片类文档转换飞快，小体积多表格、公式、嵌套对象的复杂文档频繁卡死、接口超时。
经过逐层排查、多轮调优，最终完成网络、代码、中间件全维度优化。本篇完整记录问题根因、落地方案与优化结论。
一、问题背景
文档转换表现两极分化：
-
188MB 纯图片文档：转换速度正常
-
仅 20MB、包含大量表格/公式/嵌套对象的文档：长时间卡住，最终超时
初期使用公网域名访问内网 S3，文件下载速度缓慢；切换为内网 IP 直连后，下载速度恢复至原 FTP 水平，但复杂文档转换卡死问题依旧存在。
原超时时长配置为 10 分钟，异常场景下用户等待过久，交互体验差。
二、核心根因分析
1. 网络层面
公网域名访问内网 S3 会触发 DNS 解析、跨路由转发、防火墙及 NAT 校验，产生大量额外网络延迟。改用内网 IP 直连后，消除链路损耗，下载速度回归正常。
2. LibreOffice 工具局限
项目基于 LibreOffice + JodConverter 实现文档转换，该组合属于黑盒进程。当文档包含嵌套表格、公式、OLE 对象、畸形样式时，LibreOffice 极易陷入死循环、持续占用 CPU，只能依靠超时机制强制终止。
文件大小不等于转换难度：
-
大体积图片文档：结构简单，转换效率高
-
小体积复杂排版文档：表格/公式/嵌套多，解析运算量指数级增长
3. 读取模式差异
-
纯流模式：无磁盘 IO，速度快，但 S3 流式读取仅支持单次，复杂文档兼容性差
-
临时文件模式：增加磁盘读写，速度略有下降，但支持随机读取，稳定性更强
三、最终落地方案
1. 网络优化
统一修改配置，后端服务访问内网 S3 全部使用内网 IP 直连，彻底规避公网域名带来的路由、DNS、防火墙额外开销。
2. 代码逻辑优化
2.1 智能分流策略（以10MB为阈值）
-
文件 ≤ 10MB：纯流模式，最大化传输、转换速度
-
文件 > 10MB：落地为本地临时文件再转换，规避流式读取兼容问题
2.2 临时文件管控
转换完成后立即清理源临时文件，PDF 文件随程序退出自动删除，避免磁盘冗余。
2.3 异常与日志
捕获转换超时异常，向前端返回友好提示；全流程埋点日志，记录文件信息、运行模式、转换状态、清理结果，方便线上排查。
3. JodConverter 中间件配置优化
yaml
jodconverter:
local:
enabled: true
office-home: /usr/lib/libreoffice
port-numbers: [2002,2003,2004]
process-timeout: 300000 # 转换进程超时：5分钟
task-execution-timeout: 300000 # 任务执行超时：5分钟
max-tasks-per-process: 30 # 单进程最大任务数，自动重启防内存泄漏-
超时由 10 分钟下调至 5 分钟（基于线上复杂文档耗时统计的经验值，既能覆盖正常文档，又不会让用户等太久）
-
多端口部署，提升并发处理能力
-
限制单进程最大任务数，自动重启进程，解决 LibreOffice 长期运行的内存泄漏
四、关键结论与后续优化建议
-
工具局限：LibreOffice 无法提前检测高危文档，主流方案均为「执行转换 + 超时终止」
-
读写规范：小文件用流模式提速，大文件/复杂文档强制用临时文件保稳定
-
边界管控：限制最大转换文件为 500MB，提前过滤超大文件
-
前端体验：超时后统一提示「文档结构复杂，建议下载至本地查看」
-
运维监控：依托全链路日志统计转换耗时、文档类型、异常频次，后续归纳高危特征实现前置拦截
五、优化整体效果
| 维度 | 效果 |
|---|---|
| 网络 | 内网 IP 直连，文件下载速度恢复最优 |
| 功能 | 大小文件智能分流，兼顾速度与稳定性 |
| 异常 | 复杂文档 5 分钟自动终止，不长期占用线程 |
| 运维 | 全链路日志完整，问题定位高效 |
写在最后
本次存储迁移引发的转换异常，本质是网络链路、工具特性、文件读写模式三者叠加的综合故障。
面对开源组件的固有短板，无法从底层改造时，通过分层优化、策略分流、参数调优，也能在现有架构下把稳定性和体验做到最优。
本文是《技术底稿》系列第45篇，记录 Word 转 PDF 功能存储迁移后的全流程问题排查与优化落地过程。