信创环境下PageOffice文档控件适配与实践
信创项目的推进顺序,通常是"底座—应用—外设":先换芯片和操作系统,再改造 OA、公文、合同这些业务系统,最后联调打印机、扫描仪、高拍仪。夹在应用与外设之间,还有一类东西因为太寻常而被漏掉——文档控件。
在 Windows 上,网页里直接编辑文件是理所当然的能力。做 OA、公文、合同系统的团队,随手就能找到现成的控件:嵌进网页,用户点"编辑",Word 就在浏览器里打开,改完保存,文件原样回到系统。用户和甲方都习以为常——网页里能直接改文件,本来就该是这样,没有人会把它当成一个需要专门解决的问题。
换到国产操作系统,这条链断在中间。芯片、操作系统、办公套件都换成了国产的,但"把本地 WPS 接进网页"的那一层——文档控件——在国产环境里长期是缺位的。没有这一层,OA 能做的只剩最原始的流程:把文件下载到本地,用 WPS 打开、修改,再手动上传回系统。
退回去的代价不只是多几次点击。改了什么、改的是不是最新版、有没有人绕过流程动了正文,系统都无从知晓;会签、留痕、套红、盖章这些依赖"文档始终在系统里"的设计,在"下载—上传"之间全部落空。底座换完了,应用层的在线编辑却退回单机时代——信创推进到这一步,只完成了"换电脑",没有完成"能办公",最后一公里并没有走通。
PageOffice 国产版补的正是这一环:用户在网页里点开公文,PageOffice启动本地WPS打开那份 .docx,改完保存,文件直接回到系统,不必再下载、上传。信创项目缺的那最后一公里,到这里才算走完。
本文不谈概念,只谈适配:一个文档控件在信创环境下要同时对准哪几层,哪几处最容易出问题,以及一个项目从 Windows 单轨走到双轨、再走到国产单轨,实践上可以按什么顺序推进。
一、适配的重心,其实在客户端
把"国产化适配"理解成"把 exe 重新打成 deb",是项目里最常见的误判;另一种误判则是把面铺得太开,以为服务器端也要重新适配一遍。实际情况恰好相反:PageOffice 的服务端本来就不挑平台——Windows Server、Linux、国产信创服务器环境都能部署,Tomcat、Jetty、IIS、Resin、JBoss、WebSphere、WebLogic 等常见 Web 服务器也都在支持之列,中间件与 JDK 的版本随业务系统自身走即可。所以国产化适配真正要谈的,是客户端这一侧的国产化,服务器端不必再单独考虑;那边要做的是常规的集成配置,交给下一节讲。
要花力气的都在客户端:终端换成统信 UOS、银河麒麟,办公套件换成 WPS,芯片从以 x86 为主变成 X86_64、ARM64、LoongArch64、MIPS64 多种架构并存,浏览器也从 IE 系换成 Chromium 系。这些变化叠在一起,才是"适配"三个字的分量所在。往下分三层说。
第一层,操作系统与芯片。 国产版支持统信 UOS、银河麒麟,配合金山 WPS 使用,芯片架构覆盖 X86_64、ARM64、LoongArch64、MIPS64 四种。四种架构与两种系统两两组合,意味着八个 deb 安装包,这是后面所有"装不上"问题的主要来源。
第二层,文档内核。 编辑的到底是本地 WPS 打开的 .docx,还是被转成 HTML 再渲染的网页副本,决定了版式和打印能不能过关。PageOffice 调用本地 WPS,文档是"真文档",版式与打印由 WPS 直接保证,不需要在转换环节做任何补偿。
第三层,浏览器与插件机制。 国产终端上的浏览器基本都基于 Chromium 内核,早期那套插件机制已经退场——文档控件以什么方式进入浏览器,是这一层要回答的问题,后面单独说。
二、服务端:一套代码,两类终端
PageOffice 的开发团队从 2019 年开始重新研发国产版本,与 Windows 版分属两套架构——官方也明确说明,Windows 版的程序代码在国产操作系统环境下几乎不能复用,因此两个版本分别开发、分别定价、分别授权。
但对集成商来说,关键结论只有一句:服务端代码只有一套。 两个版本的服务器端被合并成一个组件(Java 平台就是同一个 jar 包),服务端接口完全相同;客户端封装的 JS 接口也几乎完全相同。这意味着业务系统里那段"打开文档、赋值、保存"的逻辑,不需要为两类终端写两个分支。
适配的工作量不在业务代码,而在分发:把安装包放进 PageOffice 的系统文件夹(SysPath),客户端打开文档时,由控件按自身平台取用对应的那一份:
SysPath(存放 license 与客户端安装包)
├─ license.lic ← Windows 版注册后生成
├─ license_gc.lic ← 国产版注册后生成
├─ posetup_6.7.0.1.exe ← Windows 客户端
└─ com.zhuozhengsoft.pageoffice_6.7.0.1_amd64_kylin.deb
com.zhuozhengsoft.pageoffice_6.7.0.1_amd64_uos.deb
…(按现场「架构 × 系统」各拷一份)
Spring Boot 项目里的配置就是设置这个目录,再把必要的 Servlet 注册上:
Server poserver = new Server();
poserver.setSysPath(poSysPath); // license.lic 与客户端安装包所在目录
ServletRegistrationBean srb = new ServletRegistrationBean(poserver);
srb.addUrlMappings("/poserver.zz");
srb.addUrlMappings("/poclient");
srb.addUrlMappings("/pageoffice.js");
有一处容易漏:从 V6.6 起,服务端通信改走 WebSocket,使用 Spring Boot 内嵌容器(Jar 包部署)时必须额外注册 ServerEndpointExporter,并配置 powserver-allowedOrigins 允许的来源;War 包部署在外部容器里则不需要。官方示例里专门标注了"内嵌容器必须注册"这句话,老项目升级到 6.6 以上时,最容易被连带漏掉的就是这一段配置。
配套要求也一并记在方案里:6.6.1.1 及以上版本要求 JDK 1.8+、Tomcat 8.5+、ASP.NET Core 3.1、.NET 5.0+;仍在 ASP.NET Framework 上的老项目需要提前评估。
注册环节也要提醒一句:Windows 版与国产版是两套授权,双轨期需要在同一个 SysPath 下分别注册,生成 license.lic 与 license_gc.lic 两个文件。一次注册即可覆盖该平台的所有终端,与终端数量无关。
三、客户端:安装包按「系统 × 芯片」分发,升级跟着服务端走
国产终端上的客户端安装,用户不需要自己去找安装包。在浏览器里点开文档,控件检测到未安装就会提示,下载、安装、注册一气呵成;客户端程序做了代码签名,内网离线环境同样适用,因为安装包就在单位自己的服务器上,不经过任何公网链路。
前提是服务端先把对应的安装包准备好。这一步不需要实施人员自己打包、自己命名——下载中心按版本把每个平台的客户端列成一张固定的清单,文件名由"产品名_版本号_架构_系统"拼成,照抄即可。国产终端上,四种芯片架构与两种操作系统两两组合,一共 8 个 deb 包:
| 芯片架构 | 银河麒麟 | 统信 UOS |
|---|---|---|
| amd64 | …_amd64_kylin.deb |
…_amd64_uos.deb |
| arm64 | …_arm64_kylin.deb |
…_arm64_uos.deb |
| loongarch64 | …_loongarch64_kylin.deb |
…_loongarch64_uos.deb |
| mips64 | …_mips64_kylin.deb |
…_mips64_uos.deb |
(表内省略了统一前缀 com.zhuozhengsoft.pageoffice_6.7.0.1_;Windows 端是单文件 posetup_6.7.0.1.exe。版本号按项目实际部署的版本取,文件名其余部分不可改。)
于是要人工把关的只有两件事。
一是按"系统 × 架构"盘终端,而不是只盘架构。同样是 ARM64,麒麟与 UOS 是两个包,装错系统装不上;现场两种系统都有,就两个都要拷进 SysPath。多放几个包不影响其他终端使用,少放一个,对应终端就装不上。
二是别改名。这套文件名是客户端识别平台、服务端分发安装包的依据,改成 pageoffice-uos-arm.deb 之类好记的名字,就对不上了。升级时也一样:换新版本号的文件,保留原名。
升级本身是自动的:服务端换了 PageOffice 版本,SysPath 里换成新版本号的同名文件,客户端就会按服务器端版本号发现更新并自动跟进,不需要运维逐台重装。对动辄几千个终端的单位,这一点比安装本身更重要。
顺带把边界说清楚,免得方案里写进不该有的期待:PageOffice 客户端在 Mac 电脑上会直接提示不支持;国产版目前是面向信创环境的企业版形态。
四、文档内核层:调本地 WPS,编辑真文档
国产终端的办公软件配置是既定的:客户端电脑上装的就是金山 WPS,微软 Office 不在信创终端的软件清单里,也无处可装。所以这一层不存在"选哪个 Office"的取舍——PageOffice 国产版做的,就是把这台机器上的 WPS 调起来,打开那份 .docx,用户在网页里改的就是文件本身。
由此得到的第一个结果是版式不需要"还原",它本来就是对的。字体、行距、页码、表格线、页边距全部由 WPS 计算,不存在"网页上看着好好的、打印出来全乱了"的转换失真;红头文件的版记位置、成文日期,也不需要额外补偿。这正是 HTML 转换路线最难补齐的地方。
第二个结果是能力边界清楚。用户在浏览器里用到的就是 WPS 的能力,不需要另学一套操作;该由系统管住的也仍然管得住——只读打开、只允许改指定区域、强制留痕,都由服务端在打开文档之前下发,不依赖用户在使用中自觉。
五、浏览器层:插件机制退场之后
在国产终端上,浏览器这一层的问题和 Windows 上不是同一类。Windows 上要问的是"装了哪个浏览器、什么版本";国产终端上要问的是一个更底层的问题——文档控件以什么方式进入浏览器。
国产终端上的浏览器基本都基于 Chromium 内核,而 Chromium 从 45 版起就停止支持 NPAPI 插件,之后的版本更把相关代码从源码里删掉。国产浏览器为了兼容存量业务系统,又把这块能力补了回来,代价是每跟进一次内核升级,就要重新把 NPAPI 适配一轮。摆在厂商面前的选择只有两个:停在某个内核版本不再升级,或者最终放弃 NPAPI。
对文档控件来说,这意味着把"能不能打开文档"押在宿主浏览器的插件接口上,越来越不划算:接口随时可能消失,而消失的时间点不由项目决定。可行的路线是让控件自带运行环境,用产品自己的窗口承载页面与控件,不再经过宿主浏览器的插件接口。PageOffice 6 走的就是这条路。这样一来,浏览器怎么升级、是否保留 NPAPI,都不再是业务系统的风险项;前端仍是标准 Web 页面,调用的仍是原来那套 JS 接口,业务代码不用改。
需要提前和业务方对齐的只剩交互形态:文档在独立窗口中打开,而不是嵌在宿主页面的 iframe 里,弹窗尺寸、关闭后回跳、与主页面的传值这些细节,要在方案阶段定下来。
六、一份可执行的适配验收清单
把上面的内容收拢成可执行的顺序,迁移项目大致按这八步走:
- 环境盘点:终端操作系统与芯片分布、WPS 版本、浏览器版本;服务器操作系统、JDK 与中间件版本。
- 安装包齐备:
posetup_<版本>.exe与现场涉及的「架构 × 系统」deb 包,按固定文件名放入 SysPath,不要改名。 - 双版本注册:分别在 Windows 终端与国产终端完成注册,确认
license.lic与license_gc.lic均已生成。 - 功能等价性验证:打开、编辑、保存、只读、局部编辑、强制留痕、模板套红、盖章、打印,逐项在两类终端上对比。
- 版式与打印抽检:用真实红头文件核对版式,并做一次实际打印比对。
- 浏览器验证:在国产浏览器上确认文档能在 PageOffice 自带窗口中正常打开、打印可用;双轨期的 Windows 终端也必须实测一遍。
- 灰度与回退:先在一个处室或一批终端上跑通,再全量推进;保留回退到上一版本服务端的能力。
- 升级链路验证:服务端升版后,观察客户端是否按版本号自动更新,而不是靠人工通知。
七、结语
信创适配做到文档控件这一层,拼的已经不是"有没有国产版本",而是同一个功能在两类终端上是否真的等价。等价的标准很具体:同一次点击能得到同样的结果,同一份公文能得到同样的版式,同一个项目不需要维护两套代码。
这背后是三件并不轻松的工作:服务端用一套接口同时支撑两类终端,客户端把两种系统与四种芯片的安装包分发清楚,文档内核层由产品侧跟着 WPS 的版本走。浏览器这一层的压力,则被收进了产品自己的窗口里——升级节奏由产品掌握,不再交给运气。这些工作用户看不见,却直接决定"在线编辑"这个按钮在国产终端上是有用的,还是只是一个摆设。
对集成商来说,交付物因此可以简化成一句话:一套集成代码、一份验收清单,覆盖 Windows 与国产两类终端。 授权上仍需按平台分别采购——单位同时有 Windows 终端和国产终端时,Windows 版与国产版各买一套;但技术方案与维护分支只需要准备一套。省下来的不是采购预算,而是长期的适配人力。
参考文档(PageOffice 开发者中心与下载中心):
- PageOffice 介绍(含运行环境与版本说明)
- 在 Web 项目里同时部署 Windows 版和国产版
- PageOffice 最简集成代码(Spring Boot)
- 打开保存文件的执行流程(工作原理)
- 关于浏览器升级至 Chrome 142 / Edge 143 后导致客户端误报未安装的说明
- 版本更新记录
- 客户端与安装包下载(PageOffice 开发者中心)
- 各平台客户端安装程序清单(下载中心)
- 文档索引
(本文技术细节以开发者中心当期文档为准,核对版本为 6.7.0.1;客户端安装包版本以项目实际部署为准。)
浙公网安备 33010602011771号