Stirling-PDF 3.2.0 配置参数详解

目标：系统性讲清 Stirling-PDF 3.2.0 的配置体系——settings.yml 全部配置域的结构、每个核心参数的默认值与实测行为、四种修改方式（界面/主配置/自定义配置/环境变量）的优先级关系，并给出生产配置模板。全部参数清单提取自部署环境首次启动生成的 /configs/settings.yml（544 行官方模板，实测逐段核对），关键开关行为（如 metrics.enabled）在部署环境（Ubuntu 22.04、Stirling-PDF 3.2.0，服务地址 http://192.168.146.128:8129）实测验证。部署过程见 《Stirling-PDF 3.2.0 Docker Compose 部署指南》。

一、环境信息

本篇参数实测环境与版本基线如下：

• 服务端：Stirling-PDF 3.2.0（Java/Spring Boot，运行时为 JDK 25，部署形态见部署篇）
• 操作系统：Ubuntu 22.04.4 LTS
• 服务地址：http://192.168.146.128:8129
• 配置目录：/opt/stirling-pdf/stirling-data/configs/（服务端配置与数据库落点，见部署篇第五章）
• 管理账号：admin（界面「系统设置」可见全部配置域）
• 参数权威来源：首次启动自动生成的 /configs/settings.yml 官方模板（本篇逐段引用其默认值与官方注释）；应用版本内 appVersion: 3.2.0
• 部署篇：从零部署与重启命令见 《Stirling-PDF 3.2.0 Docker Compose 部署指南》

💡 说明：Stirling-PDF 的配置是「单文件 + 环境变量覆盖」模型：一切配置都收敛到 settings.yml 一个 YAML 文件的十几个配置域里，部署环境可用环境变量按「路径大写」规则覆盖任意一项。理解这个模型（第三章）比记住单个参数更重要。

二、前置条件

阅读与动手本篇前，确认以下前提：

1. Stirling-PDF 已部署并健康（验证：curl http://192.168.146.128:8129/api/v1/info/status 返回 {"version":"3.2.0","status":"UP"}；部署方法见部署篇）；
2. 拥有 admin 账号（部署时由 SECURITY_INITIALLOGIN_* 注入；界面右上角「设置 → 系统设置」仅管理员可见）；
3. 能访问服务器上的配置目录（第三章的文件级操作需要）；
4. 配置修改后需重启服务生效（除特别注明外），请在业务低峰操作。

三、参数查看与修改方式

3.1 界面查看（管理员）

admin 登录后，右上角「设置」→「系统设置」提供图形化配置面板，覆盖 security、system、storage 等常用配置域，改动保存后立即写回 /configs/settings.yml。适合单个参数的快速调整；批量调整、版本化管理（把配置纳入 git）必须走文件方式（3.2/3.3 节）。

3.2 主配置文件 settings.yml

首次启动时服务在 /configs 生成带完整官方注释的模板文件。查看：

head -11 /opt/stirling-pdf/stirling-data/configs/settings.yml

实测回显：

#############################################################################################################
#                                         Welcome to settings file from                                     #
#                      ____ _____ ___ ____  _     ___ _   _  ____       ____  ____  _____                   #
#                     / ___|_   _|_ _|  _ \| |   |_ _| \ | |/ ___|     |  _ \|  _ \|  ___|                  #
#                      ___) || |  | || |_) | |    | || |\  | |_| |_____|  __/| |_| |  _|                    #
#                     |____/ |_| |___|_| \_\_____|___|_| \_|\____|     |_|   |____/|_| \_\____|_| |____|    #
#                                                                                                           #
# 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 #
#############################################################################################################

模板头两条规则就是 settings.yml 的使用铁律：

1. 不要注释掉任何条目——注释掉的条目会在下次启动被删除（服务按「完整模板 + 覆盖值」模型管理该文件，注释即「删除此键」）。想临时停用某项，把值改成默认值或 false，不要加 #；
2. 环境变量覆盖的命名规则：配置路径转大写、分隔点换下划线，如 security.initialLogin.username → SECURITY_INITIALLOGIN_USERNAME（部署篇 compose 用的正是这条规则）。

查看某个配置域（以 security 为例）：

sed -n '/^security:/,/^premium:/p' /opt/stirling-pdf/stirling-data/configs/settings.yml | head -22

实测回显（节选）：

