Stirling-PDF 3.2.0 介绍与选型指南

目标：本文是基于官方站点、官方仓库与官方文档的联网溯源认知篇，帮助读者在 10 分钟内建立对 Stirling-PDF 的全景认识——它是谁、能做什么、技术栈是什么、和同类 PDF 工具相比强在哪里，并给出量化选型对比与选型建议。所有数据均标注来源与查询日期（2026-10-22），本文不含本地实测结论；部署实操见 《Stirling-PDF 3.2.0 Docker Compose 部署指南》，配置参数见 《Stirling-PDF 3.2.0 配置参数详解》，API 实操见 《Stirling-PDF 3.2.0 API 使用详解》。

一、环境信息

本文为 A1 认知溯源篇，与实操篇不同，以下信息均来自公开官方渠道的桌面调研，未在本地环境执行任何命令：

• 调研对象：Stirling-PDF（官方名称 "Stirling PDF"，项目与镜像历史上以 Stirling-PDF 为主流拼写）
• 官方站点：https://stirling.com（产品主页）、https://www.stirlingpdf.com
• 官方仓库：https://github.com/Stirling-Tools/Stirling-PDF
• 官方文档站：https://docs.stirlingpdf.com
• 官方 API 文档：https://registry.scalar.com/@stirlingpdf/apis/stirling-pdf-processing-api/
• 最新稳定版：v3.2.0（来源：shields.io 版本徽章 https://img.shields.io/github/v/release/Stirling-Tools/Stirling-PDF.json，查询日期 2026-10-22，返回 "message":"v3.2.0"）
• 溯源查询日期：2026-10-22（下文所有来源标注均为此日期，不再重复）

💡 说明：Stirling-PDF 的版本号在 2025 年经历了一次大版本跃迁（V1 时代 0.x 小版本 → 直接发布大版本），官方文档专门设有 "Upgrading from V1 / Breaking changes / Settings changes" 章节指引老用户迁移（来源：docs.stirlingpdf.com 站点导航 "Upgrading from V1"，查询日期 2026-10-22）。选型时认准当前主版本线（3.x）即可。

二、软件概述

2.1 项目定位

Stirling PDF 官方自述为 "The Open-Source PDF Platform"（开源自托管 PDF 平台），一句话定位来自官方 README（来源：GitHub 仓库 README.md，查询日期 2026-10-22）：

"Stirling PDF is a powerful, open-source PDF editing platform. Run it as a personal desktop app, in the browser, or deploy it on your own servers with a private API. Edit, sign, redact, convert, and automate PDFs without sending documents to external services."

拆解这段官方定位，可以看到四个关键属性：

1. 全形态覆盖：桌面客户端（Windows/Mac/Linux）+ 浏览器 Web UI + 自托管服务器（含私有 API）三种运行形态，同一产品体系；
2. 隐私优先：文档处理全程在自己服务器完成，不外送第三方服务——这是它与 iLovePDF、Smallpdf 等在线 SaaS 最本质的差异；
3. 功能大而全：编辑、签名、脱敏（redact）、格式转换、OCR、压缩、自动化流水线一站式；
4. 开发者友好：几乎每个工具都有对应 REST API，可作为团队的「PDF 处理中间件」嵌入业务系统（官方 README 原文 "REST APIs available for nearly all tools"）。

官网当前的产品矩阵（来源：stirling.com / docs.stirlingpdf.com 站点导航，查询日期 2026-10-22）为三条产品线：

2.2 许可与商业模式（open-core）

Stirling PDF 采用 open-core（开放核心） 模式，这一点对选型很重要。官方仓库 LICENSE 文件（来源：GitHub 仓库 LICENSE，查询日期 2026-10-22）规定：

• 主体代码：MIT License（Copyright (c) 2025 Stirling PDF Inc.）——可自由自用、修改、商用、内嵌分发；
• 例外目录：app/proprietary/、app/saas/、engine/、frontend/editor/src/proprietary/、frontend/editor/src/desktop/、frontend/editor/src/saas/、frontend/editor/src/cloud/ 等目录下的内容按各自目录内的 LICENSE 授权（企业版/商业功能）。

