CKEditor集成PDF转图片与文本：军工OA内网部署实战解析

去年我配合一个军工单位的OA系统做二次开发需求方提了一个很具体的要求在CKEditor富文本编辑器里用户上传PDF文件后系统要能自动把PDF内容转存成图片和文本方便编辑正文时直接预览而不是让每个人下载后打开看。而且还明确交代了一句话所有转换功能必须部署在内网不能调外部接口数据流一步都不能出内网。这个需求听起来不复杂无非是“编辑器上传PDF”加“后端做转换”两个事。但实际做下来才发现军工单位的内网环境、安全管控和软件版本限制每一环都能卡住人。从CKEditor的版本选择、上传适配器的写法到PDF转图片的渲染方案、图片回显的权限校验我前后改了三四版才跑通。今天把完整配置过程和踩坑记录整理出来希望对正在做同类OA集成的朋友有帮助。1. 军工OA环境下的特殊约束与方案选型1.1 内网隔离带来的最大限制军工单位的OA系统通常部署在物理隔离的内网互联网访问被严格限制外部API、云存储、在线转换服务一律不可用。这意味着PDF转存功能的所有能力都必须自给自足转换服务本地部署字体库本地准备依赖包提前下载好通过内网私服或离线包安装。我一开始习惯性地想用某个在线转换接口来解析PDF需求方直接否了理由很简单涉密信息不能出内网。所以在方案设计阶段就要把这个约束刻在脑子里不要抱任何“外网通道可以临时开一下”的幻想。所有转换逻辑必须落在内网服务器上并且转换过程尽量不落在临时目录而是直接在内存流中处理减少中间文件的存在时间。1.2 安全合规要求对文件处理的影响军工OA对文件的安全要求比普通企业更严格通常涉及三方面上传文件的类型校验、访问权限控制、操作审计日志。PDF文件虽然常见但伪装成PDF的可执行文件、带恶意脚本的PDF也不少。上传接口不能只看扩展名必须校验文件头的魔数。PDF文件头通常是%PDF-对应十六进制是25 50 44 46 2D后端拿到文件流后先检查前几个字节再用PDF解析库尝试打开打开失败的直接拒绝。这个校验不能省我见过不少只校验扩展名的企业系统被假PDF文件绕过。文件上传后还要考虑权限模型。同一份文件不同科室或不同密级的人员可能看到的都不同。OA系统本身有组织权限体系转存后的图片和文本文件也要跟OA附件系统的权限打通不能出现附件直链可访问的情况。最稳妥的做法是转换后的文件不暴露物理路径统一通过OA的附件下载接口做权限校验后再输出。1.3 CKEditor选型4代还是5代军工行业的OA系统很多还是老平台老架构泛微E-cology、致远OA、万户等都有不少存量客户。这些系统的编辑器版本参差不齐有的是CKEditor 4.x系列有的已经升级到CKEditor 5还有一部分是国产化了基于CKEditor 4深度定制的版本。CKEditor 4和CKEditor 5在架构上差别很大文件上传的接入方式完全不同。CKEditor 4用的是filebrowserUploadUrl加上传窗口的配置CKEditor 5用的是CustomUploadAdapter也就是自定义上传适配器。做方案前一定要先确认OA平台里到底是哪个版本否则配置写完了可能完全不生效。我的建议是对老系统尽量沿用CKEditor 4不要为了这个功能升级编辑器。升级成本太高而且老平台里往往堆了大量自定义插件冒然升级会引发兼容性问题。对新系统或自研平台可以直接用CKEditor 5官方文档更全集成方式也更现代。1.4 PDF转存方案选型为什么不上外网APIPDF转存到了选型阶段常见的无外乎三种思路调用外网转换API比如各种云服务商提供的PDF转换接口。这条在军工内网直接走不通。服务器本地部署转换服务用开源的PDF解析和渲染库把PDF转成图片和提取文本。借助办公软件本身的能力比如LibreOffice无头模式、Windows服务端打印组件把PDF虚拟打印成图片。这条在纯Linux服务器上配置麻烦而且军工环境很多是国产化服务器和操作系统虚拟打印不一定好使。实际落地时我选择了第二条路线Java后端加上Apache PDFBox和PDF.js的组合。PDFBox负责解析PDF页面并渲染成图片PDF.js负责在前端做精细化的分页预览能力文本提取则可以用PDFBox自带的PDFTextStripper。如果服务器上不方便装额外的渲染库PDFBox 2.x版本的PDFRenderer已经够用输出图片清晰度完全能满足OA预览需求。2. CKEditor富文本编辑器集成PDF上传2.1 基础集成与工具栏定制我这次做的系统是自研OA用的CKEditor 4.17原因是系统里已经集成了一堆基于CKEditor 4的定制插件不能动。基础引入很简单script src/oa/static/ckeditor/ckeditor.js/script初始化的时候把上传按钮放到工具栏并指定上传URLCKEDITOR.replace(editor-content, { filebrowserUploadUrl: /oa/attach/upload?typefile, toolbar: [ { name: insert, items: [Image, Table, Flash, Link, Upload] }, { name: basicstyles, items: [Bold, Italic] }, { name: document, items: [Source, Preview] } ], height: 480 });filebrowserUploadUrl是CKEditor 4的上传接口配置编辑器会把这个地址拼在动态创建的iframe表单里提交上传后回调返回一个HTML脚本格式有固定要求后端接口必须按CKEditor的规范返回。在CKEditor 5里对应的则是Adapter的upload方法逻辑上类似但写法更符合现代开发习惯。有一个容易忽略的细节filebrowserUploadUrl是所有文件类型共用的上传入口图片、PDF、附件都打到同一个接口。军工OA里最好对资源类型做区分比如上传图片走/oa/attach/uploadImage上传PDF走/oa/attach/uploadPdf这样后端可以对PDF文件单独做扫描和转换不至于把所有逻辑都堆在一个接口里。2.2 文件上传后端接口适配CKEditor 4的上传接口返回格式是固定的必须在返回的HTML中调用window.parent.CKEDITOR.tools.callFunction带上传后的文件URL。示例代码PostMapping(/oa/attach/uploadPdf) public void uploadPdf(MultipartFile file, HttpServletResponse response) throws IOException { // 校验文件类型 byte[] header new byte[5]; file.getInputStream().read(header, 0, 5); String headerHex bytesToHex(header); if (!255044462D.equalsIgnoreCase(headerHex)) { returnError(response, 文件格式错误仅支持PDF); return; } // 安全检查文件大小、内容扫描这里省略杀毒软件对接 if (file.getSize() 50 * 1024 * 1024) { returnError(response, 文件大小不能超过50MB); return; } // 保存到附件服务器 String fileId attachService.save(file); // 异步或同步调用PDF转存服务 pdfConvertService.convertAndStore(fileId, file); // 返回CKEditor要求的HTML脚本 String callback request.getParameter(CKEditorFuncNum); String url /oa/attach/access/ fileId; String script script typetext/javascript window.parent.CKEDITOR.tools.callFunction( callback , url , ); /script; response.setContentType(text/html;charsetutf-8); response.getWriter().write(script); }函数的返回格式要严格按照CKEditor的约定来第2个参数是资源URL第3个参数是错误消息没有错误就传空字符串。很多自研OA系统接入CKEditor时第一次总是报“上传失败”其实就是返回格式不对编辑器无法解析。安全方面MultipartFile拿到文件流后不要直接保存先做魔数校验再做大小校验再做病毒扫描对接内网的杀毒引擎最后才允许落盘。落盘时文件名不要用原始文件名而是用UUID或雪花ID重命名避免路径穿越和重名覆盖。2.3 上传限制与安全防护配置军工内网OA系统的文件安全要求严格不能只做最基本的扩展名校验。我在这块做了五层防护扩展名校验只用白名单不允许黑名单方式。文件头魔数校验PDF的固定头判断是否真实PDF。大小限制默认限制50MB超过的直接拒绝。这个限制要根据实际业务调整军工行业常有大型技术文档的PDF太小容易误伤。内容扫描对接内网病毒扫描服务上传文件先过一遍杀毒再转存和预览。存储路径不透明文件保存路径包含随机目录名不让用户直接猜地址访问。前端也要做对应的限制在CKEditor配置里增加allowedContent和文件过滤CKEDITOR.replace(editor-content, { filebrowserUploadUrl: /oa/attach/uploadPdf, uploadFile: { types: [pdf], maxSize: 50 * 1024 * 1024 } });注意前端限制只是为用户体验服务的真正的安全校验永远在后端。有人会绕过前端直接POST到上传接口前端限制拦不住任何有恶意意图的人。2.4 泛微OA等国产化平台的特殊适配泛微E-cology在军工行业占有率不低它的编辑器默认并不是CKEditor而是基于百度UEditor或自己封装的富文本组件。但很多二次开发项目会单独集成CKEditor有的通过泛微的“集成器”功能有的直接在表单模板里改HTML代码。如果是在泛微E9、E10里集成CKEditor需要注意几点泛微的action URL通常要以/api/ec/dev/...开头需要查看集成器生成的请求路径不要自己想当然。泛微的session校验很严格单独调用上传接口时容易丢失登录态需要在请求头里带上X-Requested-With和Cookie。我出现过上传接口偶发性401的问题就是因为跨域请求没有带session。E9有“附件服务器”和“文档服务器”两个概念转存后的PDF预览文件最好独立存到文档服务器的隔离目录不要跟业务附件混在一起不然后续清理会很麻烦。如果系统是国产化服务器比如麒麟、统信加国产数据库达梦、人大金仓PDF转存服务里与文件系统、数据库的交互方式也要提前确认。数据库的Blob存取接口在不同数据库上差异不小用Java的InputStream方式通用性更好。3. PDF转存服务的核心实现3.1 转换服务技术选型与对比PDF转图片的方案我在实际项目中对比过几套技术各有优劣。军工OA的服务器配置通常不会太高转换服务要控制内存和CPU占用不能因为一个超大PDF把整个服务拖垮。方案优点缺点适用场景Apache PDFBox纯Java实现部署简单无需安装额外软件对复杂排版PDF渲染效果一般文字颜色和图片混合页面可能失真OA预览、内页缩略图Ghostscript渲染精度高处理复杂PDF最稳需要安装系统级依赖维护成本高高精度页面图片ImageMagick功能全面可批量处理转换PDF仍依赖Ghostscript间接增加部署复杂度其他格式混转比较多的情况LibreOffice无头模式可处理Office转PDF再转图片无法直接处理已有PDF链路长资源占用高需要同时处理Office和PDF的场景我的建议是核心链路用PDFBox把Ghostscript作为备选增强方案。PDFBox对大多数OA场景的PDF已经够用而且纯Java部署方便后续切换到国产化服务器时不用额外装系统包。3.2 接口设计与参数调优转存接口根本不用做的花哨直接面向内部调用即可。核心参数有fileId附件ID转换服务从附件服务器读取文件。pageRange可选指定转换哪些页。dpi渲染分辨率决定图片质量。withText是否提取文本层。示例接口PostMapping(/api/pdf/convert) public Result convertPdf(RequestParam String fileId, RequestParam(defaultValue 0) int startPage, RequestParam(defaultValue 0) int endPage, RequestParam(defaultValue 144) int dpi, RequestParam(defaultValue true) boolean withText) { // 读取PDF文件 PDDocument document PDDocument.load(attachService.getFileStream(fileId)); // 计算页数 int totalPages document.getNumberOfPages(); int end endPage 0 ? totalPages : Math.min(endPage, totalPages); // 逐页渲染 PDFRenderer renderer new PDFRenderer(document); ListString imageUrls new ArrayList(); for (int i startPage; i end; i) { BufferedImage image renderer.renderImageWithDPI(i, dpi); String imageUrl imageStore.save(image, jpg); imageUrls.add(imageUrl); } // 提取文本 String textContent ; if (withText) { PDFTextStripper stripper new PDFTextStripper(); stripper.setStartPage(startPage); stripper.setEndPage(end); textContent stripper.getText(document); } document.close(); return Result.ok(new PdfConvertResult(imageUrls, textContent, totalPages)); }几个关键参数要特别说明DPI设置默认我用的144换算下来每英寸144像素比屏幕72dpi高一倍在OA预览场景足够清晰图片大小也能控制。如果PDF页面是文字为主96dpi基本够用如果包含精细的工程图纸要开到200以上。DPI越大生成图片越大内存消耗也越大要综合考量服务器配置。内存控制PDFBox渲染大尺寸页面时非常吃内存尤其是页面尺寸超过A3的图纸。建议在JVM参数里增加堆内存设置同时给转换接口做线程限制用Semaphore或线程池限制并发数。我这边给的是2个并发多出来排队防止PDF转换把OA应用拖死。超时控制转换接口如果同步处理建议在网关层或调用方设置超时时间。大型PDF转换可能耗时几十秒到几分钟前端不能一直干等。通常的做法是接口里提交任务后立即返回taskId前端轮询查询转换进度转完后再刷新预览。3.3 转存存储与附件系统对接转存没有“存”这步预览就无法实现所以存储设计很重要。转换后的图片和文本分发到两个位置图片放到文件服务器的专用目录文本内容存入数据库字段、便于检索。图片的路径结构建议用/{fileId}/{page}_page.jpg这种布局方便按页加载。存储路径不要暴露物理地址前端拿到的应该是经过权限网关的访问URL比如/oa/attach/access/{fileId}?page1这个路径后端统一做权限判断、校验用户是否能看到该附件然后输出图片流。好处是文件本身存储位置可以随时迁移而且可以统一加访问审计和动态水印。军工OA还有一点要特别注意属性文件与审计日志。转存操作本身要记录日志操作人、操作时间、文件ID、转换页数、转换结果。出了问题能倒查这是安全合规的硬要求。日志不要只记“成功”失败日志要记录失败原因方便排查。涉密文件转存后如果出现异常至少能定位到哪个环节出的问题。3.4 批量转存与定时任务处理除了编辑器里的实时上传军工OA还经常遇到批量导入的场景比如一批技术文档要挂到某个项目下几十个PDF一次性导入。这种场景不能在请求里同步转换必须做成异步任务。设计一个简单的convert_task表转换服务定时扫描待处理任务CREATE TABLE convert_task ( id BIGINT PRIMARY KEY, file_id VARCHAR(64), status TINYINT DEFAULT 0, -- 0待处理 1处理中 2成功 3失败 total_pages INT DEFAULT 0, create_time TIMESTAMP, finish_time TIMESTAMP );定时任务每次拉取100条待处理记录逐个处理更新状态。任务失败的要记录错误码和错误消息并对失败任务设置重试上限避免死循环。定时任务实现时我用了Scheduled加上一个简单的分布式锁防止多实例部署时任务重复执行。军工OA的服务器集群规模一般不大但多实例部署很常见不加锁会出现重复转换的浪费。4. 前端回显与完整交互链路4.1 上传后PDF预览的交互设计PDF转存完成后编辑器里插入的内容不是PDF文件本身而是图片序列。用户点开附件直接在正文里看到PDF每一页渲染后的图片这个视觉交互比下载打开文件舒服得多。在CKEditor 4里PDF上传成功后会插入一个自定义div或者图片占位符。我用的方式是插入一个包含PDF预览容器的div往里塞几个关键信息fileId、总页数、当前显示页。CKEditor源码模式下看到的是一段HTML渲染后就是PDF预览组件。div classpdf-preview>script src/oa/static/ckeditor/ckeditor.js/script script CKEDITOR.replace(content, { filebrowserUploadUrl: /oa/attach/uploadPdf?typepdf, toolbar: [ { name: document, items: [Source, -, Preview] }, { name: insert, items: [Image, Table, -, Upload] } ], height: 500, allowedContent: { $: { // 允许自定义div属性 attributes: data-file-id,data-total-pages,data-page,class,id } } }); /script后端关键过滤器伪代码Component public class SecurityFilter implements Filter { Override public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) { // 1. 校验登录token // 2. 校验URL是否在白名单内如登录页、静态资源 // 3. 校验请求来源是否在内网IP段内 // 4. 对附件访问接口做权限校验 // 5. 记录审计日志 chain.doFilter(request, response); } }OA附件表结构建议CREATE TABLE oa_attach ( id BIGINT PRIMARY KEY COMMENT 主键, file_name VARCHAR(255) NOT NULL COMMENT 原始文件名, store_path VARCHAR(512) NOT NULL COMMENT 存储路径, file_size BIGINT DEFAULT 0 COMMENT 文件大小, file_type VARCHAR(32) DEFAULT pdf COMMENT 文件类型, pdf_total_pages INT DEFAULT 0 COMMENT PDF总页数, convert_status TINYINT DEFAULT 0 COMMENT 转存状态, create_user VARCHAR(64) COMMENT 创建人, create_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT 创建时间 );我一个人做这套功能的时候从设计到联调花了三周其中一半时间花在适配不同PDF格式和排查兼容性问题上。CKEditor的配置本身并不难真正的复杂度在它的外围——文件系统、转换引擎、缓存机制、权限控制这些都不在编辑器里但缺一个环节功能就跑不完整。最后分享一个小的经验军工OA环境做这种文件处理类功能最忌讳的是依赖服务器上“临时装一下”的东西。环境是封闭的今天能装明天系统升级可能就没了。PDF转换涉及的依赖和字体文件最好在项目实施文档里明确写出来连同部署包一起交给运维而不是口头说“到时候我装一下”。这样后续维护升级时别的同事接手也能顺利跑起来不至于变成了只有你一个人知道怎么做的“黑盒”。