Gotenberg 8 配置参数详解

目标：本文系统梳理 Gotenberg v8.39.0 的命令行参数体系（约 90 个参数，覆盖 API、Chromium、LibreOffice、PDF 引擎、Webhook、监控日志六大模块），给出每个参数的环境变量等价写法与真实默认值，并以实测演示「查看、修改、验证」的完整闭环。全部参数清单来自服务内 gotenberg --help 实测导出，运行时配置来自 /debug 路由实测回显；部署步骤见 《Gotenberg Docker Compose 部署实战》，各参数对应的 API 行为实测见 《Gotenberg 常用命令与运维实战（核心篇）》。

一、环境信息

本章说明本文参数体系的取证环境，保证读者按相同版本对照。

• 软件版本：Gotenberg v8.39.0（2026-10-28 实查的最新稳定版）
• 内嵌引擎版本（/debug 路由实测回显）：Chromium 156.0.8078.47、LibreOffice 26.8.1.1、qpdf 12.2.0、pdftk 3.3.3、exiftool 13.25
• 操作系统：Ubuntu 22.04（x86_64）
• 参数总量：gotenberg --help 实测导出 106 行帮助文本、约 90 个参数
• 官方参数文档：https://gotenberg.dev/docs/configuration（2026-10-28 对照核验）
• 本文约定：每个参数同时给出「命令行参数」与「环境变量」两种写法，二者完全等价，同一参数不可同时以两种方式赋予不同值

💡 说明：Gotenberg 无配置文件概念，一切配置走命令行参数或环境变量。这与 Nginx/Redis 等「配置文件驱动」的服务差异很大——配置即启动参数，改动必然伴随重启。

二、前置条件

阅读与实操本文需满足以下条件，逐项确认后参数修改才能落地验证。

1. 服务已部署并可访问：已有运行中的 Gotenberg 实例（部署过程见姊妹篇），且知道其管理方式（本文以命令行与进程管理视角书写，容器化部署者在 compose 的 environment/command 段落做等价配置）。
2. 可执行 gotenberg --help：二进制随官方发布件分发，能在服务器上直接调用；无法登机时也可通过开启 /debug 路由远程查看生效配置（见第三章）。
3. 验证用客户端：curl 可用，用于探活与配置验证。

# 确认参数体系可查看（help 输出首尾节选）
gotenberg --help | head -6

实测回显：

Usage of gotenberg:
      --api-bind-ip string                              Set the IP address the API should bind to for incoming connections
      --api-body-limit string                           Set the body limit for multipart/form-data requests - it accepts values like 5MB, 1GB, etc
      --api-correlation-id-header string                Set the header name to use for identifying requests (default "Gotenberg-Trace")
      --api-disable-debug-route-telemetry               Disable telemetry for the debug route (default true)
      --api-disable-download-from                       Disable the download from feature

⚠️ 注意：Gotenberg 没有 --version 参数（实测 gotenberg --version 返回 unknown flag: --version）。版本确认请用 API 路由 curl http://localhost:3000/version。

三、参数查看与修改方式

本节讲清「当前生效值去哪看、改了如何生效」两个运维闭环，先看后改，改必验证。

3.1 查看方式一：命令行帮助

# 全量参数清单（约 106 行）
gotenberg --help

帮助文本每行一个参数，格式为 --参数名 类型 说明 (default 默认值)。有默认值的参数会显式标注，如 --api-timeout duration ... (default 30s)；布尔开关不标注默认值的均为 false。这是离线环境下最快的参数手册。

3.2 查看方式二：/debug 运行时配置导出

/debug 路由输出当前真实生效的全部配置（含模块版本与逐参数值），是排查「配置到底生效没有」的权威手段。该路由默认关闭，需先开启：

# 以环境变量方式开启 debug 路由后重启服务
API_ENABLE_DEBUG_ROUTE=true gotenberg
# 随后导出运行时配置（JSON，实测约 5.5KB）
curl -s http://localhost:3000/debug

实测回显（节选，完整输出以 python3 -m json.tool 美化后展示首段）：

{
    "version": "8.39.0",
    "timezone": "UTC",
    "architecture": "amd64",
    "modules": [
        "api", "chromium", "exiftool", "libreoffice", "libreoffice-api",
        "libreoffice-pdfengine", "pdfcpu", "pdfengines", "pdftk",
        "prometheus", "qpdf", "webhook"
    ],
    "modules_additional_data": {
        "chromium": { "version": "Chromium 156.0.8078.47 built on Debian GNU/Linux 13 (trixie)" },
        "exiftool": { "version": "13.25" },
        "libreoffice-api": { "version": "LibreOffice 26.8.1.1 680(Build:1)" },
        "pdftk": { "version": "pdftk port to java 3.3.3 a Handy Tool for Manipulating PDF Documents" },
        "qpdf": { "version": "qpdf version 12.2.0" }
    },
    "flags": {
        "api-bind-ip": "",
        "api-body-limit": "",
        "api-correlation-id-header": "Gotenberg-Trace",
        "api-enable-debug-route": "true",
        "api-port": "3000",
        "api-timeout": "30s"
    }
}

