Stirling-PDF 自托管实践：把常用 PDF 操作搬到自己的服务器上

季度末整理合同归档时，我手头有二十多份扫描件要合并成册，还要把几份带敏感信息的报价单压到能发邮件的体积。按老习惯打开某个在线 PDF 工具，上传进度条走到一半突然意识到：这些文件里有客户名称、金额和签章，它们正在经过一台我完全不认识的服务器。关掉页面，我开始认真考虑把这类操作搬回自己的机器上。

这就是 Stirling-PDF 进入视野的原因。它是一个开源的、自托管的 Web 版 PDF 工具箱，把合并、拆分、压缩、旋转、水印、格式转换、OCR、签署、涂黑等几十种操作集中在一个浏览器界面里，而所有文件始终留在你自己的服务器上。对于经常处理合同、报告和扫描件的办公与开发用户来说，它解决的不是"有没有工具"的问题，而是"文件到底经过谁的手"的问题。

为什么值得自托管

在线 PDF 工具的问题不在于功能，而在于数据流向。每一次上传，文档都会离开你的设备，落到第三方服务器上，而对方的隐私政策通常模糊且随时可改。合同、银行对账单、身份扫描件、税务文件这类材料，一旦上传就很难确认它被如何处理、保留多久。

Stirling-PDF 的核心机制很直接：它是一个跑在容器里的 Java 应用，前端是浏览器页面，后端在本机或你自己的服务器上完成全部处理。文件不上传到任何外部服务，处理结果直接下载回本地。项目在 GitHub 上开源，支持 Docker、Kubernetes、裸机 JAR 等多种部署方式，官方文档把 Docker Compose 列为生产环境的推荐路径。

它适合的人群也比较明确：有固定 PDF 处理需求、在意文件隐私、手头有一台常开的机器或 VPS 的人。如果你只是偶尔转一次格式，用在线工具可能更快；但如果你每周都要处理合同或报表，自托管的边际成本会迅速摊薄。

部署：从零到能打开页面

官方文档给出的资源底线是至少 2 GB 内存（推荐 4 GB）和 10 GB 磁盘空间。如果走 JAR 裸机安装，还需要 Java 25 或更高版本，以及 LibreOffice 和 Tesseract 来支撑格式转换和 OCR。用 Docker 的话，这些依赖都打包在镜像里，省去不少麻烦。

最简的 docker run 命令是这样：

docker run -d 
  --name stirling-pdf 
  -p 8080:8080 
  -v ./stirling-data:/configs 
  docker.stirlingpdf.com/stirlingtools/stirling-pdf:latest

更推荐用 docker-compose，方便后续调整和更新：

services:
  stirling-pdf:
    image: docker.stirlingpdf.com/stirlingtools/stirling-pdf:latest
    container_name: stirling-pdf
    ports:
      - '8080:8080'
    volumes:
      - ./stirling-data:/configs
    restart: unless-stopped

启动后访问 http://localhost:8080，看到登录页就说明服务已经跑起来了。

这里有个容易忽略的点：登录默认是开启的。配置项 security.enableLogin 默认为 true，首次启动会创建一个默认管理员账号，用户名 admin，密码 stirling。官方文档明确要求首次登录后立刻改密码。如果你确实想要无登录体验，必须显式设置 SECURITY_ENABLELOGIN=false 来关闭，而不是什么都不做。

挂载点也值得留意。/configs 目录里存放着 settings.yml、custom_settings.yml、内置数据库及其备份、生成的密钥等，官方文档强调这个目录必须挂载，否则容器重建后配置全丢。此外还有 /logs 存日志、/customFiles 放品牌定制和签名文件、/pipeline 作为流水线处理的监控与完成目录。

如果部署在公网 VPS 上，别直接把 8080 端口暴露出去。常见做法是用 Caddy 或 Nginx 做反向代理，把域名指向容器内部的 8080，再配合防火墙只放行 SSH、80 和 443。这样既能上 HTTPS，也避免服务裸奔。

界面与常用操作

Stirling-PDF 的界面按功能分区组织，左侧或顶部是工具分类，主区域是当前工具的参数面板和文件拖放区。工具数量很多，但对办公场景来说，真正高频的其实就那么几个。

合并与拆分。合并就是把多个文件拖进同一个列表，调整顺序后执行；拆分支持按页数、按固定区间或按指定页码切分。我处理那批扫描件时，先把二十多份按类别合并成三册，再用拆分把其中一份错插的页面单独拎出来重排。

压缩。这是最实用也最容易产生预期落差的功能。压缩通过重新编码图像和优化结构来减小体积，效果高度依赖原文件构成：如果 PDF 里主要是文字，压缩空间有限；如果里面塞了大量高分辨率扫描图，压缩比例会明显得多。执行时可以选压缩级别，级别越高体积越小，但图像质量下降也越明显。发邮件用的版本可以激进一些，归档版本建议保守。

格式转换。PDF 与图片、Office 文档之间的互转都支持，图片转 PDF、PDF 转图片这类操作基本一键完成。涉及 Office 格式的转换依赖 LibreOffice，容器镜像里已经包含。

OCR。对扫描件做文字识别，让原本是图片的 PDF 变得可搜索、可复制。这一步依赖 Tesseract，处理速度和识别质量跟文档清晰度、语言设置直接相关。

水印、签署、涂黑。给文件加文字或图片水印，添加手写签名，或者把敏感区域涂黑后再外发。涂黑功能要确认是真删除内容而非仅覆盖视觉层，处理敏感文件时值得多验证一次。

限制与容易踩的坑

用下来，有几个问题几乎必然会遇到。

大文件与内存。PDF 处理是内存密集型操作，尤其是压缩、OCR 和大型文档合并。官方建议的 4 GB 内存不是随口说的，处理几百页的扫描件时，内存不足会直接导致容器被 OOM Killer 干掉，表现为页面卡住或请求失败。生产部署指南里提到可以在 compose 文件里为服务设置资源限制，按服务器实际情况调整。如果经常处理大文件，宁可多给内存，也别让它频繁重启。

中文内容。OCR 对中文的识别需要正确的语言包和参数设置。默认配置未必针对中文优化，扫描件质量差、字体特殊或排版复杂时，识别结果可能不理想。涉及中文文档时，建议先用少量样本测试识别效果，再决定是否批量处理。另外，界面和文档以英文为主，中文用户在配置项理解上可能需要多查一轮文档。

权限与配置。/configs 目录的读写权限如果不对，容器可能启动失败或配置无法保存。用 Docker 卷挂载时要留意宿主机目录的属主。多人使用的场景下，登录账号、权限分级和访问控制需要提前规划，别等到同事都在用了才发现所有人共用 admin。

更新与备份。升级方式是拉取新镜像并重建容器，但重建前务必确认 /configs 已经正确挂载并做好备份。配置、数据库和密钥都在里面，丢了就得从头配一遍。

排错思路。页面打不开，先看容器是否在运行、端口是否被占用；功能执行失败，去看 /logs 里的日志，多数错误信息足够定位问题；处理大文件时容器重启，基本可以判断是内存不足；转换或 OCR 报错，检查对应依赖是否可用。官方文档的 FAQ 和工具指南覆盖了不少常见问题，遇到具体报错时值得先搜一遍。