---
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 验证。