对应到功能层面，官方 settings.yml 模板与文档（来源：docs.stirlingpdf.com "Plans & licensing" 导航，查询日期 2026-10-22）显示三档许可：社区版（免费）→ Pro → Enterprise，Pro/Enterprise 特性包括 S3 兼容对象存储（settings.yml 中注明 "PRO / ENTERPRISE LICENSE REQUIRED"）、SAML SSO（"Only enabled for paid enterprise clients"）、审计日志导出、存储静态加密、集群（clustering）等。社区版免费包含的能力依然覆盖绝大多数个人与中小团队需求：完整 Web UI、全部 60+ 基础操作、REST API、用户名密码登录、OAuth2 SSO（GitHub/Google/Keycloak 等通用 OIDC）、SQLite 内置数据库等。

2.3 社区热度与版本节奏

量化数据（来源：shields.io GitHub Stars 徽章，查询日期 2026-10-22）：

• GitHub Stars：95k（https://img.shields.io/github/stars/Stirling-Tools/Stirling-PDF.json 返回 "95k"）；
• 官网标注 89.1k（docs.stirlingpdf.com 页头实时计数，与徽章因统计口径略有差异）；
• Docker 拉取量徽章（官方 README 挂载 https://img.shields.io/docker/pulls/frooodle/s-pdf，沿用历史镜像名计数）；
• 社区渠道：官方 Discord（README 挂载 invite discord.gg/HYmhKj45pU）、GitHub Issues 跟踪缺陷；
• 安全治理：README 挂载 OpenSSF Scorecard 徽章（scorecard.dev），表明项目接入自动化安全评分体系。

版本节奏上，官方通过 GitHub Releases 发布，latest 镜像随每次发布滚动更新；官方 Docker 文档明确建议生产用版本号 tag 固定（"To control when you upgrade, use a version tag instead"），并提示升级前备份 /configs（来源：docs.stirlingpdf.com "Server → Install → Docker"，查询日期 2026-10-22）。

三、核心架构

3.1 技术栈与底层引擎

Stirling-PDF 本体是 Java（Spring Boot）Web 应用，采用「自研编排 + 成熟引擎组合」的架构思路：Web 层与 API 层为自有代码，PDF 各类操作则调用业界最成熟的开源引擎。官方 Docker 安装文档（来源：docs.stirlingpdf.com "Server → Install → Docker"，查询日期 2026-10-22）明确列出 latest 标准版镜像内置的引擎清单：

💡 技术拓展：PDF 处理类软件的引擎路线不止 Stirling-PDF 这种「组合引擎」一种，常见三类对比——

路线	代表	原理/特点	适用场景
组合引擎编排	Stirling-PDF	各操作调用该领域最成熟的开源引擎，覆盖面最广	全功能 PDF 平台
单一库自研	PDF Arranger、PDFsam	基于 pikepdf/PyPDF2 或 PDFBox 自己实现页面级操作，轻量	桌面单机拆合
转换 API 专精	Gotenberg	只做 HTML/Office → PDF 的无头转换服务，无 UI	微服务文档转换中间件

Stirling-PDF 选择组合引擎路线，换来的是「一个入口覆盖 60+ 操作」的平台能力，代价是标准版镜像体积与内存占用较大（官方建议 4GB 内存档，见 4.2 节）。本文介绍的部署方案即采用官方标准镜像。

V3 时代的架构亮点（来源：docs.stirlingpdf.com 站点导航与 settings.yml 结构说明，查询日期 2026-10-22）：

• JVM 弹性内存：按容器内存配额自动计算堆参数（官方文档 "Performance & operations → Performance" 有专门章节）；
• 多节点集群：cluster 配置域支持多节点组网，节点间通过 Valkey（Redis 兼容）共享状态、S3 存放任务工件（Enterprise 特性）；
• MCP 服务器：内置 MCP（Model Context Protocol）端点，可把 PDF 工具暴露给 Claude Desktop 等 AI 客户端（settings.yml mcp: 域，默认关闭，认证支持 OAuth 或每用户 API key）；
• AI 引擎：aiEngine 配置域支持接入 Anthropic/OpenAI/Ollama 等模型做文档问答、分类、RAG（latest-fat 镜像内置 Python AI 引擎，默认关闭）。

3.2 部署形态与镜像档位

官方支持的部署方式（来源：docs.stirlingpdf.com "Server → Install" 导航，查询日期 2026-10-22）：Docker（官方推荐）、Kubernetes、裸机 JAR（Bare bones），另有平台快捷包：TrueNAS SCALE、Unraid、Proxmox LXC（社区脚本）、Synology/UGREEN/Asustor、CasaOS/Portainer、Podman Quadlet。

