📋 项目简介

Stirling PDF 是一个功能强大的开源 PDF 编辑平台，被誉为首屈一指的 PDF 应用。你可以在浏览器、桌面客户端或自己的服务器上运行它，提供私有 API，无需将文档发送到外部服务即可完成编辑、签名、涂黑、转换和自动化处理。

核心能力：

能力 说明
多平台 桌面客户端、浏览器 UI、自托管服务器及私有 API
50+ PDF 工具 编辑、合并、拆分、签名、涂黑、转换、OCR、压缩等
自动化与工作流 UI 内无代码管线，API 可处理海量 PDF
企业级 SSO、审计、灵活本地部署
开发者平台 几乎所有工具均提供 REST API，可集成到现有系统
全球化 UI 支持 40+ 种语言界面

一、部署方式概览

Stirling PDF 提供多种部署方式，本教程主要讲解最常用的 Docker 部署：

  1. Docker 快速启动（单条命令，最快上手）
  2. Docker Compose 部署（推荐，便于管理）
  3. NAS 部署（绿联、飞牛等）
  4. VPS 生产部署（含反代和 HTTPS）
  5. Unix 手动安装（无 Docker 环境）

二、前置准备

2.1 系统要求

项目 最低建议 说明
操作系统 Linux（Ubuntu 24.04 等） 也支持 macOS、Windows WSL
内存 ≥ 2 GB 实测 3845 MB 时 JVM 自动分配约 15%～70%
CPU 双核即可
磁盘 ≥ 5 GB 可用 镜像 + configs 数据
端口 8080 容器内固定监听 8080，可映射到其他宿主机端口

⚠️ 重要提示：Stirling PDF 是 Java 应用（基于 Spring Boot），不像静态站点那样轻量。Docker 镜像超过 1 GB，Java 后端常驻内存，空闲时也占用可观内存。OCR 和格式转换任务会大量消耗 CPU 和内存。

2.2 安装 Docker

如果尚未安装 Docker，可执行：

1
2
3
4
5
# Ubuntu/Debian
sudo apt-get update
sudo apt-get install -y docker.io docker-compose
sudo systemctl start docker
sudo systemctl enable docker

验证安装：

1
2
docker --version
docker compose version

三、方式一：Docker 快速启动

3.1 最简命令

1
2
3
4
5
docker run -d \
  --name stirling-pdf \
  -p 8080:8080 \
  -v ./stirling-data:/configs \
  docker.stirlingpdf.com/stirlingtools/stirling-pdf:latest

然后浏览器访问：http://localhost:8080

3.2 完整功能版本（含 OCR、日志、自动化）

1
2
3
4
5
6
7
8
9
10
docker run -d \
  --name stirling-pdf \
  -p 8080:8080 \
  -v ./stirling-data/tessdata:/usr/share/tessdata \
  -v ./stirling-data/configs:/configs \
  -v ./stirling-data/logs:/logs \
  -v ./stirling-data/pipeline:/pipeline \
  -e SECURITY_ENABLELOGIN=false \
  -e SYSTEM_DEFAULTLOCALE=zh-CN \
  docker.stirlingpdf.com/stirlingtools/stirling-pdf:latest

各卷（volume）用途：

卷路径 用途
/configs 设置与数据库
/usr/share/tessdata OCR 语言文件
/logs 应用日志
/pipeline 自动化配置

3.3 ⚠️ 登录默认开启

默认情况下 security.enableLogin: true，新容器启动时会创建默认管理员账户：

  • 用户名：admin
  • 密码：stirling

首次登录后请立即修改密码！ 如需无登录体验（无认证、无管理员账户），需显式设置 SECURITY_ENABLELOGIN=false 来选择退出。

四、方式二：Docker Compose 部署（推荐）

4.1 创建项目目录

1
2
mkdir -p ~/stirling-pdf
cd ~/stirling-pdf