security:
  honorOwnerPasswords: true # Require the permissions password for restricted PDF actions; opening passwords are always required.
  enableLogin: true # set to 'true' to enable login
  ssoAutoLogin: false
  loginAttemptCount: 5 # lock user account after 5 tries; when using e.g. Fail2Ban you can deactivate the function with -1
  loginResetTimeMinutes: 120 # lock account for 2 hours after x attempts
  loginMethod: all # Accepts values like 'all' and 'normal'(only Login with Username/Password), 'oauth2'(only Login with OAuth2) or 'saml2'(only Login with SAML2)
  initialLogin:
    username: "" # initial username for the first login
    password: "" # initial password for the first login

3.3 自定义配置 custom_settings.yml（推荐落点）

/configs/custom_settings.yml 首次启动生成时为空文件（实测 stat -c%s 为 0 字节），它与 settings.yml 合并生效且升级时不会被官方模板覆盖，是把「自己的改动」与「官方模板」分离的推荐落点。写法就是普通 YAML 片段，只需包含要覆盖的域和键。

实测：用 custom_settings.yml 覆盖 metrics.enabled 并验证生效。写入配置：

printf 'metrics:\n  enabled: false\n' > /opt/stirling-pdf/stirling-data/configs/custom_settings.yml
cat /opt/stirling-pdf/stirling-data/configs/custom_settings.yml

实测回显：

metrics:
  enabled: false

