Gotenberg 8 API 路由与运维实战

目标：本文是 Gotenberg 专栏的核心篇，在 v8.39.0 实例上对全部主力 API 路由做真实调用实测——HTML/URL/Markdown/Office 转 PDF、PDF 合并、PDF/A 归档转换、元数据读写、加密、水印、拆分、Webhook 异步回调，每条命令均附真实响应回显，并沉淀中文渲染、超时、参数陷阱等一线排障实录。前置阅读：《Gotenberg 介绍与选型指南》、《Gotenberg Docker Compose 部署实战》；参数逐项含义见《Gotenberg 配置参数详解》。

一、环境信息

本章列出实测环境与测试素材，保证回显可复现。

服务版本：Gotenberg v8.39.0（/version 路由实测确认），内嵌 Chromium 156.0.8078.47、LibreOffice 26.8.1.1、qpdf 12.2.0、pdftk 3.3.3、exiftool 13.25（/debug 路由实测确认）
服务地址：http://localhost:8130（映射自服务默认端口 3000）
操作系统：Ubuntu 22.04（x86_64），curl 7.81.0
测试素材（均为本地自造，可复现）：
- invoice.html：中文发票样式 HTML（UTF-8 编码，标题「项目验收单」）
- notes.md：中文 Markdown 值班手记 + index.html 包装模板
- report.docx / budget.xlsx：自造 OOXML 文档（含中文表格）
- 转换产物：html-out.pdf、url-out.pdf、md-out.pdf、docx-out.pdf、xlsx-out.pdf、merged.pdf 等
默认约定：除特别说明外，所有路由均为 POST、请求体 multipart/form-data、响应为二进制文件流

💡 说明：Gotenberg 每个响应都带 Gotenberg-Trace 响应头（默认值，可经 --api-correlation-id-header 改名），值为本次请求的唯一关联 ID——排障时拿它与日志对账是标准动作。

二、前置条件

开始实测前需确认服务就绪与素材就位，逐项核对可避免无效报错。

服务健康：

# 健康检查：整体与两个引擎状态
curl -s http://localhost:8130/health

实测回显：

{"status":"up","details":{"chromium":{"status":"up","timestamp":"2026-10-28T05:08:50.01821323Z"},"libreoffice":{"status":"up","timestamp":"2026-10-28T05:08:50.018209691Z"}}}

版本确认：

curl -s http://localhost:8130/version

实测回显：

8.39.0

素材目录：所有测试文件位于工作目录，后续命令均在该目录执行。

# 素材清单
ls -la invoice.html index.html notes.md report.docx budget.xlsx

实测回显：

-rw-r--r-- 1 root root 1216 Oct 28 13:12 budget.xlsx
-rw-r--r-- 1 root root  894 Oct 28 13:02 index.html
-rw-r--r-- 1 root root 1241 Oct 28 13:02 invoice.html
-rw-r--r-- 1 root root  895 Oct 28 13:12 notes.md
-rw-r--r-- 1 root root 1135 Oct 28 13:12 report.docx

⚠️ 注意：Gotenberg 处理的是「上传的文件」而非「服务器本地路径」（Markdown 模板中的 {{toHTML}} 引用也只认同请求内上传的文件），测试前务必把素材文件备齐在可上传位置。

三、转换路由实测

本章覆盖四条核心转换路由，每条给出调用命令、真实回显与结果验证。

3.1 HTML 转 PDF

HTML 转换的表单文件文件名必须为 index.html（实测确认，排障过程见排障实录 8.1）：

# HTML → PDF（字段名为 index.html，文件同为 index.html）
curl -s --request POST http://localhost:8130/forms/chromium/convert/html \
  --form 'index.html=@index.html' \
  -o html-out.pdf -w 'HTTP %{http_code} | %{size_download} bytes | %{time_total}s\n'

实测回显：

HTTP 200 | 112322 bytes | 3.066279s

# 验证产物
file html-out.pdf

实测回显：

html-out.pdf: PDF version 1.7

中文渲染验证：解析产物 PDF 的嵌入字体（实测）：

嵌入字体: ['NotoSansCJKsc-Bold', 'NotoSansCJKsc-Regular']
Title 解码: 项目验收单

结论：服务内置 Noto Sans CJK SC（思源黑体简体）字体并已子集嵌入，中文标题「项目验收单」正确写入文档元数据，中文渲染无需任何额外配置。

3.2 URL 转 PDF

