Stirling PDF 自托管：镜像选择、部署步骤与授权边界

Stirling PDF 是把几十种 PDF 操作装进一个网页界面的开源工具，你可以用 Docker 在自己的服务器上跑起来，文件不出内网。2026 年的 3.x 版本在易用性上往前走了一步，同时把用户数和自动化调用量变成了明确的额度。这篇按项目定位、镜像选择与部署、升级变更、额度边界和局限几块拆开写。

它到底是什么，解决哪一步的问题

它把日常和 PDF 有关的琐碎操作集中到一个界面：合并、拆分、旋转、压缩、页面重排、PDF 与图片或 Office 文档互转、加水印、加页码、OCR 识别、密文涂黑、表单填写、签名。官方文档的表述是 60 多种 PDF 操作。

处理全部发生在你自己部署的实例里，没有第三方服务器参与。底层依赖一串成熟命令行程序：LibreOffice 负责 Office 双向转换，Tesseract 与 OCRmyPDF 负责文字识别，Ghostscript 和 QPDF 负责压缩与修复。转换质量取决于这些上游组件，它不是自研的一套排版引擎。

除了网页界面，它还提供 REST API、可视化流水线、被监视的文件夹扫描，以及让 AI 助手调用工具的 MCP 服务。对写脚本的人来说，这意味着能把“上传发票、OCR、按内容重命名、归档”串成一条无人值守的链路。

部署形态有四种：Docker 容器、Kubernetes、直接运行 JAR、以及 Windows、macOS、Linux 桌面客户端。桌面版适合只处理自己文件的个人，服务端适合多人共用或需要接口调用的场景。自托管服务的部署思路可以参照站内 Immich 自托管相册那篇，挂载与端口习惯是相通的。

三个镜像与六个挂载点：用 Docker 跑起来

官方给出的 compose 文件很短：镜像来自 docker.stirlingpdf.com，映射 8080 端口，挂六个目录，加一条 mem_limit: 4g，然后执行 docker compose up -d。打开 http://localhost:8080，用 admin 和 stirling 登录，随后会被要求改密码，长度至少 8 位。

镜像分三种标签，差别不小，选错会白折腾一晚上：

六个挂载点各有分工，漏挂会出问题。/configs 保存 settings.yml、内置数据库和生成出来的密钥，必须挂；/storage 是用户在服务端保存文件的库，功能默认开启，建议挂；/usr/share/tessdata 用来放额外的 OCR 语言包；/pipeline 是被监视文件夹和已完成文件的目录；/customFiles 放品牌替换与签名文件；/logs 放日志。

容器以 UID 和 GID 1000 运行。如果宿主机上的目录属于别的用户，用 PUID 和 PGID 对齐，否则首次启动就会撞上权限拒绝。

少踩坑的做法是固定版本标签。版本标签有 version、version-fat、version-ultra-lite 三种形式，锁住以后升级时机由你决定；latest 每次发布都会移动，出问题只能靠备份回滚。

ultra-lite 没有登录，也没有用户体系和后台设置，能访问到端口的人可以直接进编辑器。它适合完全可信的内网，不要拿它对外。

从 V1 到 V3：升级前必须知道的变更

2.0 起前端换成独立的 Web 应用。V1 靠 customFiles/templates/ 里改模板来调整页面的做法失效，那些模板会被忽略，改名称和图标要走界面里的品牌设置。

一批配置项被删除或改名，例如 ui.appName 和 pdf-organizer 这个工具 ID。如果你以前用 endpoints.toRemove 关掉过某些工具，升级前要照设置变更文档重新核对一遍。

登录不再由镜像决定。V2 之后 latest 与 latest-fat 一律带登录和后台，DOCKER_ENABLE_SECURITY、DISABLE_ADDITIONAL_FEATURES 不再起作用，开关统一到 security.enableLogin。用 JAR 部署的人还要注意运行环境：V2 起 JAR 需要 Java 25，Docker 镜像已自带。内置数据库在首次启动时原地升级，想退回去只能靠升级前的备份。

把下面几件事当成固定动作，能省掉大部分事故：

• 停容器后整份打包 /configs 与 compose 文件，只备份数据库不够，配置和密钥同样在里面。
• 单独备份 configs/credential-encryption.key。丢失后已存的集成密钥和流水线附件无法恢复，这是官方启动日志里专门提醒的一条。
• 3.x 新增 /storage 挂载点。不补这一行，服务端文件库写在容器层里，重建容器即丢。
• 升级后浏览器可能仍在用旧的语言文件缓存，界面上出现未翻译的键名，强制刷新一次即可恢复。