4.2 创建 docker-compose.yml

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
services:
  stirling-pdf:
    image: docker.stirlingpdf.com/stirlingtools/stirling-pdf:latest
    container_name: stirling-pdf
    ports:
      - '8080:8080'
    volumes:
      - ./stirling-data/tessdata:/usr/share/tessdata    # OCR 语言文件
      - ./stirling-data/configs:/configs                 # 设置与数据库
      - ./stirling-data/logs:/logs                       # 应用日志
      - ./stirling-data/pipeline:/pipeline               # 自动化配置
    environment:
      - SECURITY_ENABLELOGIN=false       # 关闭登录（默认是 true / 开启）
      - SYSTEM_DEFAULTLOCALE=zh-CN       # 默认界面语言
    restart: unless-stopped

4.3 启动服务

1
docker compose up -d

4.4 查看启动日志

首次启动约 30 秒～2 分钟，期间请不要用 Ctrl+C 打断：

1
docker compose logs -f stirling-pdf

当看到 Started StirlingPDFApplication 类似的日志时，说明启动成功。

4.5 访问

浏览器打开 http://localhost:8080 或 http://你的服务器IP:8080

五、镜像版本选择

Stirling PDF 提供三种版本，按需选择：

版本 标签 包含内容 适用场景
标准版 latest 所有 PDF 功能 大多数用户，功能与体积平衡
Fat 版 latest-fat 全部功能 + 额外字体与工具 最高质量转换，完整格式支持
Ultra-Lite 版 latest-ultra-lite 仅核心功能 资源受限（树莓派、低端 VPS），启动最快

💡 选型建议：

  • 不确定选哪个 → 用 latest
  • 需要最高质量转换和完整字体支持，磁盘空间充足 → 用 latest-fat
  • 硬件资源非常有限，只需要基础 PDF 操作 → 用 latest-ultra-lite

切换版本只需更改标签：

1
docker run -d docker.stirlingpdf.com/stirlingtools/stirling-pdf:latest-ultra-lite

⚠️ 注意：使用 ultra-lite 时，侧栏可能出现灰色不可用的工具（如 Word/Excel 转 PDF），属预期行为，可换 latest 或 fat 镜像。

六、NAS 部署

6.1 绿联 NAS 部署

在绿联 NAS 的 UGOS Pro 系统中，打开 Docker 应用，点击 【项目】→【创建】，使用以下 Compose 配置：

1
2
3
4
5
6
7
8
9
10
11
12
services:
  stirling-pdf:
    image: frooodle/s-pdf:latest
    ports:
      - '8080:8080'
    volumes:
      - ./trainingData:/usr/share/tesseract-ocr/5/tessdata
      - ./extraConfigs:/configs
      - ./customFiles:/customFiles/
      - ./logs:/logs/
    environment:
      - DOCKER_ENABLE_SECURITY=false

确认配置无误后，点击 【立即部署】，完成后通过 http://<NAS_IP>:8080 访问。

6.2 飞牛 NAS 部署

  1. 打开”文件管理”，在 docker 文件夹中创建 stirling-pdf 文件夹
  2. 在其中创建 configs 和 logs 两个子文件夹
  3. 打开”Docker” → “镜像仓库”，搜索 frooodle/s-pdf 并下载
  4. 切换到”本地镜像”，创建容器：
    • 选择”开机自动开启”
    • 端口：修改左侧端口（如 3456），右侧 8080 不能改
    • 存储位置：将刚创建的文件夹分别挂载到 /configs 和 /logs，权限给”读写”
  5. 构建完成后，浏览器访问 http://<NAS_IP>:3456

首次登录：账号 admin，密码 stirling。登录后会要求立即改密码。

七、VPS 生产部署

7.1 资源规划

对于 VPS 部署，需要根据使用场景规划资源：

使用场景 建议配置
单用户或小团队 12 GB RAM
OCR 或批量转换频繁 24 GB RAM

