PDFreactor Docker镜像技术文档

1. 镜像概述和主要用途

PDFreactor是一款强大的格式化处理器，支持从HTML 5文档进行服务器端PDF转换，使用CSS定义页面布局和样式。该Docker镜像提供即用型PDFreactor Web Service，可通过REST API将HTML转换为PDF，适用于动态生成报告、发票、对账单等PDF文档。

2. 核心功能和特性

• 服务器端HTML转PDF：支持HTML 5文档的服务器端PDF转换，无需客户端依赖。
• W3C标准支持：实现W3C Paged Media和打印规范，通过CSS精确控制分页输出。
• 灵活的页面控制：通过CSS设置页面大小、边距、分页规则，自定义页眉页脚。
• PDF文档增强：支持添加PDF元信息（作者、关键词）、生成文档大纲和链接。
• REST API与多语言包装器：提供REST API，并支持Java、JavaScript、.NET、Node.js、PHP、Python、Ruby等语言的API包装器。
• 可配置性：支持自定义字体、许可证管理、服务器参数调整（如线程池大小、内存配置）。

3. 使用场景和适用范围

• 动态文档生成：企业系统中动态生成财务报告、发票、对账单、合同等业务文档。
• Web内容打印：将网页内容（如报表、表单）转换为格式一致的PDF用于存档或分发。
• 集成系统：与CMS、CRM、ERP等系统集成，提供PDF导出功能。
• 开发与测试：快速部署PDF转换服务，用于开发环境中的功能验证。

4. 使用方法和配置说明

4.1 基本运行

通过以下命令启动PDFreactor Web Service容器，将容器内端口9423映射到主机端口（如8080）：

sh
docker run -d -p 8080:9423 realobjects/pdfreactor

服务启动后，可通过主机端口（如8080）访问REST API。例如，使用JavaScript客户端连接：

javascript
var pdfReactor = new PDFreactor("[***]");

4.2 高级配置

4.2.1 卷映射与用户权限

推荐将主机目录映射到容器内/ro/config目录，用于管理许可证、字体和配置文件：

sh
docker run -d -p 8080:9423 -v /your/config:/ro/config realobjects/pdfreactor

权限说明：容器内服务以用户pdfreactor（组ID 555）运行。若需服务对映射卷有写权限，需确保主机目录可被组ID 555写入（通常对应主机docker组，可将目录权限设置为组可写）。如需精细权限控制，可使用Docker用户命名空间。

4.2.2 许可证设置

PDFreactor默认以评估模式运行，需通过许可证文件激活正式版：

1. 将许可证文件命名为licensekey.txt。
2. 放置于映射到/ro/config的主机目录中（容器内路径为/ro/config/licensekey.txt）。

获取许可证：商业环境需申请评估许可证或购买许可证。

4.2.3 自定义字体

PDFreactor会自动加载/ro/config/fonts目录下的字体文件。添加自定义字体步骤：

1. 在映射到/ro/config的主机目录中创建fonts子目录。
2. 将字体文件（如.ttf、.otf）放入该目录，服务会自动识别。

4.2.4 服务器配置

配置文件

通过pdfreactorwebservice.config文件设置服务器级参数（影响所有转换任务），需放置于/ro/config目录（或直接映射文件：-v /your/config/pdfreactorwebservice.config:/ro/config/pdfreactorwebservice.config）。

Java环境变量

通过JAVA_OPTIONS环境变量设置内存分配和Java系统属性，例如：

sh
docker run -d -p 8080:9423 -e JAVA_OPTIONS="-Xmx2g -Dcom.realobjects.pdfreactor.webservice.threadPoolSize=4" realobjects/pdfreactor

• -Xmx2g：设置最大堆内存为2GB。
• -Dcom.realobjects.pdfreactor.webservice.threadPoolSize=4：设置线程池大小为4。

4.3 Docker Compose示例

使用docker-compose.yml配置服务，示例如下：

yaml
version: '2'

services:
  pdfreactor:
    container_name: pdfreactor
    ports:
      - "86:9423"  # 主机端口86映射到容器端口9423
    image: "realobjects/pdfreactor"
    environment:
      JAVA_OPTIONS: "-Xmx2g -Dcom.realobjects.pdfreactor.webservice.threadPoolSize=4"  # Java配置
    volumes:
      - /path/to/host/config:/ro/config  # 映射配置目录（含许可证、字体、配置文件）

启动命令：docker-compose up -d

5. 许可信息

• 商业软件：镜像中包含的“PDFreactor Web Service”为商业产品，受PDFreactor Web Service软件许可协议约束。生产环境使用需获取有效许可证。
• 评估与购买：可申请评估许可证或购买许可证。
• 第三方许可：镜像内/ro/pdfreactor/license目录包含第三方许可信息。

PDFreactor是RealObjects GmbH的注册商标。

参考链接

• REST API使用文档
• Web Service客户端参考
• 服务器参数说明
• Docker配置文档