运维部署

Docker 文档转换

通过 Docker Compose 与强化的 GordonKit 镜像执行文档转换，可使用内置 LibreOffice、具认证 API 或隔离的 Gotenberg renderer。

选择 Profile

所有 Compose service 都必须明确选用，且共用同一个 GordonKit 镜像。cli 适合本地命令；standalone-lo 使用内置 LibreOffice；gateway-gotenberg 则让 API 搭配独立排版服务。

CLI Profile

CLI 模式使用内置 LibreOffice、将当前目录挂载至 /work，且不需要 API 密钥；相同的单行命令可用于 Bash 与 PowerShell。

docker compose -f docker/compose.yaml --profile cli run --rm --build cli convert /work/report.docx --output /work/report.pdf --engine libreoffice --overwrite

单体 LibreOffice API

需要简单部署与本地排版，且不需独立扩展 renderer 时，可在同一容器执行具认证的 API 与 LibreOffice。

# .env
GORDON_DOC_API_KEY=replace-me

docker compose -f docker/compose.yaml --env-file .env --profile standalone-lo up --build

Gotenberg Gateway

偏好 renderer 隔离与独立服务健康状态时，可让 API 搭配个别 Gotenberg service；Compose 会将两者连至 gordon-doc network，并等待 Gotenberg 健康后再启动 API。设置 Gotenberg URL 代表明确选用该引擎；失败时不会静默改用 LibreOffice。

docker compose -f docker/compose.yaml --env-file .env --profile gateway-gotenberg up --build

Bash API 请求

从 .env 加载部署者管理的密钥，明确指定引擎并存储 PDF 响应。

set -a; . ./.env; set +a
curl --fail-with-body -H "Authorization: Bearer $GORDON_DOC_API_KEY" -H "Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document" -H "X-Filename: report.docx" --data-binary @report.docx "http://127.0.0.1:8000/conversions?engine=gotenberg" --output report-gb.pdf

PowerShell API 请求

PowerShell 可读取相同的 .env，并以 Invoke-WebRequest 存储二进制响应；使用 standalone profile 时请改为 engine=libreoffice。

$env:GORDON_DOC_API_KEY = ((Get-Content .env | Where-Object { $_ -match '^GORDON_DOC_API_KEY=' }) -replace '^GORDON_DOC_API_KEY=', '')
$headers = @{ Authorization = "Bearer $env:GORDON_DOC_API_KEY"; 'X-Filename' = 'report.docx' }
Invoke-WebRequest -Uri 'http://127.0.0.1:8000/conversions?engine=gotenberg' -Method Post -Headers $headers -ContentType 'application/vnd.openxmlformats-officedocument.wordprocessingml.document' -InFile .\report.docx -OutFile .\report-gb.pdf

停止服务

本地测试后停止对应 profile；已产生的 PDF 会保留在主机。

docker compose -f docker/compose.yaml --profile standalone-lo down
docker compose -f docker/compose.yaml --profile gateway-gotenberg down

正式发布镜像

正式版本会发布单一 linux/amd64 镜像至 gordonkit/gordon-doc-converter。默认 entrypoint 执行 CLI；传入 api 则启动 HTTP service。需要可重现部署时，请使用明确版本 tag。

docker run --rm gordonkit/gordon-doc-converter:0.6.0 version
docker run --rm -p 8000:8000 -e GORDON_DOC_API_KEY=replace-me gordonkit/gordon-doc-converter:0.6.0 api

运维与安全

所有 profile 都以非 root 用户、只读 root filesystem、有限 tmpfs 与 no-new-privileges 执行。API profile 必须使用高强度 key；生产环境 ingress 也应限制 request 大小并提供分布式 rate limit。

python docker/smoke.py --token replace-me --docx sample.docx