Stirling-PDF 从零开始详细教程:Docker 一键部署,PDF 合并拆分压缩 OCR 全流程(2026)

Stirling-PDF 的界面:左侧是 PDF Library 和分类图标,右侧 PDF Tools 栏按推荐、签名、文档安全、校验分组列出工具
图源:Stirling-PDF 官方文档首页截图

Stirling-PDF 是一个跑在自己机器上的 PDF 工具箱。Docker 起一个容器,浏览器打开 8080,五十多个 PDF 操作都在里面:合并、拆分、压缩、扫描件识别、转 Word、签名、打码、加密码。

代码在 GitHub 上(Stirling-Tools/Stirling-PDF),到今天 95,821 颗星,2023 年 1 月建仓,不算新项目。官方给它的定位是开源的 PDF 平台:能当桌面软件装,能架成局域网服务,也能调 API 做批量处理。

绝大多数人装它只有两个原因:扫描件要能搜,和不想把合同传到某个在线转换站。

一、先划清它和 Acrobat 的分界

Acrobat 里收费的那部分,大致是三类活:格式转换、批量整理、扫描件识别。这三类 Stirling 都做了,免费,没有页数限制。

它替不了的是另一类:印刷文件、复杂交互表单、把一份定稿的 PDF 重新排版。下表按需求逐条对。

你要干的事AcrobatStirling-PDF说明
合并、拆分、提取、重排有有都有,见页面编辑器
压缩有有它能直接填目标体积
扫描件 OCR付费版才有有标准镜像自带简体中文
PDF 转 Word / PPT / Excel有有走 LibreOffice
加密码、改权限、打码有有打码是真删除
数字签名有有证书要自己备
改已有正文文字有部分能改,做不了整段重排
商业印刷(CMYK、专色、出血)有无这类别用它
复杂交互表单有部分能填不能做逻辑

一句话概括:从零做出一份 PDF 的活它都干,改一份已经定稿的 PDF 它只干一半。

二、Docker:一次拿到全部功能

官方推荐 Docker,这也是唯一能一次装齐全部工具的装法。命令照着抄,路径换成你自己的,其余不用动(完整参数见安装文档)。

docker run -d \
  --name stirling-pdf \
  -p 8080:8080 \
  -v ./stirling-data/configs:/configs \
  -v ./stirling-data/logs:/logs \
  -v ./stirling-data/storage:/storage \
  -v ./stirling-data/tessdata:/usr/share/tessdata \
  --memory 4g \
  --restart unless-stopped \
  docker.stirlingpdf.com/stirlingtools/stirling-pdf:latest

跑完打开 http://localhost:8080。首次登录账号 admin、密码 stirling,进去会强制你设一个至少八位的新密码,改完才算登进来。

想留得规整一点,用 compose。多挂两个卷,日志和 OCR 语言包也在里面。

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/storage:/storage
      - ./stirling-data/tessdata:/usr/share/tessdata
    mem_limit: 4g
    restart: unless-stopped
Docker 部署三步示意:跑一行命令、容器在 8080 起来、浏览器打开并用 admin 登录

镜像有三个标签,功能差得不少,选错了会以为功能缺失。

标签建议内存带什么
latest4 GBLibreOffice、Tesseract、OCRmyPDF、WeasyPrint、Calibre、Ghostscript、QPDF、ImageMagick。不含 rar,所以没有 PDF 转 CBR
latest-fat6 GB,开 AI 更高在 latest 之上多打包一套 AI 引擎,默认关着
latest-ultra-lite2 GB只有核心 PDF 操作,没有 OCR,没有 Office / HTML / 电子书转换,也没有登录和后台设置

三条部署上的说明。第一,/configs 和 /storage 两个卷必须挂,官方原话是 always mount,不挂的话容器一重建,设置和用户保存的文件都没了。第二,容器以 UID 和 GID 1000 运行,宿主机目录属主不是 1000 就设 PUID 和 PGID。第三,换镜像只改 tag 再重建,卷里的数据带得过去。

更新是 pull 加 up -d。跨大版本前把 /configs 备一份,官方专门提了这句。

不想自己敲命令的话,几个成品平台都有一键包。群晖、绿联、爱速特在各自应用商店里搜 Stirling PDF;Unraid 装上 Community Applications 插件再搜同名;TrueNAS SCALE 的 Apps 里直接有;Proxmox 有社区脚本,一行就能装成 LXC。这些包是社区维护的,出问题报到各自项目去,别去官方仓库提。

除 Docker,官方还给 Kubernetes 和裸 JAR 两条路,另附一份生产环境检查清单。个人和小团队用 Docker 就够,JAR 那条只在你连 Docker 都装不了的时候才考虑。

自己用,还是给全家、给团队用?

上面这条 docker run 是跑在你自己电脑上的。关掉容器、合上笔记本,或者人在外面,这个地址就打不开了。

