94k Star 的 PDF 神器,我把 Stirling-PDF 装进了 NAS

上周帮朋友改一份文件。对方发来的是扫描件，要转成 Word。改完还得合并附件，发给客户前再压一压体积。

我打开了三个在线工具。两个要先登录，一个免费转换只给前三页。

关掉网页，我把这件事丢给了 NAS 上的 Stirling-PDF。

9.5 万 Star，50 多个 PDF 工具。装一次，家里所有设备打开浏览器就能用。

这篇把我自己的部署过程写清楚，也说说哪些地方值得用，哪些地方别抱太高期待。

打开就是一个 PDF 工作台，左边文件库，中间阅读器，右边工具面板

01

它到底是什么

官方对它的定义很克制，开源 PDF 平台。

翻成大白话，一个装在浏览器里的 PDF 工具箱。

合并、拆分、压缩、OCR、格式转换、改文字、加密码、遮盖、签名，五十多个工具放在同一个界面里。

项目 2023 年 1 月创建，现在 94,686 Star、11,383 个 fork，最新版本 3.2.2，界面支持四十多种语言。

它有三种跑法，桌面客户端、云端、自己部署的服务器。我们要用的是第三种。

还有两个容易被忽略的能力。它开放 REST API，几乎每个工具都能用代码调用；也支持 MCP，可以让 Claude、GPT 这类助手直接操作 PDF。

这意味着它不只是给人点鼠标用的，也能接进自动化流程。

五十多个工具，日常用到的其实就这四类。

02

为什么放在 NAS 上

在线 PDF 工具不是不能用，问题是文件要离开家。

合同、发票、体检报告、身份证扫描件，上传到别人服务器的那一刻，后面发生什么你控制不了。

第一是文件。放 NAS 上，文件从浏览器进容器，处理完再回浏览器，中间不出局域网。

第二是设备。部署一次，电脑、手机、平板都能用，不用每台机器装软件。

第三是时间。转换、OCR、压缩这些活都在 NAS 上跑，电脑可以关，手机可以锁屏。

第四是文件本来就在 NAS 上。处理完直接落盘，快照、备份、同步都是现成的。

如果只是偶尔合并两个 PDF，它有点重。但只要家里经常有人跟 PDF 打交道，这套东西很快就会变成基础设施。

浏览器只负责操作，计算和存储都在 NAS 上

03

部署，一段 Compose 和四个注意

先说前提，NAS 能跑 Docker，内存 4GB 以上，硬盘留 10GB 左右。x86 和 ARM 都支持，群晖、威联通、极空间、绿联、TrueNAS、Unraid 流程一样。

新建一个 Compose 项目，把下面这段贴进去。群晖在 Container Manager 里点项目、新增，选创建 docker-compose.yml；威联通在 Container Station 的应用程序里粘贴；极空间和绿联在 Docker 应用里选自定义 Compose。

DOCKER-COMPOSE.YML

services:  stirling-pdf:    image: docker.stirlingpdf.com/stirlingtools/stirling-pdf:latest    container_name: stirling-pdf    ports:      - "8088:8080"    volumes:      - /volume1/docker/stirling/configs:/configs      - /volume1/docker/stirling/logs:/logs      - /volume1/docker/stirling/customFiles:/customFiles      - /volume1/docker/stirling/pipeline:/pipeline      - /volume1/docker/stirling/storage:/storage      - /volume1/docker/stirling/tessdata:/usr/share/tessdata    environment:      - TZ=Asia/Shanghai      - PUID=1000      - PGID=1000      - UMASK=022    mem_limit: 4g    restart: unless-stopped

路径按自己的 NAS 改。先在 Docker 目录下建好 stirling 这个总目录，子目录让容器自己生成。群晖一般在 /volume1，威联通是 /share，极空间和绿联可以在界面里直接选目录。

四个注意。

第一，端口。左边 8088 可以换成任何没被占用的数字，右边 8080 别动。

第二，镜像。docker.stirlingpdf.com 在国内偶尔拉不动，可以换 Docker Hub 的 stirlingtools/stirling-pdf:latest，或者 ghcr.io/stirling-tools/stirling-pdf:latest。三个地址是同一个镜像。

第三，权限。容器默认用 1000 这个用户跑。如果日志里出现 Permission denied，把 PUID 和 PGID 改成你 NAS 上那个用户的 ID，群晖可以 SSH 进去用 id 命令查。

第四，内存。官方建议 4GB。实在紧张可以换 latest-ultra-lite，但那个镜像没有 OCR、Office 转换和登录，只剩核心工具。

三个镜像的区别，一张表能说清。

启动后浏览器打开 http://NAS的IP:8088。

第一次登录用 admin 和 stirling，系统会要求你改一个至少 8 位的密码。

这一步别跳过。尤其是你打算做端口映射或者内网穿透。

