維運部署

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