---
order: 5
navTitle: 文档转换服务
---
# 文档转换服务

SuccBI提供两种方式来进行文档转换：`纯JAVA转换`和`外部转换服务转换`。外部转换服务使用[documents4j](https://github.com/documents4j/documents4j)来部署服务。

\[\[toc]]

## 两种文档转换服务对比{#compare}

::: tip
如果[在系统中配置了外部转换服务器地址](#在succbi系统设置中配置documents4j服务器地址)，则系统仅会使用`外部转换服务`来进行转换
:::

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

::: tip

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

:::

## 配置外部转换服务{#tools}

### 安装office工具{#install-office}

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

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

```bash
yum -y install libreoffice
```

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

```bash
whereis libreoffice
```

### 安装documents4j服务{#install-documents4j}

下载后直接启动即可：

1. 点击[这里](https://www.jianguoyun.com/p/DdsbrEIQ3O-gChid5KwE)下载
2. 启动documents4j服务

```bash
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](https://www.libreoffice.org/)的内置工具来进行转换，若都没有安装，则服务器将会启动失败。
- `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-settings}

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

![settings](./images/2022-08-18-17-53-00.png)

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