用Docker本地部署Stirling-PDF：打造私密PDF工具箱

我有一阵子为了把扫描件变成可编辑的Word文档，几乎把市面上叫得上名字的在线PDF工具都试了一遍。速度确实快，浏览器打开就能用。但每次点击上传那个按钮，心里总会冒出一点说不清的别扭——文件已经在别人的服务器上跑了一圈，对方留存多久、拿去做了什么，完全不在我的掌控范围内。尤其是碰上带身份证号、合同金额、内部报价的PDF，那种不安会加倍。后来我在GitHub上刷到一个叫Stirling-PDF的开源项目，Star数已经涨到21.7k，定位一句话就能说明白：一个完全本地的PDF工具箱。我顺手按文档部署了一份，实际用了两个多月，处理了上千个文件，再回头去看那些在线PDF网站，确实已经没有回去的理由了。

这篇文章我会把部署思路、完整步骤、常用功能实操、隐私加固和排坑经验都写出来。项目本身不算复杂，部署门槛主要卡在Docker理解上，所以就算你之前没怎么碰过容器，只要照着走也能跑起来。

1. 为什么非要在本地部署PDF工具箱

1.1 在线PDF网站到底有哪些让数据不安的地方

很多人可能觉得，在线PDF工具方便就够了，文件上传后就当没发生。但稍微较真一点，就会发现这里面全是模糊地带。文件上传到网站服务器之后，背后可能是自建机房，也可能是对象存储，甚至可能被第三方CDN缓存。你并不知道它落在哪台机器上，也不知道存储策略是多长时间，更不知道服务方是否会用这些文件做模型训练、数据分析，或者单纯被内部员工多看一眼。

我印象最深的一次，是把一份带公司盖章的扫描件传到在线工具里做拆分。两分钟后处理完，网页上还弹出一个“文件已安全删除”的提示。但“安全删除”这四个字本身就是个无法证伪的说法——我既看不到服务器日志，也抽查不了底层存储，除了选择相信，没有任何办法。对于普通简历、学习资料这类低敏感文件，风险或许可以忽略。但换作合同协议、银行流水、身份证明，这种“赌概率”就显得很不划算。

本地部署的核心逻辑，是把整个处理链路锁在自己的设备里。文件上传、转换、存储全部在本地容器内完成，访问服务用的是localhost，不经过任何外部网络请求。程序是开源的，代码逻辑摆在那里，你甚至可以把容器完全断网运行，彻底消除文件外泄的通道。这种自主可控的感觉，在线工具给不了。

1.2 21.7k Star开源项目的选型逻辑

GitHub上PDF相关的开源项目数量很多，Star数是重要的参考维度，但不是唯一标准。Stirling-PDF能在众多项目中冲到21.7k Star，背后有几层真实的原因。

第一是功能覆盖度。市面在线PDF站点的常用功能，它基本都有：合并拆分、格式转换、压缩、加密解密、水印、页面旋转、OCR文字识别、电子签名、PDF/A归档、批量处理，还包括一些比较进阶的清理元数据、修复损坏PDF、比较文档差异。这意味着部署一份之后，日常能想到的PDF操作基本覆盖了，不用再为某个冷门需求去装第二套工具。

第二是工程形态。项目用Java/Spring Boot编写，服务本身是一个Web应用，提供简洁的浏览器界面，同时也暴露REST API。普通用户用界面操作，程序员可以拿API做自动化集成。这种形态比纯命令行工具更容易让非技术用户接受，也比桌面GUI应用更容易部署和管理。

第三是社区活跃度。21.7k Star不是一天堆出来的，高关注度意味着插件更新频繁、Issue反馈多、文档迭代快。我在使用过程中遇到过一个中文PDF导出乱码的问题，通过搜索Issue列表，发现早就有人提交过详细讨论，照着解决方案调整字体配置就解决了。这种社区沉淀对自托管用户来说，是很值钱的隐形资产。