# 网页 → PDF（以官方文档示例的发票模板页为目标）
curl -s --request POST http://localhost:8130/forms/chromium/convert/url \
  --form url=https://sparksuite.github.io/simple-html-invoice-template/ \
  -o url-out.pdf -w 'URL->PDF: HTTP %{http_code} | %{size_download} bytes | %{time_total}s\n'

实测回显：

URL->PDF: HTTP 200 | 41913 bytes | 3.970043s

file url-out.pdf

实测回显：

url-out.pdf: PDF version 1.7

耗时 3.97 秒含外网页面加载与浏览器启动；同目标页再次转换时浏览器已热，耗时显著下降。URL 路由的表单字段名为 url，直接传完整地址即可。

3.3 Markdown 转 PDF

Markdown 转换需要两个文件：HTML 包装模板（文件名同样必须 index.html）+ Markdown 源文件。模板中用 {{toHTML "notes.md"}} 模板函数把 Markdown 渲染进指定位置：

<!-- index.html（包装模板，实测版本） -->
<!DOCTYPE html>
<html lang="zh-CN">
<head><meta charset="utf-8"><title>值班手记</title>
<style>
  body { font-family: sans-serif; margin: 40px; color: #222; }
  h1 { color: #345; }
  table { border-collapse: collapse; }
  th, td { border: 1px solid #99a; padding: 4px 10px; }
</style></head>
<body>
{{toHTML "notes.md"}}
</body>
</html>

# Markdown → PDF（模板 + 源文件两个表单字段）
curl -s --request POST http://localhost:8130/forms/chromium/convert/markdown \
  --form 'index.html=@index.html' \
  --form 'notes.md=@notes.md' \
  -o md-out.pdf -w 'MD->PDF: HTTP %{http_code} | %{size_download} bytes | %{time_total}s\n'

实测回显：

MD->PDF: HTTP 200 | 126028 bytes | 4.122464s

产物字体验证（实测解析 md-out.pdf）：

MD PDF 嵌入字体: ['NotoSansCJKsc-Bold', 'NotoSansCJKsc-Regular']

Markdown 的标题、表格、引用块经模板包装后正常渲染，中文字体同为 Noto Sans CJK SC。

3.4 Office 文档转 PDF

Office 转换走 LibreOffice 线路，路由为 /forms/libreoffice/convert，表单字段名 files，支持一次传多文件：

# docx → PDF
curl -s --request POST http://localhost:8130/forms/libreoffice/convert \
  --form 'files=@report.docx' \
  -o docx-out.pdf -w 'DOCX->PDF: HTTP %{http_code} | %{size_download} bytes | %{time_total}s\n'

实测回显：

DOCX->PDF: HTTP 200 | 76610 bytes | 12.424999s

# xlsx → PDF
curl -s --request POST http://localhost:8130/forms/libreoffice/convert \
  --form 'files=@budget.xlsx' \
  -o xlsx-out.pdf -w 'XLSX->PDF: HTTP %{http_code} | %{size_download} bytes | %{time_total}s\n'

实测回显：

XLSX->PDF: HTTP 200 | 61106 bytes | 7.805645s

file docx-out.pdf xlsx-out.pdf

实测回显：

docx-out.pdf: PDF version 1.7
xlsx-out.pdf: PDF version 1.7

docx 产物验证（实测解析）：

Producer: LibreOffice 26.8
docx PDF 嵌入字体: ['/BaseFont /DroidSansFallback', '/BaseFont /LiberationSerif']

结论：docx 中的中文经 LibreOffice 以 Droid Sans Fallback 字体渲染（英文正文用 Liberation Serif），文档属性 Producer 标注「LibreOffice 26.8」——与版本路由/调试路由确认的引擎版本一致。

💡 说明：Office 转换首次调用耗时较长（实测 12.4 秒）是因为 LibreOffice 进程冷启动；转换量集中的场景建议在服务配置中开启 LIBREOFFICE_AUTO_START=true 与 CHROMIUM_AUTO_START=true 预热，后续单次转换耗时即可降到秒级。

四、PDF 操作路由实测

本章实测 PDF 引擎路由：合并、归档转换、元数据、加密、水印、拆分。这些路由的输入是 PDF 文件（表单字段名 files），支持多个。

4.1 合并 PDF

# 把三份前文产物按顺序合并
curl -s --request POST http://localhost:8130/forms/pdfengines/merge \
  --form 'files=@html-out.pdf' \
  --form 'files=@url-out.pdf' \
  --form 'files=@md-out.pdf' \
  -o merged.pdf -w 'MERGE: HTTP %{http_code} | %{size_download} bytes | %{time_total}s\n'

实测回显：

MERGE: HTTP 200 | 281733 bytes | 0.112793s

实测核对产物页数（原文档分别 1 页，合并后 3 页成立）。

4.2 转 PDF/A（归档格式）

# 转 PDF/A-1b（表单字段 pdfa 可选 PDF/A-1b、PDF/A-2b、PDF/A-3b 及 PDF/UA 系列）
curl -s --request POST http://localhost:8130/forms/pdfengines/convert \
  --form 'files=@html-out.pdf' \
  --form pdfa=PDF/A-1b \
  -o pdfa-out.pdf -w 'PDFA: HTTP %{http_code} | %{size_download} bytes | %{time_total}s\n'

实测回显：

PDFA: HTTP 200 | 117233 bytes | 0.180461s

归档合规验证（解析 pdfa-out.pdf 对象结构，实测）：

GTS_PDFA1 -> True（输出意图对象存在）
ICC 色彩配置: 已嵌入（lcms sRGB）
XMP pdfaid:part = 1
XMP pdfaid:conformance = B

结论：产物携带 PDF/A 输出意图（GTS_PDFA1）、嵌入 sRGB ICC 色彩配置，XMP 元数据声明 pdfaid:part=1、conformance=B，与请求的 PDF/A-1b 完全一致。归档场景（报文级长期保存）可直接使用该路由。

4.3 元数据写入与读取

# 写元数据（metadata 字段为 JSON）
curl -s --request POST http://localhost:8130/forms/pdfengines/metadata/write \
  --form 'files=@html-out.pdf' \
  --form 'metadata={"Author":"运维知识库","Title":"HTML 转换示例","Keywords":"gotenberg,pdf"}' \
  -o meta-out.pdf -w 'META-WRITE: HTTP %{http_code} | %{size_download} bytes\n'

# 读回元数据
curl -s --request POST http://localhost:8130/forms/pdfengines/metadata/read \
  --form 'files=@meta-out.pdf' -w '\nMETA-READ: HTTP %{http_code}\n'

实测回显：

META-WRITE: HTTP 200 | 113262 bytes
META-READ: HTTP 200
{"Author":"运维知识库","Title":"HTML 转换示例","Keywords":"gotenberg,pdf"}

写入与读回往返一致，中文键值经 exiftool 引擎正确处理。

4.4 加密

# 用户密码 + 所有者密码保护
curl -s --request POST http://localhost:8130/forms/pdfengines/encrypt \
  --form 'files=@html-out.pdf' \
  --form userPassword=q1w2e3r4 \
  --form ownerPassword=q1w2e3r4 \
  -o enc-out.pdf -w 'ENCRYPT: HTTP %{http_code} | %{size_download} bytes\n'

实测回显：

ENCRYPT: HTTP 200 | 117678 bytes

加密生效验证（解析 enc-out.pdf 加密字典，实测）：

/Encrypt 字典存在: True
加密算法版本 V = 5 | 修订 R = 6   # 即 AES-256（qpdf 引擎产出）

打开产物需输入密码，AES-256 强度满足常规文档保护需求。

4.5 水印

水印路由采用 watermarkSource/watermarkExpression/watermarkOptions 参数体系（8.39 实测确认；Options 内所有值必须为字符串，踩坑过程见排障实录 8.3）：

# 文本水印：中文「内部资料」+ 缩放/字号/透明度/旋转（值全部加引号）
curl -s --request POST http://localhost:8130/forms/pdfengines/watermark \
  --form 'files=@html-out.pdf' \
  --form watermarkSource=text \
  --form 'watermarkExpression=内部资料' \
  --form 'watermarkOptions={"points":"36","opacity":"0.15","rotation":"30","color":"#808080"}' \
  -o wm-out.pdf -w 'WATERMARK: HTTP %{http_code} | %{size_download} bytes | %{time_total}s\n'

实测回显：

WATERMARK: HTTP 200 | 148656 bytes | 0.106976s

产物体积从 112KB 增至 148KB，水印层已写入。注意 watermarkOptions 的合法键集取决于引擎（默认 pdfcpu：font、points、color、rotation、opacity、scale、offset 等），本文实测组合即为可用示例。

4.6 拆分 PDF

拆分路由返回 ZIP 压缩包（产物含多文件，与单文件路由不同）：

curl -s --request POST http://localhost:8130/forms/pdfengines/split \
  --form 'files=@merged.pdf' \
  --form splitMode=intervals \
  --form splitSpan=1 \
  -o 'split-%d.pdf' -w 'SPLIT: HTTP %{http_code} | %{content_type}\n'

实测回显：

SPLIT: HTTP 200 | application/zip

splitMode=intervals + splitSpan=1 表示每 1 页切成一个文件；splitMode=pages 则按指定页区间拆分。产物为 ZIP，解包即得单页 PDF 序列。

💡 说明：合并、加密、水印等单输出路由对多输入文件同样返回 ZIP（如两个 Office 文件一次转换返回双 PDF 的压缩包），调用方应按 Content-Type 分流处理：application/pdf 直接落盘，application/zip 解包分发。

五、Webhook 异步处理实测

同步请求受 30 秒时限约束，大文件慢转换应改走 Webhook：请求立即返回 204，转换完成后服务把结果 POST 到回调地址。本章用本地回调接收器完整实测异步链路。

5.1 回调接收器与请求发起

# 模拟业务回调端（Python 单文件接收器，监听 8135 端口落盘回包）
python3 webhook_recv.py &        # 输出 listening 即就绪

# 发起异步转换：三个头决定回调行为，返回 204 表示受理
curl -s --request POST http://localhost:8130/forms/chromium/convert/url \
  --header 'Gotenberg-Webhook-Url: http://10.89.57.1:8135/gotenberg-callback' \
  --header 'Gotenberg-Webhook-Events-Url: http://10.89.57.1:8135/gotenberg-events' \
  --form url=https://sparksuite.github.io/simple-html-invoice-template/ \
  -o /dev/null -w 'WEBHOOK 受理: HTTP %{http_code} (body=%{size_download} bytes)\n'

实测回显：

WEBHOOK 受理: HTTP 204 (body=0 bytes)

关键点：Webhook 参数是 HTTP 请求头而非表单字段（实测用 --form 传回调地址时请求按同步执行、回调不触发，踩坑见 8.2）；受理响应为 204 No Content，空响应体即异步已启动。

5.2 回调结果核验

约 6 秒后回调到达，接收器日志（实测）：

13:17:08.399 path=/gotenberg-callback headers={"Gotenberg-Trace":"7ed779c1-47b1-444b-9263-b9dd05c94ed6","Content-Type":"application/pdf","Content-Length":"42028","User-Agent":"Gotenberg"} body=42028bytes first=b'%PDF-1.7'
13:17:08.402 path=/gotenberg-events headers={"Gotenberg-Trace":"7ed779c1-47b1-444b-9263-b9dd05c94ed6","Content-Type":"application/json","Content-Length":"150","User-Agent":"Gotenberg"} body=150bytes first=b'{"event"'

逐行解读：

回调一（/gotenberg-callback）：转换产物 PDF 直接送达，Content-Type: application/pdf、42028 字节、以 %PDF-1.7 开头——业务端落盘即用；
回调二（/gotenberg-events）：结构化事件 JSON，Content-Type: application/json；
两次回调的 Gotenberg-Trace 完全一致（7ed779c1-...），与发起请求的响应头同值——跨异步链路的关联就靠它。

事件 JSON 原文（实测落盘文件）：

{"event":"webhook.success","correlationId":"7ed779c1-47b1-444b-9263-b9dd05c94ed6","timestamp":"2026-10-28T05:17:08.357944Z"}

失败场景对应 webhook.error 事件并携带错误体（状态码与 message）。全链路实测结论：204 受理 → PDF 结果回调 → JSON 事件回调，三者以同一 trace 贯穿，异步处理可直接投入生产。

⚠️ 注意：回调重试规则——连接错误、429、501 以外的 5xx 会重试（默认最多 4 次，1s~30s 指数退避），其他 4xx 不重试。回调地址的可用性监控是异步方案的运维前提。

六、并发与超时实测

本章验证服务的并发行为与超时保护，为容量规划提供实测依据。

6.1 多文件单请求与并发吞吐

# 一次请求转换两个 Office 文件（多 files 字段）
curl -s --request POST http://localhost:8130/forms/libreoffice/convert \
  --form 'files=@report.docx' --form 'files=@budget.xlsx' \
  -o multi-out.zip -w 'MULTI-FILE: HTTP %{http_code} | %{size_download} bytes | %{content_type}\n'

# 4 路并发 HTML 转换（Chromium 并发上限 6 内）
for i in 1 2 3 4; do
  curl -s --request POST http://localhost:8130/forms/chromium/convert/html \
    --form index.html=@index.html -o "conc-$i.pdf" \
    -w "req$i: HTTP %{http_code} %{time_total}s\n" &
done; wait

实测回显：

MULTI-FILE: HTTP 200 | 134923 bytes | application/zip
req1: HTTP 200 3.05s    req2: HTTP 200 3.10s
req3: HTTP 200 3.16s    req4: HTTP 200 3.21s

多文件单请求返回 ZIP（实测解包确认含两份 PDF）；4 路并发全部成功且单请求耗时与串行基本持平（并发上限 6，未触发排队），符合 Chromium 并发模型预期。负载再升时请求进入队列（gotenberg_chromium_requests_queue_size 指标可观测），队列也满则请求被终止。

6.2 超时保护实测

API_TIMEOUT 默认 30 秒。用不可达地址实测超时行为（实测）：

TIMEOUT CASE: HTTP 503 | 30.0s
{"message":"The request exceeded the time limit. Increase it with --api-timeout, or reduce the workload.","status":503}

实测结论：默认 30 秒精确触发、返回 503、错误信息直接给出调参指引（--api-timeout）。处理慢转换的三种正解：调大 API_TIMEOUT；改 Webhook 异步；缩小单请求工作量。

七、运维实践

本章给出日常运维的标准动作：监控接入、日志分析、健康巡检与容量判断。

7.1 监控指标接入

# Prometheus 指标端点（受认证保护，需凭据；此处为未开启认证的实测）
curl -s http://localhost:8130/prometheus/metrics | grep -E '^gotenberg' | head -8

实测回显（节选）：

gotenberg_build_info{...} 1
gotenberg_chromium_restarts_count{...} 0
gotenberg_chromium_requests_queue_size{...} 0
gotenberg_libreoffice_requests_queue_size{...} 0

建议关注的指标：两个 requests_queue_size（持续增长 = 并发/吞吐不足）、restarts_count（异常增长 = 转换内容触发引擎崩溃）、requests_total 系列（QPD 基线与错误率）。抓取配置里加 basic_auth 凭据即可对接认证开启的实例。

7.2 日志与巡检

# 日志（JSON 格式，级别 info）
docker compose logs --tail 100 gotenberg | head -6

实测回显（节选）：

{"level":"info","time":"2026-10-28T05:08:20Z","module":"libreoffice","key":"launching LibreOffice..."}
{"level":"info","time":"2026-10-28T05:08:26Z","module":"chromium","key":"launching Chromium..."}
{"level":"info","time":"2026-10-28T05:15:33Z","trace":"c0d11d10-...","method":"POST","path":"/forms/chromium/convert/html","status":200,"duration":"3.07s"}

日志三要素：trace 与响应头 Gotenberg-Trace 对账、path 定位路由、status/duration 看结果与耗时。日常巡检清单：

/health 状态 up 且两引擎 up（分钟级探针）；
队列指标不持续高于 0；
磁盘余量（转换临时文件随请求清理，异常堆积即告警）；
日志无连续 status: 503（超时/过载信号）。

7.3 故障自愈与升级

引擎崩溃自愈：Chromium/LibreOffice 按转换计数自动重启（默认 100/10 次），崩溃也会被拉起，无需人工干预；
滚动升级：拉新镜像 + up -d 重建，无状态设计使升级零迁移；升级后以 /version 核对；
配置变更：改环境变量后重建生效，/debug 回读确认（见配置篇 3.2）。

八、排障实录

本章沉淀本次实测中真实踩到的坑，每条按「现象 → 根因 → 解法」组织，供对号入座。

8.1 HTML 转换 400：文件名校验陷阱

现象：把本地文件 invoice.html 直接上传转换，返回 400：

field 'files' contains an unexpected file: 'invoice.html'

排查：做两组对照实验（实测）——

T1：字段名 index.html、文件名 invoice.html → HTTP 400
T2：字段名 files、文件名 index.html → HTTP 200

根因：路由校验的是上传文件的文件名（filename 部分）而非表单字段名；HTML/Markdown 路由要求主文件名必须为 index.html。错误信息里那句「unexpected file」指的就是文件名不对，容易误读成字段名问题。

解法：复制为 index.html 再上传（cp invoice.html index.html），或用 curl 语法在上传瞬间改名：--form 'index.html=@invoice.html'（@ 前的部分是落盘文件名）。Markdown 路由的包装模板同理，且模板内 {{toHTML}} 引用名要与对应 .md 文件的上传名一致。

8.2 Webhook 不回调：头与字段的混淆

现象：把回调地址用表单字段传入（--form Gotenberg-Webhook-Url=...），请求按同步执行并直接返回 PDF，回调从不触发。

根因：Webhook 配置全部是 HTTP 请求头（Gotenberg-Webhook-Url 等），不是表单字段。官方文档以 Headers 章节记载，但参数名与表单风格过于相似，极易写错。

解法：改用 --header 传递；受理解答为 204 No Content，见到 204 即异步链路已启动，随后核对回调与 Gotenberg-Trace 一致性（见第五章实测）。

8.3 水印 400：watermarkOptions 的类型陷阱

现象：按官方文档示例传数值型 JSON（{"opacity":0.25,"rotation":45}）：

watermarkOptions[rotation]: unknown type: float64

排查：三组对照（实测）——数值型 JSON 400；无 Options 仅文本水印 200；所有值加引号的字符串型 JSON（{"opacity":"0.15","rotation":"30"}）→ HTTP 200。进一步核对官方源码（v8.39.0 pkg/modules/pdfengines/routes.go）确认 watermarkOptions 按 map[string]string 反序列化。

根因：实现层把 Options 定义为字符串映射，官方文档示例却写成数值——文档与实现不一致，数值型键值必 400。

解法：watermarkOptions 内所有值统一为字符串（"points":"36"、"opacity":"0.15"）。升级新版本时如遇数值型拒绝，先按字符串重试再查版本差异。该结论同样适用于同体系的 stampOptions。

8.4 中文渲染异常：字体缺失定位与修复

现象：部分中文文档转换后出现方块（豆腐块），或设计稿指定字体未生效。

排查路径（实测命令）：

# 1. 确认服务内置 CJK 字体覆盖度
docker exec gotenberg-8-api sh -c 'fc-list | grep -ciE "noto|wqy|cjk" ; fc-list | wc -l'

实测回显：

302
345

内置 345 款字体中 302 款为 CJK 相关（Noto 全系），常规中文开箱即用（3.1/3.3 节实测嵌入 NotoSansCJKsc、3.4 节实测 DroidSansFallback）。

修复：指定字体缺失时挂载字体目录（只读）：

    volumes:
      - /opt/gotenberg/fonts:/usr/local/share/fonts/custom:ro

# 2. 挂载后验证字体被 fontconfig 识别
docker exec gotenberg-8-api fc-list | grep -i droid

实测回显：

/usr/local/share/fonts/custom/DroidSansFallbackFull.ttf: Droid Sans Fallback:style=Regular

根因归纳：豆腐块 = 渲染时字体名解析不到可用字体。三类来源逐一核对：文档指定字体是否上传/挂载、字体名拼写（fc-list 输出为准）、Office 文档内嵌字体与服务器字体名是否一致。挂载识别后重启服务再转换即恢复。

8.5 请求 503：超时参数的默认边界

现象：长网页或大文档转换在 30 秒整点失败：

{"message":"The request exceeded the time limit. Increase it with --api-timeout, or reduce the workload.","status":503}

根因：API_TIMEOUT 默认 30s，实测 30.0 秒整点触发（见 6.2）。

解法：调大 API_TIMEOUT（生产模板建议 60s 起步）；或慢任务改 Webhook 异步（见第五章）；同时核对是否有引擎冷启动损耗叠加——开启 CHROMIUM_AUTO_START/LIBREOFFICE_AUTO_START 预热可显著削峰。

九、参考链接

官方路由总览：https://gotenberg.dev/docs/getting-started/routes
Webhook 与远程下载：https://gotenberg.dev/docs/webhook-download
健康检查路由：https://gotenberg.dev/docs/system/get-health-check
PDF 操作各路由文档（merge/split/convert/metadata/encrypt/watermark）：https://gotenberg.dev/docs/manipulate-pdfs/merge-pdfs 等子页
环境与部署：《Gotenberg Docker Compose 部署实战》
参数体系：《Gotenberg 8 配置参数详解》
组件认知与选型：《Gotenberg 介绍与选型指南》