文档转换服务

SuccBI提供两种方式来进行文档转换：纯JAVA转换和外部转换服务转换。外部转换服务使用documents4j (opens new window)来部署服务。

• 两种文档转换服务对比{#compare}
• 配置外部转换服务{#tools}
  • 安装office工具{#install-office}
  • 安装documents4j服务{#install-documents4j}
  • 在SuccBI系统设置中配置外部转换服务器地址{#succbi-settings}

两种文档转换服务对比

TIP

如果在系统中配置了外部转换服务器地址，则系统仅会使用外部转换服务来进行转换

对比	纯JAVA转换	外部转换服务转换
部署	系统内置，无需额外配置。会占用当前java进程一定资源	单独部署,需要在系统中添加配置
转换效率	转换效率较高，并发量大时依赖应用服务器集群配置	调用进程外服务进行转换，存在固定的通信开销。documents4j支持集群部署，当存在大量转换调用时可配置多个转换服务器组成集群
转换效果	存在一定失真	使用Office软件本身的转换功能，可以做到和在Microsoft office中导出PDF一样的转换效果

TIP

• 纯JAVA转换不支持修订，如果在文档中使用到了修订，请使用外部转换服务转换。

配置外部转换服务

安装office工具

Windows下安装Microsoft office不做介绍，以Centos为例，介绍Linux下安装Libreoffice。

保证外网访问正常，使用yum安装：

yum -y install libreoffice

等待安装成功后执行如下命令查找Libreoffice可执行文件所在路径：

whereis libreoffice

安装documents4j服务

下载后直接启动即可：

1. 点击这里 (opens new window)下载
2. 启动documents4j服务

java -jar succ-documents4j-server-standalone-1.1.4.jar http://192.168.7.123:9998 -W true

在保存有documents4j-server-standalone-shaded.jar文件夹中在启动命令行工具，执行上述命令，即可在监听端口9998开启服documents4j服务，这里-W true标识使用Microsoft office开启转换服务。该命令行支持指定服务器上下文地址，如 http://192.168.7.123:9998/context/。

TIP

• documents4j使用Microsoft office软件或者libreoffice (opens new window)的内置工具来进行转换，若都没有安装，则服务器将会启动失败。
• Microsoft office提供的转换效果要优于libreoffice。
• 只有在安装有Microsoft office 2010以上版本的Windows机器上才能使用Microsoft office。
• libreoffice软件的安装没有操作系统限制。
• 使用libreoffice软件时候，为了更好转换效果，请安装最新的版本。
• libreoffice软件对于并发的支持效果很差，并发进行多个文件转换操作时候，失败率非常高。
• 若同时开启了Microsoft office（命令行参数指定-W true）和libreoffice(命令行参数指定 -H {path})，documents4j服务将仅会使用Microsoft office。

命令行主要参数说明：

1. -W,--msoffice <boolean>: 是否服务器中安装有Microsoft office软件，如果指定为true，则默认使用Microsoft office软件做为转换服务，默认为false。
2. -H,--libreoffice-path <string>：服务器中安装libreoffice软件的可执行文件位置，若指定了这个参数，则会开启使用libreoffice的转换服务。
3. -F，--base-folder <FilePath>： 用于指定临时文件的创建地址，如果不指定，将使用操作系统默认指定的临时目录。
4. -P，--process-timeout <long>：执行一次转换的超时时间，单位为毫秒，默认值为300000。
5. -R，--request-timeout <long>：响应一起http请求的超时时间，单位为毫秒，默认值为。120000。
6. -S，--core-size <interger>：转换服务的核心线程数量，默认为15。
7. -B，--fallback-size <interger>：当所有核心线程都处于工作状态，需要添加新的工作线程时，一次性创建的线程个数，默认为15。
8. -T，--lifetime <long>：非核心线程的空闲时间，单位为毫秒，默认值为600000。
9. -V，--level <long> 日志级别，可被设置的值有 off，error，warn，info，debug和 trace，默认值和建议设置的值为warn。
10. -L,--log <FilePath>：指定记录日志文件位置，但是只能指定一个，可能会导致这个日志文件增长到非常大。默认打印在控制台。

在SuccBI系统设置中配置外部转换服务器地址

在 系统设置 > 更多 > 外部服务 > 文档转换 中配置文档转换服务器地址:

服务器地址需要为SuccBI服务器可访问到的地址，可以是内网IP加端口号的组合：http://192.168.1.2:9998，也可以是域名：https://example.com。请务必要带上http://或者https://用于指定协议，避免出现访问不正确的问题。