🚀 使用 Docker Compose 部署 Stirling PDF

🚀 使用 Docker Compose 部署 Stirling-PDF

本教程将指导您使用 Docker Compose 部署 Stirling-PDF，这是一个功能强大的、本地托管的基于 Web 的 PDF 操作工具，支持超过 50 种 PDF 操作。

📝 项目简介

Stirling-PDF 是一个开源、可本地部署的网页端 PDF 编辑与处理平台。它使您能够对 PDF 文件执行各种操作，包括拆分、合并、转换、重新组织、添加图像、旋转、压缩等。

核心特点：

丰富的 PDF 操作：支持合并、拆分、旋转、裁剪、压缩、OCR、格式转换等超过 50 种 PDF 操作
隐私安全：所有文件仅在任务执行期间驻留在服务器内存中或临时文件中，完成后自动从服务器删除
跨平台支持：基于 Docker，Windows、Mac、Linux 都能使用
多语言界面：支持 38 种国家和地区的语言，包括中文
并行处理：支持批量任务与自定义流水线，提高处理效率

🔧 部署前准备

系统环境要求

操作系统：支持 Linux、Windows（WSL）、macOS
Docker 版本：Docker 24.0+
Docker Compose：版本 2.0+
硬件资源：
内存：至少 2GB，推荐 4GB 以上
存储空间：至少 2GB 可用空间

环境检查

检查 Docker 服务状态 bash systemctl status docker 确保 Docker 服务处于 active (running) 状态
检查 Docker 版本 bash docker -v 确保版本为 24.0 或更高
检查 Docker Compose 版本 bash docker compose version 确保版本为 v2.0 或更高

⚙️ 配置 Docker Compose

创建部署目录

mkdir -p /data/stirling-pdf && cd /data/stirling-pdf

准备 Dockerfile

创建 Dockerfile 文件，内容如下：

FROM frooodle/s-pdf:latest  # 基于官方最新镜像构建

# 永久禁用字体安装（避免启动时因网络问题卡住，非必需但推荐）
RUN sed -i 's/install_fonts "$INSTALL_FONTS"/# install_fonts "$INSTALL_FONTS"/g' /scripts/init.sh

# 替换为阿里云 Alpine 镜像源（加速依赖下载，解决国内网络问题）
RUN echo "http://mirrors.aliyun.com/alpine/v3.22/main" > /etc/apk/repositories && \
    echo "http://mirrors.aliyun.com/alpine/v3.22/community" >> /etc/apk/repositories

# 确保 OCR 语言包目录存在（避免复制文件失败）
RUN mkdir -p /usr/share/tessdata

# 添加简体中文语言包（使用国内镜像源）
#RUN wget -O /usr/share/tessdata/chi_sim.traineddata https://gitee.com/mirrors/tessdata/raw/main/chi_sim.traineddata
# 从 Gitee 镜像下载 Tesseract 中文 OCR 语言包（国内加速，避免 GitHub 访问慢）
RUN curl -L -o /usr/share/tessdata/chi_sim.traineddata https://gitee.com/mirrors/tessdata/raw/main/chi_sim.traineddata

#如果下载步骤仍然失败，可以使用本地下载后添加到镜像的方法：
#手动下载语言包：
#wget https://gitee.com/mirrors/tessdata/raw/main/chi_sim.traineddata
#修改 Dockerfile：
# （可选）若上述下载失败，改用本地文件复制（需先手动下载 chi_sim.traineddata 到部署目录）
#COPY chi_sim.traineddata /usr/share/tessdata/chi_sim.traineddata
#RUN chmod 644 /usr/share/tessdata/chi_sim.traineddata
#构建镜像：
#docker build --no-cache -t stirling-pdf-custom .

# 赋予语言包正确权限（确保 OCR 服务可读取）
RUN chmod 644 /usr/share/tessdata/chi_sim.traineddata

准备 docker-compose.yml

创建 docker-compose.yml 文件，内容如下：