1.3 部署前先弄清它的运行架构

初次部署前，我建议先花五分钟左右理解一下这个项目的运行逻辑，后面排查问题会轻松很多。

Stirling-PDF本质上是一个基于Spring Boot的Java Web应用，打包后运行在容器里。它对外暴露一个HTTP端口，浏览器访问后加载前端界面；用户上传PDF，后端调用各种处理引擎来完成具体操作。这些引擎分好几类：OCR相关用的是OCRmyPDF和Tesseract，Office文档转换靠的是LibreOffice，图像处理走的是OpenCV，PDF底层操作使用的是PDFBox和iText。容器镜像里已经把Java运行时、处理引擎、依赖库都打包好了，这也是推荐Docker部署的最直接原因——你不用自己一样样装环境。

举个实际例子：如果你只用PDF合并拆分，那容器里的LibreOffice和OCR组件基本不参与工作，内存占用会相对低一些。但如果要做扫描件OCR，Tesseract和OCRmyPDF会同时启动，内存消耗会明显上升。理解了这个机制，你在配置容器资源限制的时候，心里就会更有数。

2. 部署准备：Docker方案与硬件环境如何取舍

2.1 Docker为什么是自托管PDF工具的首选

部署这类Web服务，Docker几乎是最省心的路径。核心原因就一句话：镜像把应用和运行环境打包成一个整体，你拉下来启动就算部署完成。

如果不走Docker，你需要在机器上装Java运行环境、装LibreOffice、装Tesseract、装各种系统依赖库，还要手工处理版本兼容。任何一个依赖的版本没对上，启动就是一连串莫名其妙的报错。而Docker镜像里的环境是作者验证过能正常运行的组合，等于别人帮你踩完了环境配置的坑，你只需要关心容器本身的运行参数。

另外，Docker对系统是隔离的。容器里装了什么组件、生成了什么临时文件，都不会污染宿主机。以后想升级版本，拉一个新镜像，重建容器就完事，不需要在宿主机里清残留文件。这一点在长期维护的视角下，省下的精力非常可感。

2.2 硬件、系统与网络环境准备清单

官方对硬件没有特别苛刻的要求，但根据实际操作经验，我可以给一个更贴合现实的参考。

内存方面，基础功能（合并、拆分、转换、水印）只要1GB到2GB空闲内存就能跑。PDF文件特别大（单个几百MB）时，Java进程的内存会明显上升，建议部署机器的总内存不低于2GB。如果要比较重度地使用OCR，内存建议放量到4GB以上。我自己在2GB内存的VPS上跑过，普通文件处理流畅，但OCR一个几十页的扫描件时，明显感觉到机器变卡。后来换到4GB内存的设备，体验才算真正稳定。

CPU要求不高，双核就够了。毕竟是个人使用，不是高并发的在线服务。平时处理文件时，CPU占用率不会拉满，也就OCR或转换大量文件时能持续看到负载上升。

磁盘方面，镜像本身加上依赖，体积不小。以我的环境为例，镜像解压后占用的空间在1GB到2GB范围。建议预留5GB以上磁盘空间，其中还需要考虑OCR语言包、日志文件以及你处理过程中产生的临时文件空间。语言包这点很多人容易忽略，不同语言识别数据包体积不一样，几个主流语言包装下来，几百MB是正常的。

系统方面，x86_64和ARM64架构的机器都能跑，官方提供了对应架构的镜像。Windows、macOS、Linux均可，只要先装好Docker引擎即可。如果机器在局域网内，浏览器直接访问容器映射的端口就可以操作。如果打算部署在云服务器上，为了安全，后续第5节的加固配置建议不要跳过。

2.3 两种部署方式的对比选择

这里有两种常见的部署启动方式：一种是docker-compose，适合希望配置可维护、未来要调整参数的人；另一种是docker run单行命令，适合快速验证部署是否OK。

我用表格对比两者的适用场景，方便你直接判断：

