Docker 部署 Stirling-PDF：本地 PDF 工具箱、持久化、登录安全与升级备份

如果只是偶尔合并、拆分或压缩 PDF，安装多个桌面软件很快会变得混乱；把文件上传到陌生在线网站，又要考虑隐私和留存问题。

本文根据 Stirling-PDF 官方 Docker 文档，用 Docker Compose 部署一个本地 PDF Web 工具箱，重点解决四件事：

• 如何启动一个可访问的实例；
• 哪些目录必须持久化；
• 默认登录和首次密码如何处理；
• 如何备份、升级，以及避免错误地暴露到公网。

一、部署完成后的效果

准备目录：

024-stirling-pdf/
├── compose.yaml
├── README.md
└── stirling-data/
    ├── configs/
    ├── customFiles/
    ├── logs/
    ├── pipeline/
    └── tessdata/

启动后访问：

http://localhost:8080

可以在 Web 界面中使用合并、拆分、旋转、加密、加水印、转换等 PDF 操作。官方文档将其描述为包含60多项工具的本地托管应用，具体功能会随镜像版本和镜像标签变化。

验收标准不是“容器显示 Up”，而是完成一次小文件操作：登录、上传测试 PDF、合并、下载并重新打开，同时确认宿主机数据目录出现配置和日志。

二、开始前检查 Docker

先确认客户端、Compose 和 Docker daemon 可用：

docker --version

docker compose version

docker info

docker --version 只说明客户端命令存在；docker info 能进一步确认 daemon 正在运行。Windows 用户如果看到无法连接 Docker Engine，先启动 Docker Desktop。

官方生产部署文档列出的参考要求是 Docker Engine 20.10+、Docker Compose 1.29+、至少2GB内存（推荐4GB以上）和约10GB磁盘空间。OCR和复杂格式转换可能需要更多资源，这些数字不应被理解成所有场景的最低保证。

三、创建 Compose 配置

在空目录中保存 compose.yaml：

services:
  stirling-pdf:
    image: ${STIRLING_IMAGE:-stirlingtools/stirling-pdf:latest}
    container_name: stirling-pdf
    ports:
      - "${STIRLING_PORT:-8080}:8080"
    volumes:
      - ./stirling-data/tessdata:/usr/share/tessdata
      - ./stirling-data/configs:/configs
      - ./stirling-data/logs:/logs
      - ./stirling-data/customFiles:/customFiles
      - ./stirling-data/pipeline:/pipeline
    environment:
      SECURITY_ENABLELOGIN: "true"
      SYSTEM_DEFAULTLOCALE: "en-US"
      SYSTEM_GOOGLEVISIBILITY: "false"
      SYSTEM_ROOTURIPATH: "/"
      SYSTEMFILEUPLOADLIMIT: "2000MB"
    restart: unless-stopped

这份配置使用官方镜像、把状态目录绑定到宿主机，并让容器异常退出后自动重启。

3.1 默认打开登录

官方 Docker 文档说明新容器默认启用登录。这里再次显式写出：

SECURITY_ENABLELOGIN: "true"

如果只在完全隔离的临时环境测试，可以自行关闭；局域网共享或公网部署不能把“没有登录”当作默认选择。

3.2 端口和镜像标签

默认访问8080。如果端口被占用，可以设置 STIRLING_PORT=9080，然后访问 http://localhost:9080，容器内部仍监听8080。

官方文档提供 latest、latest-fat、latest-ultra-lite 等标签。本文用 latest 便于首次跟随快速开始；生产环境应在验证后固定明确版本或镜像 digest，避免下一次拉取自动引入未经测试的变化。

四、启动并验证

docker compose config

docker compose pull

docker compose up -d

docker compose ps

docker compose config 会展开变量并检查 YAML，适合在启动前发现路径、变量和缩进问题。

查看日志：

docker compose logs -f stirling-pdf

浏览器打开 http://localhost:8080。不要只看容器状态，按下面顺序做一次真实验证：

1. 登录 Web 界面；
2. 上传两个测试 PDF；
3. 执行“合并 PDF”；
4. 下载并用本地阅读器打开；
5. 检查 stirling-data 中是否产生配置和日志。

测试文件不要使用身份证、合同或其他敏感原件。

五、首次登录与密码安全

官方文档给出的新容器默认账号是：

用户名：admin
密码：stirling

首次登录后必须立即修改密码。这个账号只适合第一次进入系统，不能作为长期凭据。

也可以在第一次启动前设置初始账号：

environment:
  SECURITY_ENABLELOGIN: "true"
  SECURITY_INITIALLOGIN_USERNAME: "youradmin"
  SECURITY_INITIALLOGIN_PASSWORD: "use-a-long-random-password"

这些变量只影响数据库尚未创建的首次启动。容器已经初始化后再修改 Compose 文件，旧账号不会自动替换；此时应在界面中修改账号。

不要把真实密码提交到公开仓库。生产环境应使用未提交的 .env、Docker secrets 或外部凭据管理系统。

六、五个数据目录分别保存什么

