Stirling-PDF 3.2.0 Docker Compose 部署指南

目标：在 Ubuntu 22.04 服务器上用 Docker Compose 从零部署 Stirling-PDF 3.2.0（官方 stirlingtools/stirling-pdf 标准版镜像），完成版本选型与锁定、数据持久化（六个挂载目录）、首次登录初始化、JVM 堆内存限制（256–512MB）与动态内存分档验证、健康检查验收、升级与卸载运维。文中全部命令与回显均在真实部署环境（Ubuntu 22.04、Docker 29.8.1、Docker Compose v5.5.1、Stirling-PDF 3.2.0，服务地址 http://192.168.146.128:8129）实测通过。组件定位与选型背景见 《Stirling-PDF 3.2.0 介绍与选型指南》。

一、环境信息

本篇部署目标与实测环境的关键信息如下，读者按本文操作时请将 IP 换成自己服务器的地址：

• 操作系统：Ubuntu 22.04.4 LTS（Jammy Jellyfish）
• Docker：Docker version 29.8.1, build 4a63305
• Docker Compose：Docker Compose version v5.5.1
• Stirling-PDF：stirlingtools/stirling-pdf:3.2.0（Docker Hub 官方镜像，3.2.0 于 2026-10-15 推送，本文部署时点 2026-10-22 锁定该版本）
• 应用本体：Java（Spring Boot）Web 应用，镜像内置 JDK 25 运行时（JAVA_VERSION=jdk-25.0.4+7），内置 Tesseract、OCRmyPDF、LibreOffice、WeasyPrint、Calibre、Ghostscript、QPDF、ImageMagick 八大处理引擎
• 服务端口：应用内监听 8080，对外发布 8129
• 部署目录：/opt/stirling-pdf/（compose 文件），数据目录 /opt/stirling-pdf/stirling-data/
• 初始管理账号：admin（密码 q1w2e3r4，部署时通过环境变量注入，首次登录后应修改）
• 实测验收链路：compose 部署 → 健康检查 healthy → 登录页 200 → 管理员登录 → 设置文件与数据库落盘验证

💡 说明：Stirling-PDF 是单体 Java 应用，官方镜像自带全部处理引擎与嵌入式 H2 数据库，单服务即可运行，不需要额外数据库组件；多用户数据、用户文件存储全部落在这一个服务的挂载目录里，持久化方案见第五章。

二、镜像选型说明

2.1 官方三个镜像档位

官方为不同资源预算提供三档镜像（档位差异与官方建议内存引自官方文档 "Install → Docker → Choose an image"，镜像体积为 Docker Hub 2026-10-22 实查压缩尺寸）：

如何选：需要多用户、登录、REST API、OCR 与 Office 转换的团队场景选标准版（本文方案）；只做页面拆合且内存紧张的选 ultra-lite（但无 API 管理设置与登录体系）；需要 AI 文档问答（接入 Anthropic/OpenAI/Ollama）选 fat 版。

💡 技术拓展：三个档位本质是「同一应用 + 不同引擎打包」的取舍，类似 PDF 处理平台的"功能裁剪"策略。对比另一条路线——功能专精型工具（OCRmyPDF 只做 OCR、Gotenberg 只做转换）：专精工具单机资源需求低但需多组件拼装，Stirling-PDF 档位化镜像用一个服务换全功能，代价是标准版 4GB 内存门槛。本专栏全套文档采用标准版。

2.2 版本选型说明与 3.2.1 升级提示

本文编写时点（2026-10-22）实测 Docker Hub 标签列表（https://hub.docker.com/v2/repositories/stirlingtools/stirling-pdf/tags，节选）：

latest             2026-10-21  1112MB   （已指向 3.2.1）
3.2.1              2026-10-21  1112MB
3.2.1-fat          2026-10-21  1161MB
3.2.1-ultra-lite   2026-10-21   377MB
latest-ultra-lite  2026-10-21   377MB
3.2.0-ultra-lite   2026-10-15   376MB

要点解读：