如果你之前没接触过docker-compose，也不用有太大压力。它本质上就是把docker run命令里的那些参数，换一种格式写进文件里而已。后面的实操步骤里，我会把两种方式都写出来，你可以按自己的习惯选择。

3. 实操部署全流程：从拉取镜像到浏览器访问

3.1 用docker-compose完成标准化安装

我当前部署用的就是docker-compose方式，先把完整的配置文件贴出来，这份配置我实测稳定运行过很长时间，可以放心参考。

先创建一个工作目录，比如stirling-pdf，进入目录后新建docker-compose.yml：

version: '3.3' services: stirling-pdf: image: frooodle/s-pdf:latest container_name: stirling-pdf ports: - "8080:8080" volumes: - ./trainingData:/usr/share/tessdata - ./extraConfigs:/configs - ./customFiles:/customFiles - ./logs:/logs environment: - TZ=Asia/Shanghai - SERVER_PORT=8080 - DOCKER_UI_PORT=8080 restart: unless-stopped

写完后，在同一个目录执行：

docker compose up -d

镜像体积比较大，第一次拉取可能需要几分钟，取决于你的网络情况。启动完成后，用docker ps查看容器状态，如果状态是Up，说明已经正常启动。

这里逐个解释一下配置里的关键项。

端口映射部分，我选择8080:8080，宿主机8080端口映射到容器的8080端口。页面地址是http://localhost:8080。如果你8080端口被别的服务占用了，把左边改成比如8088:8080，那访问地址就是http://localhost:8088。端口冲突是新手最容易遇到的问题，在云服务器上部署还需要检查防火墙和平台安全组是否放行了对应端口。

挂载卷部分，四个目录各有分工。trainingData对应OCR语言包目录，Tesseract在启动时会读取这个目录下的语言数据，这样以后换容器实例时，不需要重新下载语言包。extraConfigs放应用的自定义配置文件，比如做进阶定制时会用到。customFiles对应自定义静态资源目录。logs存放容器日志，方便排查问题。我在实际使用中，最喜欢的就是这个目录映射设定：升级容器版本时，语言包和日志不会跟着容器被销毁，数据不丢失。

时区设置TZ=Asia/Shanghai也值得提一下。不设置时区的话，容器默认是UTC时间。PDF文件的时间戳、日志时间会比北京时间慢8小时，排查日志时很容易被误导。

restart: unless-stopped表示容器异常退出后会自动重启。机器重启后容器也会自动恢复运行，省去手动启动的麻烦。个人使用场景下，这个配置基本是必写的。

3.2 用docker run快速启动方式

如果你只是先体验一下，不想创建目录写配置文件，docker run一条命令就能跑起来：

docker run -d \ --name stirling-pdf \ -p 8080:8080 \ -v ./trainingData:/usr/share/tessdata \ -v ./extraConfigs:/configs \ -v ./logs:/logs \ -e TZ=Asia/Shanghai \ frooodle/s-pdf:latest

这里的参数跟compose文件里的配置是一个意思。-d表示后台运行，--name给容器取名字方便后续操作，-p端口映射，-v挂载目录，-e设置环境变量。

提醒一点：docker run创建容器后，如果要修改参数，不能直接改，需要先停止并删除旧容器，再重新运行新的命令。所以这个方式更适合前期验证，确定要长期用的话，还是建议转到compose方式上。

3.3 首次启动检查与中文界面配置

容器跑起来之后，访问http://localhost:8080，正常情况下会看到Stirling-PDF的Web界面。第一次打开的加载时间可能会略久，因为后端Java进程还在初始化。如果页面转圈超过一两分钟，可以用docker logs stirling-pdf查看日志，看到启动完成的标志通常说明一切正常。

界面语言切换是个很容易找但不一定一眼注意到的设置。我一开始进后台，界面默认是英文，英语看了不费劲，但总觉得不顺手。在页面右上角的设置菜单里找到Language选项，选择简体中文，界面会即时切换。这个选项会保存到浏览器本地，下次打开还是中文界面。