备份策略可以参考站内的 自建备份工具清单，把 configs 目录和数据库快照一起纳入定时任务。

免费额度的边界：5 个用户与每月 1000 份

自托管不等于无限制。Free 计划允许 5 个用户，从 V1 升上来的实例以原有用户数作为上限保留，但不能再加。第 6 个用户会被拒绝，提示 Maximum number of users reached。

3.0 又加了一层计量：通过 API 键、Processor 自动化和 AI 功能处理的文件，计入每月 1000 份的免费额度，用尽后接口返回 402 与 FREE_TIER_EXHAUSTED，旧的被监视文件夹也会停下。用浏览器手动点选的操作不计入这项额度。

计量的麻烦之处在于按程序调用数算，不做文件去重。同一个文件反复调用也每次计 1 个单位，所以写脚本之前不妨先估算月调用量，再决定要不要关联到云端团队多拿额度。

付费档位对应的是管理能力，不只是席位。Team 档从 100 用户起，含外部数据库、集群、S3 或数据库文件存储、Prometheus 指标、自定义 PDF 元数据；SAML 单点登录、审计日志、离线证书激活属于 Enterprise。价格以官网为准，第三方实测记录里 Team 是每月 99 美元或每年 999 美元。

局限：什么时候它不合适

识别语言不是装上就能全用。标准镜像自带英语、德语、法语、葡萄牙语和简体中文，其他语言要自己把 traineddata 文件放进挂载的 tessdata 目录再重启；在界面里直接下载的语言文件写在容器内部，容器重建就没了。

资源占用需要手动设限。镜像会按容器内存上限推算 Java 堆大小，不设 mem_limit 时按宿主机内存推算，空闲状态也可能吃掉大量内存。第三方实测里，不设限的实例启动后占用接近 13 GiB，加上 4 GB 限制后降到 2 GiB 出头。

批量任务可能长时间停在队列。服务按宿主机负载与核数的比值判断资源状态，超过阈值就压住作业，共享服务器上常见 PENDING 不动，需要调高 STIRLING_RESOURCE_CPU_CRITICALTHRESHOLD 才会走。

它不是文档管理系统。没有全文检索库、版本历史和标签体系，归档与检索这类工作更适合交给 Paperless-ngx 那一类工具；它也不做版面结构化抽取，要把扫描件转成字段化数据的场景需要另找方案。

定制前端有成本。V2 之后改模板不管用，深度定制要自己构建前端。涂黑类操作会移除文字层，但处理前仍应保留原件，别把它当成不可撤销的合规手段。

适合谁用，怎么起步

个人用户省事的路径是桌面客户端，装完即用，不需要服务器和端口。要给家人或小团队共用，一台 2 核 4 GB 的机器按官方建议内存刚好够跑 latest。

起步按这个顺序比较稳：先固定版本标签；再补齐 /storage 与 tessdata 两个挂载；然后设好 mem_limit；接着用 SECURITY_INITIALLOGIN_USERNAME 和 SECURITY_INITIALLOGIN_PASSWORD 建自己的初始管理员，这两个变量只在数据库还没有用户时生效；最后再决定是否对外暴露。

常见问题

• 忘记管理员密码怎么办：数据库里没有任何用户之前，可以用初始账号环境变量重建；已有用户后这两个变量失效，只能在应用内改密码。
• 上传大文件失败怎么办：反向代理默认限制请求体大小，nginx 初始值只有 1 MB，需要按业务文件大小调 client_max_body_size。
• 能不能只用接口：可以，Stirling-PDF-server.jar 只提供 REST API，不带网页界面。
• 桌面版和服务器版差别在哪：工具本身同一套，差在多人协作、单点登录、审计这类组织能力。

一句话总结适用人群：手里有敏感 PDF、需要批量处理和接口调用的个人或小团队，它值得部署一套；如果只是偶尔改一份文件，桌面客户端或系统自带工具已经够用。官方文档从 docs.stirlingpdf.com 进入，部署细节看 Docker 安装页，升级前的变更清单在 破坏性变更页，额度与席位以 计划与许可页 为准，语言包的处理见 OCR 语言页。

两组第三方材料可以交叉验证：Jacar 的 3.0 升级实测 记录了额度计量与内存占用的真实数字，Open Source For You 关于 2.0 的报道 说明了 open-core 授权与五人免费额度的由来。