### [雨云搭建 Stirling-PDF 私有PDF工具箱](https://www.jiyueip.com/article/12288)

**Published:** 2026-07-28T10:09:50

**Author:** 斑斓助理

**Excerpt:** 用雨云 KVM 云服务器 Docker 自建 Stirling-PDF 私有 PDF 工具箱：合并拆分压缩、中文 OCR、登录保护与 HTTPS 反代全流程，含 413 上传限制坑与优惠码 admin01 五折。

把 PDF 拆分、合并、压缩、加水印、OCR 识别这些活儿交给在线网站，最大的问题不是收费，而是你把合同、简历、发票这类敏感文件上传到了别人的服务器。Stirling-PDF 是一个开源的自托管 PDF 工具箱，一个 Docker 容器就能跑起 50 多种 PDF 处理功能，文件全程只在你自己的服务器上流转。本文用雨云 KVM 云服务器从零把它部署好，并配好 HTTPS 和访问密码。

## 为什么值得自建一个 PDF 工具箱

在线 PDF 工具的套路大同小异：免费版限制文件大小和次数，处理完的文件在对方服务器上停留多久、有没有被留存，普通用户无法核实。对经常处理合同、标书、证件扫描件的人来说，这是实打实的数据外泄风险。

Stirling-PDF 的优势在于功能密度：合并、拆分、旋转、压缩、格式转换（PDF 转图片/Word/文本）、加解密、加水印、页码、签名、OCR 文字识别，全部在同一个 Web 界面里完成，处理过程不出服务器。它基于 Java + LibreOffice + Tesseract 实现，官方 Docker 镜像把依赖都打包好了，部署门槛很低。

## 服务器准备

Stirling-PDF 带 OCR 和格式转换组件，比一般轻量工具吃内存，建议至少 2G 内存起步；如果只用合并拆分等基础功能，1 核 1G 也能跑 lite 版镜像。

我这次用的是雨云的 KVM 云服务器（详情见 [雨云官网入口](https://www.jiyueip.com/link/5617)），选宁波或深圳节点国内访问快，系统装 Debian 12。下单时优惠码填 **admin01** 可以打五折，雨云支持 7 天无理由退款，跑不满意可以退。如果还没想好怎么挑配置，可以先看这篇 [雨云 VPS 选购与上手指南](https://www.jiyueip.com/article/12235)。

装好系统后先把 Docker 备齐：

```bash
curl -fsSL https://get.docker.com | bash
systemctl enable --now docker
```

## Docker 部署 Stirling-PDF

新建目录和 compose 文件：

```bash
mkdir -p /opt/stirling && cd /opt/stirling
```

`docker-compose.yml` 内容：

```yaml
services:
  stirling-pdf:
    image: stirlingtools/stirling-pdf:latest
    container_name: stirling-pdf
    restart: unless-stopped
    ports:
      - "127.0.0.1:8080:8080"
    volumes:
      - ./trainingData:/usr/share/tessdata
      - ./configs:/configs
    environment:
      - DOCKER_ENABLE_SECURITY=true
      - SECURITY_ENABLELOGIN=true
      - LANGS=zh_CN
```

两点说明：

-   `DOCKER_ENABLE_SECURITY` 和 `SECURITY_ENABLELOGIN` 同时开启后，Stirling-PDF 会启用登录页，避免工具箱裸奔在公网上被人白嫖算力。
-   端口绑在 `127.0.0.1`，只允许通过后面的 Nginx 反代访问。

启动：

```bash
docker compose up -d
```

首次启动会初始化默认账号 `admin` / `stirling`，登录后第一件事就是在右上角账户设置里改掉默认密码。

## 中文 OCR 语言包

默认镜像只带英文 OCR。要识别中文扫描件，下载 Tesseract 中文训练数据放进挂载目录：

```bash
cd /opt/stirling/trainingData
wget https://github.com/tesseract-ocr/tessdata/raw/main/chi_sim.traineddata
docker restart stirling-pdf
```

重启后在 OCR 功能页的语言下拉框里就能选到「chi\_sim」，对清晰的打印体扫描件识别率相当不错。

## Nginx 反代与 HTTPS

PDF 上传走明文 HTTP 等于把文件内容直接暴露在链路上，HTTPS 必须配。安装 Nginx 和 certbot 后写反代配置：

```nginx
server {
    listen 443 ssl;
    server_name pdf.example.com;
    ssl_certificate /etc/letsencrypt/live/pdf.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/pdf.example.com/privkey.pem;
    client_max_body_size 200m;
    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}
```

注意 `client_max_body_size` 一定要调大，Nginx 默认 1M 的上传限制会让稍大一点的 PDF 直接报 413 错误，这是部署 Stirling-PDF 最常见的坑。

## 踩坑记录

-   **OCR 或转换任务卡住不动**：多半是内存不够被 OOM 杀了进程，`docker stats` 观察一下峰值，2G 内存以下建议避开大文件 OCR，或换 `stirling-pdf:latest-ultra-lite` 镜像只用基础功能。
-   **中文文件名乱码**：老版本镜像存在此问题，把镜像更新到近期版本即可解决。
-   **处理大 PDF 很慢**：OCR 是 CPU 密集型任务，雨云上多加一个核心比加内存对速度提升更明显。

日常我把 Stirling-PDF 和之前部署的 [AList 网盘挂载](https://www.jiyueip.com/article/12253) 配合使用：扫描件先归档到 AList 管理的存储里，需要处理时下载下来丢进 Stirling-PDF，处理完再传回去，全链路不经过任何第三方在线工具。服务多了以后，入口可以统一收进 [Heimdall 导航页](https://www.jiyueip.com/article/12265)。

## 合规提醒

自建 PDF 工具仅限处理自有或已获授权的文件。依据《网络安全法》《个人信息保护法》《数据安全法》，处理包含他人个人信息的文档时应取得合法授权，不得利用 OCR 等功能非法收集、加工、出售个人信息。服务器登录、HTTPS 与访问控制请务必配置到位，避免敏感文件因配置疏漏泄露。

## 小结

Stirling-PDF 用一个容器解决了 PDF 处理的隐私焦虑，功能覆盖面比大多数付费在线工具还全。雨云 KVM 2 核 2G 档位足够家用，优惠码 admin01 五折入手，配好登录、HTTPS 和中文 OCR 后，就是一台完全属于自己的 PDF 工作站。

**Tags:** 云服务器, 建站教程, 雨云, 雨云优惠码

**Categories:** 行业洞察

---