• 官方已于 2026-10-21 发布 3.2.1（标准/fat/ultra-lite 三档同步），latest 已滚动指向 3.2.1；
• 本文全套文档以 3.2.0 为版本基线撰写与实测，3.2.1 为补丁版本，配置参数与 API 结构一致，升级方法见第十章「升级到 3.2.1」；
• 生产部署一律锁定精确补丁版本号（如 stirlingtools/stirling-pdf:3.2.0），不用 latest——latest 随官方发布自动漂移，升级时机不可控；
• alpha 标签为开发预览版，禁用于生产。

2.3 镜像仓库三选一

官方提供三个等价镜像仓库，任选其一（内网环境推荐官方自有仓库或提前 docker save/load 搬运）：

架构覆盖 amd64 与 arm64（树莓派等 ARM 设备可用）。

三、前置条件

部署前确认三件事：Docker 环境就绪、端口未被占用、目录已规划。

1. 确认 Docker 与 Compose 版本：

docker --version && docker compose version

实测回显：

Docker version 29.8.1, build 4a63305
Docker Compose version v5.5.1

2. 确认服务端口未被占用（本文对外发布 8129，应用内部固定 8080）：

ss -ltn | grep -E ':(8129|8080)\s'

实测回显（端口空闲时无输出，命令正常返回；若有输出说明端口被占，换一个宿主端口映射即可）：

（无输出）

3. 创建部署与数据目录：

mkdir -p /opt/stirling-pdf/stirling-data/{configs,logs,customFiles,pipeline,storage,tessdata}
ls /opt/stirling-pdf/stirling-data/

实测回显：

configs  customFiles  logs  pipeline  storage  tessdata

⚠️ 注意：镜像内进程以 UID/GID 1000 运行，若宿主目录属主不是 1000，可在 compose 中用 PUID/PGID 环境变量适配（见第六章），或 chown -R 1000:1000 /opt/stirling-pdf/stirling-data。

四、部署步骤

4.1 编写 docker-compose.yml

在 /opt/stirling-pdf/ 下创建 docker-compose.yml（完整生产版，与本文实测环境一致）：

name: stirling-pdf-3.2.0-stack

services:
  stirling-pdf:
    image: stirlingtools/stirling-pdf:3.2.0
    container_name: stirling-pdf-3.2.0-app
    mem_limit: 4g
    ports:
      - '8129:8080'
    volumes:
      - ./stirling-data/configs:/configs
      - ./stirling-data/logs:/logs
      - ./stirling-data/customFiles:/customFiles
      - ./stirling-data/pipeline:/pipeline
      - ./stirling-data/storage:/storage
      - ./stirling-data/tessdata:/usr/share/tessdata
    environment:
      SYSTEM_DEFAULTLOCALE: zh-CN
      SYSTEM_ENABLEANALYTICS: "false"
      SECURITY_INITIALLOGIN_USERNAME: admin
      SECURITY_INITIALLOGIN_PASSWORD: q1w2e3r4
      JAVA_CUSTOM_OPTS: "-Xms256m -Xmx512m -Xlog:gc+init"
    restart: unless-stopped

逐项说明：

• name: stirling-pdf-3.2.0-stack：compose 项目名。必须显式指定——多套 compose 项目同机部署时，项目名默认取目录名，若与其他组件目录同名，docker compose down 会误删他人在跑的服务；
• image：锁定 3.2.0 精确版本（2.2 节选型结论）；
• mem_limit: 4g：限制服务可用内存为 4GB。强烈建议显式设置——Stirling-PDF 启动脚本按内存限制自动分档计算 JVM 参数，不设限制时会按宿主机全部内存计算，产生过大的内存百分比基线（实测对比见 7.3 节）；
• ports '8129:8080'：宿主 8129 → 应用 8080，读者可按需改宿主端口；
• volumes 六个挂载：作用与实测落盘内容见第五章；
• environment 五个变量：界面语言中文、关闭遥测分析、注入初始管理员账号（admin / q1w2e3r4）、限制 JVM 堆在 256–512MB（第七章专项说明）。环境变量命名规则与完整清单见第六章；
• restart: unless-stopped：服务器重启后自动拉起（手动 stop 的除外）。

