使用Docker快速搭建Stirling-PDF：从镜像拉取到容器部署全指南

1. 为什么选择Docker部署Stirling-PDF最近在处理PDF文档时我发现了一个宝藏工具——Stirling-PDF。这个开源项目提供了20种PDF处理功能从基础的合并拆分到OCR文字识别一应俱全。最让我惊喜的是它完全可以在本地运行不需要把文件上传到第三方服务器这对注重隐私的用户来说简直是福音。官方推荐用Docker部署但实际操作时我发现官方镜像经常拉取失败。经过多次尝试终于通过阿里云私人镜像仓库解决了这个问题。下面就把我的完整部署过程分享给大家包括镜像拉取、目录配置、环境变量设置等关键步骤保证新手也能轻松搞定。2. 解决镜像拉取问题2.1 官方镜像为何失效很多小伙伴第一次尝试时都会遇到docker pull frooodle/s-pdf失败的情况。这是因为官方镜像托管在Docker Hub国内访问经常不稳定。我测试发现下午时段成功率不到30%反复重试还会被临时封禁IP。2.2 使用国内镜像源推荐使用阿里云个人镜像仓库的备用镜像速度稳定在5MB/s左右。执行以下命令获取0.26.1版本当前最新稳定版docker pull crpi-k5k93ldwfc7o75ip.cn-hangzhou.personal.cr.aliyuncs.com/tirling-pdf/s-pdf:0.26.1-fat如果提示认证失败需要先登录阿里云容器镜像服务docker login --usernameyour_username crpi-k5k93ldwfc7o75ip.cn-hangzhou.personal.cr.aliyuncs.com3. 准备部署环境3.1 创建项目目录建议将所有相关文件集中管理避免配置散落各处。我习惯在/data目录下创建专用文件夹mkdir -p /data/s-pdf/{trainingData,extraConfigs,customFiles,logs} cd /data/s-pdf目录结构说明trainingData存放OCR训练数据支持中文需额外下载extraConfigs自定义配置文件customFiles用户上传的模板文件logs容器运行日志3.2 编写docker-compose配置用vim创建docker-compose.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 - /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 # 中英文双语界面 restart: unless-stopped # 自动重启保障服务可用性关键参数解析ports8080是容器内部端口6080可替换为服务器空闲端口volumesOCR识别中文需要额外下载训练文件后文详述environment建议修改默认密码并开启登录验证4. 启动与验证服务4.1 启动容器在docker-compose.yaml所在目录执行docker compose up -d首次启动约需1-2分钟可以通过日志观察进度docker logs -f Stirling-PDF看到Started Application in 45.234 seconds即表示启动成功。4.2 访问Web界面浏览器访问http://服务器IP:6080用配置的用户名密码登录。成功后会看到如下功能模块基础工具合并/拆分/旋转转换工具PDF与Office互转OCR识别需额外配置中文支持安全工具加密/解密/签名4.3 检查服务状态查看容器运行状态docker compose ps正常情况应显示NAME IMAGE COMMAND SERVICE STATUS PORTS Stirling-PDF s-pdf:0.26.1-fat /bin/sh -c java ... stirling-pdf running 0.0.0.0:6080-8080/tcp5. 高级配置技巧5.1 添加中文OCR支持默认安装不包含中文识别库需要手动下载训练数据wget -P /data/s-pdf/trainingData https://github.com/tesseract-ocr/tessdata/raw/main/chi_sim.traineddata重启容器生效docker compose restart5.2 性能优化建议处理大文件时可能出现内存不足可通过JVM参数调整environment: JAVA_TOOL_OPTIONS: -Xmx2g -Xms1g # 最大2G内存5.3 定期维护建议每周清理日志文件truncate -s 0 /data/s-pdf/logs/*.log6. 常见问题排查6.1 端口冲突处理如果启动时报错Bind for 0.0.0.0:6080 failed说明端口被占用。有两种解决方案修改docker-compose.yaml中的端口映射ports: - 6081:8080 # 改用新端口查找并终止占用进程sudo lsof -i :6080 kill -9 PID6.2 中文乱码问题如果生成PDF出现方框乱码需要安装中文字体docker exec -it Stirling-PDF apt update docker exec -it Stirling-PDF apt install -y fonts-wqy-zenhei6.3 忘记管理员密码如果遗失了登录密码可以通过重置环境变量来恢复修改docker-compose.yaml中的密码字段重新创建容器docker compose down docker compose up -d7. 安全加固措施7.1 启用HTTPS建议通过Nginx反向代理添加SSL证书server { listen 443 ssl; server_name pdf.yourdomain.com; ssl_certificate /path/to/cert.pem; ssl_certificate_key /path/to/key.pem; location / { proxy_pass http://localhost:6080; proxy_set_header Host $host; } }7.2 防火墙配置仅开放必要端口ufw allow 6080/tcp ufw enable7.3 定期备份重要配置文件建议每日备份tar -czvf /backups/s-pdf-$(date %F).tar.gz /data/s-pdf