本文档提供了在各种环境中部署 Stirling-PDF 的全面指南。它涵盖了基于 Docker 的部署选项、原生安装方法以及运行应用程序所需的基本配置设置。有关系统架构和组件的信息，请参阅架构。
Stirling-PDF 提供灵活的部署方法，以满足不同的环境和需求。
来源：README.md100-111 .github/workflows/push-docker.yml91-183
Stirling-PDF 提供三种 Docker 镜像变体以满足不同需求。
| 镜像类型 | 标签格式 | 描述 | 用例 |
|---|---|---|---|
| 常规 | latest, <version> | 包含核心 PDF 功能的标准镜像。 | 通用部署。 |
| 超轻量版 | latest-ultra-lite, <version>-ultra-lite | 最小化镜像，依赖项较少。 | 资源受限环境。 |
| 完整版 | latest-fat, <version>-fat | 包含所有依赖项的完整镜像。 | 最大功能。 |
所有镜像均可从 Docker Hub 获取，镜像名为 frooodle/s-pdf，或从 GitHub Container Registry 获取，镜像名为 ghcr.io/stirling-tools/s-pdf 和 ghcr.io/stirling-tools/stirling-pdf。
来源：.github/workflows/push-docker.yml76-183 Dockerfile1-96
使用 Docker run 进行基本部署。
为了更易于管理的部署，请使用 Docker Compose。
来源：Dockerfile25-37 .github/workflows/testdriver.yml65-90
用于持久化数据的推荐卷挂载。
| 容器路径 | 目的 |
|---|---|
/configs | 配置文件 |
/customFiles | 自定义文件（模板等）。 |
/logs | 应用程序日志 |
/usr/share/tessdata | Tesseract OCR 语言数据。 |
/pipeline/watchedFolders | 管道自动化输入。 |
/pipeline/finishedFolders | 管道自动化输出。 |
来源：Dockerfile82 .github/workflows/testdriver.yml75-77
Stirling-PDF 为各种平台提供了原生安装程序。
| 平台 | 安装程序类型 | 备注 |
|---|---|---|
| Windows | .exe 安装程序。 | 提供标准版和带登录版。 |
| macOS | .dmg 安装程序。 | 支持 ARM 和 x86_64 架构。 |
| Linux | .deb 包。 | 适用于 Debian 系发行版。 |
这些安装程序是为每个发行版自动生成的，可以从GitHub releases page 下载。
来源：.github/workflows/multiOSReleases.yml132-223 .github/workflows/releaseArtifacts.yml1-181
用于手动安装 JAR 文件。
对于带有登录功能的版本。
应用程序将可通过 http://:8080 访问。
来源：.github/workflows/releaseArtifacts.yml42-58
| 可变 | 描述 | 默认 |
|---|---|---|
DOCKER_ENABLE_SECURITY | 启用安全/登录功能。 | false |
SECURITY_ENABLELOGIN | 启用登录页面。 | false |
SYSTEM_DEFAULTLOCALE | 默认语言。 | en-GB |
UI_APPNAME | UI 中的应用程序名称。 | Stirling-PDF |
UI_HOMEDESCRIPTION | 主页上的自定义描述。 | - |
SYSTEM_MAXFILESIZE | 最大文件大小（单位 MB）。 | 100 |
METRICS_ENABLED | 启用指标收集。 | true |
SYSTEM_GOOGLEVISIBILITY | 允许 Google 索引。 | false |
PUID | 运行的用户 ID | 1000 |
PGID | 要运行的组 ID。 | 1000 |
UMASK | 文件创建权限掩码。 | 022 |
来源：Dockerfile25-37 .github/workflows/testdriver.yml78-89 scripts/init-without-ocr.sh6-15 scripts/init.sh16-29 src/main/resources/templates/fragments/languages.html1-42 scripts/ignore_translation.toml1-269
Stirling-PDF 支持 39 种以上语言。系统将默认使用浏览器的语言，但您可以使用 SYSTEM_DEFAULTLOCALE 环境变量设置系统范围内的默认语言。
安装额外的 Tesseract OCR 语言数据以实现 OCR 功能。
这将安装法语、德语和西班牙语的 OCR 语言数据。
来源：scripts/init.sh16-29 src/main/resources/templates/fragments/languages.html1-42 scripts/ignore_translation.toml1-269
对于安全安装。
| 可变 | 描述 | 默认 |
|---|---|---|
DOCKER_ENABLE_SECURITY | 使用启用安全的 JAR。 | false |
SECURITY_ENABLELOGIN | 启用登录页面。 | 取决于镜像。 |
SECURITY_DEFAULT_ADMIN_PASSWORD | 默认管理员密码。 | - |
SECURITY_JWT_SECRETKEY | JWT 令牌的密钥。 | 自动生成 |
当 DOCKER_ENABLE_SECURITY 设置为 true 时，容器将自动下载并使用启用安全的 JAR 文件版本。
来源：scripts/download-security-jar.sh1-22 .github/workflows/releaseArtifacts.yml16-21
下图说明了 Stirling-PDF 的部署架构以及各组件如何交互。
来源： Dockerfile1-96 scripts/init.sh1-30 scripts/init-without-ocr.sh1-41
此图表显示了 Docker 镜像的构建和发布过程。
来源： .github/workflows/push-docker.yml13-196
文件权限问题：如果您遇到权限问题，请检查 PUID 和 PGID 环境变量是否与您的用户/组 ID 匹配。
内存问题：通过 JAVA_CUSTOM_OPTS 环境变量调整 Java 内存设置。
JAVA_CUSTOM_OPTS="-Xmx2g -Xms1g"
缺少 OCR 语言：使用 TESSERACT_LANGS 环境变量添加其他语言。
安全 JAR 下载失败：如果您使用了 DOCKER_ENABLE_SECURITY=true 并且安全 JAR 下载失败，请从 GitHub releases 页面手动下载并挂载到容器中。
来源： scripts/init-without-ocr.sh3-40 scripts/download-security-jar.sh1-22
要进行故障排除，请检查以下位置的日志：
docker logs stirling-pdf/logs 目录中检查。为获得最佳性能，请考虑以下设置：
JVM 内存设置：根据您的服务器资源调整 Java 内存分配。
JAVA_CUSTOM_OPTS="-Xmx4g -Xms2g -XX:+UseG1GC"
并发用户：对于具有许多并发用户的环境，请增加线程池大小。
JAVA_CUSTOM_OPTS="-Dserver.tomcat.max-threads=200"
文件大小限制：根据您的需求调整最大文件大小限制。
SYSTEM_MAXFILESIZE=500