#version: '3.3'
services:
  stirling-pdf:
    #image: frooodle/s-pdf:latest
    image: stirling-pdf-custom    # 使用刚构建的自定义镜像（必须与构建时的镜像名一致）
    container_name: stirling-pdf  # 容器名称，便于管理（如停止/查看日志）
    restart: always  # 容器退出后自动重启（保障服务稳定，适合长期运行）
    ports:
      - '8085:8080'  # 端口映射：主机 8085 → 容器 8080（Web 界面访问端口，左侧可自定义）
    volumes:
      # OCR 语言包挂载：本地 trainingData → 容器 /usr/share/tessdata（补充或替换语言包）
      - ./trainingData:/usr/share/tessdata       # OCR 语言包目录
      # 自定义配置挂载：本地 extraConfigs → 容器 /configs（修改应用配置）
      - ./extraConfigs:/configs                  # 自定义配置文件
      # 用户文件挂载：本地 customFiles → 容器 /customFiles（上传的 PDF 临时存储）
      - ./customFiles:/customFiles/               # 用户上传文件临时存储
      # 日志挂载：本地 logs → 容器 /logs（应用运行日志，便于排错）
      - ./logs:/logs/                             # 日志持久化
      #- ./configs:/configs
    environment:
      - DOCKER_ENABLE_SECURITY=false  # 关闭安全限制（内网使用推荐，外网需设为 true 并配置密码）
      - SYSTEM_ENABLEANALYTICS=false   # 禁用分析服务（避免离线时启动异常）
      - LANGS=zh_CN  # 关键！设置界面语言为中文（无需手动切换）
      - POSTHOG_ENABLED=false  # 禁用数据统计（隐私保护）
      - TESSERACT_PATH=/usr/share/tessdata  # OCR 语言包路径（与挂载目录一致）
      - JAVA_TOOL_OPTIONS="-Xmx1g -Xms512m"  # Java 内存限制（1G 最大内存，512M 初始内存）
      - INSTALL_FONTS=false  # 禁用字体安装（与 Dockerfile 配置一致，避免重复操作）
      - ALPINE_REPOSITORIES="http://mirrors.aliyun.com/alpine/v3.22/main"  # 国内镜像源（加速后续依赖安装）

#VPS小鸡版的配置yml
#version: '3.3'
services:
  stirling-pdf:
    image: frooodle/s-pdf:latest
    container_name: stirling-pdf
    restart: unless-stopped
    ports:
      - '8080:8080'
    volumes:
      - ./trainingData:/usr/share/tessdata
      - ./customFiles:/customFiles/
      - ./logs:/logs/
    environment:
      - DOCKER_ENABLE_SECURITY=false
      - SYSTEM_ENABLEANALYTICS=false
      - POSTHOG_ENABLED=false
      - LANGS=zh_CN
      - TESSERACT_PATH=/usr/share/tessdata
      - INSTALL_FONTS=false  # 关键修复项
      - JAVA_TOOL_OPTIONS="-Xmx1g -Xms512m"

关键配置说明

网络配置：使用默认的 bridge 网络，端口映射到宿主机的 8085 端口
数据持久化：
./trainingData:/usr/share/tessdata：OCR 语言包目录
./extraConfigs:/configs：自定义配置文件
./customFiles:/customFiles/：用户上传文件临时存储
./logs:/logs/：日志持久化
环境变量：
DOCKER_ENABLE_SECURITY=false：关闭安全限制（内网环境使用）
LANGS=zh_CN：设置中文界面
JAVA_TOOL_OPTIONS="-Xmx1g -Xms512m"：配置 JVM 内存参数

🚀 启动与验证

构建自定义镜像并启动服务

# 构建自定义镜像
docker build -t stirling-pdf-custom .

# 启动服务
docker compose up -d

#方法2

# 构建镜像（--no-cache 表示不使用缓存，确保语言包最新）
docker build --no-cache -t stirling-pdf-custom .

# 验证镜像是否构建成功（出现 stirling-pdf-custom 即正常）
docker images | grep stirling-pdf-custom