4.2 启动服务

cd /opt/stirling-pdf && docker compose up -d

首次启动实测回显（镜像已拉取时直接创建；首次拉取约 1.1GB，视带宽需数分钟）：

[+] Running 3/3
 ✔ Network stirling-pdf-3.2.0-stack_default  Created
 ✔ Container stirling-pdf-3.2.0-app          Created
 ✔ Container stirling-pdf-3.2.0-app          Started

4.3 观察启动过程

Spring Boot 应用启动约需 20–40 秒（含引擎初始化），跟踪日志：

docker compose logs -f stirling-pdf

实测回显（节选，关键行）：

[init][warn] Using TESSDATA_PREFIX=/usr/share/tesseract-ocr/5/tessdata
Detected container memory: 4096MB
Dynamic memory: InitialRAM=2%, MaxRAM=70%, MaxMeta=512m
Using _JVM_OPTS (ConcGCThreads=3)
Picked up JAVA_TOOL_OPTIONS: -XX:+ExitOnOutOfMemoryError -XX:+HeapDumpOnOutOfMemoryError ... -XX:InitialRAMPercentage=2 -XX:MaxRAMPercentage=70 -XX:MaxMetaspaceSize=512m -Xms256m -Xmx512m -Xlog:gc+init
00:53:07.942 [main] INFO  s.s.S.config.MultipartConfiguration - Using default multipart file upload limit: 2000MB
00:53:08.717 [main] INFO  s.s.p.s.configuration.DatabaseConfig - Using default H2 database
00:53:13.070 [main] INFO  s.s.c.c.RuntimePathConfig - Using Tesseract data path: /usr/share/tesseract-ocr/5/tessdata

要点解读：

• Detected container memory: 4096MB + Dynamic memory: ...：启动脚本读取内存限制并完成 JVM 动态内存分档（详见 7.2 节）；
• Picked up JAVA_TOOL_OPTIONS: ...：JVM 拾取了镜像基础参数 + 我们注入的 -Xms256m -Xmx512m，这是堆限制生效的直接证据（7.4 节验证方法）；
• Using default H2 database：使用嵌入式 H2 数据库（数据文件落在 /configs 挂载目录）。

4.4 验证服务状态与健康检查

1. compose 状态（镜像内置健康检查：每 30 秒对应用内 http://localhost:8080/api/v1/info/status 发起探测，启动宽限期 120 秒，超时 15 秒，连续失败 5 次标记 unhealthy）：

docker compose ps

实测回显（启动约 1 分钟后）：

NAME                     IMAGE                              COMMAND                   SERVICE        CREATED                  STATUS                                     PORTS
stirling-pdf-3.2.0-app   stirlingtools/stirling-pdf:3.2.0   "tini -- /scripts/in…"   stirling-pdf   About a minute ago       Up About a minute (healthy)                0.0.0.0:8129->8080/tcp, [::]:8129->8080/tcp

2. 登录页 HTTP 探测：

curl -s -o /dev/null -w '%{http_code}\n' http://192.168.146.128:8129/login

实测回显：

200

3. 免认证状态接口（健康检查同款端点，从服务器侧探测）：

curl -s http://192.168.146.128:8129/api/v1/info/status

实测回显：

{"version":"3.2.0","status":"UP"}

三条全部符合预期即部署完成。浏览器打开 http://192.168.146.128:8129，用 admin / q1w2e3r4 登录，界面语言已按 SYSTEM_DEFAULTLOCALE 显示为中文。

五、数据持久化说明

5.1 六个挂载目录的作用与实测落盘

Stirling-PDF 的所有状态都必须落盘持久化，compose 中六个挂载的实测产物如下（重启/升级后数据不丢）：

💡 技术拓展：数据卷形态不止 bind mount 一种，常见三种对比——

形态	原理/特点	适用场景
bind mount（本文方案）	宿主目录直挂，路径可见、可直接备份与编辑	生产自托管，需人工查看/备份数据
named volume	Docker 托管卷，位置由引擎管理，迁移方便	不关心内部路径、用 docker volume 管理备份
tmpfs	内存盘，重启即失	临时处理目录等非持久数据

