夜雨聆风一、Stirling-PDF是什么？开源界的PDF全能选手
Web界面：浏览器打开就能用，所有功能页面化、可视化、零学习成本，普通员工也能直接上手操作 原生桌面客户端：支持 Windows、macOS、Linux 三大平台，启动速度快，可以与系统右键菜单集成，支持离线使用，对于个人用户尤其友好 服务器模式 + REST API：这是企业级开发最关心的形态，部署到内网服务器后，所有功能都以HTTP 接口形式暴露，业务系统可以直接通过HTTP 请求调用，将PDF 处理能力无缝嵌入产品流程
二、四大核心优势，直击企业PDF痛点
三、50 +功能全景，按业务场景全覆盖
四、REST API接口体系，标准化易对接
合并 PDF：接口路径/api/v1/general/merge-pdfs，POST 请求，files字段提交多份 PDF 文件，返回合并后的 PDF 二进制流 拆分 PDF：接口路径/api/v1/general/split-pdf，POST 请求，file上传 PDF，pages指定拆分页码范围，返回 ZIP 压缩包包含拆分后的文件 PDF转 Word：接口路径/api/v1/convert/pdf-to-word，POST 请求，file上传 PDF，返回 docx 文件 PDF压缩：接口路径/api/v1/general/compress-pdf，POST 请求，file和optimizeLevel（1-3 级）参数，返回压缩后的 PDF 添加水印：接口路径/api/v1/security/add-watermark，POST 请求，支持水印文字、字号、透明度、旋转角度、位置等参数，返回处理后的PDF OCR识别：接口路径/api/v1/ocr/pdf，POST 请求，file和languages参数，返回可搜索的 PDF
五、Java系统集成方案，附代码示例
import org.springframework.core.io.FileSystemResource;import org.springframework.http.*;import org.springframework.util.LinkedMultiValueMap;import org.springframework.util.MultiValueMap;import org.springframework.web.client.RestTemplate;import java.io.File;import java.nio.file.Files;import java.nio.file.Path;public class PdfMergeExample {public static void main(String[] args) throws Exception {RestTemplate restTemplate = new RestTemplate();String url = "http://localhost:8080/api/v1/general/merge-pdfs";// 构造多文件参数MultiValueMap<String, Object> body = new LinkedMultiValueMap<>();body.add("files", new FileSystemResource(new File("contract-part1.pdf")));body.add("files", new FileSystemResource(new File("contract-part2.pdf")));// 设置请求头HttpHeaders headers = new HttpHeaders();headers.setContentType(MediaType.MULTIPART_FORM_DATA);HttpEntity<MultiValueMap<String, Object>> request = new HttpEntity<>(body, headers);// 发起请求，接收字节流结果ResponseEntity<byte[]> response = restTemplate.exchange(url, HttpMethod.POST, request, byte[].class);// 保存合并后的文件if (response.getStatusCode() == HttpStatus.OK && response.getBody() != null) {Files.write(Path.of("contract-merged.pdf"), response.getBody());System.out.println("PDF合并完成");}}} |
方式二：OpenFeign声明式调用
import feign.Response;import org.springframework.cloud.openfeign.FeignClient;import org.springframework.http.MediaType;import org.springframework.web.bind.annotation.PostMapping;import org.springframework.web.bind.annotation.RequestPart;import org.springframework.web.multipart.MultipartFile; @FeignClient(name = "stirling-pdf", url = "${stirling.pdf.service-url}") public interface StirlingPdfClient {/** *合并多个PDF文件 */@PostMapping(value = "/api/v1/general/merge-pdfs",consumes = MediaType.MULTIPART_FORM_DATA_VALUE)Response mergePdfs(@RequestPart("files") MultipartFile[] files);/** *PDF转换为Word文档*/ @PostMapping(value = "/api/v1/convert/pdf-to-word",consumes = MediaType.MULTIPART_FORM_DATA_VALUE)Response pdfToWord(@RequestPart("file") MultipartFile file);/** *给PDF添加文字水印*/@PostMapping(value = "/api/v1/security/add-watermark",consumes = MediaType.MULTIPART_FORM_DATA_VALUE)Response addWatermark(@RequestPart("file") MultipartFile file,@RequestPart("watermarkText") String watermarkText,@RequestPart("opacity") String opacity); } |
业务层直接注入接口即可调用，无需手动构造 HTTP 请求，非常适合微服务架构下的能力复用。
开启登录鉴权后，要做好会话 Cookie 管理，建议用 OkHttp 的 CookieJar 自动维护 根据业务场景调大文件上传大小限制，避免 413 文件过大错误 OCR、格式转换这类耗时操作，HTTP 客户端要设置合理的读写超时，建议 60 秒起步，OCR 可设置到 5 分钟 高并发场景下可以横向扩容多实例，配合网关限流，防止大文件并发拖垮服务
六、Docker部署全流程，附完整脚本示例
| docker run -d \-p 8080:8080 \-v ./stirling-pdf/configs:/configs \-v ./stirling-pdf/logs:/logs \--name stirling-pdf \stirlingtools/stirling-pdf:latest |
这条命令做了四件事：以守护进程模式启动容器、映射 8080 端口、挂载配置和日志目录实现数据持久化、指定容器名称方便管理。
version: '3.8'services:stirling-pdf:# 推荐使用fat镜像，预装完整字体和中文OCR语言包image: stirlingtools/stirling-pdf:latest-fatcontainer_name: stirling-pdfrestart: alwaysports:- "8080:8080"volumes:- ./configs:/configs# 配置文件持久化- ./logs:/logs# 日志持久化- ./customFiles:/customFiles # 自定义Logo、主题等资源- ./tmp:/tmp# 临时文件目录environment:# 启用登录鉴权，内网部署可设为false- SECURITY_ENABLE_LOGIN=true# 界面默认简体中文- LANGS=zh_CN# 自定义应用名称- UI_APPNAME=企业内部PDF处理平台# 开启Prometheus监控指标- METRICS_ENABLED=true# 关闭界面广告- SHOW_ADVERT=false# 启用OCR功能- TESSERACT_INSTALLED=true# JVM内存与垃圾回收参数- JAVA_TOOL_OPTIONS=-Xmx4g -Xms2g -XX:+UseG1GC -XX:MaxGCPauseMillis=200# 健康检查，自动重启异常容器healthcheck:test: ["CMD", "curl", "-f", "http://localhost:8080/api/v1/info/status"]interval: 30stimeout: 10sretries: 3start_period: 60s |
latest-fat：推荐企业环境使用，预装了完整字体和 OCR 语言包，对中文 PDF 的转换和识别效果最好 latest：标准版镜像，体积适中，覆盖绝大多数常用功能 latest-ultra-lite：轻量版镜像，体积小、启动快，适合资源紧张的服务器，仅保留核心功能