首次进来建议先试一个最简单的操作：随便选一个PDF文件，做一次“合并”或者“格式转换”。确认后端处理链路是通的，再开始正式使用。我习惯用“PDF转图片”来做冒烟测试，因为这条链路调用了PDF解析和图像生成，覆盖面广，任何一环出问题都会立即报错。

4. 高频率功能实战：从合并拆分到OCR识别

4.1 合并拆分与页面管理：最常用的场景

PDF合并是我日常最常用的功能。有时候一个项目里的多个文档需要合并成一个完整附件发出去，过去用在线工具要一个个上传再排顺序，现在本地界面里一次拖入多个文件，拖动调整顺序，点击合并就完事。处理的原理是后端用PDFBox读取每个源文件的所有页面，按你指定的顺序拼成一个新的PDF文档，不涉及图像重渲染，所以速度非常快。即使文件很多，通常也是几秒内完成。

拆分功能有两种选择：按固定页数拆，比如每两页拆成一个文件；或者指定某个范围提取出来。我处理一份几十页的合同扫描件时，经常需要把某一页单独抽出来打印，用范围提取方式非常方便。这个操作的原理就是按页码范围复制页面生成新文件，哪怕源文件很大，也不会卡顿。

页面的旋转和删除也值得一提。手机上扫描的文件经常出现方向颠倒，以前需要电脑上装专业软件处理，现在直接在页面上选中旋转按钮就行。页面删除操作我建议谨慎一点，尤其面对重要文档时，误删后没有回收站，原文件最好先备份。

4.2 PDF压缩与体积控制技巧

PDF压缩这个功能，很多人会遇到一个困惑：怎么压缩完文件反而变大了？这背后有一套可以解释的逻辑。

Stirling-PDF的压缩功能底层是通过OCRmyPDF或Ghostscript重新处理PDF。如果你选择的是基于图像质量的压缩策略，工具会把PDF内部图像重新编码。但某些情况下，如果原PDF内部图像本来质量就不高，重新编码时会加入新的元数据，或者选择了更高质量参数，结果文件反而变大。这不是程序bug，是参数选择问题。

我实测几次后，总结出比较实用的压缩策略。文件里全是文字和矢量图形，这种PDF本身很小，不需要压缩，硬压反而可能增大体积。文件里有很多图片，想明显缩小体积，选择中高压缩等级，观察输出文件大小即可。如果压缩后的清晰度下降得太厉害，把压缩等级调低一档再试。这个功能的核心价值在于，它是本地处理，你可以反复调整参数实验，不需要考虑在线工具的配额限制。

4.3 OCR文字识别与扫描件处理

OCR是我部署Stirling-PDF后最依赖的功能之一。很多扫描件本质上是图片合集，文字无法选中，无法搜索，也无法直接复制。OCR要做的事情，就是识别图片里的文字信息，把它嵌入到PDF中。

操作路径很清晰：选择一个扫描版PDF文件，点击OCR功能，选择需要识别的语言，再点识别。如果界面提示缺少语言包，需要先到设置里的OCR语言管理选项中下载对应的语言数据。这个过程需要联网下载训练数据，下载一次后就会存在我们之前挂载的trainingData目录里，以后离线也能用。

中文识别效果的好坏，跟扫描件的清晰度直接相关。300dpi以上的扫描件识别效果基本可用，低于150dpi的模糊件错误率会显著上升。还有一个容易踩的坑：扫描件本身是横向排版的报纸或表格，识别前需要在页面旋转那里把文字方向调整正，否则识别效果会大打折扣。我收到的别人发来的扫描件五花八门，歪着斜着的很多，提前转正再OCR，识别率提升非常明显。

OCR处理结束之后，文件会变成可搜索PDF。在浏览器里打开，用Ctrl+F可以精确搜索到文件里的关键词，这个体验和纯扫描件是天壤之别。

