★ FEATURED ARTICLE 你有没有想过每次用网页工具转一个PDF其实都等于把文件递给了不知道在哪里的服务器前阵子我要把一份带身份证复印件的扫描PDF转成Word在线网站确实方便可文件一旦上传删除权就不在自己手里了——这个念头反复出现我决定彻底换一种方式自己部署一套私人PDF工具箱。于是我在GitHub上找到了已经狂揽21.7k Star的开源项目Stirling-PDF用Docker Compose几分钟就把PDF转换、合并、加密、OCR这些能力全部装进了本地容器。文件不会离开我的电脑隐私风险基本清零。这篇就记录整个部署过程以及我在真实使用中踩过和解决的坑。1. 为什么非要自己部署在线PDF网站的真实风险先说个我自己的故事。上个月我要给一份合同打水印随手搜了个在线PDF工具上传、加水印、下载整个过程不到30秒。但当天晚上我突然意识到这份合同上有公司全称、银行账号、还有双方签字页的清晰扫描它现在正躺在某个免费网站的服务器缓存里说不定还被同步到了三家数据合作方。这种感觉非常糟糕。其实很多人都知道在线PDF工具有风险但为什么大家还在用因为省事因为偶尔才用一次因为觉得我的文件没那么重要。但实际情况比想象中严峻得多。1.1 你以为“用完即走”其实文件可能被留存免费在线PDF网站靠什么赚钱广告、会员订阅以及——最容易被忽视的——用户数据。很多网站的隐私条款里写着为提供服务需要处理您的文档数据可能存储于境外服务器只是绝大多数人根本不会点开去看。你以为上传后点个删除按钮就万事大吉实际上文件早就被写进了对象存储、日志系统、备份快照甚至被用于改进OCR模型的训练数据。这不是危言耸听。文件在传输过程中同样有风险如果你访问的还是HTTP协议的网站文件在链路中是明文传输同个WiFi下的人甚至有机会直接抓包看到内容。哪怕是HTTPS网站服务器端留存、内部人员访问、数据库泄露任何一环出问题你的合同、简历、身份证扫描件、财务报表都会变成别人手里的素材。另一个被忽视的问题是文件大小和清晰度限制。在线工具为了控制成本通常限制上传体积超过20MB就要付费。好不容易传上去处理引擎还可能主动压缩你PDF里的图片清晰度让扫描投标文件这种场景变成灾难。这些限制的本质是平台成本考量而不是你的需求。1.2 自托管方案到底改变了什么自己部署PDF工具箱核心改变只有一句话PDF文件从头到尾不离开你的设备和网络。Stirling-PDF运行在本地Docker容器里你上传文件到的是自己电脑上跑的Web服务转换、OCR、压缩、加密全在容器内完成结果文件再下载回来。整个生命周期里数据没有经过任何第三方服务器。这个不经过就是隐私风险归零的根本原因。对比下来自托管带来的实际好处非常具体不再有上传体积限制你机器的内存和CPU就是上限我实测过处理300MB的扫描PDF也没问题断网也能用内网环境天然隔离外网处理速度通常比在线网站更快省掉了上行带宽这一步所有中间文件和配置都落在自己的磁盘目录里想删就删、想备份就备份同一套服务可以给整个家庭或团队用不需要每台电脑装PDF软件用一个生活化的类比在线PDF网站相当于把衣服送到公共洗衣房你不知道上一批客人是谁也不知道衣服在机器里停留多久自托管就像在自己家装了一台洗衣机功能一样但衣服从放进来到拿出来始终在自己眼皮底下。2. 21.7k Star的项目长什么样Stirling-PDF功能全景在聊具体部署之前先搞清楚你即将得到什么。Stirling-PDF是一个基于Spring Boot的开源PDF处理Web应用界面就是浏览器里的一个网页左边是功能分类导航中间是上传和操作区域。Star数能到21.7k说明项目不仅在开发者圈子里受欢迎也切中了大量普通用户处理PDF的刚需。2.1 几十个功能常见的PDF需求基本都覆盖了我把Stirling-PDF的功能按使用场景整理了一下你可以对着看自己平时需要用哪些功能类别典型功能适用场景格式转换PDF转Word、Excel、PPT、图片以及反向转换文档编辑、提取数据页面处理合并、拆分、旋转、删除页面、提取页面、重排序整理资料、拆分合同保护与安全加密、解密、添加水印、数字签名、权限设置合同、证书、报告分发内容增强OCR文字识别、添加页码、页眉页脚、压缩扫描件处理、存档高级工具PDF比较、表单填写、页面缩放、批量处理校对版本、表单填报这个功能列表不是我随手编的你打开页面后会看到更细的入口每个类别下还有多个子操作。比如页面处理下面既有合并PDF也有拆分PDF既有旋转PDF也有提取页面基本覆盖了我这些年遇到的90%的PDF操作。界面还支持暗色模式语言切换里能找到简体中文对不爱看英文界面的用户很友好。顺带一提这些功能不是摆样子的demo。我自己拿一份300多页的标书PDF做过合并、压缩、添加页码的组合操作整个过程很顺畅输出文件的排版和原始页面几乎无差别。这种稳定性来自底层引擎的成熟度而不是项目自己从零造轮子。2.2 核心功能背后的实现逻辑为什么这个项目能保持高质量关键在它没有重复造轮子而是把开源世界里久经考验的PDF引擎整合成了一个友好界面。格式转换依靠的是LibreOffice的无头模式。Stirling-PDF在容器里预装了LibreOffice收到转换请求后在后台执行类似libreoffice --headless --convert-to docx的操作所以PDF转Word、转PPT、转Excel这类需求都能处理。这也是为什么它转换Office格式比纯PDF库方案更像人工转换——因为底层真的有一套完整办公套件在跑。OCR识别依靠Tesseract OCR引擎。扫描版PDF本质上是图片集合直接把图片扔给Tesseract识别出文字层再叠加到PDF上就能实现搜索扫描件内容的效果。中文识别需要额外语言包我下面部署部分会专门讲。压缩功能则依赖PDFBox和Ghostscript的组合前者重写PDF对象结构后者对嵌入图片重新采样在画质损失可控的前提下把文件体积压下来。加密和解密用的是PDF标准内置的加密算法。你在页面上输入密码、选择权限级别容器内部完成加密逻辑。整个过程不需要外部API也不会上传任何内容。这解释了一个疑问为什么一个Web应用敢自称隐私安全因为所有敏感操作在本地闭环内完成。3. 实操部署Docker Compose一键拉起现在我假设你已经有了一台能跑Docker的机器。可以是家里闲置的NAS、一台旧电脑或者跑着Linux的云主机。我这次的部署环境是家里的NAS系统是Debian系Docker和Compose都是现成的。如果你还没装Docker先到官方文档装好Docker Engine和Docker Compose插件这部分我就不赘述了。3.1 部署前的准备Docker环境与镜像选择打开终端先确认版本docker --version docker compose version我这边实测下来Docker 20.10以上版本配合Compose v2都没问题。版本太旧的话Compose命令格式会不一样建议先升级。Stirling-PDF官方提供了多个镜像仓库地址。我最常用的是docker.stirlingtools.com/stirlingtools/stirling-pdf:latestghcr.io/stirlingtools/stirling-pdf:latest两个都指向同一个项目随便选一个就行。如果你拉取官方仓库比较慢可以在Docker的daemon配置里配好镜像加速器再拉。这里提醒一句镜像名带latest标签意味着会跟随最新版更新如果你想求稳可以固定到一个具体版本号比如0.36.4这种格式避免某次大版本更新带来配置不兼容。另外新版本Stirling-PDF的默认内部端口是30080老版本用的还是8080。如果你在网上搜到的教程写的是8080很可能对应的旧版镜像。我下面的配置按照新版写你如果发现版本不对注意在端口映射上做相应调整。3.2 写一份docker-compose.yml逐行拆解我强烈建议用Docker Compose而不是直接docker run因为Compose文件本身就是一份可读的部署文档换机器、迁移、回滚都方便。创建一个目录来放配置mkdir -p ~/stirling-pdf cd ~/stirling-pdf然后新建docker-compose.yml内容如下services: stirling-pdf: image: docker.stirlingtools.com/stirlingtools/stirling-pdf:latest container_name: stirling-pdf ports: - 30080:30080 volumes: - ./trainingData:/usr/share/tessdata - ./extraConfigs:/configs - ./customFiles:/customFiles - ./logs:/logs environment: - DOCKER_ENABLE_SECURITYtrue - SECURITY_ENABLE_LOGINtrue - LANGSen_GB,zh_CN - APP_LOCALEzh_CN restart: unless-stopped逐行解释一下关键配置ports里的30080:30080左侧是宿主机端口可以随便改比如改成8080:30080右侧是容器内部端口对应新版默认值不要动。如果访问不了第一步先检查这里是否写反了。volumes挂载了四个目录trainingData存放Tesseract的OCR语言包放到/usr/share/tessdataextraConfigs存放应用自定义配置对应容器内/configscustomFiles放自定义文件资源比如额外的字体、模板logs放日志对应容器内/logs环境变量里比较关键的是DOCKER_ENABLE_SECURITYtrue和SECURITY_ENABLE_LOGINtrue这两个打开后首次启动会引导你创建管理员账号相当于给工具加了一把锁。LANGSen_GB,zh_CN是预置可用语言APP_LOCALEzh_CN让界面默认就显示中文。restart: unless-stopped意思是容器异常退出后自动重启除非你手动停掉。这在NAS上非常实用断电恢复后服务能自己起来。3.3 启动、验证、日常更新写完后在~/stirling-pdf目录下执行docker compose up -d第一次启动会拉取镜像取决于网络状况可能需要几分钟。等命令结束后看一下容器状态docker compose ps状态显示running就说明起来了。浏览器访问http://你的机器IP:30080应该能看到Stirling-PDF的首页。如果启用了登录先去完成管理员账号初始化。然后随便找一个小PDF试试合并或转换功能确认整个链路没问题。日常更新也很简单docker compose pull docker compose up -d这里有一个特别重要的经验更新前先备份extraConfigs目录里的配置文件。我自己有次手欠直接删了容器重建结果自定义设置全丢了。虽然影响不大但重新配置一遍确实烦人。养成备份的习惯五分钟的事。4. 进阶配置隐私加固与使用体验优化部署起来只是第一步真正要把隐私和安全做到位还需要做几件加固的事。很多人的自托管服务出事不是软件本身不行而是直接把端口暴露到公网、不加任何访问保护。这种裸奔状态比用在线工具更危险因为攻击者盯上的就是这些自建服务。4.1 反向代理与HTTPS把服务藏到安全网关后面如果你只在家庭局域网内使用HTTP其实是够用的毕竟内网相对可控。但如果要跨网络访问比如在公司连家里NAS上的PDF服务就一定要上HTTPS。这时候需要一个反向代理把外部请求转发到Stirling-PDF的30080端口。Nginx配置示例server { listen 443 ssl; server_name pdf.example.com; ssl_certificate /etc/nginx/certs/server.crt; ssl_certificate_key /etc/nginx/certs/server.key; location / { proxy_pass http://127.0.0.1:30080; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } }要点有两个proxy_pass指向Stirling-PDF所在地址X-Forwarded-Proto要正确传递否则应用里可能出现奇怪的跳转或协议判断错误。不想手写Nginx配置的话用Caddy这类自动申请证书的反代工具会更省心域名解析好之后基本零配置就能跑HTTPS。另外强烈建议在防火墙层面限制来源IP。如果只有你和少数几个同事用就把云主机的安全组或NAS防火墙的入站规则设成只允许特定IP访问。我见过太多人把Docker服务映射到公网端口最后被扫描器盯上、把CPU跑满的案例。Docker端口映射本质上是把服务公开不是默认安全的。4.2 启用登录认证与API密钥在Compose环境变量里打开DOCKER_ENABLE_SECURITY和SECURITY_ENABLE_LOGIN后Stirling-PDF的界面会要求登录。管理员账号初始化的流程是启动后打开页面按提示创建账号密码。之后所有用户操作都需要认证这就挡住了陌生人访问。如果你有脚本化批量处理PDF的需求比如每天自动给新上传的合同加水印可以在应用的用户设置里生成API密钥。调用HTTP接口时在请求头带上这个密钥就能绕过页面登录直接操作功能模块。这个设计很贴心因为普通用户用界面、开发者用API互不干扰。有一个容易忽视的点登录认证只保护了Web界面和API如果你的Stirling-PDF容器端口本身被映射到了公网攻击者还是能直接发起连接只是不知道密码而已。所以别只依赖应用层的登录一定要配合防火墙或者反代层的IP白名单把暴露面缩到最小。4.3 界面中文与功能裁剪中文界面靠环境变量APP_LOCALEzh_CN就能搞定设置后刷新页面立即生效。如果你希望团队其他人打开时也是中文这个变量必须写在Compose里而不是靠每台浏览器手动切换。功能裁剪是我后面才发现的优化点。Stirling-PDF功能很多但有的模块你可能永远用不到留着反而增加攻击面。在extraConfigs里可以通过配置文件禁用某些功能入口界面上的按钮会隐藏对应后端接口也会关闭。这种最小化暴露的思路是所有自托管服务都应该遵守的不需要的功能就不要开放。你可以在官方文档里找到功能开关的对应选项按需关闭OCR模块或者关掉不需要的格式转换都能让整个服务更精简。5. 常见问题与排查技巧实录部署和使用过程中我踩了不少坑。有些问题在官方文档里写得比较隐晦遇到时真的会卡住半天。我把典型的几个整理成表格你按图索骥排查就好。5.1 部署阶段的高频问题现象可能原因排查与解决容器启动失败docker compose ps显示不断重启端口被占用或镜像与当前系统不兼容查看docker compose logs最近几十行日志换宿主机端口比如8080:30080浏览器访问不了页面端口映射写反或防火墙拦截确认ports格式是宿主机端口:容器端口在宿主机执行curl http://127.0.0.1:30080排除应用本身问题镜像拉取一直失败或超时网络问题或镜像仓库连接不畅配置Docker镜像加速器换用另一个镜像仓库地址启用了登录但页面不跳登录框浏览器缓存了旧页面或环境变量没生效强制刷新浏览器缓存确认Compose里SECURITY_ENABLE_LOGINtrue重启容器查看日志是排查一切问题的第一步。命令是docker compose logs -f stirling-pdf日志里能看到Spring Boot的启动过程以及具体的报错堆栈。绝大多数启动失败问题日志都会直接告诉你原因比盲目改配置高效得多。5.2 使用过程中的隐藏大坑第一个坑是转换权限问题。容器以root运行时生成的临时文件在卷目录里可能带着root用户权限宿主机上普通用户删不了。更麻烦的是如果挂载目录的所有者不对容器内进程可能写不进去界面会提示转换失败。解决办法把宿主机上的目录所有权改成容器内运行用户的UID或者在Compose里通过环境变量指定PUID/PGID。具体数值以你的系统为准网上搜一下就有对应方案。第二个坑是中文OCR不识别。默认镜像只带英文语言包你上传中文扫描件识别结果会是一堆乱码。需要手动下载中文语言包chi_sim.traineddata放到./trainingData目录下然后重启容器。语言包可以从Tesseract的官方仓库下载文件名别写错放对位置后OCR功能立刻就能识别中文。第三个坑是大文件处理内存溢出。Stirling-PDF基于Java默认堆内存设置比较保守。我处理过一个200MB的PDF压缩任务直接报内存错误。解决办法是设置JVM参数在Compose里加环境变量JAVA_OPTS-Xmx4g把最大堆内存调到4GB。如果你的机器内存有富余加到8GB也可以。调整后需要重建容器才会生效。第四个坑是日志目录无限膨胀。./logs目录下的日志文件会持续推进长期运行后可能吃掉几十GB磁盘。建议配置日志轮转或者写个定时任务自动清理超过N天的日志。很多人部署自托管服务跑了一年后发现NAS磁盘满了查下来全是日志的锅。6. 实际使用一段时间后的经验心得这套私人PDF工具箱在我家NAS上稳定跑了几个月它改变的不只是我处理文件的方式更是我对待隐私的态度。6.1 私密文档处理流程彻底变了以前处理一份扫描合同的标准流程是手机拍照转PDF、在线压缩到体积限制内、上传网站加OCR、下载、再传到另一个网站加水印。现在这个流程变成了一个页面里的六次点击。尤其处理身份证、银行流水、劳动合同这类高度敏感的文件时我再也不用一边操作一边心里打鼓了。我还把服务分享给了家里人和团队同事。每个人打开浏览器输入NAS地址登录后就能用自己的PDF工具不需要每人装一套软件也不需要互相传文件。内网办公场景里这种集中部署、按需取用的方式其实比本地安装更高效。你可以把Stirling-PDF和已有的NFS共享、Nextcloud等自托管服务放在一起形成一个完整的私有办公链路。6.2 后续还能怎么玩Stirling-PDF的API能力值得深入挖掘。我用脚本把批量添加水印自动化了新生成的PDF扔进一个特定目录定时任务调用Stirling-PDF的API处理完再归档。这一套下来重复劳动基本清零。还可以考虑给Stirling-PDF接入统一身份认证。团队规模大了以后每个人单独注册账号不方便通过OIDC或LDAP对接公司现有的账号体系体验会上升一个档次。社区里这两个方向的教程都挺多的。说实话这几乎是目前自托管PDF工具里最成熟的选择。它和现在大家热衷在本地部署大模型其实是一回事数据和工具都拿回自己能控制的边界里运行。PDF处理不是什么高深技术但当它变得完全可控、不依赖任何第三方时那种踏实感是无法替代的。我的实际体会是部署这套私人PDF工具箱真正解决的其实不是省一个会员钱的问题而是让文件从上传那一秒起就始终在自己手里。最后再分享一个小技巧如果你只是图省事又不想搞复杂配置那这套Docker Compose方案已经是性价比最高的起点了——把服务跑在NAS或者旧电脑上家里任何设备都能访问的PDF处理中心就有了。希望这篇文章能帮你避掉我踩过的坑早点把PDF隐私风险关在门外。
阅读完成 · 觉得有帮助？