重启服务后验证（metrics.enabled 控制 /api/v1/info/* 信息接口的开关，健康探测端点 /api/v1/info/status 不受影响）：

curl -s -w '\nHTTP %{http_code}\n' -H "X-API-KEY: <你的APIKey>" http://192.168.146.128:8129/api/v1/info/uptime
curl -s -w '\nHTTP %{http_code}\n' http://192.168.146.128:8129/api/v1/info/status

实测回显（enabled: false 后信息接口被禁用，健康探测保留）：

This endpoint is disabled.
HTTP 403
{"version":"3.2.0","status":"UP"}
HTTP 200

改回 enabled: true 并重启后复测（恢复开放，uptime 为重启后时长）：

0d 0h 0m 32s
HTTP 200

💡 说明：<你的APIKey> 为管理员在界面「账户设置」生成的 API 密钥（API 认证全流程见 《Stirling-PDF 3.2.0 API 使用详解》）。

3.4 环境变量覆盖

部署时用环境变量覆盖任意配置项（命名规则见 3.2 节）。适合「部署即定死」的参数：初始账号、界面语言、遥测开关、JVM 参数等。部署篇 compose 实测注入了五个变量（SYSTEM_DEFAULTLOCALE、SYSTEM_ENABLEANALYTICS、SECURITY_INITIALLOGIN_USERNAME/PASSWORD、JAVA_CUSTOM_OPTS），全部生效。

3.5 三层来源的优先级与生效方式

四种修改方式按优先级从高到低：环境变量 > custom_settings.yml / settings.yml（两文件合并，同一键冲突时 custom_settings.yml 生效）> 界面修改（本质是写回 settings.yml）。除界面修改实时保存外，文件与环境变量的改动需重启服务生效；SECURITY_INITIALLOGIN_* 仅在数据库首次初始化时读取，之后修改不追溯已有账号。

四、参数总览

settings.yml 按配置域组织（YAML 顶层键），3.2.0 完整域清单与职责如下（均实测存在于本环境 settings.yml）：

关键解读：日常运维 90% 的调整集中在 security、system、storage、processExecutor 四个域（5.1–5.5 节详解）；aiEngine/mcp/cluster 是 3.2 架构新域，默认全部关闭（5.6 节概览）。

五、核心参数分类详解

5.1 security：登录与账号安全

登录体系核心参数（默认值即实测文件值）：

💡 技术拓展：Web 应用的登录认证存储方案对比——

方案	原理	适用
内置用户库（默认）	用户/密码哈希存内置数据库	无企业 IdP 的自托管
OAuth2/OIDC	对接 Keycloak/Google/GitHub 等 IdP	已有统一身份源
SAML2	企业级 SSO 协议（Enterprise 许可）	大型企业

Stirling-PDF 默认用内置用户库（本方案），OAuth2 在社区版即可启用（security.oauth2.enabled: true + provider 配置），SAML2 仅企业版。

OAuth2 最小启用示例（以 Keycloak 为例，写入 custom_settings.yml）：

security:
  oauth2:
    enabled: true
    issuer: https://keycloak.example.com/realms/master
    clientId: stirling-pdf
    clientSecret: "替换为你的客户端密钥"
    autoCreateUser: true
    provider: keycloak

5.2 security.jwt 与签名验证（validation/timestamp）

JWT 会话参数（默认值实测）：security.jwt.tokenExpiryMinutes: 1440（Web 端访问令牌 1 天）、desktopTokenExpiryMinutes: 43200（桌面端 30 天）、allowedClockSkewSeconds: 60、refreshGraceMinutes: 15。官方注释标注 JWT 机制仍在开发中，生产保持默认即可。

PDF 数字签名验证的信任链参数（security.validation.*）决定了「验证签名」功能的信任基础，默认值：

时间戳服务：security.timestamp.defaultTsaUrl 默认 http://timestamp.digicert.com（RFC 3161 TSA），customTsaUrls 可追加内部 TSA 供用户在界面选择。

5.3 system：运行行为

system 域高频参数（默认值实测）：

HTML 处理的 URL 安全（system.html.urlSecurity.*，默认 MEDIUM 档）：阻止内网地址（RFC 1918）、localhost、链路本地地址、云元数据端点（169.254.169.254）及 .local/.internal/.corp/.home 伪 TLD，可用 allowedDomains 白名单放行指定域名。这组默认值就是 URL→PDF 类 SSRF 风险的纵深防御，建议不动。

5.4 system.tempFileManagement 与 databaseBackup

临时文件治理（默认值实测）：

数据库自动备份一行搞定：system.databaseBackup.cron: "0 0 0 * * ?"（每日 00:00），备份产物落在 /configs/backup/。自建数据库连接（system.datasource.*）默认走内置 H2（启动日志 Using default H2 database），enableCustomDatabase: true 仅供企业版外接 PostgreSQL。

5.5 processExecutor：外部引擎会话池

Stirling-PDF 对每个外部引擎维护独立会话池，processExecutor.sessionLimit.* 控制并发进程数上限（官方注释：每个额外 LibreOffice 会话约 50MB 常驻内存），timeoutMinutes.* 控制单次处理超时。实测默认值：

调参要点：多人团队遇到「Office 转换排队慢」时优先调大 libreOfficeSessionLimit（每加 1 个预算 50MB 内存，且需对应调大部署内存限制）；单用户批处理 OCR 慢时调大 tesseractSessionLimit；反向地，2GB 小内存机器可把 ghostscriptSessionLimit 等下调到 2。processExecutor.autoUnoServer: true（默认）表示 LibreOffice 会话由服务按 libreOfficeSessionLimit 自动池化。

5.6 storage：文件存储与配额

5.7 ui / endpoints / metrics / toolRecommendations：界面与功能开关

5.8 premium 与企业特性（audit 审计）

premium.enabled: false、premium.key 为全零占位（未授权实测值）。社区版下与许可相关的企业特性域保持默认即可；其中审计参数默认值值得了解（premium.enterpriseFeatures.audit.*）：level: 2（STANDARD：基础操作 + 用户行为）、retentionDays: 90、captureFileHash/capturePdfAuthor: false（开启各增加 50–200ms/文件）。审计写入内置数据库，社区版可记录不可导出，导出为企业版能力。

5.9 3.2 新特性配置域概览（aiEngine / mcp / cluster / policies）

四个默认关闭的新域，选型认知需要知道它们的存在与开启前提：

docparse.enabled: true 与 formDetection.enabled: true 默认开启（文档理解与表单识别），不需要时在 custom_settings.yml 置 false 可减少后台模型加载。

5.10 AutomaticallyGenerated：自动生成域（禁手改）

文件末尾的自动生成段（本环境实测值）：

AutomaticallyGenerated:
  key: ebb6ccd8-aacb-4b29-992c-aed1cc8e2e82 # AES key for stored metadata. Differs per node = one node cannot decrypt another's rows.
  UUID: 5dadb827-0bbd-430d-b56b-6da57fb23908 # Part of the licence-seat HMAC. Differs per node = peers reject each other's seat count.
  appVersion: 3.2.0

要点解读：key 是存储元数据的 AES 加密密钥、UUID 参与许可席位校验，首次启动生成后不可更改、必须随 /configs 备份；集群部署时官方注释要求各节点携带相同值（经环境变量 AUTOMATICALLYGENERATED_KEY/UUID 注入），否则节点间互不认数据。

六、生产配置模板

以下为「4GB 内存、多用户团队、内网部署」场景的推荐配置，写入 /configs/custom_settings.yml（与部署篇 compose 的环境变量互补；环境变量已定的项不必重复）：

security:
  loginAttemptCount: 5          # 失败 5 次锁定
  loginResetTimeMinutes: 120    # 锁 2 小时
  xFrameOptions: DENY           # 禁止被内嵌

system:
  defaultLocale: zh-CN          # 界面中文
  enableAnalytics: false        # 关闭遥测
  googlevisibility: false       # 不被搜索引擎收录
  enableUrlToPDF: false         # 保持关闭（SSRF 风险，官方标注 INTERNAL ONLY）
  fileUploadLimit: 500MB        # 单文件上传限制（按业务定）
  corsAllowedOrigins: ["https://pdf.example.com"]   # 锁定 CORS 来源，勿留空

metrics:
  enabled: true                 # 保留信息类 API（监控探测用）

toolRecommendations:
  enabled: true
  retentionDays: 90             # 用量统计保留 90 天（默认 180，按合规要求调）

storage:
  quotas:
    maxStorageMbPerUser: 2048   # 单用户 2GB 配额
    maxStorageMbTotal: 20480    # 全站 20GB
    maxFileMb: 200              # 单存档文件 200MB

processExecutor:
  sessionLimit:
    libreOfficeSessionLimit: 2  # 团队 Office 转换并发（每会话约 50MB 内存）
    tesseractSessionLimit: 2
  timeoutMinutes:
    libreOfficetimeoutMinutes: 30
    tesseractTimeoutMinutes: 30

endpoints:
  groupsToRemove: []            # 按需裁剪功能组，如 ['DeveloperTools']

适用场景与配套说明：该模板面向 20 人以内团队、4GB 内存限制（部署篇 mem_limit: 4g）、NVMe 磁盘；JVM 堆仍由部署篇的 JAVA_CUSTOM_OPTS（-Xms256m -Xmx512m）与动态内存分档管理，本模板不含 JVM 参数；sessionLimit 调大后请同步核对内存预算（每加 1 个 LibreOffice 会话 +50MB）。写入后重启服务，按 3.3 节方法逐项验证（如 storage 配额在界面「存储」页可见）。

七、常见问题

Q1：改了 settings.yml 重启后改动消失了？

三种可能：改动写成了注释（模板头规则「注释掉的条目下次启动被删除」）；环境变量同名覆盖（优先级更高，printenv 核对部署注入的变量）；改在了错误文件（界面保存写回的是 settings.yml，custom_settings.yml 冲突时以 custom_settings.yml 为准）。正确姿势：改动统一写 custom_settings.yml（3.3 节），并用同节的 403/200 探针法验证生效。

Q2：settings.yml 手滑改坏了，服务起不来？

官方模板可随时重建：把损坏的 settings.yml 移走（mv settings.yml settings.yml.bak），重启服务会按默认模板重新生成；你的自定义改动若在 custom_settings.yml 中则不受影响。数据库文件（.mv.db）与 settings.yml 互不影响，用户数据不会因此丢失。

Q3：enableLogin: false 后哪些行为变了？

匿名模式：任何人打开即用全部功能，无用户/团队/文件历史；官方同时把 xFrameOptions 自动置为 DISABLED、toolRecommendations 停止记录（无用户可归属）。个人单机可用，团队场景不建议。

Q4：信息类接口 403（This endpoint is disabled.）？

metrics.enabled: false 所致（3.3 节实测行为：uptime/load/requests 403，status 保留）。检查 custom_settings.yml 是否残留该开关，改回 true 重启恢复。

Q5：上传大文件报错？

两层限制：system.fileUploadLimit（settings 层，默认不限）与单请求 2000MB 硬上限（Spring multipart，启动日志实测 Using default multipart file upload limit: 2000MB）。再往外还有存储配额（storage.quotas.maxFileMb）与反向代理的 client_max_body_size（如有）。逐层核对。

Q6：URL 转 PDF 找不到入口？

默认关闭（system.enableUrlToPDF: false），官方因 SSRF 类安全问题标注仅内部使用。确需开启时在 custom_settings.yml 置 true，并保持 5.3 节 html.urlSecurity 的 MEDIUM 档（默认）作为防护，且实例只在内网暴露。

八、参考链接

• 官方文档 Configuration：https://docs.stirlingpdf.com（Server → Configuration/Settings，配置域官方说明，查询日期 2026-10-22）
• 官方文档 Upgrading/Settings changes：https://docs.stirlingpdf.com（V1→V3 的 settings 结构变更说明）
• 官方仓库 settings.yml 模板：https://github.com/Stirling-Tools/Stirling-PDF（各域默认值第一手出处）
• 本专栏系列文档：《Stirling-PDF 3.2.0 介绍与选型指南》、《Stirling-PDF 3.2.0 Docker Compose 部署指南》（环境变量注入与重启命令）、《Stirling-PDF 3.2.0 API 使用详解》（API Key 生成与信息接口实测）