输出解读：modules 列出已加载模块；modules_additional_data 给出各内嵌引擎的精确版本（排障时核对引擎行为差异的关键依据）；flags 段逐参数列出当前生效值——这里看到什么就是什么，与猜测默认值相比，以它为准。

⚠️ 注意：/debug 会暴露完整运行时配置，仅建议在内网排障场景临时开启，排查完毕后关闭并重启（关闭后该路由实测返回 404）。

3.3 修改方式与生效规则

两种写法完全等价，选择一种贯穿即可：

# 写法一：命令行参数（key=value 等号连接）
gotenberg --api-timeout=60s --api-port=3000

# 写法二：环境变量（参数名去连字符转大写）
API_TIMEOUT=60s API_PORT=3000 gotenberg

命名映射规则实测核对：--api-timeout → API_TIMEOUT、--chromium-max-concurrency → CHROMIUM_MAX_CONCURRENCY、--pdfengines-merge-engines → PDFENGINES_MERGE_ENGINES。唯一例外是 Basic 认证的两个凭据变量，带 GOTENBERG_ 前缀：GOTENBERG_API_BASIC_AUTH_USERNAME、GOTENBERG_API_BASIC_AUTH_PASSWORD（来源：--help 中 --api-enable-basic-auth 的说明原文）。

生效规则：参数在进程启动时读取一次，运行中不热加载——改配置 = 改启动参数 + 重启进程。修改后按 3.2 的 /debug 回读验证，或直接用行为验证（如调大 API_TIMEOUT 后发起一个原先会超时的请求）。

💡 说明：布尔开关参数（如 --api-enable-basic-auth）在命令行写法中不带值即为 true；环境变量写法必须显式给 "true"/"false" 字符串。二者混用且值冲突时，以实际启动环境为准并务必用 /debug 回读确认。

四、参数总览

本节按模块给出参数全景地图，先建立整体认知，再进入逐类详解。

表格解读：六成以上的参数集中在 API 与 Chromium 两个模块，也是调优的主战场；PDF 引擎参数虽然条目多，但结构高度一致（每个功能一组「引擎选择」参数）；LibreOffice 与 Webhook 参数最精简。日常运维中真正常改的约十几个，其余保持默认即可。

五、核心参数分类详解

本章按模块逐类详解参数。每类先给核心参数表（含真实默认值），再对易错项展开。

5.1 API 服务参数（api-*）

API 模块是所有请求的入口，这组参数决定端口、时限、认证与请求体边界。

关键项展开：

• --api-timeout 是全局限流阀：Chromium 渲染慢网页、LibreOffice 转大文档都受它约束。实测默认值下，一个指向不可达地址的转换请求恰好在 30.0 秒返回 503 与提示「The request exceeded the time limit. Increase it with --api-timeout, or reduce the workload.」。生产环境建议结合业务最慢转换调定，并为慢任务改走 Webhook 异步。
• --api-body-limit 在 8.38.0 后从「解析后表单大小」改为「原始请求体大小（含 multipart 边界与头）」，同值的实际约束更严格，迁移版本时注意口径变化。
• 出站过滤三件套（allow-list / deny-private-ips / deny-public-ips）同时适用于 downloadFrom 取件、Chromium 导航与 Webhook 回调（各自模块同名参数），是防 SSRF 的核心开关。默认放行一切，面向不可信输入的部署建议至少开启 deny-private-ips。

💡 技术拓展：HTTP 服务鉴权不止 Basic 一种，Gotenberg 内置的两种方式对比——

方式	机制	适用
Basic Auth	用户名密码经 Authorization 头（Base64）传输，配合 HTTPS 使用	内网服务间调用、快速接入
OIDC Bearer Token	JWT 校验（issuer/audience/JWKS），无状态验签	已有统一身份体系、需细粒度授权

两者互斥（--api-enable-oidc-auth 说明原文：mutually exclusive with basic authentication）。Gotenberg 无内置用户体系与业务级授权，更细的访问控制应由网关或调用方承担。本文实测采用 Basic 认证（演示账号 admin，密码 q1w2e3r4），开启后 /health 仍豁免、其余路由实测返回 401，认证行为验证见部署篇。

5.2 Chromium 模块参数（chromium-*）

Chromium 模块承载 URL/HTML/Markdown 转换与截图，这组参数管理它的并发、生命周期与出站安全。