本文采用 bind mount：Stirling-PDF 的核心数据（settings.yml、H2 数据库）需要运维直接可见可备份，bind mount 路径透明最合适。

5.2 持久化验证：重启后数据不丢

cd /opt/stirling-pdf && docker compose restart && sleep 40
curl -s http://192.168.146.128:8129/api/v1/info/status

实测回显（重启后版本与状态正常，登录账号、用户文件、设置均保留）：

{"version":"3.2.0","status":"UP"}

⚠️ 注意：官方文档特别强调 /configs 必须挂载（"Always mount this"）——不挂载时 settings.yml 与 H2 数据库写在容器可写层内，服务重建（down + up）后全部用户数据丢失。

六、环境变量表

Stirling-PDF 支持用环境变量覆盖 settings.yml 中的任意配置，命名规则为「配置路径大写 + 下划线」：如 security.initialLogin.username → SECURITY_INITIALLOGIN_USERNAME、system.defaultLocale → SYSTEM_DEFAULTLOCALE。运行时环境变量优先级高于 settings.yml 文件值。部署常用变量如下（全部实测可用）：

⚠️ 注意：SECURITY_INITIALLOGIN_* 只在数据库首次初始化时读取；之后改密码请在 Web 界面「账户设置」操作，改环境变量不会重置已存在的账号。

七、配置参数说明：JVM 堆内存专项

Stirling-PDF 是 Java 应用，内存治理分两层：镜像启动脚本的动态内存分档（自动）与用户注入的堆参数（JAVA_CUSTOM_OPTS，建议显式设置）。本章全部结论来自部署环境的启动日志实测。

7.1 参数注入链路与修改位置

用户堆参数的唯一修改位置是 docker-compose.yml 的 JAVA_CUSTOM_OPTS 环境变量（本文 4.1 节 compose 已配置）。生效链路（启动脚本实测逻辑）：

JAVA_CUSTOM_OPTS（用户堆参数，如 -Xms256m -Xmx512m）
  └─ 与镜像基础参数 _JVM_OPTS + 动态内存百分比拼接
      └─ export JAVA_TOOL_OPTIONS="<基础参数> <动态内存参数> <JAVA_CUSTOM_OPTS>"
          └─ JVM 启动自动拾取（日志打印 Picked up JAVA_TOOL_OPTIONS: ...）

要点解读：JAVA_CUSTOM_OPTS 不是 JVM 原生变量，而是镜像启动脚本（init-without-ocr.sh）约定的入口，最终以 JAVA_TOOL_OPTIONS 传递给 JVM——因此 ps 里看不到 -Xms/-Xmx 属正常现象，验证以启动日志为准（7.4 节）。

7.2 动态内存分档机制（必须设 mem_limit 的原因）

启动脚本按容器内存限制自动计算堆百分比与 Metaspace 上限，实测分档（摘自启动脚本 compute_dynamic_memory()）：

💡 技术拓展：MaxRAMPercentage 只约束 JVM 堆，进程总占用还包括 Metaspace（100–700MB）、代码缓存（约 100–200MB）、线程栈与堆外直接内存——标准版镜像内 LibreOffice、Calibre 等外部引擎进程另算。这也是官方对标准版建议 4GB 内存档的原因：堆之外的引擎子进程需要余量。

7.3 不设 mem_limit 的实测后果（排障实录）

未配置 mem_limit 时启动，日志实测：

No container memory limit set; sizing from host RAM (32050MB). Set mem_limit / -m to cap it.
Detected container memory: 32050MB
Dynamic memory: InitialRAM=2%, MaxRAM=70%, MaxMeta=768m

后果解读：分档按宿主机 32GB 内存计算，MaxRAMPercentage=70% 意味着 JVM 认为自己可以扩张到约 22GB 堆——虽然 JAVA_CUSTOM_OPTS 的 -Xmx512m 硬上限仍会压住堆，但任何未显式限制堆的部署形态（或用户误删 JAVA_CUSTOM_OPTS）都会让 JVM 在高负载时膨胀到宿主机内存的 70%，挤压同机其他服务。加上 mem_limit: 4g 后重建，日志变为正常分档：

