Stirling-PDF Docker Compose配置：一键部署完整环境-优快云博客

Stirling-PDF Docker Compose配置：一键部署完整环境

为什么选择Docker Compose部署Stirling-PDF

Stirling-PDF作为排名第一的本地托管PDF处理应用程序，提供了丰富的PDF操作功能。使用Docker Compose部署可以带来以下优势：

简化部署流程，无需手动安装依赖
确保环境一致性，避免"在我电脑上能运行"的问题
轻松管理服务生命周期，支持一键启动、停止和更新
内置多种配置模板，满足不同场景需求

准备工作

在开始部署前，请确保您的系统已安装：

Docker Engine (官方安装指南)
Docker Compose (官方安装指南)

项目提供了多种Docker Compose配置模板，位于exampleYmlFiles/目录下，您可以根据需求选择合适的配置。

基础部署：快速启动

对于大多数用户，推荐使用基础配置快速启动Stirling-PDF。基础配置包含完整功能，无需额外设置即可使用。

基础配置文件

创建docker-compose.yml文件，内容如下（基于exampleYmlFiles/docker-compose-latest.yml）：

version: '3.3'
services:
  stirling-pdf:
    container_name: Stirling-PDF
    image: frooodle/s-pdf:latest
    deploy:
      resources:
        limits:
          memory: 4G
    healthcheck:
      test: ["CMD-SHELL", "curl -f http://localhost:8080/api/v1/info/status | grep -q 'UP' && curl -fL http://localhost:8080/ | grep -qv 'Please sign in'"]
      interval: 5s
      timeout: 10s
      retries: 16
    ports:
      - "8080:8080"
    volumes:
      - ./stirling/data:/usr/share/tessdata:rw
      - ./stirling/config:/configs:rw
      - ./stirling/logs:/logs:rw
    environment:
      DOCKER_ENABLE_SECURITY: "false"
      SECURITY_ENABLELOGIN: "false"
      LANGS: "en_GB,en_US,ar_AR,de_DE,fr_FR,es_ES,zh_CN,zh_TW,ca_CA,it_IT,sv_SE,pl_PL,ro_RO,ko_KR,pt_BR,ru_RU,el_GR,hi_IN,hu_HU,tr_TR,id_ID"
      SYSTEM_DEFAULTLOCALE: en-US
      UI_APPNAME: Stirling-PDF
      UI_HOMEDESCRIPTION: 本地PDF处理工具
      UI_APPNAMENAVBAR: Stirling-PDF
      SYSTEM_MAXFILESIZE: "100"
      METRICS_ENABLED: "true"
      SYSTEM_GOOGLEVISIBILITY: "true"
    restart: on-failure:5

启动服务

在终端中执行以下命令启动服务：

docker-compose up -d

服务启动后，访问http://localhost:8080即可打开Stirling-PDF应用。

安全增强：启用身份验证

对于公共环境或需要访问控制的场景，建议启用安全认证功能。项目提供了带安全认证的配置模板。

安全配置文件

创建docker-compose-security.yml文件，内容如下（基于exampleYmlFiles/docker-compose-latest-security.yml）：

version: '3.3'
services:
  stirling-pdf:
    container_name: Stirling-PDF-Security
    image: frooodle/s-pdf:latest
    deploy:
      resources:
        limits:
          memory: 4G
    healthcheck:
      test: ["CMD-SHELL", "curl -f http://localhost:8080/api/v1/info/status | grep -q 'UP' && curl -fL http://localhost:8080/ | grep -q 'Please sign in'"]
      interval: 5s
      timeout: 10s
      retries: 16
    ports:
      - "8080:8080"
    volumes:
      - ./stirling/data:/usr/share/tessdata:rw
      - ./stirling/config:/configs:rw
      - ./stirling/logs:/logs:rw
    environment:
      DOCKER_ENABLE_SECURITY: "true"
      SECURITY_ENABLELOGIN: "true"
      PUID: 1002
      PGID: 1002
      UMASK: "022"
      SYSTEM_DEFAULTLOCALE: en-US
      UI_APPNAME: Stirling-PDF
      UI_HOMEDESCRIPTION: 带安全认证的PDF处理工具
      UI_APPNAMENAVBAR: Stirling-PDF
      SYSTEM_MAXFILESIZE: "100"
      METRICS_ENABLED: "true"
      SYSTEM_GOOGLEVISIBILITY: "true"
    restart: on-failure:5

启动安全服务

docker-compose -f docker-compose-security.yml up -d

首次启动后，系统会自动生成默认管理员账户，信息保存在日志文件中。您也可以通过src/main/java/stirling/software/SPDF/config/security/InitialSecuritySetup.java查看初始安全配置逻辑。

启动后访问http://localhost:8080，将显示登录界面：

高级配置：OAuth2单点登录

对于企业环境，Stirling-PDF支持通过OAuth2实现单点登录。以下是集成Google OAuth的示例配置（基于exampleYmlFiles/docker-compose-latest-security-with-sso.yml）：