7.2 完整生产配置

1
2
3
4
5
6
7
8
9
10
11
12
services:
  stirling-pdf:
    image: stirlingtools/stirling-pdf:latest
    container_name: stirling-pdf
    ports:
      - "8080:8080"
    volumes:
      - ./stirling/trainingData:/usr/share/tessdata
      - ./stirling/extraConfigs:/configs
      - ./stirling/customFiles:/customFiles
      - ./stirling/logs:/logs
    restart: unless-stopped

启动：

1
docker compose up -d

首次启动初始化时间明显长于后续重启（JVM 和 OCR 数据需要预热）。

7.3 反代与 HTTPS（重要）

在将服务暴露给非私有网络之前，务必配置反向代理和 TLS。 Stirling PDF 负责 PDF 处理，不负责传输安全。

配置 HTTPS 后，需在 Settings → General 中更新：

  • Root URI Path：/（或使用子目录时的 /pdf）
  • Frontend URL：你的完整 HTTPS 地址
  • CORS Allowed Origins：允许的来源

八、配置说明

Stirling PDF 支持三种配置方式：

8.1 方式一：应用内设置（推荐）

适用于启用了登录的生产部署：

  1. 设置 SECURITY_ENABLELOGIN=true
  2. 以管理员身份登录
  3. 进入 Settings → 通过 UI 配置
  4. 更改立即生效，无需重启

8.2 方式二：环境变量

适用于 Docker 部署、基础设施即代码、初始设置：

1
2
3
4
5
docker run -d \
  -e SECURITY_ENABLELOGIN=true \
  -e LANGS=en_GB \
  -e SYSTEM_DEFAULTLOCALE=zh-CN \
  stirlingtools/stirling-pdf:latest

8.3 方式三：settings.yml 文件

适用于复杂配置或偏好文件方式：

直接编辑 /configs/settings.yml：

1
2
3
4
security:
  enableLogin: true
system:
  defaultLocale: zh-CN

8.4 常用配置项

认证配置：

1
2
SECURITY_INITIALLOGIN_USERNAME=admin
SECURITY_INITIALLOGIN_PASSWORD=YourSecurePassword123!

⚠️ 注意：这些环境变量仅在首次启动时生效。数据库创建后再修改，旧凭据仍然有效。首次登录后务必通过 UI 修改密码。

语言与本地化：

1
2
LANGS=en_GB                    # 可用语言
SYSTEM_DEFAULTLOCALE=zh-CN     # 默认语言

语言选择优先级（从高到低）：

  1. 用户手动选择（存储在浏览器 localStorage）
  2. 浏览器语言偏好（Accept-Language 头）
  3. 系统默认 locale

文件上传限制：

1
2
3
SYSTEM_MAXFILESIZE=2000        # MB
SPRING_SERVLET_MULTIPART_MAX_FILE_SIZE=2000MB
SPRING_SERVLET_MULTIPART_MAX_REQUEST_SIZE=2000MB

内存管理：

1
JAVA_TOOL_OPTIONS="-Xms512m -Xmx4g"  # 最小 512MB，最大 4GB

九、初始登录与管理员设置

9.1 首次登录

访问你的实例，使用默认凭据登录：

  • 用户名：admin
  • 密码：stirling

9.2 立即修改密码

登录后进入 Settings → Account，修改为强密码（12+ 字符，大小写混合，含数字和符号）。

9.3 验证管理员权限

点击顶部导航栏的 Settings 齿轮图标，确认可以看到仅管理员可见的区块：

  • General Settings - 系统配置
  • Security Settings - 用户管理、登录设置
  • UI Customization - 品牌与外观
  • User Management - 创建/管理用户
  • Endpoint Configuration - 启用/禁用工具

💡 普通用户也能访问 Settings，但只能看到个人偏好（语言、主题）。

9.4 用户角色说明