官方镜像档位（来源：docs.stirlingpdf.com "Server → Install → Docker → Choose an image" 表格，查询日期 2026-10-22）：

镜像仓库三选一（官方原文 "Other registries"）：docker.stirlingpdf.com/stirlingtools/stirling-pdf（官方自有仓库）、stirlingtools/stirling-pdf（Docker Hub）、ghcr.io/stirling-tools/stirling-pdf（GitHub GHCR）；架构覆盖 amd64 与 arm64。

四、功能特性

4.1 功能全景

官方 README 概括为 "50+ PDF tools"，官网产品页 2026 年口径为 "60+ PDF operations"（来源：stirling.com "PDF Editor 60+ PDF operations"，查询日期 2026-10-22）。按官方文档 "Guides → User guide" 与 REST API 分组归纳（来源：docs.stirlingpdf.com 导航，查询日期 2026-10-22）：

• 页面操作：合并、拆分（按页码/按章节/按大小份数/打印海报）、旋转、重排、删除、提取、裁剪、多页拼版；
• 内容编辑：页面编辑器（Page Editor）、表单填写、水印、页码、盖章、红字脱敏（redact）、消毒清理（sanitize，移除脚本/元数据）；
• 转换：PDF ↔ 图片/文本/Word/HTML/Markdown/epub/CBZ/PDF-A，URL → PDF（默认关闭，官方注明 INTERNAL ONLY 有安全问题）；
• OCR 与识别：40+ 界面语言、Tesseract 多语言 OCR、辅助功能报告（accessibility report）；
• 安全与签名：密码加密/解除、证书签名（含多人签署会话 cert-sign sessions）、时间戳（RFC 3161 TSA）、签名验证、Auto Redact；
• 自动化：无代码流水线（pipeline）、文件夹监听（watched folders）、Webhook 触发、定时策略（schedule）、Telegram 机器人；
• 团队协作：多用户与团队（teams）、文件存储与分享链接、移动端扫码上传（mobile scanner）、手机签名；
• 管理：审计日志（audit，企业版含导出）、使用统计、数据库自动备份、用量监控。

4.2 资源需求与持久化目录

官方建议（来源：docs.stirlingpdf.com "Install → Docker" 与 "Production checklist"，查询日期 2026-10-22）：

• 标准版 latest 建议 4GB 内存（fat 版 6GB，ultra-lite 版 2GB）；
• 持久化卷六个：/configs（settings.yml、内置数据库及备份、密钥——官方注明 "Always mount this"）、/logs、/customFiles（品牌定制与签名文件）、/pipeline（流水线监听目录）、/storage（用户文件存储，官方注明默认开启须挂载）、/usr/share/tessdata（OCR 语言包）；
• 容器内进程以 UID/GID 1000 运行，宿主目录属主不一致时用 PUID/PGID 适配，UMASK 默认 022。

五、快速开始（官方最小示例）

以下命令直接引自官方 README 的 Quick Start（来源：GitHub 仓库 README.md，查询日期 2026-10-22，本文不做实测，实操验证与逐步讲解见 B2 部署篇）：

docker run -p 8080:8080 docker.stirlingpdf.com/stirlingtools/stirling-pdf

官方 Compose 版本（来源：docs.stirlingpdf.com "Server → Install → Docker → Quick start"，查询日期 2026-10-22）核心结构：

services:
  stirling-pdf:
    image: docker.stirlingpdf.com/stirlingtools/stirling-pdf:latest
    container_name: stirling-pdf
    ports:
      - '8080:8080'
    volumes:
      - ./stirling-data/configs:/configs
      - ./stirling-data/logs:/logs
      - ./stirling-data/customFiles:/customFiles
      - ./stirling-data/pipeline:/pipeline
      - ./stirling-data/storage:/storage
      - ./stirling-data/tessdata:/usr/share/tessdata
    mem_limit: 4g
    restart: unless-stopped

官方文档注明首次登录凭据为 admin / stirling（"Open http://localhost:8080 and sign in as admin / stirling (see First login)"），登录后应立即修改默认密码。完整的部署、健康验证、升级与卸载流程见 《Stirling-PDF 3.2.0 Docker Compose 部署指南》。

六、适用场景与限制

6.1 适用场景

