入门指南
本指南将引导您完成启动 ComPDFKit Processor 所需的步骤。它还向您展示如何使用它来处理文档。
要求
ComPDFKit Processor 可以运行在多种平台上。支持以下操作系统:
- Ubuntu、Fedora、Debian 或 CentOS。同时也支持 Ubuntu 和 Debian 的衍生版本,如 Kubuntu 或Xubuntu。目前仅支持 64 位的 Intel (x86_64) 处理器。
无论您使用的是哪个操作系统,至少需要 4GB 的 RAM。
安装 Docker
ComPDFKit Processor 以 Docker 容器的形式进行分发。要在您的计算机上运行它,您需要为您的操作系统安装 Docker 运行环境。
请按照 Docker官方网站 上的说明,安装并启动 Docker Engine。
安装 Docker 后,可以使用 安装说明 来安装 Docker Compose。
启动 ComPDFKit Processor
ComPDFKit Processor 还提供了一个简单的 Web 网页,该网页主要是为了渲染 PDF 文件并展示在 Web 网页上,你可以通过它直接在 Web 网页上处理 PDF 文件。你可以通过 localhost:7000/index.html
访问它。
ComPDFKit Processor 使用 MySQL 数据库做数据存储,因此,您需要配置一个可用的 MySQL 数据库,并将 “compdfkit.sql” 导入到您的数据库中。
注册 Docker Hub,并使用compdfkit/compdfkit:tag
引用 ComPDFKit Processor 镜像。要拉取最新的 ComPDFKit Processor 镜像,请运行以下命令:
docker pull compdfkit/compdfkit:2.0.0
您需要先保证您的系统中已经安装了 docker-compose
,要安装 docker-compose
,请前往 Overview of installing Docker Compose | Docker Docs 了解您所使用的系统如何安装 docker-compose
。
首先您需要在一个您所希望的位置创建一个docker-compose.yml
文件并可以使用 vim docker-compose.yml
编辑它,将下面的内容复制到 docker-compose.yml
文件中。
version: '3.3'
services:
compdfkit_processor:
restart: always
image: compdfkit/compdfkit:2.0.0
container_name: compdfkit_processor
ports:
- 7000:7000
environment:
LICENSE: your LICENSE_KEY
DB_URL: dbmysql:3306/compdfkit
DB_USERNAME: root
DB_PASSWORD: mypassword
# 文件处理的临时存储空间。
TMP_PATH: /tmp/compdfkit
# 错误提示语言设置,支持中文和英文两种语言(默认英文)。
LANGUAGE: zh_cn
depends_on:
- dbmysql
dbmysql:
image: mysql:8.0.27
restart: always
command: --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci --skip-character-set-client-handshake --skip-name-resolve --max_allowed_packet=500M --max_connections=1000 --default-authentication-plugin=mysql_native_password
container_name: dbmysql
ports:
- 3306:3306
environment:
MYSQL_ROOT_PASSWORD: mypassword
MYSQL_DATABASE: compdfkit
volumes:
- ./data:/var/lib/mysql
- ./compdfkit.sql:/docker-entrypoint-initdb.d/compdfkit.sql
其次您需要将 "compdfkit.sql" 文件复制到和 docker-compose.yml
同一级的目录中。然后您需要执行如下命令:
docker-compose up
当您看到以下内容,代表项目启动成功:
Running ComPDFKit Processor version 2.0.0 port(s) 7000 (http)
API 配置
必须配置的内容:
LICENSE
- 这是用于激活 ComPDFKit Processor 的许可证密钥。如果未指定或不正确,ComPDFKit Processor 将无法启动。DB_URL
- 数据库链接地址,组成部分为<host>
:<port>
/<数据库名>
。如果未指定或不正确,ComPDFKit Processor 将无法启动。DB_USERNAME
- 数据库链接用户名。如果未指定或不正确,ComPDFKit Processor 将无法启动。DB_PASSWORD
- 数据库链接用户密码。如果未指定或不正确,ComPDFKit Processor 将无法启动。
可选的配置:
SERVER_PORT
- ComPDFKit Processor 监听端口。默认7000
。TMP_PATH
- 装载临时文件的临时存储空间。默认/tmp/compdfkit
。LANGUAGE
- 接口错误描述语种zh_cn
||en
。默认en
。CONVERT_TIMEOUT
- 文件处理超时时间(分钟单位)。默认15
。
自动化容器内存释放方案
ComPDFKit 的自动化容器内存释放方案,为您提供基础的负载均衡能力以及自动化的容器监控。
队列服务:
我们使用 RabbitMQ 作为我们的异步消息队列解决方案。RabbitMQ 的高性能和可靠性使我们能够实现高效的消息传递,提高了我们系统的响应性能和可靠性。
容器监控:
我们提供 Compdfkit Server 服务,启动之后将会自动监控容器的内存使用率。如果内存使用率超过了您在docker-compose.yml
中定义的最大值,它就会在容器没有文件正在处理的情况下自动释放容器的内存。
示例
1. 开启 Docker 守护程序端口
要从 Docker 中获取容器的相关数据来操作容器实现 容器监控,需要开启 Docker 守护程序端口。
打开 Docker 配置文件
服务器:ubuntu18.0
sudo vim /lib/systemd/system/docker.service
服务器:ubuntu20.0
sudo vim /usr/lib/systemd/system/docker.service
修改配置
请在配置文件中找到如下代码,并添加
-H tcp://0.0.0.0:12375
。具体代码如下:ExecStart=/usr/bin/dockerd -H unix:///var/run/docker.sock
添加成功后,示例如下:
ExecStart=/usr/bin/dockerd -H unix:///var/run/docker.sock -H tcp://0.0.0.0:12375
重启 Docker
systemctl daemon-reload && systemctl restart docker
2. 启动
ComPDFKit Server 和 ComPDFKit Async 使用 MySQL 数据库来存储数据,因此,您需要配置一个可用的 MySQL 数据库,并将 “compdfkit.sql” 导入到您的数据库中。
首先,请注册 Docker Hub,并使用compdfkit/compdfkit-xxx:tag
引用 ComPDFKit 镜像。要拉取最新的 ComPDFKit 镜像,请运行以下命令:
docker pull compdfkit/compdfkit-server:2.0.0
docker pull compdfkit/compdfkit-async:2.0.0
然后,您需要在一个您所希望的位置创建一个docker-compose.yml
文件,并可以使用 vim docker-compose.yml
编辑它。创建成功之后,将下面的内容复制到 docker-compose.yml
文件中。
注意:请先确保您的系统中已经安装了 docker-compose
。如果暂时还未安装 docker-compose
,请前往 Overview of installing Docker Compose | Docker Docs 了解您所使用的系统如何安装 docker-compose
。
version: '3.3'
services:
compdfkit_async1:
restart: always
image: compdfkit/compdfkit-async:2.0.0
container_name: compdfkit_async1
ports:
- 17001:7000
environment:
LICENSE: your LICENSE_KEY
DB_URL: dbmysql:3306/compdfkit
DB_USERNAME: root
DB_PASSWORD: mypassword
# 文件处理的临时存储空间。
TMP_PATH: /tmp/compdfkit
# 错误提示语言设置,支持中文和英文两种语言(默认英文)。
LANGUAGE: zh_cn
MQ_HOST: rabbitmq
MQ_PORT: 5672
MQ_USERNAME: admin
MQ_PASSWORD: admin
# compdfkit_server容器访问地址
COMPDFKIT_SERVER_ADDRESS: http://127.0.0.1:17000
volumes:
- /tmp/compdfkit:/tmp/compdfkit
depends_on:
- dbmysql
compdfkit_async2:
restart: always
image: compdfkit/compdfkit-async:2.0.0
container_name: compdfkit_async2
ports:
- 17002:7000
environment:
LICENSE: your LICENSE_KEY
DB_URL: dbmysql:3306/compdfkit
DB_USERNAME: root
DB_PASSWORD: mypassword
# 文件处理的临时存储空间。
TMP_PATH: /tmp/compdfkit
# 错误提示语言设置,支持中文和英文两种语言(默认英文)。
LANGUAGE: zh_cn
MQ_HOST: rabbitmq
MQ_PORT: 5672
MQ_USERNAME: admin
MQ_PASSWORD: admin
# compdfkit_server容器访问地址
COMPDFKIT_SERVER_ADDRESS: http://127.0.0.1:17000
volumes:
- /tmp/compdfkit:/tmp/compdfkit
depends_on:
- dbmysql
compdfkit_server:
restart: always
image: compdfkit/compdfkit-server:2.0.0
container_name: compdfkit_server
ports:
- 17000:17000
environment:
SERVER_PORT: 17000
DOCKER_HOST: tcp://127.0.0.1:12375
DOCKER_VERSION: 1.41
CONTAINER_LIST: compdfkit_async1,compdfkit_async2
MEMORY_USAGE_RATE_LIMIT: 30
MEMORY_USAGE_LIMIT: 2048
DB_URL: 127.0.0.1:3307/compdfkit
DB_USERNAME: root
DB_PASSWORD: mypassword
MQ_HOST: 127.0.0.1
MQ_PORT: 5672
MQ_USERNAME: admin
MQ_PASSWORD: admin
TMP_PATH: /tmp/compdfkit
LANGUAGE: en
volumes:
- /tmp/compdfkit:/tmp/compdfkit
network_mode: "host"
depends_on:
- dbmysql
dbmysql:
image: mysql:8.0.27
restart: always
command: --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci --skip-character-set-client-handshake --skip-name-resolve --max_allowed_packet=500M --max_connections=1000 --default-authentication-plugin=mysql_native_password
container_name: dbmysql
ports:
- 3307:3306
environment:
MYSQL_ROOT_PASSWORD: mypassword
MYSQL_DATABASE: compdfkit
volumes:
- ./compdfkit.sql:/docker-entrypoint-initdb.d/compdfkit.sql
rabbitmq:
image: rabbitmq:3.10.0-rc.3-management
container_name: convert-rabbitmq
restart: always
ports:
- '5672:5672'
- '15672:15672'
environment:
- RABBITMQ_DEFAULT_USER=admin
- RABBITMQ_DEFAULT_PASS=admin
volumes:
- ./rabbitmq_data:/var/lib/rabbitmq
最后,您需要将 "compdfkit.sql" 文件复制到和 docker-compose.yml
同一级的目录中。完成之后,请执行如下命令:
docker-compose up -d
当您看到以下内容,代表项目启动成功:
Creating dbmysql ... done
Creating convert-rabbitmq ... done
Creating compdfkit_async1 ... done
Creating compdfkit_async2 ... done
Creating compdfkit_server ... done
必须配置的内容:
LICENSE
- 这是用于激活 ComPDFKit Async 的许可证密钥。如果未指定或不正确,ComPDFKit Async 将无法启动。DB_URL
- 数据库链接地址,组成部分为<host>
:<port>
/<数据库名>
。如果未指定或不正确,ComPDFKit Server 或者 Async 将无法启动。DB_USERNAME
- 数据库链接用户名。如果未指定或不正确,ComPDFKit Server 或者 Async 将无法启动。DB_PASSWORD
- 数据库链接用户密码。如果未指定或不正确,ComPDFKit Server 或者 Async 将无法启动。DOCKER_VERSION
- Docker 守护程序 API 版本,可通过命令docker version --format '{ {.Server.APIVersion} }'
查看。如果未开启 Docker 守护程序端口或者不正确,ComPDFKit Monitor 将无法监控对应 Docker 中的容器。DOCKER_HOST
- Docker 守护程序 API 地址。如果未开启 Docker 守护程序端口或者不正确,ComPDFKit Server 将无法监控对应 Docker 中的容器。CONTAINER_LIST
- 您需要监控的 ComPDFKit Conversion 容器名列表。如果未指定或容器名不正确,ComPDFKit Server 将不会自动监控该容器。MEMORY_USAGE_RATE_LIMIT
- 你可以接受的 ComPDFKit Conversion 的最大内存使用率。如果超出,ComPDFKit Server 将会对其进行内存释放。MEMORY_USAGE_LIMIT
- 你可以接受的 ComPDFKit Conversion 的最大内存使用量,单位为 MB。如果超出,ComPDFKit Server 将会对其进行内存释放。MQ_HOST
- 队列的地址,默认为127.0.0.1。如果未设置,ComPDFKit Server 或者 Async 将无法启动。MQ_PORT
- 队列的端口,默认为127.0.0.1。如果未设置,ComPDFKit Server 或者 Async 将无法启动。MQ_USERNAME
- 队列用户名,默认为 admin。如果未设置,ComPDFKit Server 或者 Async 将无法启动。MQ_PASSWORD
- 队列的密码,默认为 admin。如果未设置,ComPDFKit Server 或者 Async 将无法启动。COMPDFKIT_SERVER_ADDRESS
- ComPDFKit Server 服务的请求地址。如果未设置或设置不正确,ComPDFKit Conversion 将无法正常启动
可选的配置:
SERVER_PORT
- ComPDFKit Processor 监听端口,默认7000
。TMP_PATH
- 装载临时文件的临时存储空间,默认/tmp/compdfkit
。LANGUAGE
- 接口错误描述语种zh_cn
||en
,默认en
。CONVERT_TIMEOUT
- 文件处理超时时间(分钟单位),默认15
。
安装 curl
与处理器的交互是通过其 HTTP API 进行的: 发送请求并携带文件和命令,并接收结果文件。在此之前,首先需要安装 curl,以便调用 API。大多数桌面 Linux 版本都捆绑了 curl。你可以在终端运行 curl --version 命令来检查它是否已安装。如果出现错误,可以使用发行版的软件包管理器安装:curl
Ubuntu/Debian :
apt-get update && apt-get install -y curl
功能示例:PDF 文件转档
现在一切都已设置完毕,您可以开始使用 ComPDFKit Processor 进行 PDF 文档的处理了,这里以 PDF 转档功能的 PDF 转 Word 为例。更多其他功能的API调用请查看 “ComPDFKit_Processor_API_Reference.pdf” 。
选择您希望执行的文件并移动到你期望的位置(比如:document.pdf 文件)。
运行以下命令:
curl -f -X POST http://localhost:7000/file/handle \
-H "Content-Type: multipart/form-data" \
-F file=@"document.pdf" \
-F executeType="pdf/docx" \
-F password="file open password" \
> result.docx
在 Word 查看器中打开文件result.docx
— 您将看到一个 Word 文档。