配置系统

相关源文件

• CONTRIBUTING.md
• DATABASE.md
• DeveloperGuide.md
• HowToAddNewLanguage.md
• HowToUseOCR.md
• src/main/java/stirling/software/SPDF/config/AppConfig.java
• src/main/java/stirling/software/SPDF/config/ConfigInitializer.java
• src/main/java/stirling/software/SPDF/config/EndpointConfiguration.java
• src/main/java/stirling/software/SPDF/controller/web/SecurityWebController.java
• src/main/java/stirling/software/SPDF/controller/web/UploadLimitService.java
• src/main/java/stirling/software/SPDF/model/ApplicationProperties.java
• src/main/resources/settings.yml.template

本文档详细介绍了 Stirling-PDF 的配置系统，解释了设置如何在整个应用程序中加载、管理和应用。它涵盖了配置文件位置、加载过程、可用设置以及如何自定义系统以满足特定需求。

有关特定于部署的配置选项的信息，请参阅 部署配置选项。

配置文件和位置

Stirling-PDF 使用多个配置文件来管理其设置

文件	位置	目的
settings.yml.template	类路径资源	默认设置模板
settings.yml	/configs 目录	应用程序使用的主要配置文件
custom_settings.yml	/configs 目录	用于自定义覆盖的可选文件（自动创建）

主要配置文件（settings.yml）在不存在时会根据模板自动创建。当应用程序更新时，模板中的新属性将被合并到现有配置文件中，以确保兼容性。

来源：src/main/java/stirling/software/SPDF/config/ConfigInitializer.java23-81 src/main/resources/settings.yml.template1-152

配置加载过程

下图说明了应用程序启动期间配置的加载方式

配置加载过程遵循以下步骤

1. ConfigInitializer.ensureConfigExists() 检查 `settings.yml` 文件是否存在
2. 如果不存在，它会通过复制 `settings.yml.template` 来创建该文件
3. 如果存在，它会将现有设置与模板合并，以确保所有必需的属性都存在
4. ApplicationProperties 类将设置文件加载为 `PropertySource`
5. 该 `PropertySource` 被添加到 Spring 的 `Environment` 中
6. 使用配置中的值创建 `ApplicationProperties` bean
7. 各种应用程序组件使用 `ApplicationProperties` bean 来配置自身

来源：src/main/java/stirling/software/SPDF/config/ConfigInitializer.java24-81 src/main/java/stirling/software/SPDF/model/ApplicationProperties.java51-75

配置结构

配置分为几个主要部分，每个部分处理应用程序的不同方面

来源：src/main/java/stirling/software/SPDF/model/ApplicationProperties.java44-581

主要配置部分

下表描述了配置的主要部分

章节	目的	关键属性
安全	身份验证和授权设置	enableLogin, loginMethod, oauth2, saml2
system	通用系统设置	defaultLocale, googlevisibility, customPaths, fileUploadLimit
ui	用户界面定制	appName, homeDescription, languages
endpoints	功能管理	toRemove, groupsToRemove
metrics	应用程序指标设置	enabled
legal	法律文件链接	termsAndConditions, privacyPolicy
premium	高级/企业功能	enabled, key, proFeatures
processExecutor	外部进程执行	sessionLimit, timeoutMinutes

来源：src/main/resources/settings.yml.template13-151

配置应用

配置通过各种组件应用于应用程序的不同部分

来源：src/main/java/stirling/software/SPDF/config/AppConfig.java32-199 src/main/java/stirling/software/SPDF/controller/web/UploadLimitService.java13-54

AppConfig

AppConfig 类根据配置属性创建 Spring bean。这些 bean 然后在整个应用程序中使用以访问配置值。一些关键 bean 包括

来源：src/main/java/stirling/software/SPDF/config/AppConfig.java47-199

EndpointConfiguration

EndpointConfiguration 类管理哪些端点（功能）是启用或禁用的。它维护两个关键数据结构

1. endpointStatuses：将端点名称映射到布尔值，指示它们是否已启用
2. endpointGroups：将组名映射到端点名称集合

可以在配置文件中禁用端点和组

init() 方法定义了相关端点的组，例如“PageOps”、“Convert”、“Security”和“Other”。这允许启用或禁用整个功能类别。

来源：src/main/java/stirling/software/SPDF/config/EndpointConfiguration.java19-303

配置定制

环境变量

可以通过遵循特定命名约定（将属性路径转换为大写并用下划线替换点）的环境变量来覆盖配置设置。

示例