验证服务状态

检查容器运行状态

   docker ps

应该看到 stirling-pdf 服务处于 Up 状态

查看服务日志

   docker compose logs -f

访问 Web 界面 在浏览器中访问 http://你的服务器IP:8085

初始设置

首次访问会显示英文界面，点击右下角语言切换按钮选择"简体中文"即可切换到中文界面。

🔌 基础配置与使用

OCR 功能配置

Stirling-PDF 使用 OCRmyPDF 进行文字识别，而 OCRmyPDF 又使用 tesseract 进行文本识别。要启用中文 OCR 功能：

验证中文语言包

docker exec stirling-pdf ls /usr/share/tessdata/

应该看到 chi_sim.traineddata 文件

使用 OCR 功能
在 WebUI 中选择"OCR PDF"功能
上传需要识别的 PDF 文件
选择中文识别语言
开始处理

基本使用流程

Stirling-PDF 提供了丰富的 PDF 操作功能：

功能分类	主要功能
页面操作	合并、拆分、旋转、删除、重新排序页面
转换操作	PDF 与图像互转、Office 文档转换
安全权限	添加/移除密码、设置权限、添加水印
其他操作	OCR 识别、压缩、比较、修复 PDF

常用操作示例：

合并 PDF 文件
选择"合并 PDF"功能
上传多个 PDF 文件
调整文件顺序
点击合并并下载
PDF 转 Word
选择"PDF 转 Word"功能
上传 PDF 文件
选择输出格式
开始转换

🛠️ 维护与管理

日常维护操作

服务启动/停止

   # 停止服务
   docker compose down

   # 启动服务
   docker compose up -d

数据备份

   # 备份配置和数据
   tar -czf stirling-pdf-backup-$(date +%Y%m%d).tar.gz ./trainingData ./extraConfigs

服务更新

   # 进入部署目录
   cd /data/stirling-pdf

   # 拉取最新基础镜像并重新构建
   docker pull frooodle/s-pdf:latest
   docker build -t stirling-pdf-custom .

   # 重启服务
   docker compose down
   docker compose up -d

监控与日志

查看实时日志

   docker compose logs -f

监控资源使用

   docker stats stirling-pdf

检查存储空间

   df -h  # 检查磁盘空间
   du -sh ./trainingData  # 查看 OCR 数据大小

🐛 常见问题排查

1. 容器启动失败

问题现象：docker ps 显示容器状态不是 Up

解决方案： - 检查日志：docker compose logs - 验证端口占用：netstat -tulpn | grep 8085 - 检查镜像构建：确保自定义镜像构建成功

2. 无法访问 Web 界面

问题现象：浏览器访问 http://IP:8085 无响应

解决方案： - 检查防火墙设置：

# 开放 8085 端口
ufw allow 8085

验证服务绑定：确保服务绑定到 0.0.0.0 而不是 127.0.0.1

3. OCR 功能无法使用

问题现象：OCR 处理失败或无法识别中文

解决方案： - 检查语言包权限：

docker exec stirling-pdf ls -la /usr/share/tessdata/

验证语言包完整性：重新下载中文语言包
检查 Tesseract 路径：确保环境变量 TESSERACT_PATH 设置正确

4. 文件处理失败

问题现象：上传文件后处理失败

解决方案： - 检查文件格式：确保上传的是有效的 PDF 文件 - 查看处理日志：docker compose logs 查看详细错误信息 - 验证存储权限：确保挂载目录有读写权限

5. 性能问题

问题现象：处理大文件时内存不足或响应慢

解决方案： - 增加 JVM 内存：调整 JAVA_TOOL_OPTIONS 环境变量 - 优化处理参数：对于大文件使用分批处理 - 增加系统资源：适当增加容器内存限制

通过本教程，您应该已经成功部署并配置了 Stirling-PDF，现在可以享受这款功能强大的本地 PDF 处理工具了。如果在使用过程中遇到其他问题，可以参考项目官方文档或社区支持资源。