PDF REST API 镜像文档

镜像概述和主要用途

该Docker镜像将PDF处理库及转换工具封装为REST API接口，提供标准化的HTTP访问方式。用户无需直接操作底层PDF工具，可通过简单的API调用来实现PDF文件的转换、合并、拆分等处理需求，简化集成流程。

核心功能和特性

• RESTful API接口：提供标准化HTTP接口，支持GET/POST等请求方法，易于集成到各类应用系统
• 多工具集成：整合主流PDF处理工具（如Poppler、PDFtk等），支持丰富的文件操作
• 多样化处理能力：支持PDF与常用格式转换（PDF→PNG/TXT/DOCX）、PDF合并/拆分、页面提取、水印添加等功能
• 轻量级部署：基于精简基础镜像构建，资源占用低，支持容器化环境快速启动
• 可配置性：支持通过环境变量自定义端口、认证方式、文件大小限制等参数

使用场景和适用范围

• Web应用后端：为在线文档转换、电子合同生成等Web服务提供PDF处理能力
• 企业自动化流程：用于内部系统PDF文件批量处理（如报表转换、归档文件格式化）
• 微服务架构：作为独立微服务，为多应用提供共享的PDF处理能力，避免重复开发
• 教育/出版领域：支持教材、文档的格式转换与处理，适配在线教育平台资源管理需求

使用方法和配置说明

基本部署命令

bash
docker run -d -p 8080:8080 --name pdf-api [镜像名称]

• -p 8080:8080：映射容器端口8080至主机，用于API访问
• --name pdf-api：指定容器名称，便于管理

环境变量配置

支持通过环境变量自定义服务参数，常用配置如下：

带认证和自定义端口的部署示例：

bash
docker run -d \
  -p 9000:9000 \
  -e PORT=9000 \
  -e API_KEY=my-secret-key \
  -e MAX_FILE_SIZE=100 \
  -v /host/output:/app/output \
  --name pdf-api [镜像名称]

注：-v /host/output:/app/output 可将处理结果持久化到主机目录，避免容器重启后文件丢失

API端点示例

服务启动后，通过以下端点调用功能（假设服务地址为http://localhost:8080）：

健康检查

• 请求：GET /health
• 响应：{"status": "ok", "version": "1.0.0"}（状态码200表示服务正常）

PDF格式转换

• 请求：POST /convert
• 请求体：multipart/form-data格式，包含：
  • file：待转换的PDF文件
  • target_format：目标格式（支持png、txt、docx）
• 响应：转换后的文件流（状态码200）或JSON格式错误信息（状态码4xx/5xx）

PDF合并

• 请求：POST /merge
• 请求体：multipart/form-data格式，包含多个file参数（待合并的PDF文件）
• 响应：合并后的PDF文件流（状态码200）

注意事项

• 处理大文件时需调大MAX_FILE_SIZE参数，并确保主机磁盘空间充足
• 启用API_KEY时，需在请求头中添加Authorization: Bearer <API_KEY>进行认证
• 生产环境建议配合反向代理（如Nginx）使用，增强安全性和请求处理能力