属性	环境变量
security.enableLogin	SECURITY_ENABLELOGIN
ui.appName	UI_APPNAME
system.defaultLocale	SYSTEM_DEFAULTLOCALE

这在 `settings.yml.template` 文件的顶部注释中有所提及

# Do not comment out any entry, it will be removed on next startup                                          
# If you want to override with environment parameter follow parameter naming SECURITY_INITIALLOGIN_USERNAME

Docker 示例

来源：src/main/resources/settings.yml.template9-11

文件上传限制

可以通过 `system.fileUploadLimit` 属性配置文件上传限制

UploadLimitService 解析此值并将其转换为字节

来源：src/main/java/stirling/software/SPDF/controller/web/UploadLimitService.java18-42 src/main/resources/settings.yml.template113

特殊配置区域

安全配置

安全设置控制身份验证和授权

ApplicationProperties 中的 `Security` 类提供了检查活动身份验证方法的方法

来源：src/main/java/stirling/software/SPDF/model/ApplicationProperties.java104-153 src/main/resources/settings.yml.template13-62

UI自定义

UI 设置允许自定义应用程序的外观

Ui 类在未设置自定义值时提供默认值

languages 属性控制 UI 中可用的语言。如果为空，则所有语言都启用。

来源：src/main/java/stirling/software/SPDF/model/ApplicationProperties.java354-375 src/main/resources/settings.yml.template115-119

OCR 配置

对于 OCR 功能，必须配置 Tessdata 文件的路径

这对于 Windows 系统尤其重要，如配置模板注释中所述

# path to the directory containing the Tessdata files. This setting is relevant for Windows systems. For Windows users, this path should be adjusted to point to the appropriate directory where the Tessdata files are stored.

来源：src/main/resources/settings.yml.template93 HowToUseOCR.md95-99

进程执行限制

可以配置外部进程执行的限制

这些设置控制可以同时运行多少个外部工具实例以及在超时之前允许它们运行多长时间。

来源： src/main/resources/settings.yml.template134-151 src/main/java/stirling/software/SPDF/model/ApplicationProperties.java487-579

配置持久化和更新

当模板中添加了新属性时，配置系统会自动更新 settings.yml 文件。这确保了配置始终与应用程序的最新版本保持同步，同时保留用户定义的值。

当应用程序启动时

1. 它会检查 settings.yml 文件是否存在
2. 如果不存在，则从模板创建它
3. 如果存在，它会合并模板中的任何新属性，同时保留现有值
4. 仅当发生更改时，合并的配置才会保存回 settings.yml 文件

此过程确保了在更新到新版本的 Stirling-PDF 时向后兼容。

来源： src/main/java/stirling/software/SPDF/config/ConfigInitializer.java62-69

功能管理

EndpointConfiguration 类提供了一种机制来启用或禁用特定功能（端点）或相关功能组。这对于限制特定部署的功能或禁用依赖于可能未安装的外部工具的功能特别有用。

在初始化过程中，EndpointConfiguration 类

1. 定义相关端点组（例如，“PageOps”、“Convert”、“Security”）
2. 将每个端点关联到一个或多个组
3. 处理配置以确定应禁用哪些端点和组
4. 提供在运行时检查端点是否启用的方法

这允许对应用程序中可用的功能进行精细控制。

来源： src/main/java/stirling/software/SPDF/config/EndpointConfiguration.java114-272 src/main/resources/settings.yml.template121-123

故障排除

常见配置问题

1. 缺少必需属性：如果缺少必需的属性，应用程序可能会启动失败或行为异常。请确保您的 settings.yml 文件包含所有必需的属性。

2. 无效属性值：检查属性值是否是正确的类型（布尔型、字符串、数字）并且在可接受的范围内。

3. 权限问题：确保应用程序对 /configs 目录具有读/写权限。

4. 环境变量优先：请记住，环境变量的优先级高于基于文件的配置。如果您设置了环境变量，它将覆盖 settings.yml 中的值。

5. OCR 路径配置：对于 Windows 用户，必须正确设置 tessdataDir 路径，使其指向包含语言文件的 Tessdata 目录。

6. 文件上传限制：如果文件上传失败，请检查 fileUploadLimit 设置是否包含遵循“数字后跟 KB、MB 或 GB”模式的有效值。

本概述涵盖了 Stirling-PDF 中配置系统的主要方面。有关部署相关的更具体的配置选项，请参阅部署配置选项部分。

来源： DeveloperGuide.md297-306 HowToUseOCR.md5-9