只在局域网用，也可以把 SECURITY_ENABLELOGIN 设成 false 关掉登录。但默认登录开着有它的道理，免费版支持 5 个用户，够一家人用。

04

第一次打开，先认三块区域

界面不复杂。左边是 PDF 库，中间是阅读器和工作区，右边是工具面板。

顶部搜索框可以直接搜工具名，不用在一长串菜单里找。中文是自动的，跟着浏览器语言走。

上传有两个方式，点添加文件，或者把文件直接拖进窗口。

文件会进 PDF 库，处理完的结果也在里面。下面挑五个我用得最多的场景。

05

五个最常用的场景

合并。把合同和报价单一起拖进来，右边会列出文件顺序，拖动就能调。

两个开关值得看一眼，一个是在合并后的文件里删掉数字签名，一个是自动生成目录。

两个文件排成一条线，顺序拖一下就行

压缩。这个功能应该是最常用的。

压缩方式有两种，质量优先和文件大小优先。质量优先给一个 1 到 9 的档位，数字越大压得越狠。

扫描件可以勾选转灰度，体积能再降一截。线性化那个选项是给网页快速预览用的，普通存档不用开。

质量优先适合合同和报告，文件大小优先适合扫描件归档

转换。PDF 转 Word、Excel、PPT、图片，反过来也能转。

格式列表比大多数在线工具全，连 PDF/A、PDF/X、PDF/UA 这些归档标准都带着。

转换靠镜像里的 LibreOffice，普通文档问题不大，复杂排版还是得手动收一下。

常用的办公格式都在，归档标准也给了

改字。这是它跟大多数在线工具拉开差距的地方。

PDF 文本编辑器可以直接点页面上的文字改，不用先转 Word 再转回来。

改完点保存，字体和位置尽量保持原样。复杂排版不敢保证，但改个金额、日期、地址，比来回转换省事。

点中文字块，直接进入编辑状态，改完存成 PDF

签名。支持四种方式，手绘、打字、上传图片、手机扫码。

签过一次会存在浏览器里，下次直接拖到位置上。给客户发合同、给文件签个字，够用了。

手绘、输入、上传、手机扫码，四种方式都在一个面板里

还有一个场景值得单独说，OCR。

扫描件变成可搜索、可复制的 PDF，就靠它。标准镜像自带英语、德语、法语、葡萄牙语和简体中文，中文不用额外装。

要加别的语言，把对应的 .traineddata 文件放进 tessdata 目录，重启容器就行。

06

真正好玩的是文件夹监听

前面那些功能，在线工具多少都能替代。文件夹监听不行。

在 /pipeline/watchedFolders 下面建一个任务文件夹，放一个工作流 JSON，再把文件丢进去。

它每分钟扫一次，自动跑完整个流程，不需要人登录。

工作流不用手写，在界面里的自动化工具搭好，导出成 .folder-scan.json 就行。

比较典型的配法是扫描件处理，OCR 识别，压缩，落到成品目录。扫描仪扫完，剩下的事就不用管了。

有一个坑要提前说，处理成功后原文件会被删掉。重要文件先留一份副本。

一次配置，之后只需要往文件夹里丢文件。

再往上一层是 API 和 MCP。

REST API 几乎覆盖所有工具，脚本可以批量处理。MCP 则让 AI 助手直接调用这些能力。

这部分普通家庭用户可能用不上。但要把它接进自己的工作流，它的上限比在线工具高很多。

07

几个坑，和它的边界

镜像不小。下载 1.2GB 左右，装完占 3GB 上下，别塞在快满的盘里。

内存要够。官方建议 4GB，OCR 和 Office 转换同时跑的时候更吃内存。

免费版 5 个用户。所有 PDF 工具、API、OIDC 单点登录都在免费范围，团队要用的外接数据库、S3 存储、审计日志才收费。个人和家庭完全够。

要外网访问，别直接把端口映射出去。套一层反向代理，上 HTTPS，顺手把上传上限调到 2000MB。这是它的默认值，而 nginx 默认只有 1MB，大文件会直接失败。

升级先备份。更新就是 docker compose pull 再 up -d，数据都在挂载目录里。但大版本升级前，还是把 configs 目录复制一份，设置、密钥、内置数据库都在里面。

它不是万能。复杂排版转换会错位，扫描件 OCR 的质量取决于原件，重要文件该留原件还是留。

如果你只是偶尔用一次，在线工具更省事。如果你家里经常有人处理合同、发票、简历、扫描件，这套东西值得装。

装完这段时间，我最大的感受不是它工具多。是这些事终于不用再经过别人的服务器。

以前处理 PDF，是在不同网站之间跳。现在是把文件拖进自己家的一个网页，处理完，文件还在原来的盘里。

NAS 本来只是存东西。多跑一个容器，它开始干活了。

项目地址：github.com/Stirling-Tools/Stirling-PDF