4.4 格式转换、水印与加密权限设置

格式转换是我使用频率排第二的功能。Stirling-PDF支持PDF转Word、转图片、转HTML，也支持Word、PowerPoint、Excel文档转PDF。这个功能主要依赖容器内置的LibreOffice。

第一次做Word转PDF时，我注意到一个现象：如果源文件中使用了一些非常规的中文字体，转换结果偶尔会出现字体替换导致的排版错位。这也是一个值得记住的考点：如果对排版要求严格，先确认源文件的字体兼容性再转换。反过来，PDF转Word的限制更大，转换结果需要自己检查一下文本框、表格的排列是否有错乱，这属于格式转换的固有局限，任何工具都无法完全避免。

加密功能也相当实用。给客户发送带合同信息的PDF时，可以设置打开密码，同时限制打印权限、复制权限。解密功能则支持移除密码保护，但前提是你知道密码。水印功能支持自定义文字水印和图片水印，批量文件处理场景下效率很高。我之前给一组内部培训材料统一加上“内部资料”斜体水印，选中文件，输入文字，设置透明度，点击执行，几十个文件一次处理完，整个过程在本地完成，不需要担心文件内容被第三方看到。

5. 部署完的隐私加固：这层防护不能省

5.1 开启登录认证与会话保护

如果服务只在本机访问，理论上不需要登录认证。但现实情况是，很多人会把服务部署在NAS、家庭服务器或云主机上，局域网内其他人也可能访问到。这时候，默认的无认证状态就是一个隐患。

Stirling-PDF从较早版本开始就内置了登录认证能力，不过它默认是关闭状态。按照官方文档的配置，通过设置相关的安全环境变量可以启用登录功能。启动后首次访问会要求创建管理员账号，之后的每一次操作都需要登录。我自己部署后第一时间就把这一步开了，虽然平时只有我一个人用，多一次登录不麻烦，但心里踏实很多。

除了登录认证，还要检查一下容器对外暴露的端口范围。如果服务只在家庭局域网使用，端口映射就没有必要暴露到公网。云服务器场景下，限制更严格一些，不要在安全组里放行所有来源IP访问该端口，尽量只允许你的常用IP地址访问。

5.2 用反向代理加一层HTTPS

公网访问场景下，我强烈建议在容器前面加一层反向代理，把HTTP升级为HTTPS。原因很直白：如果不加密，局域网或公网传输中的请求和数据包都是明文传输，别人在网络层抓包就能看到HTTP请求的全部内容，包括登录账号密码和上传的PDF文件内容。

反向代理的工具选择很多，我个人觉得Caddy是体验最好的——它最吸引人的地方是自动申请和续期HTTPS证书，配置文件极其简洁。一个简单的Caddyfile示例如下：

pdf.example.com { reverse_proxy 127.0.0.1:8080 }

把域名指向服务器IP，Caddy会自动配置HTTPS，并转发请求到本机的8080端口。配置完成后，浏览器地址栏会显示证书有效，传输链路加密，文件上传下载过程的安全性有了基本保障。如果你熟悉Nginx，也可以用Nginx实现同样的目的，只是SSL证书的申请和自动续期需要额外处理，Caddy对这种个人场景明显更友好。

5.3 容器资源限制与日志清理策略

一个容易忽略但实际很重要的安全问题：容器默认是可以无限使用宿主机资源的。Docker提供了一组资源限制参数，建议在compose文件里给服务加上内存和CPU上限。比如限制容器最多使用2GB内存和2个CPU核心，避免某个异常进程把宿主机拖垮。

deploy: resources: limits: memory: 2G cpus: '2.0'

这个配置在docker-compose中的写法各版本略有差异，但原理一致。容器的日志也是一个隐形磁盘杀手。Spring Boot应用默认输出大量日志，长时间运行后日志文件可能膨胀到几个GB。Docker默认的json-file日志驱动有对应配置可以控制上限：