想让它 7×24 在线、手机和同事都能直接打开,把这同一条命令搬到一台常开的机器上就行——镜像、端口、挂载卷都不用改。阿里云轻量应用服务器 + Token Plan 组合购 68 元起,选好系统跑一条 Docker 命令就起来了;机器上还预置了 OpenClaw / Hermes 的官方镜像,如果你也在折腾 AI 助手,一台机器两件事都能干,全程不用写代码。

放公网之前先做一件事:Stirling-PDF 默认不带登录验证,要打开 SECURITY_ENABLELOGIN,或者在前面加一层反向代理认证——否则等于把 PDF 处理能力公开给全互联网。本文第九节也提到过这条边界。

👉 阿里云 · 轻量应用服务器(68 元起,可选 OpenClaw / Hermes 官方镜像)

说明:上面是推广链接,你通过它购买我会拿到一点返佣,不会让你多付钱;价格与活动细则以活动页实时显示为准。

三、不装 Docker:桌面版,以及它的限制

桌面版是独立客户端(下载页)。Windows 10 或 11 用 MSI,或者 winget install StirlingTools.StirlingPDF;macOS 10.15 以上用 DMG,或者 brew install –cask stirling-pdf;Linux 有 deb、rpm 和 AppImage。

装完不用起容器,界面和服务器版一样。代价是有几个工具跑不了。

Windows 上有一种情况是装完点开没反应:进程在跑,窗口不出现。装一下 Microsoft Edge WebView2 Runtime 再打开就好,官方安装页专门写了这条。

桌面版工具分流:合并拆分压缩签名等在本地跑,OCR、Office 转 PDF、PDF 转 Word 要连 Stirling Cloud 或自建服务器

它有三种连接模式,决定了文件会不会离开你的机器。

模式要登录吗工具在哪跑
Local Only不用全在你电脑上,需要服务器的工具直接挡住
Stirling CloudStirling 账号能本地跑的就本地跑,跑不了的送到云上
Self-Hosted你自己服务器的账号全部在你那台服务器上

这里有个最容易踩的坑:Local Only 不等于所有功能都能离线用。OCR、Office 和电子书转 PDF、PDF 转 Word 或 PPT、修复损坏文件、压缩里的转线稿,这几项在 Local Only 下会带一个云朵标记,点下去会让你登 Stirling Cloud 或者连一台服务器。官方工具运行位置那一页写得很明确。

所以要完全不联网又要有 OCR,只有一条路:自己架服务器,桌面版连过去。或者干脆只在浏览器里用服务器版。

四、每天都在用的那几个

工具按用途分组(全工具清单),最常用的八个固定在工具选择器最上面,各自带快捷键:文本编辑、页面编辑器、合并、比对、压缩、转换、OCR 与清理扫描件、打码。

页面编辑器在列表里叫 PDF Multi Tool,是干杂活的主力。旋转、重排、删页、拆分、插空白页在同一个界面里做完,不用来回切工具。

页码、水印、页尺寸、多页合一、小册子拼版在 Page formatting 组;提取图片、拆出指定页在 Extraction 组;删空白页、删批注、删图片、去密码在 Removal 组。

还有一个 Automate:把几个工具串成一条链存下来,以后丢进文件一次跑完。批量处理值得先花五分钟配一条。

五、压缩:可以填目标体积

压缩有两种模式。Quality 是拖一个 1 到 9 的滑块,默认 5,数字越大文件越小、图片越糊。File Size 是直接填你要的体积,KB 或 MB,它自己往那个数上靠。

第二种是它比多数在线工具好用的地方。要发邮件、要过 10 MB 的限制,填 9 MB 就行,不用一档一档试着压。

附加选项作用什么时候用
转灰度图片变黑白灰内容本来就是黑白的扫描件
线性化重排文件,首页先出来要放在网页上边下边看
转线稿压成高对比黑白,省得最多纯文字扫描件,照片别用

转线稿打开后会多两个参数:细节程度 1 到 5,默认 3;边缘强调分柔和、均衡、强,默认强。

能压到几分之一,我给不了你一个数。扫描件的分辨率、是不是彩色、底噪多少决定了上限,同一份文件换台扫描仪结果都不一样。

也会有压不动的时候。文件里本来就全是高质量 JPEG,或者整份以矢量图和文字为主,可剥的水分不多,压完可能只小一成。这时换 File Size 硬压,代价是图片开始发糊,值不值要自己看。

顺序上有个讲究:扫描件既要能搜又要小,先 OCR 再压缩。反过来的话,压完图糊了,识别就认不准。

六、扫描件 OCR:这一项最值钱

拍照或者扫描出来的 PDF 本质是一堆图片。放大能看清,但搜不到、选不中、复制不出来。OCR 把识别出的文字作为一层透明文本压在上面,文件外观不变,但能搜了。

这是整个工具里最值得装的一项。Acrobat 的 OCR 要付费版才有,在线 OCR 站要么限页数,要么把文件留在它服务器上。

