verapdf/rest

veraPDF-rest 镜像文档

镜像概述和主要用途

veraPDF-rest是基于Dropwizard构建的REST服务镜像，提供PDF/A和PDF/UA格式验证功能。该镜像包含Web界面、REST API及Swagger文档，支持根据请求的Content-Type返回XML或JSON格式结果。作为开发原型，其技术栈包括Jetty（HTTP服务器）、Jersey（REST服务）和Jackson（序列化），适用于快速部署PDF验证服务的场景。

核心功能和特性

• 多格式支持：根据请求头Accept返回XML或JSON格式数据
• 完整服务集：包含环境信息查询、验证配置文件管理、PDF验证等REST API
• Swagger文档：内置Swagger UI，可通过http://localhost:8080/swagger访问API详情
• 轻量级部署：采用Docker多阶段构建，Alpine基础镜像版本体积仅约103MB
• 灵活扩展：支持Docker单机部署和Kubernetes集群部署，可动态调整副本数
• 可配置性：支持自定义最大文件大小、Java堆大小及服务器参数（线程数、队列大小等）

使用场景和适用范围

适用于需要快速部署PDF/A或PDF/UA格式验证服务的开发、测试环境，可作为独立服务运行，或集成到自动化测试、文档处理流程中。支持单机轻量部署和集群规模化部署，满足不同场景下的验证需求。

详细使用方法和配置说明

从DockerHub运行镜像

直接拉取并启动官方镜像：

bash
docker run -d -p 8080:8080 -p 8081:8081 verapdf/rest:latest

端口说明：

• 8080：提供Web界面和veraPDF REST API
• 8081：提供Dropwizard诊断信息（如健康检查、线程状态等）

本地构建和运行

Docker构建

使用多阶段构建生成优化镜像（需本地克隆项目）：

bash
# 克隆项目仓库
git clone https://github.com/veraPDF/veraPDF-rest.git
cd veraPDF-rest
# 切换至稳定版分支（master）或开发版分支（integration）
git checkout master
# 构建并运行镜像
docker build -t verapdf-rest:latest . && docker run -d -p 8080:8080 -p 8081:8081 verapdf-rest:latest

注意：若运行时出现"Can't set cookie dm_task_set_cookie failed"错误，执行以下命令修复：

bash
sudo dmsetup udevcomplete_all

Kubernetes部署

通过Kubernetes配置实现负载均衡和动态扩缩容（2-4副本）：

bash
kubectl apply -f kubernetes.yaml

本地Maven构建运行

需Maven环境，直接构建并运行jar包：

bash
# 克隆并进入项目目录
git clone https://github.com/veraPDF/veraPDF-rest.git
cd veraPDF-rest
git checkout master
# 构建Maven项目
mvn clean package
# 启动服务
java -jar target/verapdf-rest-1.26.5.jar server server.yml

服务启动后，可访问http://localhost:8080/api/info验证运行状态，返回包含OS、Java版本、服务器IP等信息的环境数据。

REST API使用示例

API环境信息服务

查询服务器环境信息：

bash
curl localhost:8080/api/info

验证配置文件服务

验证配置文件包含PDF/A和PDF/UA的验证规则，支持以下操作：

• 列出所有配置文件：

  bash
  curl localhost:8080/api/profiles
  

• 列出所有配置文件ID：

  bash
  curl localhost:8080/api/profiles/ids
  

• 获取指定ID的配置文件（如1b对应PDF/A-1b）：

  bash
  # 默认返回JSON
  curl localhost:8080/api/profiles/1b
  # 返回XML格式
  curl localhost:8080/api/profiles/1b -H "Accept:application/xml"
  

验证服务

支持本地文件上传或URL指定文件验证：

• 上传本地文件验证（以配置文件1b为例）：

  bash
  curl -F "file=@本地文件路径.pdf" localhost:8080/api/validate/1b
  # 返回XML格式
  curl -F "file=@本地文件路径.pdf" localhost:8080/api/validate/1b -H "Accept:application/xml"
  

• 验证URL文件：

  bash
  curl -F "url=http://示例.com/test.pdf" localhost:8080/api/validate/url/1b
  

• 验证Docker挂载文件（需先挂载本地目录）：

  bash
  # 挂载本地目录并启动容器
  docker run -d -p 8080:8080 -p 8081:8081 -v /本地目录:/home/folder verapdf/rest:latest
  # 验证挂载的文件
  curl -F "url=file:///home/folder/test.pdf" localhost:8080/api/validate/url/1b
  

• 指定文件大小（通过X-File-Size头，单位：字节）：

  bash
  curl -H "X-File-Size: 307200" -F "url=http://示例.com/test.pdf" localhost:8080/api/validate/url/auto
  

配置参数说明

配置文件位于容器内/opt/verapdf-rest/config目录，包含server.yml（Dropwizard配置）及veraPDF验证参数（详见veraPDF CLI配置文档）。

关键配置项

• 最大PDF文件大小：

  • 通过server.yml的maxFileSize配置
  • 或通过环境变量设置（单位：MB，默认100MB）：

    bash
    docker run -d -p 8080:8080 -p 8081:8081 -e VERAPDF_MAX_FILE_SIZE=1 verapdf/rest:latest
    

• Java最大堆大小：通过JAVA_OPTS环境变量设置：

  bash
  docker run -d -p 8080:8080 -p 8081:8081 -e JAVA_OPTS="-Xmx128M" verapdf/rest:latest
  

• 其他服务器参数：如线程数、队列大小等，详见Dropwizard配置参考。