关键项展开：

• 并发上限 6 是浏览器硬约束：官方配置文档明确「A Chromium browser can handle up to 6 parallel operations」，把 --chromium-max-concurrency 设为大于 6 的值没有意义。吞吐不足时的官方建议是横向加实例（负载均衡后面多跑几份 Gotenberg），而非调大这个数字。
• --chromium-restart-after 默认 100：浏览器长跑会积累内存，每 100 次转换自动重启是官方平衡点（8.15.2 之前的版本重启会产生僵尸进程，升级旧版时注意）。
• 默认黑名单 ^file:(?!//\/tmp/).*：允许服务内部 /tmp 的 file:// 访问（上传文件落盘位置），其余 file:// 全拒——这是防「用 file:// 探测服务器文件系统」的兜底。需要访问其他路径时用 allow-list 精确放行，不要直接清空黑名单。

5.3 LibreOffice 模块参数（libreoffice-*）

LibreOffice 模块负责 Office 文档转换，参数最少但决定 Office 线的吞吐与稳定性。

关键项展开：LibreOffice 单实例串行是架构事实（官方文档：due to a lock mechanism, a LibreOffice instance cannot execute parallel operations），因此没有并发参数、只有队列参数。--libreoffice-restart-after 默认 10（比 Chromium 的 100 保守得多），因为 LibreOffice 进程在持续转换中更容易积累状态——Office 转换量大的部署若发现内存爬升，可把它调小。8.34.0 起文档内链的 file:// 取件一律丢弃（上传文件不作为信任源），白名单只管 HTTP(S) 外链。

5.4 PDF 引擎参数（pdfengines-*）

PDF 引擎模块把 qpdf、pdfcpu、pdftk、exiftool 四个引擎按功能分配，每个 PDF 功能都有独立的引擎选择参数。

结构规则：每个功能一对参数——--pdfengines-<功能>-engines（引擎与优先顺序，列表）与全局唯一的并发参数。引擎列表按序尝试：首个引擎不支持该请求时自动落到下一个；留空表示该功能用全部可用引擎。

关键项展开：默认并发 1 意味着 PDF 后处理完全串行——大批量合并/加密场景这是首要瓶颈，把 --pdfengines-max-concurrency 提到 4~8（视内存）是最直接的吞吐手段。引擎选型差异举例：合并用 qpdf 与 pdfcpu 输出基本无感差异，但加密的加密强度与兼容性以 qpdf（实测产出 AES-256，/V 5 /R 6）为佳；元数据读写只有 exiftool 一个引擎可选，实测其版本为 13.25。若想固化某个引擎避免行为漂移，把对应列表收窄为单引擎即可。

5.5 Webhook 模块参数（webhook-*）

Webhook 模块把同步转换转为异步回调，这组参数控制回调的安全边界与重试节奏。

关键项展开：重试触发条件是连接错误、429 与 501 以外的 5xx；其余 4xx 不重试（官方文档明确）。官方给出最坏场景总时限公式：WEBHOOK_CLIENT_TIMEOUT × (WEBHOOK_MAX_RETRY + 1) + WEBHOOK_RETRY_MAX_WAIT × WEBHOOK_MAX_RETRY，默认值下为 270 秒——评估异步链路超时预算时按此公式核算。面向不可信调用方的部署建议开启 --webhook-deny-private-ips，防诱导服务向内网回调。

5.6 监控与日志参数（prometheus-* / log-*）

这组参数控制可观测性行为，量少但排查问题天天用。

关键项展开：指标端点实测输出 gotenberg_chromium_requests_queue_size（排队长度）、gotenberg_chromium_restarts_count（浏览器重启次数）等，是容量与健康的直接信号——排队持续增长说明并发不足，重启计数异常增长提示转换内容触发崩溃。排障时把 --log-level 调为 debug 可看到每个请求的引擎调用细节，生产长期运行建议保持 info。

5.7 全局参数（gotenberg-*）

三个全局参数影响进程级行为，一目了然。

关键项展开：--gotenberg-graceful-shutdown-duration 在滚动升级时很重要——默认 30 秒给在途请求收尾，配合编排平台的宽限期（termination grace period）使用时，两边取值应对齐（编排侧不小于此值），避免在途转换被硬杀。

六、生产配置模板

本节给出两套可直接套用的生产配置（环境变量形式），按资源与场景二选一，落到启动环境或编排平台的 environment 段均可。

模板一：中小规模通用型（4GB 内存、转换峰值每分钟数十次、内网可信调用方）

# ---- API ----
API_TIMEOUT=60s                 # 慢转换容忍；超时错误若常见再逐步上调
API_BODY_LIMIT=50MB             # 防异常大包
API_ENABLE_BASIC_AUTH=true      # 开启接入认证
GOTENBERG_API_BASIC_AUTH_USERNAME=admin
GOTENBERG_API_BASIC_AUTH_PASSWORD=q1w2e3r4
# ---- 引擎预热与生命周期 ----
CHROMIUM_AUTO_START=true        # 冷启动敏感场景预热浏览器
LIBREOFFICE_AUTO_START=true
CHROMIUM_RESTART_AFTER=100      # 保持默认防泄漏
LIBREOFFICE_RESTART_AFTER=10
# ---- PDF 后处理并发 ----
PDFENGINES_MAX_CONCURRENCY=4    # 合并/加密等吞吐瓶颈的主调节项
# ---- 可观测 ----
LOG_LEVEL=info
PROMETHEUS_COLLECT_INTERVAL=5s

适用说明：60 秒请求时限覆盖绝大多数网页与文档转换；PDF 后处理并发提到 4，利用 4GB 内存余量换取合并/加密吞吐；两个引擎预热消除首请求冷启动延迟。

模板二：不可信输入加固型（面向上传内容不可信的场景，在模板一基础上叠加）

API_DOWNLOAD_FROM_DENY_PRIVATE_IPS=true   # 远程取件禁内网
CHROMIUM_DENY_PRIVATE_IPS=true             # 浏览器导航禁内网
LIBREOFFICE_DENY_PRIVATE_IPS=true          # Office 外链禁内网
WEBHOOK_DENY_PRIVATE_IPS=true              # 回调禁内网
CHROMIUM_MAX_QUEUE_SIZE=50                 # 队列封顶防打满
LIBREOFFICE_MAX_QUEUE_SIZE=20
CHROMIUM_DISABLE_JAVASCRIPT=false          # 按需：纯静态模板可置 true 进一步收缩攻击面

适用说明：四路 DENY_PRIVATE_IPS 构成 SSRF 基线防护；队列上限让过载快速失败而非无限堆积。若调用方可信且内网互通是必需场景（如回调到内网接收器），改用 allow-list 精确放行目标地址而非关闭防护。

💡 说明：模板中的演示凭据仅用于快速上手。生产环境凭据应从密钥管理系统注入（环境变量注入时避免落入日志）；Gotenberg 侧则建议叠加网关层 HTTPS，Basic 认证明文凭据才不会在链路上裸奔。

七、常见问题

本章沉淀参数使用中的高频坑位，均来自实测或官方文档明确记载。

Q1：参数设了但好像没生效？

按顺序排查：确认没有同一参数「命令行与环境变量」双写冲突；重启是否真的执行（参数仅启动时读取，不热加载）；用 /debug 路由回读生效值（开启方式见 3.2，flags 段即权威答案）。

Q2：--chromium-max-concurrency 调到 12 为什么没有提升并发？

浏览器硬上限 6（官方文档明确 Chromium supports up to 6）。调大该值不会突破浏览器能力，吞吐提升请横向扩实例。

Q3：Basic 认证开启后健康检查为什么不需要密码？

设计如此：/health 豁免认证以兼容负载均衡与编排平台探针（实测未带凭据访问 /health 返回 200，而 /version 与转换路由返回 401）。若安全基线要求全路由认证，可在网关层对 /health 做来源限制。

Q4：升级到 8.29 之后日志里出现 deprecated 提示？

--api-trace-header 已由 --api-correlation-id-header 取代，--api-disable-health-check-logging 由 --api-disable-health-check-route-telemetry 取代（来源：官方配置文档的版本注记）。旧参数仍兼容但应迁移。

Q5：gotenberg --version 报 unknown flag？

正常现象，该命令没有版本参数（实测返回 unknown flag: --version）。版本确认用 API：curl http://localhost:3000/version，或看启动日志横幅的 Version: 行。

Q6：PDF 合并高峰期很慢，调哪个参数？

--pdfengines-max-concurrency（默认 1，串行）。上调至 4~8 可显著提升合并/加密/元数据等 PDF 后处理吞吐；注意它对 LibreOffice 转换线路无效，Office 转换慢只能扩实例。

八、参考链接

1. 官方配置文档（参数与环境变量权威来源）：https://gotenberg.dev/docs/configuration
2. 出站 URL 过滤（allow-list/deny 体系详解）：https://gotenberg.dev/docs/outbound-url-filtering
3. /debug 系统路由文档：https://gotenberg.dev/docs/system/debug
4. /version 版本路由文档：https://gotenberg.dev/docs/system/version
5. 本文实测环境对应的部署过程：《Gotenberg Docker Compose 部署实战》
6. 参数对应的 API 行为实测：《Gotenberg 常用命令与运维实战（核心篇）》
7. 组件认知与选型：《Gotenberg 介绍与选型指南》