角色 权限 适用场景
Admin 完全访问所有功能、设置、用户管理 系统管理员、IT 人员
User 仅访问已启用的 PDF 工具，无设置访问权限 普通员工、最终用户

十、OCR 中文模型配置

如果需要 OCR 扫描识别，需自行下载中文模型。将以下文件上传到 trainingData 文件夹：

文件 说明
eng.traineddata 英文
chi_sim.traineddata 简体中文
chi_tra.traineddata 繁体中文
chi_sim_vert.traineddata 简体中文竖排
chi_tra_vert.traineddata 繁体中文竖排

下载地址：https://github.com/tesseract-ocr/tessdata/tree/main

十一、更新 Stirling PDF

11.1 Docker 命令方式

1
2
3
4
docker stop stirling-pdf
docker rm stirling-pdf
docker pull docker.stirlingpdf.com/stirlingtools/stirling-pdf:latest
# 然后重新运行原始的 docker run 命令

11.2 Docker Compose 方式

1
2
3
docker-compose down
docker-compose pull
docker-compose up -d

✅ 你的数据（/configs 卷中）会保留，更新不会丢失配置。

十二、监控与使用追踪

12.1 查看日志

1
2
3
4
5
6
7
8
9
10
11
# Docker Compose
docker-compose logs -f stirling-pdf

# Docker Run
docker logs -f stirling-pdf

# 最后 100 行
docker logs --tail 100 stirling-pdf

# 过滤错误
docker logs stirling-pdf 2>&1 | grep ERROR

常见日志条目：

1
2
3
4
INFO: User john.doe uploaded file document.pdf
INFO: Operation MERGE completed successfully
WARN: Disk space low: 85% used
ERROR: OCR operation failed: Tesseract not found

12.2 API 监控

1
2
3
4
5
6
7
8
# 应用状态
curl http://localhost:8080/api/v1/info/status

# 请求计数
curl http://localhost:8080/api/v1/info/requests/all

# 唯一用户
curl http://localhost:8080/api/v1/info/requests/all/...

十三、常见问题排查

13.1 连接问题

无法连接？ 检查防火墙规则：

1
sudo ufw allow 8080

13.2 容器无法启动

1
2
# 查看日志
docker logs stirling-pdf

13.3 权限错误

1
sudo chmod -R 755 ~/stirling-data

13.4 启动时间过长

首次启动需 30 秒～2 分钟，不要中途打断。JVM 和 OCR 数据需要预热。

13.5 端口冲突

将 -p 8080:8080 改为其他端口，如 -p 8090:8080，浏览器访问 http://YOUR_SERVER_IP:8090。

13.6 工具显示灰色不可用

可能使用了 ultra-lite 镜像，不含 LibreOffice（无法 Word/Excel 转 PDF）且 OCR 能力受限。换用 latest 或 fat 镜像。

十四、部署检查清单

  • □

    Docker / Docker Compose 已安装并运行

  • □

    docker-compose.yml 或 docker run 命令配置正确

  • □

    数据卷已正确挂载（configs、logs、tessdata）

  • □

    容器成功启动，日志无报错

  • □

    浏览器可访问 http://<IP>:8080

  • □

    首次登录并修改了默认密码

  • □

    （如需）配置了反向代理和 HTTPS

  • □

    （如需）下载了 OCR 中文模型

  • □

    （如需）配置了语言、文件上传限制等

  • □

    更新流程已测试

🔗 相关链接

十五、开发者指南

本项目使用 Task 作为统一命令运行器处理所有构建、开发和测试命令：

1
2
task dev    # 启动开发环境
task        # 查看最常用命令

详细开发信息参见 DeveloperGuide.md。

添加翻译请参见 Translation Guide。

许可说明

Stirling PDF 采用 open-core 模式，核心平台基于 MIT 许可证，可永久免费自托管。可选的付费层级提供本地 AI 模型和 SSO 等功能，但运行工具包本身不需要这些付费功能。详见 LICENSE。