识别质量有一半在源文件。扫描仪设 300 dpi,存灰度或彩色都行,别为了省体积用 150 dpi。糊掉的笔画认不出来,后面 OCR 参数调得再好也补不回来。

语言包:标准镜像自带简体中文

OCR 只能用装了语言包的语种。标准镜像和 fat 镜像自带英语、德语、法语、葡萄牙语和简体中文,ultra-lite 完全没有 OCR(语言包文档)。

要加别的语种,在设置里的服务器高级页,Processing 卡片会列出已装的语种,下面能勾选下载。它从 tesseract-ocr/tessdata 仓库拉,服务器要能上网。

这样下载的语言包放在容器里,容器一重建就没了。要长期留着,把宿主机目录挂到 /usr/share/tessdata。

三种模式,别选错

模式行为什么时候用
Auto(跳过已有文本层)默认,已经有文字的页跳过大多数情况
Force(全部重做)每页都重认,覆盖原有文字上一次 OCR 质量差
Strict(发现文字就中止)有任何一页能选中文字就停要确认文件干不干净

处理选项

选项干什么
兼容模式文件更大,但老 PDF 软件和一些语种更认
生成文本文件顺手存一份 .txt
摆正页面识别前把歪的页掰直
清理输入去噪、提对比度
清理输出把识别出来的文本层理干净

一个流程建议:扫描歪的先勾摆正页面,手机拍的先勾清理输入,中英混排的把两个语种都选上,最后勾生成文本文件,顺手留一份纯文本。

七、转换、签名、打码、加密码

格式互转走 Convert。PDF 转 Word、PPT、RTF、HTML、Markdown、XML、EPUB,反方向的 Office、电子书、网页、邮件转 PDF 也在这里。转换靠 LibreOffice 和几个转换库,这是官方镜像比同类工具重的原因。

两点要说清。转出来的 Word 是重新排的,不是原文件的编辑工程,复杂版式会走样。扫描件转 Word 得先 OCR,否则转出来还是一堆图片。

签名有两种。Sign 是画一个、打一个或者贴一张图片签名,看着像签了。Sign with Certificate 是用证书做数字签名,能证明是谁签的、签完之后有没有被改过,要你自己有证书。

打码用 Redact,是把内容真的删掉。盖一个黑框那种,框底下的文字还能复制出来,等于没打。

加密码用 Add Password,可以设打开密码,也可以只限制打印、复制、编辑。要解开得知原密码,用 Remove Password。

文件交出去之前还有一步:Sanitize,把 PDF 里的 JavaScript、嵌入文件这些看不见的东西清掉。

八、它替不了 Acrobat 的地方

先说清楚,免得装完觉得被骗。

改已有的正文。它有 PDF Text Editor,能改文字和图片,但那是补几个字、改个错别字用的,不是排版工具。整段重排、换字体、调行距,到不了 Acrobat 那种程度。

印刷。商业印刷要 CMYK、专色、出血、陷印,它一样都不管。要做印刷文件还是回 Acrobat 或 InDesign。

复杂交互表单。它能填、能加字段、能自动找表单域,但做不了带计算和校验逻辑的表单。

反过来,如果你的活只是把一堆文件理成一份、压小、扫描件变能搜、加个密码再发出去,Acrobat 对你就没有用处。

九、许可和部署上的几条边界

仓库的 LICENSE 一栏显示 NOASSERTION,容易被误会成没开源。原文是 MIT,但有几个目录另算:app/proprietary、app/saas、engine,加上前端的几个 editor 子目录和 processor。README 里写的是 open-core。自己用、公司内部用,MIT 覆盖的那部分足够。

服务器版是免费方案,但有用户数上限:Free 5 个,Team 从 100 个起、可以按 100 递增,再多走企业版。SAML 单点登录、审计日志、离线激活这些也在企业版(方案与许可)。个人和小团队碰不到这条线。

部署上有一条别省:这东西能读能改你机器上的文件,别直接开到公网。至少改掉默认密码,前面挂一层反向代理加认证,只在内网或 VPN 里用。

还有一条给写代码的人:几乎每个工具都有对应的 REST API,可以拿它做批量处理,几百份文件丢进去一次跑完。官方文档里单列了一节讲 API 和 MCP。

值不值得装,看你一个月有几次要处理 PDF。一年用两回的,在线工具够了。每周都要合并拆分、还要处理扫描件的,装一次省下来的时间比装它花的时间多。

本文的功能范围、命令参数、镜像标签、语言包范围、方案限制都取自官方文档,正文里逐处给了链接。压缩率我没有在你的文件上跑过,所以没写具体倍数。

站内相关:Adobe 全套软件的开源替代、默读 Modu Reader:扫描书 OCR 之后能划词、翻译、PDF 加盖骑缝章小工具。

© 版权声明
THE END
喜欢就支持一下吧
点赞13 分享
评论 抢沙发
头像-二楼后座
欢迎您留下宝贵的见解!
提交
头像-二楼后座

昵称

取消
昵称表情代码图片快捷回复

    暂无评论内容