宿主机目录	容器目录	作用
stirling-data/configs	/configs	设置和应用数据库
stirling-data/tessdata	/usr/share/tessdata	OCR语言数据
stirling-data/logs	/logs	应用日志
stirling-data/customFiles	/customFiles	自定义品牌或文件
stirling-data/pipeline	/pipeline	自动化 pipeline 配置

容器是可替换的，宿主机目录才是需要保护的状态。至少要备份 configs；如果使用 OCR、自定义界面或 pipeline，也要一并备份。

七、备份与恢复

备份前先停止服务，避免配置或数据库正在写入：

docker compose stop

Windows 示例：

$backup = "D:\backup\stirling-pdf\$(Get-Date -Format yyyyMMdd-HHmmss)"
New-Item -ItemType Directory -Force -Path $backup | Out-Null
Copy-Item -Recurse -Force .\stirling-data $backup

备份完成后启动：

docker compose up -d

恢复演练的基本流程是：

停止容器 → 备份当前目录 → 用备份替换 stirling-data → 启动 → 登录并执行合并测试

不要在没有备份的情况下直接覆盖当前数据目录。真正可靠的备份还要定期做恢复演练，而不是只看复制命令是否成功。

八、升级与回滚

官方 Docker 文档给出的更新思路是拉取新镜像并重新创建容器：

docker compose pull

docker compose up -d

docker compose ps

docker compose logs --tail 100 stirling-pdf

升级前应记录当前镜像标识、备份数据目录、阅读官方迁移说明，并准备一份测试 PDF。具体版本号或 digest 必须以当时官方发布信息为准，本文不虚构一个固定版本。

如果升级后出现问题，把 STIRLING_IMAGE 改回升级前已验证的版本，恢复数据备份，再启动。不要为了“修复升级”直接删除 stirling-data。

九、局域网与公网访问边界

直接映射 8080:8080 适合本机访问。局域网共享时，应确认：

• 登录功能保持打开；
• 管理员密码已修改；
• 防火墙只允许可信网段；
• 不把容器端口直接映射到公网。

公网访问更适合采用：

浏览器 → HTTPS 反向代理 → 内网 Stirling-PDF:8080
                         ├── 登录
                         ├── 持久化数据
                         └── 日志

反向代理可以提供 HTTPS 和访问控制，但不能替代应用登录、备份和更新流程。没有 TLS、访问控制和恢复方案时，保持服务只监听本机或放在 VPN 后面。

十、OCR与镜像选择

合并、拆分等基础操作不一定需要 OCR。要识别扫描件文字，需要准备对应语言的 Tesseract 数据，并保持 tessdata 到 /usr/share/tessdata 的挂载。

建议先用标准 latest 完成基础部署，再按官方 OCR 文档增加语言包：

• 服务器资源充足、需要更多字体和格式支持时，考虑 latest-fat；
• 低配置设备只需要基础 PDF 操作时，考虑 latest-ultra-lite；
• 功能差异以官方版本文档为准，升级前重新验证。

十一、常见故障排查

1. 端口被占用

docker compose ps

Get-NetTCPConnection -LocalPort 8080 -ErrorAction SilentlyContinue

换宿主机端口：

$env:STIRLING_PORT = "9080"
docker compose up -d

2. 容器启动后退出

docker compose ps -a

docker compose logs --tail 200 stirling-pdf

先查看配置、挂载和权限错误，不要直接删除数据目录重来。

3. 更新后配置像丢失

确认 Compose 文件仍包含：

- ./stirling-data/configs:/configs

还要确认执行命令的目录没有切换到另一份 compose.yaml。相对路径由 Compose 文件解析，换项目目录可能使用另一套数据。

4. OCR没有识别中文

确认 tessdata 中存在对应语言数据、挂载路径正确，再查看日志。OCR语言包不是安装容器后自动拥有的。

十二、核验结果与边界

本次已完成官方文档对照、Compose 配置展开校验、Docker 客户端和 Compose 版本检查。当前机器版本为 Docker 29.1.5、Compose v5.0.1。

但本机 Docker daemon 当前未启动，无法完成官方镜像拉取、容器启动和浏览器端合并验证。因此本文不把“已通过本机真实容器运行”写成事实。启动 Docker Desktop 后，按 pull → up → 浏览器操作 → 日志检查 完成最后验证即可。

十三、总结

部署自托管 PDF 工具，真正重要的不是执行一次 docker compose up -d，而是把以下链路做完整：

Compose 配置 → 持久化目录 → 首次登录改密 → 小文件功能验证
      ↓
备份 → 更新 → 日志排错 → 局域网/公网访问边界

Stirling-PDF适合本机和受控局域网中的 PDF 日常处理。它能减少文件上传到第三方网站的需要，但自托管不等于自动安全；密码、网络暴露、备份和版本升级仍然需要使用者负责。

参考资料

• Stirling-PDF 官方文档：Getting Started
• Stirling-PDF 官方文档：Docker Installation
• Stirling-PDF 官方文档：Production Deployment Guide
• Stirling-PDF 官方文档：Versions
• Stirling-PDF 官方文档：Configuration