Stirling-PDF:把 50 多个 PDF 工具搬回自己电脑
读者假设:会敲命令行,装过 Docker。 需要:一台常开的电脑(2 GB 内存够),10 分钟。 读完你能:在浏览器里用上合并、拆分、压缩、OCR、格式转换、加密签名一整套 PDF 工具,文件不出本机。
一、为什么不用在线网站
"PDF 合并""在线压缩"这类网站,用起来确实爽:打开、拖文件、点按钮、下载。但它们有三个隐患:
- 文件去哪了:你上传的合同、身份证扫描件、体检报告,落在别人的服务器上,存多久、谁在看,你不知道
- 限制:免费版限制文件数、大小、每天次数,压缩还给你降质
- 哪天就没了:这类站靠广告活着,随时关停
Stirling-PDF 就是把这些工具整套搬到你自己机器上:开源、Docker 一键起、浏览器打开就用、文件根本不出内网。
它内置 50+ 工具,日常能想到的基本都有。
二、它能干什么
| 类别 | 具体功能 |
|---|---|
| 页面操作 | 合并、拆分、提取页面、调整顺序、旋转、删除空白页 |
| 优化 | 压缩(多档)、修复、扁平化 |
| 格式转换 | PDF ↔ 图片、PDF → Word/Excel/PPT、HTML → PDF、Markdown → PDF |
| 识别 | OCR(把扫描件变成可搜索文本,支持中文) |
| 安全 | 加密/解密、加水印、盖章、涂黑(redact)、签名 |
| 其他 | 页码、目录、对比两份 PDF、拆分按大小/书签 |
几个真正常用的:合并、拆分、压缩、OCR、加水印、PDF 转图片。
三、部署:一条命令
先建目录:
mkdir -p ~/stirling/{data,tessdata,logs} && cd ~/stirling
然后(一行,注意换行符):
docker run -d \
--name stirling-pdf \
-p 8080:8080 \
-v ~/stirling/data:/configs \
-v ~/stirling/tessdata:/usr/share/tessdata \
-v ~/stirling/logs:/logs \
-e LANGS=zh_CN \
--restart unless-stopped \
stirlingtools/stirling-pdf:latest
三个挂载点分别对应:
| 宿主机目录 | 容器内 | 存什么 |
|---|---|---|
~/stirling/data |
/configs |
配置、自定义设置 |
~/stirling/tessdata |
/usr/share/tessdata |
OCR 语言包(中文包放这里) |
~/stirling/logs |
/logs |
日志 |
环境变量名会随版本变。装之前扫一眼官方 README 里的
docker run示例,如果你那版叫DOCKER_ENABLE_SECURITY、INSTALL_BOOK_AND_ADVANCED_HTML_OPS之类,照抄官方的即可,别的不用改。
你应该看到
docker ps
CONTAINER ID IMAGE STATUS PORTS
a1b2c3d4e5f6 stirlingtools/stirling-pdf:latest Up 2 minutes 0.0.0.0:8080->8080/tcp
浏览器打开 http://你的机器IP:8080。
四、先解决一个安全问题(重要)
Stirling-PDF 默认没有登录——谁能访问 8080 端口,谁就能用。
三种处理方式,按你的场景选:
方案 A:只在内网用(最简单)
不映射到公网,只在家里/办公室局域网用。路由器别做端口转发。
方案 B:前面加一层 Nginx Basic Auth
location / {
auth_basic "Restricted";
auth_basic_user_file /etc/nginx/.htpasswd;
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
client_max_body_size 100m; # 大 PDF 要放宽
}
生成密码文件:
sudo apt install apache2-utils -y
sudo htpasswd -c /etc/nginx/.htpasswd 你的用户名
方案 C:开启内置登录
新版支持用环境变量开安全模块(变量名以官方文档为准),大致是:
-e DOCKER_ENABLE_SECURITY=true \
-e SECURITY_INITIALLOGIN_USERNAME=admin \
-e SECURITY_INITIALLOGIN_PASSWORD='换成强密码' \
不管选哪种,别把 8080 裸着放到公网。 这玩意儿能读写你的文件,比一般服务危险。
五、六个最常用的操作
打开网页,左侧是工具列表,点进去就是上传界面。
1. 合并(Merge)
左侧 Merge → 拖入多个 PDF → 拖拽调整顺序 → Merge → 下载。
2. 拆分(Split)
两种模式:
- 按页数拆:每 N 页一个文件(扫描件按章节拆很实用)
- 按范围拆:填
1-3,5,7-9这种区间
3. 压缩(Compress)
Compress → 选压缩等级(1–9,数字越大压得越狠、质量越低)→ 运行。
经验:扫描件选 5–7 能压到原来的 1/3 且肉眼可读;文字版 PDF 压缩空间有限,压不动是正常的(它本来就没多少冗余)。
4. OCR(让扫描件能搜)
OCR → 上传 → 选语言 Chinese (Simplified) + English → 运行。
中文 OCR 要先装语言包,否则下拉框里只有英文:
cd ~/stirling/tessdata
curl -LO https://github.com/tesseract-ocr/tessdata_fast/raw/main/chi_sim.traineddata
然后刷新页面,语言列表里就有中文了。
识别质量取决于扫描分辨率。300 dpi 以上的扫描件效果好;手机拍照歪着拍、有阴影的,识别率会明显下降。
5. PDF ↔ 图片
PDF to Image:整份 PDF 转成 PNG/JPG,可批量打包下载Image to PDF:多张图合成一份 PDF(报销单据、证件照合并都靠它)
6. 加水印 / 加页码
Add Watermark 支持文字水印(可调透明度、旋转角度、铺满全页);Add Page Numbers 支持位置和起始页。
给合同加水印(比如"仅用于XX用途")就用这个,比截图再贴回去体面得多。
六、备份与升级
备份
真正要备份的只有两样:
# 配置
tar czf stirling-config-$(date +%F).tar.gz ~/stirling/data
# 中文语言包(重新下载也行,备份了省事)
cp ~/stirling/tessdata/chi_sim.traineddata ~/backup/
处理过的文件不会留在容器里——它在内存/临时目录里处理完就给你下载,不落盘。这是它的设计,也意味着没有"文档库"要备份。
升级
docker pull stirlingtools/stirling-pdf:latest
docker stop stirling-pdf && docker rm stirling-pdf
# 再执行一次上面那条 docker run
配置在 /configs 挂载着,重建容器不丢。
七、常见报错
| 现象 | 原因 | 处理 |
|---|---|---|
| 8080 打不开 | 容器还在启动 | docker logs -f stirling-pdf 等它起来,首次约 30 秒 |
| 上传大文件报 413 | 反代限制 | Nginx 加 client_max_body_size 100m; |
| OCR 下拉框没有中文 | 语言包没放对 | 确认 chi_sim.traineddata 在 /usr/share/tessdata,然后重启容器 |
| 转换 Word 失败 | 缺少 LibreOffice 组件 | 换用带完整依赖的镜像 tag,或看日志缺什么 |
| 页面空白 / 一直转圈 | 浏览器缓存了旧版本 | 强制刷新(Ctrl+Shift+R) |
| 内存爆掉 | 大 PDF + OCR 很吃内存 | 限制单文件大小,或给容器加 -m 2g |
| 中文界面没生效 | LANGS 写错 |
用 zh_CN,重启容器 |
八、下一步
跑顺之后可以配这两件事:
- 接到 Paperless-ngx 前面:扫描件先用它压缩/OCR,再丢进归档系统(站内有那篇)
- 手机访问:内网用 IP 就行;要在外面用,走 Tailscale 或 frp,别直接开端口
九、出处与参考
- 官网:https://stirlingpdf.com/
- 源码仓库:https://github.com/Stirling-Tools/Stirling-PDF
- 官方 Docker 文档(部署参数以这里为准):https://docs.stirlingpdf.com/
- 镜像地址:
stirlingtools/stirling-pdf(Docker Hub) - Tesseract 语言包:https://github.com/tesseract-ocr/tessdata_fast
项目以 MIT 许可开源。命令在 2026-11 的
latest镜像上验证;环境变量名随版本有调整,部署前对照官方 README。
默认评论
Halo系统提供的评论