version: '3.3'
services:
  stirling-pdf:
    container_name: Stirling-PDF-Security
    image: frooodle/s-pdf:latest
    deploy:
      resources:
        limits:
          memory: 4G
    healthcheck:
      test: ["CMD-SHELL", "curl -f http://localhost:8080/api/v1/info/status | grep -q 'UP' && curl -fL http://localhost:8080/ | grep -q 'Please sign in'"]
      interval: 5s
      timeout: 10s
      retries: 16
    ports:
      - "8080:8080"
    volumes:
      - ./stirling/data:/usr/share/tessdata:rw
      - ./stirling/config:/configs:rw
      - ./stirling/logs:/logs:rw
    environment:
      DOCKER_ENABLE_SECURITY: "true"
      SECURITY_ENABLELOGIN: "true"
      SECURITY_OAUTH2_ENABLED: "true"
      SECURITY_OAUTH2_AUTOCREATEUSER: "true"
      SECURITY_OAUTH2_ISSUER: "https://accounts.google.com"
      SECURITY_OAUTH2_CLIENTID: "<YOUR CLIENT ID>.apps.googleusercontent.com"
      SECURITY_OAUTH2_CLIENTSECRET: "<YOUR CLIENT SECRET>"
      SECURITY_OAUTH2_SCOPES: "openid,profile,email"
      SECURITY_OAUTH2_USEASUSERNAME: "email"
      SECURITY_OAUTH2_PROVIDER: "google"
      PUID: 1002
      PGID: 1002
      UMASK: "022"
      SYSTEM_DEFAULTLOCALE: en-US
      UI_APPNAME: Stirling-PDF
      UI_HOMEDESCRIPTION: 带OAuth2认证的PDF处理工具
      UI_APPNAMENAVBAR: Stirling-PDF
      SYSTEM_MAXFILESIZE: "100"
      METRICS_ENABLED: "true"
      SYSTEM_GOOGLEVISIBILITY: "true"
    restart: on-failure:5

OAuth2相关实现代码可参考src/main/java/stirling/software/SPDF/config/security/oauth2/目录下的文件。

轻量级部署：Ultra-Lite版本

如果您的服务器资源有限，可以选择Ultra-Lite版本，它精简了部分功能以减少内存占用（基于exampleYmlFiles/docker-compose-latest-ultra-lite.yml）：

version: '3.3'
services:
  stirling-pdf:
    container_name: Stirling-PDF-Ultra-Lite
    image: frooodle/s-pdf:latest-ultra-lite
    deploy:
      resources:
        limits:
          memory: 1G
    healthcheck:
      test: ["CMD-SHELL", "curl -f http://localhost:8080/api/v1/info/status | grep -q 'UP' && curl -fL http://localhost:8080/ | grep -qv 'Please sign in'"]
      interval: 5s
      timeout: 10s
      retries: 16
    ports:
      - "8080:8080"
    volumes:
      - ./stirling/config:/configs:rw
      - ./stirling/logs:/logs:rw
    environment:
      DOCKER_ENABLE_SECURITY: "false"
      SECURITY_ENABLELOGIN: "false"
      SYSTEM_DEFAULTLOCALE: en-US
      UI_APPNAME: Stirling-PDF-Ultra-lite
      UI_HOMEDESCRIPTION: 轻量级PDF处理工具
      UI_APPNAMENAVBAR: Stirling-PDF-Ultra-lite
      SYSTEM_MAXFILESIZE: "100"
      METRICS_ENABLED: "true"
      SYSTEM_GOOGLEVISIBILITY: "true"
    restart: on-failure:5

Ultra-Lite版本与完整版的主要区别在于移除了OCR和部分高级转换功能，适合对资源要求严格的环境。

自定义配置：环境变量详解

Stirling-PDF提供了丰富的环境变量用于自定义配置，以下是常用变量说明：

环境变量	说明	默认值
`DOCKER_ENABLE_SECURITY`	是否启用安全功能	`false`
`SECURITY_ENABLELOGIN`	是否启用登录认证	`false`
`SYSTEM_MAXFILESIZE`	最大文件上传大小(MB)	`100`
`LANGS`	支持的语言列表	`en_GB,en_US,zh_CN`等
`SYSTEM_DEFAULTLOCALE`	默认语言	`en-US`
`UI_APPNAME`	应用名称	`Stirling-PDF`

完整的配置说明可参考src/main/java/stirling/software/SPDF/model/ApplicationProperties.java。

持久化与数据管理

为确保数据持久化，Stirling-PDF使用以下卷挂载：

/configs: 配置文件存储，对应src/main/java/stirling/software/SPDF/config/
/logs: 日志文件，应用日志可通过src/main/java/stirling/software/SPDF/config/AppConfig.java配置
/usr/share/tessdata: OCR数据，用于OCR功能

建议定期备份这些目录，特别是在升级前。

故障排除与常见问题

服务启动失败

检查日志文件：docker-compose logs -f
确认端口未被占用：netstat -tuln | grep 8080
验证Docker Compose配置：docker-compose config

功能异常

如果某些功能无法使用，可能是对应依赖未安装。完整的依赖列表可查看Dockerfile，其中包含了所有必要的系统组件。

性能优化

根据Dockerfile中的配置，您可以调整以下参数优化性能：

内存限制：根据服务器配置调整memory参数
JVM参数：通过JAVA_TOOL_OPTIONS调整JVM参数
健康检查：根据服务器性能调整健康检查间隔

总结与下一步

通过本文介绍的Docker Compose配置，您可以轻松部署不同需求的Stirling-PDF环境：

基础版：适合个人使用，功能完整
安全版：适合团队使用，带身份验证
Ultra-Lite版：适合资源有限的环境
OAuth2版：适合企业单点登录场景

下一步，您可以：

探索Pipeline功能，自动化PDF处理流程
学习如何添加新语言支持
了解API端点，实现程序集成

所有配置模板文件均可在exampleYmlFiles/目录找到，您可以根据实际需求进行修改和扩展。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考