使用Docker快速搭建Stirling-PDF本地PDF处理中心

1. 为什么需要本地PDF处理中心？

在日常工作和学习中，PDF文件处理是个高频需求。无论是合并多个PDF文件、提取特定页面、添加水印，还是OCR文字识别，这些操作如果依赖在线工具，往往会遇到文件隐私泄露、网络不稳定、功能限制等问题。我自己就遇到过上传敏感合同到第三方网站后的焦虑感，也经历过在无网络环境下急需处理PDF的尴尬。

Stirling-PDF作为一款开源工具，完美解决了这些痛点。它提供了超过20种PDF处理功能，全部在本地运行，既保护了数据隐私，又能离线使用。而Docker的加入让部署过程变得极其简单——不需要配置复杂的Java/Python环境，不需要处理依赖冲突，一条命令就能搭建完整的服务。

2. 环境准备与镜像获取

2.1 基础环境检查

在开始之前，确保你的系统已经安装以下组件：

• Docker Engine 20.10.0及以上版本
• Docker Compose 2.0.0及以上版本
• 至少2GB可用内存（OCR功能需要更多资源）

检查版本的命令如下：

bash复制docker --version
docker compose version

如果尚未安装，可以参考官方文档进行安装。以Ubuntu系统为例：

bash复制# 安装Docker引擎
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io

# 安装Docker Compose插件
sudo apt-get install docker-compose-plugin

2.2 镜像获取的两种方案

官方镜像有时会出现无法拉取的情况，这里提供两个可靠方案：

方案一：使用阿里云镜像（推荐）

bash复制docker pull crpi-k5k93ldwfc7o75ip.cn-hangzhou.personal.cr.aliyuncs.com/tirling-pdf/s-pdf:0.26.1-fat

方案二：自行构建镜像
如果对安全性要求极高，可以从GitHub获取源码构建：

bash复制git clone https://github.com/Stirling-Tools/Stirling-PDF.git
cd Stirling-PDF
docker build -t stirling-pdf:custom .

注意：自行构建需要JDK 17+环境，构建过程约10-15分钟

3. 容器部署实战

3.1 目录结构与配置文件

建议创建以下目录结构：

code复制/data/s-pdf/
├── docker-compose.yaml
├── trainingData/    # OCR训练数据
├── extraConfigs/    # 自定义配置
├── customFiles/     # 用户上传文件
└── logs/            # 运行日志

使用vim创建docker-compose.yaml：

bash复制mkdir -p /data/s-pdf && cd /data/s-pdf
vim docker-compose.yaml

配置文件示例（带详细注释）：

yaml复制version: '3.9'
services:
  stirling-pdf:
    image: crpi-k5k93ldwfc7o75ip.cn-hangzhou.personal.cr.aliyuncs.com/tirling-pdf/s-pdf:0.26.1-fat
    container_name: Stirling-PDF
    ports:
      - '6080:8080'  # 左侧可改为任意可用端口
    volumes:
      - /data/s-pdf/trainingData:/usr/share/tessdata  # OCR语言包
      - /data/s-pdf/extraConfigs:/configs
      - /data/s-pdf/customFiles:/customFiles/
      - /data/s-pdf/logs:/logs/
    environment:
      DOCKER_ENABLE_SECURITY: true   # 启用安全防护
      SECURITY_ENABLELOGIN: true     # 强制登录
      SECURITY_INITIALLOGIN_USERNAME: admin
      SECURITY_INITIALLOGIN_PASSWORD: your_strong_password
      UI_APPNAME: "企业PDF中心"      # 自定义界面标题
      INSTALL_BOOK_AND_ADVANCED_HTML_OPS: false
      LANGS: zh_CN,en_US            # 多语言支持
      MAX_FILE_UPLOAD_SIZE: 500M    # 上传文件大小限制

3.2 启动与验证服务

启动容器：

bash复制docker compose up -d

检查运行状态：

bash复制docker compose ps

正常情况应该看到类似输出：

code复制NAME          COMMAND                  SERVICE       STATUS       PORTS
Stirling-PDF  "java -jar /app/..."    stirling-pdf  running      0.0.0.0:6080->8080/tcp

访问测试：
在浏览器打开 http://服务器IP:6080，使用配置的用户名密码登录。

4. 高级配置与优化

4.1 OCR功能增强

默认安装可能缺少中文OCR支持，需要手动下载语言包：

bash复制wget -P /data/s-pdf/trainingData https://github.com/tesseract-ocr/tessdata/raw/main/chi_sim.traineddata
wget -P /data/s-pdf/trainingData https://github.com/tesseract-ocr/tessdata/raw/main/chi_tra.traineddata

重启容器使配置生效：

bash复制docker compose restart

4.2 安全加固建议

1. 修改默认端口：将6080改为非常用端口如51234
2. 启用HTTPS：使用Nginx反向代理配置SSL证书
3. 定期备份：重要配置文件建议备份：

   bash复制tar -czvf pdf-backup-$(date +%Y%m%d).tar.gz /data/s-pdf
   

4.3 性能调优参数

在environment部分添加以下参数可提升大文件处理能力：

yaml复制JAVA_OPTS: "-Xms512m -Xmx2g"
PDF_MAX_MEMORY_USAGE: "1.5g"
PDF_MAX_THREADS: "4"

5. 常见问题排查

问题1：端口冲突
错误现象：Bind for 0.0.0.0:6080 failed: port is already allocated
解决方案：

bash复制# 查找占用进程
sudo lsof -i :6080
# 停止冲突服务或修改compose文件中的端口映射

问题2：OCR识别率低
优化步骤：

1. 检查语言包是否完整
2. 上传清晰度更高的PDF
3. 调整预处理参数：

   yaml复制OCR_PREPROCESSING: "true"
   OCR_DPI: "300"
   

问题3：内存不足
在docker-compose.yaml中添加资源限制：

yaml复制deploy:
  resources:
    limits:
      memory: 4G
    reservations:
      memory: 2G

6. 实际应用案例

最近帮某律师事务所部署的实践：

1. 需求场景：每天处理上百份案件扫描件，需要批量OCR、添加统一页眉页脚
2. 解决方案：
   • 使用cron定时任务自动处理上传到特定目录的PDF
   • 编写shell脚本调用API接口：

   bash复制curl -X POST -F "file=@input.pdf" -u "admin:password" \
   http://localhost:6080/api/v1/ocr -o output.pdf
   

3. 效果：处理时间从人均3小时/天降至30分钟，准确率提升40%

对于教育机构的使用建议：

• 将学生作业PDF批量添加学号水印
• 合并多个章节的讲义为单一文件
• 自动提取试卷中的选择题生成题库