Detected container memory: 4096MB
Dynamic memory: InitialRAM=2%, MaxRAM=70%, MaxMeta=512m

7.4 堆限制生效验证

方法一（官方镜像唯一可行）：启动日志检查。官方镜像基于精简 JRE，不含 jps/jcmd 等 JDK 诊断工具（实测镜像内仅有 java/jfr/jrunscript/jwebserver/keytool/rmiregistry 八个命令，jps 提示 jps: not found），因此验证堆参数以启动日志为准：

docker compose logs stirling-pdf 2>&1 | grep -o '\-Xms[0-9a-z]* -Xmx[0-9a-z]*' | head -1

实测回显：

-Xms256m -Xmx512m

方法二：进程命令行反证。ps 中看不到堆参数（参数经 JAVA_TOOL_OPTIONS 环境变量传入 JVM，不进命令行），如果命令行里出现了 -Xms 反而说明走了非官方启动路径：

docker exec stirling-pdf-3.2.0-app ps -ef | grep [j]ava

实测回显（确无堆参数，符合预期）：

ubuntu       264       7  2 00:53 ?        00:01:38 java -Dfile.encoding=UTF-8 -Djava.io.tmpdir=/tmp/stirling-pdf -cp /app/app.jar:/app/lib/* stirling.software.SPDF.SPDFApplication

💡 说明：若采用裸机 JAR 方式部署（自备完整 JDK 25，安装方法见官方文档 "Install → Bare bones"），堆参数写入启动脚本的 JAVA_OPTS 后可用 jps -v 直接看到 -Xms256m -Xmx512m；JAR 部署的堆上限同样建议控制在 256–512MB，把更多内存留给外部引擎子进程。

八、配置文件挂载

服务首次启动后，会在 /configs（宿主 ./stirling-data/configs）生成完整配置文件与数据文件：

ls /opt/stirling-pdf/stirling-data/configs/

实测回显：

backup
cache
credential-encryption.key
custom_settings.yml
heap_dumps
server-certificate.p12
settings.yml
stirling-pdf-DB-2.3.232.mv.db

逐项说明：

• settings.yml：主配置文件（544 行带注释的官方模板，首次启动按默认值生成并回写实例 ID 与密钥）。所有参数的含义与调法是 《Stirling-PDF 3.2.0 配置参数详解》 的主题；
• custom_settings.yml：用户自定义配置片段，与 settings.yml 合并生效，升级时不会被官方模板覆盖，是推荐的配置落点；
• stirling-pdf-DB-2.3.232.mv.db：H2 嵌入式数据库（用户、团队、审计、文件索引全在这里），实测 332KB 起步；自动备份落在 backup/ 子目录（默认每日 00:00，cron 可调）；
• credential-encryption.key：凭据加密密钥——丢失即无法解密已存密码，务必随 /configs 一起备份；
• server-certificate.p12：内置签名证书（"Sign with Stirling-PDF" 功能用），默认有效期 365 天，可配置自动再生成；
• heap_dumps/：JVM OOM 时堆转储落点（镜像默认开启 HeapDumpOnOutOfMemoryError）。

⚠️ 注意：OCR 语言包不在这里——tessdata 挂载点在 /usr/share/tessdata（第五章第 6 行），把 chi_sim.traineddata 等语言文件放宿主 ./stirling-data/tessdata/，启动日志会打印 [init][warn] Found user-mounted tessdata ... 并自动复制进引擎目录。

九、等价 docker run

不用 compose 时，以下单条命令与本文 compose 等价（便于临时验证或迁移到其他编排工具）：

docker run -d \
  --name stirling-pdf-3.2.0-app \
  --memory 4g \
  --restart unless-stopped \
  -p 8129:8080 \
  -v /opt/stirling-pdf/stirling-data/configs:/configs \
  -v /opt/stirling-pdf/stirling-data/logs:/logs \
  -v /opt/stirling-pdf/stirling-data/customFiles:/customFiles \
  -v /opt/stirling-pdf/stirling-data/pipeline:/pipeline \
  -v /opt/stirling-pdf/stirling-data/storage:/storage \
  -v /opt/stirling-pdf/stirling-data/tessdata:/usr/share/tessdata \
  -e SYSTEM_DEFAULTLOCALE=zh-CN \
  -e SYSTEM_ENABLEANALYTICS="false" \
  -e SECURITY_INITIALLOGIN_USERNAME=admin \
  -e SECURITY_INITIALLOGIN_PASSWORD=q1w2e3r4 \
  -e JAVA_CUSTOM_OPTS="-Xms256m -Xmx512m -Xlog:gc+init" \
  stirlingtools/stirling-pdf:3.2.0

💡 说明：compose 版多出固定项目名与独立网络两个编排优势，其余语义等价。生产建议仍以 compose 管理（升级、回滚、日志排查都是一条命令）。

十、常用运维命令

以下命令均在 /opt/stirling-pdf/ 目录执行。

启停与状态：

docker compose ps                     # 状态与健康检查结果
docker compose stop                   # 停止（保留容器与数据）
docker compose start                  # 再启动
docker compose restart                # 重启（改完 settings.yml 后常用）
docker compose down                   # 停止并删除容器与网络（数据在 bind mount，不受影响）
docker compose up -d                  # 启动/按最新 compose 重建

实测回显（down 完整输出）：

 Container stirling-pdf-3.2.0-app Stopping
 Container stirling-pdf-3.2.0-app Stopped
 Container stirling-pdf-3.2.0-app Removing
 Container stirling-pdf-3.2.0-app Removing
 Container stirling-pdf-3.2.0-app Removed
 Network stirling-pdf-3.2.0-stack_stirling-net Removing
 Network stirling-pdf-3.2.0-stack_stirling-net Removed

日志排查：

docker compose logs --tail 100 stirling-pdf        # 最近 100 行
docker compose logs -f stirling-pdf                # 实时跟踪
docker compose logs stirling-pdf 2>&1 | grep -i error | tail -20   # 只看错误

数据库手动备份（自动备份默认每日 00:00，cron 见配置篇；手动备份直接拷贝）：

cp /opt/stirling-pdf/stirling-data/configs/stirling-pdf-DB-2.3.232.mv.db /opt/backup/stirling-db-$(date +%F).mv.db

10.1 升级到 3.2.1（2026-10-21 已发布）

升级路径三步：备份数据 → 改版本号 → 重建。实测流程：

# 1. 升级前备份核心数据（/configs 全量）
tar czf /opt/backup/stirling-configs-$(date +%F).tar.gz -C /opt/stirling-pdf/stirling-data configs

# 2. 修改 docker-compose.yml 中 image 行的版本号
sed -i 's/stirlingtools\/stirling-pdf:3.2.0/stirlingtools\/stirling-pdf:3.2.1/' docker-compose.yml

# 3. 拉取新镜像并重建服务
docker compose pull && docker compose up -d

实测回显（docker pull stirlingtools/stirling-pdf:3.2.1，tail 节选，共 10 余层）：

cf14f644dda9: Pull complete
09645525d560: Pull complete
Digest: sha256:f95b691c3df463373258e21a578b404f1eb4c7660e8170a40e3e03c9c8f208a4
Status: Downloaded newer image for stirlingtools/stirling-pdf:3.2.1
docker.io/stirlingtools/stirling-pdf:3.2.1

# 4. 验证版本与健康
curl -s http://192.168.146.128:8129/api/v1/info/status

实测回显（升级后，3.2.1 栈实测取得；升级前同命令返回 "version":"3.2.0"）：

{"version":"3.2.1","status":"UP"}

回滚：把 compose 的 image 行改回 3.2.0 后 docker compose up -d 即可；若新版本已写库，回滚前用第 1 步的备份包还原 /configs。

⚠️ 注意：跨大版本（如 0.x V1 时代 → 3.x）存在破坏性变更与 settings 结构调整，升级前必须先读官方文档 "Upgrading from V1" 章节；本文的 3.2.0 → 3.2.1 为同系列补丁升级，无配置迁移。

十一、常见问题

Q1：启动日志出现 No container memory limit set; sizing from host RAM 怎么办？

这是未设置 mem_limit 的警告（7.3 节实测）。补上 mem_limit: 4g（或按机器实际内存设 2g–4g）后 docker compose up -d 重建，日志应显示 Detected container memory: 4096MB。

Q2：状态一直是 health: starting 甚至变 unhealthy？

健康检查有 120 秒启动宽限期（StartPeriod），标准版首次启动需初始化数据库、复制 OCR 语言包、预热 LibreOffice，2–3 分钟内转 healthy 属正常。超过 5 分钟仍 unhealthy，先看日志：docker compose logs --tail 200 stirling-pdf。实测中最常见两类根因——宿主内存不足导致 JVM 启动即 OOM（日志出现 ExitOnOutOfMemoryError 触发的退出）；或 JAVA_CUSTOM_OPTS 写错参数名导致 JVM 直接拒绝启动（日志会有 Unrecognized VM option），修正后重建。

Q3：OCR 中文不生效，日志有 Found user-mounted tessdata 提示？

[init][warn] Found user-mounted tessdata in /usr/share/tessdata, copying to /usr/share/tesseract-ocr/5/tessdata 是正常信息：启动脚本把你挂载的语言包复制进引擎目录。中文 OCR 还需要语言包文件本身存在——把 chi_sim.traineddata（Tesseract 官方 GitHub tessdata_fast/tessdata_best 下载）放进 ./stirling-data/tessdata/ 后重启即可。

Q4：端口冲突（Bind for 0.0.0.0:8129 failed: port is already allocated）？

宿主 8129 被其他服务占用。把 compose 里 ports 左侧改为其他端口（如 '8229:8080'）后 docker compose up -d；应用内部 8080 不用动。

Q5：首次登录 admin 密码不对？

确认两点：compose 的 environment 段确实注入了 SECURITY_INITIALLOGIN_USERNAME/PASSWORD（docker compose exec stirling-pdf printenv | grep SECURITY_ 核实）；以及数据库是不是后改的环境变量——初始账号只在首次建库时生效，若库已存在，用旧密码登录后在界面改密，或备份后清空 configs/stirling-pdf-DB-*.mv.db 重新初始化（会丢用户与文件索引，慎用）。

Q6：升级后界面还是旧版本号？

浏览器缓存了前端静态资源，强制刷新（Ctrl+Shift+R）即可；确认后端版本的权威途径是 curl http://192.168.146.128:8129/api/v1/info/status 的 version 字段。

十二、卸载与清理

# 1. 停止并删除服务（容器与网络）
cd /opt/stirling-pdf && docker compose down

# 2. 确认无残留
docker ps -a | grep stirling-pdf || echo "no container left"
docker network ls | grep stirling-pdf || echo "no network left"

# 3. 删除镜像（如不再使用）
docker rmi stirlingtools/stirling-pdf:3.2.0

# 4. 删除数据目录（彻底清空用户数据，执行前确认备份已留存）
rm -rf /opt/stirling-pdf/

实测回显（第 2 步）：

no container left
no network left

十三、参考链接

• 官方文档 Docker 安装：https://docs.stirlingpdf.com（Server → Install → Docker，镜像档位表与持久化建议来源，查询日期 2026-10-22）
• 官方镜像（Docker Hub）：https://hub.docker.com/r/stirlingtools/stirling-pdf（tag 列表与体积取证来源）
• 官方自有镜像仓库：https://docker.stirlingpdf.com
• 官方仓库：https://github.com/Stirling-Tools/Stirling-PDF
• 本专栏系列文档：《Stirling-PDF 3.2.0 介绍与选型指南》、《Stirling-PDF 3.2.0 配置参数详解》（settings.yml 全参数）、《Stirling-PDF 3.2.0 API 使用详解》（REST API 实测）