logging: driver: "json-file" options: max-size: "20m" max-file: "5"

这段配置的意思是每个日志文件最大20MB，保留5个历史文件，超过就自动轮转清理。我配置了这个参数之后，运行了大半年，日志目录的大小一直控制在合理范围内。这些细节虽然不是核心功能，但直接影响长期维护的省心程度。

6. 常见问题排查与使用体验优化

6.1 启动失败和端口冲突怎么查

部署过程中，最常碰到的就是启动后无法访问页面。我的排查顺序是这样的：先用docker ps -a确认容器是否运行中；如果容器状态显示Exited，用docker logs stirling-pdf查看最后的输出日志，错误信息往往就藏在里面。

端口冲突也很常见。如果启动时报port is already allocated，说明宿主机上8080端口已经有进程在监听。用netstat -tulnp | grep 8080（Linux环境）查看占用情况，要么停掉占用进程，要么改掉映射的宿主机端口。

还有一次我碰到容器一直重启，排查发现是挂载目录权限不够。Docker容器内的进程对挂载目录没有写权限，导致启动写日志时崩溃。解决方法就是把宿主机的目录权限放开，或者指定正确的用户ID。这类问题看日志都比较容易定位。

6.2 中文乱码与字体缺失处理

PDF处理中最让人头疼的问题之一就是中文乱码。这里的原理涉及字体：PDF文档里通常嵌入了字体子集，但工具在处理时需要用系统字体渲染新的画面。如果容器里缺少对应字体，渲染出来的文字就会变成方块或者显示异常。

网络上类似问题不少，我自己也遇到过：把一个中文PDF转成图片时，图片中的中文全部变成了空心的方框。解决办法是给容器安装中文字体，或者其他你自己需要的字体。操作上可以进入容器执行字体安装命令，也可以把字体文件挂载到容器的字体目录。换了一个新容器实例后，我记得检查字体配置，从而避免了二次踩坑。

这里信息很多，我做一个简洁的总结：

6.3 大文件处理时的内存调优

处理超大PDF（比如几百MB的工程图纸）时，可能会出现页面崩溃或者处理失败。这本质是Java进程的堆内存不够用了。Spring Boot应用默认的堆内存上限通常是物理内存的四分之一，如果容器本身内存就不多，大文件直接触发OutOfMemoryError。

解决方向有两个：一是给容器分配更多内存，在compose文件中调大资源限制；另一个方向是调整JVM参数，通过环境变量传入JVM内存配置，比如设置初始堆大小和最大堆大小。但这部分配置对版本敏感，建议在修改前查一下当前版本官方文档中关于内存调优的说明再动手。

我的经验是，个人使用场景下不用过度优化。先把容器内存限制从2GB提高到4GB或更高，90%的情况都能解决。如果还想跑更重的任务，把并发下调，一次只处理一个文件，耐心等它跑完就好。

最后记一点自己的使用心得

部署这套PDF工具箱之后，我做事的思路确实变了不少。以前遇到PDF操作需求，第一反应是打开浏览器搜工具，现在则是顺手打开本地页面。两种方式最根本的区别在于心态：在线工具的便利是“借用”来的，本地工具的便利是“掌控”来的。文件的所有环节都发生在自己设备上，这个掌控感带来的安心，是用过之后才体会得到的。

另一个小技巧是，这个项目提供了完整的API接口，所以我后期把几个高强度重复的处理动作封装成了自动化脚本。比如每个月固定月初要把上个月的报表PDF合并存档，用API脚本定时调用一次，完全不用手动操作。如果你经常有类似的重复性PDF处理需求，建议多看看API文档，能省下大量时间。

比起单纯收藏一份工具清单，我更希望你能自己走一遍部署过程。花一个下午把环境跑通，换来的是以后所有PDF操作的彻底自主。这才是告别在线网站隐私风险的根本解法。