基于官方定位与功能矩阵，Stirling-PDF 最能发挥价值的五类场景：

1. 隐私敏感的文档处理：合同、财务、人事等不能出内网的 PDF 加工（签名、脱敏、加密），自托管保证数据不出域；
2. 团队共享 PDF 工具站：一个服务覆盖全组 60+ 需求，替代每人桌面装多款软件；
3. 业务系统集成：通过 REST API 把合并/转换/OCR/压缩嵌入 OA、归档、报表系统（配合 API Key 认证与流水线自动化）；
4. 扫描件数字化：Tesseract 40+ 语言 OCR + 文件夹监听，扫描目录自动产出可检索 PDF；
5. 批量自动化：watched folders / Webhook / 定时策略实现无人值守处理。

6.2 已知限制

• 内存门槛：全功能标准版官方建议 4GB（ultra-lite 换功能裁剪），2GB 以下小内存机器只能用精简档；
• Pro/Enterprise 门槛：S3 存储、SAML SSO、审计导出、存储加密、集群等需付费许可（来源：settings.yml 注释与 docs "Paid Offerings"，查询日期 2026-10-22）；
• 无 rar 解码：标准版镜像不含 rar 支持，PDF→CBR 转换不可用（官方镜像档位表原文 "No rar, so no PDF to CBR"）；
• V1→V3 迁移成本：从 0.x 旧版升级存在 Breaking changes 与 settings 变更，官方提供了专门迁移章节，老部署升级前应先阅读并备份 /configs；
• URL→PDF 默认关闭：因 SSRF 类安全风险官方默认禁用且标注仅内部使用，需要时自行评估开启。

七、同类选型对比

7.1 量化对比

候选范围覆盖「自托管 Web 平台 / 桌面 GUI / 转换 API / 在线 SaaS」四类。GitHub 星数取自 shields.io 徽章 JSON（查询日期 2026-10-22，徽章地址形如 https://img.shields.io/github/stars/<owner>/<repo>.json），避免直接调用 GitHub API 受限：

关键差异解读：表中前五名均为开源可自托管方案，但只有 Stirling-PDF 同时提供「Web 多用户 + REST API + 60+ 全功能 + OCR」四要素；OCRmyPDF 与 Gotenberg 是能力专精型组件（分别对应 OCR 与转换），常见做法是与 Stirling-PDF 互补而非替代——事实上 Stirling-PDF 内部就调用 OCRmyPDF；PDF Arranger/PDFsam 是无服务的桌面工具，无法做团队共享与 API 集成；Docamatic、iLovePDF 是商业 SaaS，隐私与成本模型与自托管完全不同。

7.2 选型建议

• 要一个团队共用的全功能 PDF 工作台，且数据不能出门 → 首选 Stirling-PDF 社区版（本专栏全套文档围绕它展开）；
• 只需要批量给扫描件加文字层 → OCRmyPDF 命令行更轻；如果同时还要 Web 界面与人工复核，用 Stirling-PDF 的 OCR 功能；
• 微服务里只做 HTML/Office 转 PDF → Gotenberg 更专注；若还要「转完就合并/盖章/加密」的连续处理，Stirling-PDF 一个服务搞定；
• 个人桌面偶尔拆几页 PDF → PDF Arranger / PDFsam 更轻，无需常驻服务；
• 接受数据上云、追求零运维 → iLovePDF/Docamatic 等 SaaS，但要评估按量费用与合规风险。

八、参考链接

• 官方主页：https://stirling.com
• 官方文档站：https://docs.stirlingpdf.com（Install/Configuration/Performance/Paid Offerings 等章节，本文多处引用，查询日期 2026-10-22）
• 官方仓库：https://github.com/Stirling-Tools/Stirling-PDF（README/LICENSE 溯源来源）
• 官方 API 文档：https://registry.scalar.com/@stirlingpdf/apis/stirling-pdf-processing-api/
• Docker 镜像：https://hub.docker.com/r/stirlingtools/stirling-pdf
• 版本徽章取证：https://img.shields.io/github/v/release/Stirling-Tools/Stirling-PDF.json（v3.2.0，2026-10-22）
• 本专栏实操篇：《Stirling-PDF 3.2.0 Docker Compose 部署指南》、《Stirling-PDF 3.2.0 配置参数详解》、《Stirling-PDF 3.2.0 API 使用详解》