ops: 测试服+正式服 K8s 装 Chromium + 中文字体让 PR #1655 Kimi 样式生效 (@yst)

changelogs/2026-05/05_ops_install_chromium_for_itinerary_pdf.md

@@ -0,0 +1,106 @@
+---
+date: 2026-05-05
+type: ops
+module: hl-order-service-v2
+priority: high
+related_pr: "#1655"
+notify: ["@yst"]
+status: pending
+---
+
+# 在 hl-order-service-v2 K8s pod 安装 Chromium + 中文字体
+
+## 背景
+
+PR #1655 已合并：行程附件 PDF 渲染管线从 PDFBox 切到 **Thymeleaf HTML 模板 + Microsoft Playwright Headless Chromium**，1:1 还原 Kimi 网页样式。
+
+代码已部署测试服 + 正式服。**但 Chromium 二进制 + 中文字体未在 K8s base image 中安装**，目前服务自动 fallback 到 PDFBox 老路径（PDF 样式跟之前一样不变，不阻断合同生成）。
+
+要看到 Kimi 新样式，必须装 Chromium。
+
+## K8s 改动清单
+
+### 1. 镜像加 Chromium 二进制 + 系统依赖
+
+`Dockerfile` 加：
+
+```dockerfile
+RUN apt-get update && apt-get install -y \
+    libnss3 libgbm1 libasound2 libxss1 libxshmfence1 \
+    libdrm2 libgtk-3-0 libxcomposite1 libxdamage1 libxfixes3 \
+    libxrandr2 libpango-1.0-0 libcairo2 \
+    && rm -rf /var/lib/apt/lists/*
+```
+
+### 2. 镜像装中文字体
+
+```dockerfile
+RUN apt-get update && apt-get install -y \
+    fonts-noto-cjk fonts-arphic-uming fonts-arphic-ukai \
+    && rm -rf /var/lib/apt/lists/*
+```
+
+### 3. 启动时下载 Chromium 二进制
+
+Playwright-java 第一次调用时自动下载 chromium 到 `~/.cache/ms-playwright/`（约 200MB），但 K8s pod fs 通常 ephemeral，每次 pod 重启会重下，浪费时间。
+
+**两种方案**：
+
+#### 方案 A: PV 持久化 cache 目录（推荐）
+
+K8s deployment 加 PersistentVolumeClaim 挂 `~/.cache/ms-playwright`：
+
+```yaml
+volumes:
+  - name: playwright-cache
+    persistentVolumeClaim:
+      claimName: hl-order-v2-playwright-cache
+volumeMounts:
+  - name: playwright-cache
+    mountPath: /root/.cache/ms-playwright
+```
+
+PVC 大小 500Mi 即可。首次启动 download 后所有 pod 共享。
+
+#### 方案 B: 镜像 build 时 install（更稳妥）
+
+Dockerfile 加：
+
+```dockerfile
+WORKDIR /app
+COPY app.jar /app/
+RUN java -jar /app/app.jar --spring.main.web-application-type=none \
+    --com.microsoft.playwright.cli=install --com.microsoft.playwright.cli.args=chromium
+# 或者用 maven exec 直接装
+RUN mvn -f /tmp/playwright-pom.xml exec:java \
+    -Dexec.mainClass=com.microsoft.playwright.CLI \
+    -Dexec.args="install --with-deps chromium"
+```
+
+镜像层增大约 200MB，但启动即用。
+
+## 验证
+
+部署完后：
+
+1. K8s pod exec: `ls -la ~/.cache/ms-playwright/chromium-*/chrome-linux/chrome` 看二进制存在
+2. 创建一份测试合同，下载行程附件 PDF
+3. 标题"额吉的故乡 · 6天5晚行程线路详情" 应显示**深蓝衬线字体居中**
+4. 每个 DAY 下封面图应**圆角卡片化**
+5. 三餐三栏、timeline、游客名单表样式齐全
+
+## Fallback 行为（保险）
+
+如果 Chromium 启动失败（缺二进制/缺字体/launch 异常），ItineraryAttachmentService 自动 catch + log warn + 走 PDFBox 老路径生成 PDF。**不阻断合同生成流程**。
+
+## OSS Render Version
+
+OSS_RENDER_VERSION 6→7，旧订单重新申报合同会走新版本路径。已生成的旧 v6 PDF 不影响（按月分桶 OSS Key）。
+
+## 关联
+
+- PR #1655 (Thymeleaf + Chromium 重构)
+- Issue #1651 (用户授权 完全由后端做, 不动 hl-ui)
+- 模板文件: `hl-order-service-v2/src/main/resources/templates/itinerary.html`
+
+@yst 帮忙在测试服 K8s deployment 加 Chromium 安装步骤，正式服同步处理。装好后 PD 回复一下我做 round-trip 验证。