From d5c9bfa320a0ac5a0161ed76f7d26397d92b066b Mon Sep 17 00:00:00 2001
From: Your Name <your.email@example.com>
Date: Thu, 22 Jan 2026 23:51:18 +0800
Subject: [PATCH] feat(ci): add model/headless verification, use --no-ff merge
 strategy

- Add verify-image job in release.yml with:
  - Headless environment verification (DISPLAY, Xvfb, LibreOffice, Inkscape, Calibre)
  - Model download verification (HuggingFace cache, ONNX models, offline mode)
  - Basic functionality verification (container startup, tool availability)
- Add Test 3 and Test 4 in upstream-sync.yml for headless/model verification
- Update auto-upstream-sync.yml to use git merge --no-ff for better history tracking
---
 .github/workflows/auto-upstream-sync.yml |   4 +-
 .github/workflows/release.yml            | 242 ++++++++++++++++++++++-
 .github/workflows/upstream-sync.yml      |  91 ++++++++-
 3 files changed, 329 insertions(+), 8 deletions(-)

diff --git a/.github/workflows/auto-upstream-sync.yml b/.github/workflows/auto-upstream-sync.yml
index 1716491..a78aa1d 100644
--- a/.github/workflows/auto-upstream-sync.yml
+++ b/.github/workflows/auto-upstream-sync.yml
@@ -152,8 +152,8 @@ jobs:
         run: |
           echo "🔄 Merging upstream/${{ env.UPSTREAM_BRANCH }} into ${{ env.TARGET_BRANCH }}..."
 
-          # 嘗試自動 merge
-          if git merge upstream/${{ env.UPSTREAM_BRANCH }} --no-edit -m "🔄 Auto-merge upstream changes ($(date +'%Y-%m-%d'))"; then
+          # 嘗試自動 merge（使用 --no-ff 確保創建 merge commit，保留完整歷史）
+          if git merge upstream/${{ env.UPSTREAM_BRANCH }} --no-ff --no-edit -m "🔄 Merge upstream/${{ env.UPSTREAM_BRANCH }} ($(date +'%Y-%m-%d'))"; then
             echo "✅ Merge successful!"
             echo "merge_success=true" >> $GITHUB_OUTPUT
           else
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 63e8660..a29ea29 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -185,11 +185,249 @@ jobs:
           echo "**Platforms:** linux/amd64, linux/arm64" >> $GITHUB_STEP_SUMMARY
 
   # ==============================================================================
-  # 📦 Create GitHub Release
+  # � Verify Docker Image（模型驗證 + Headless 驗證）
+  # ==============================================================================
+  verify-image:
+    name: Verify Docker Image
+    runs-on: ubuntu-latest
+    needs: build-and-push
+    timeout-minutes: 15
+
+    steps:
+      - name: Get tag name
+        id: tag
+        run: |
+          if [ "${{ github.event_name }}" == "workflow_dispatch" ]; then
+            echo "version=${{ github.event.inputs.tag }}" >> $GITHUB_OUTPUT
+          else
+            echo "version=${GITHUB_REF#refs/tags/}" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Pull Docker image
+        run: |
+          echo "📥 Pulling Docker image..."
+          docker pull ${{ env.DOCKER_IMAGE }}:${{ steps.tag.outputs.version }}
+
+      # ========================================
+      # 驗證 1: Headless 環境驗證
+      # ========================================
+      - name: "🖥️ Headless Environment Verification"
+        run: |
+          echo "========================================"
+          echo "🖥️ Headless 環境驗證"
+          echo "========================================"
+
+          IMAGE="${{ env.DOCKER_IMAGE }}:${{ steps.tag.outputs.version }}"
+          FAILED=0
+
+          # 檢查 DISPLAY 環境變數（應為空或不存在）
+          echo ""
+          echo "📋 檢查 DISPLAY 環境變數..."
+          DISPLAY_VAR=$(docker run --rm "${IMAGE}" printenv DISPLAY 2>/dev/null || echo "")
+          if [ -z "$DISPLAY_VAR" ]; then
+            echo "✅ DISPLAY 未設定（headless 模式正確）"
+          else
+            echo "⚠️ DISPLAY 已設定: ${DISPLAY_VAR}（可能影響 headless 模式）"
+          fi
+
+          # 檢查 Xvfb（應不存在或不需要）
+          echo ""
+          echo "📋 檢查 Xvfb..."
+          if docker run --rm "${IMAGE}" which Xvfb 2>/dev/null; then
+            echo "⚠️ Xvfb 存在（但應不需要）"
+          else
+            echo "✅ Xvfb 不存在（headless 模式正確）"
+          fi
+
+          # 驗證 LibreOffice headless 模式
+          echo ""
+          echo "📋 驗證 LibreOffice headless..."
+          if docker run --rm "${IMAGE}" libreoffice --headless --version 2>/dev/null | head -1; then
+            echo "✅ LibreOffice headless 模式可用"
+          else
+            echo "❌ LibreOffice headless 模式失敗"
+            FAILED=1
+          fi
+
+          # 驗證 Inkscape headless 模式
+          echo ""
+          echo "📋 驗證 Inkscape headless..."
+          if docker run --rm "${IMAGE}" inkscape --version 2>/dev/null; then
+            echo "✅ Inkscape 可用"
+          else
+            echo "❌ Inkscape 不可用"
+            FAILED=1
+          fi
+
+          # 驗證 Calibre headless 模式（使用 ebook-convert）
+          echo ""
+          echo "📋 驗證 Calibre headless..."
+          if docker run --rm -e QTWEBENGINE_CHROMIUM_FLAGS="--no-sandbox" "${IMAGE}" ebook-convert --version 2>/dev/null | head -1; then
+            echo "✅ Calibre headless 模式可用"
+          else
+            echo "❌ Calibre headless 模式失敗"
+            FAILED=1
+          fi
+
+          echo ""
+          echo "========================================"
+          if [ $FAILED -eq 0 ]; then
+            echo "✅ Headless 環境驗證通過！"
+          else
+            echo "❌ Headless 環境驗證失敗！"
+            exit 1
+          fi
+          echo "========================================"
+
+      # ========================================
+      # 驗證 2: 模型下載驗證
+      # ========================================
+      - name: "🤖 Model Download Verification"
+        run: |
+          echo "========================================"
+          echo "🤖 模型下載驗證"
+          echo "========================================"
+
+          IMAGE="${{ env.DOCKER_IMAGE }}:${{ steps.tag.outputs.version }}"
+          FAILED=0
+
+          # 檢查 HuggingFace cache 目錄
+          echo ""
+          echo "📋 檢查 HuggingFace cache..."
+          HF_CACHE=$(docker run --rm "${IMAGE}" ls -la /root/.cache/huggingface/ 2>/dev/null || echo "NOT_FOUND")
+          if [ "$HF_CACHE" != "NOT_FOUND" ]; then
+            echo "✅ HuggingFace cache 存在："
+            echo "$HF_CACHE" | head -10
+          else
+            echo "⚠️ HuggingFace cache 不存在（可能使用其他路徑）"
+          fi
+
+          # 檢查 PDFMathTranslate 模型（DocLayout-YOLO）
+          echo ""
+          echo "📋 檢查 PDFMathTranslate 模型..."
+          ONNX_MODEL=$(docker run --rm "${IMAGE}" find /root -name "*.onnx" -type f 2>/dev/null | head -5 || echo "")
+          if [ -n "$ONNX_MODEL" ]; then
+            echo "✅ ONNX 模型已預下載："
+            echo "$ONNX_MODEL"
+          else
+            echo "⚠️ 未找到 ONNX 模型（可能在其他位置或動態下載）"
+          fi
+
+          # 檢查 MinerU 模型目錄
+          echo ""
+          echo "📋 檢查 MinerU 模型..."
+          MINERU_MODELS=$(docker run --rm "${IMAGE}" ls -la /root/.cache/modelscope/ 2>/dev/null || \
+                         docker run --rm "${IMAGE}" ls -la /app/models/ 2>/dev/null || echo "NOT_FOUND")
+          if [ "$MINERU_MODELS" != "NOT_FOUND" ]; then
+            echo "✅ MinerU 模型目錄存在："
+            echo "$MINERU_MODELS" | head -10
+          else
+            echo "⚠️ MinerU 模型目錄不存在（可能使用其他路徑）"
+          fi
+
+          # 檢查 BabelDOC cache
+          echo ""
+          echo "📋 檢查 BabelDOC cache..."
+          BABEL_CACHE=$(docker run --rm "${IMAGE}" ls -la /root/.cache/babeldoc/ 2>/dev/null || echo "NOT_FOUND")
+          if [ "$BABEL_CACHE" != "NOT_FOUND" ]; then
+            echo "✅ BabelDOC cache 存在："
+            echo "$BABEL_CACHE" | head -10
+          else
+            echo "⚠️ BabelDOC cache 不存在（將在首次使用時下載）"
+          fi
+
+          # 檢查離線模式環境變數
+          echo ""
+          echo "📋 檢查離線模式環境變數..."
+          HF_OFFLINE=$(docker run --rm "${IMAGE}" printenv HF_HUB_OFFLINE 2>/dev/null || echo "")
+          if [ "$HF_OFFLINE" = "1" ]; then
+            echo "✅ HF_HUB_OFFLINE=1（離線模式已啟用）"
+          else
+            echo "⚠️ HF_HUB_OFFLINE 未設定（模型可能在 runtime 下載）"
+          fi
+
+          echo ""
+          echo "========================================"
+          echo "📊 模型驗證摘要"
+          echo "========================================"
+          echo "此驗證檢查模型是否已預下載至 Docker image。"
+          echo "若模型未預下載，轉檔功能仍可運作（首次使用時下載）。"
+          echo "========================================"
+
+      # ========================================
+      # 驗證 3: 基本功能驗證
+      # ========================================
+      - name: "⚙️ Basic Functionality Verification"
+        run: |
+          echo "========================================"
+          echo "⚙️ 基本功能驗證"
+          echo "========================================"
+
+          IMAGE="${{ env.DOCKER_IMAGE }}:${{ steps.tag.outputs.version }}"
+
+          # 啟動容器
+          echo "🚀 啟動容器..."
+          docker run -d --name verify-test -p 3000:3000 "${IMAGE}"
+
+          # 等待啟動
+          echo "⏳ 等待容器啟動..."
+          for i in {1..60}; do
+            if docker exec verify-test curl -sf http://localhost:3000/healthcheck > /dev/null 2>&1; then
+              echo "✅ 容器在 ${i} 秒內啟動成功"
+              break
+            fi
+            if [ $i -eq 60 ]; then
+              echo "❌ 容器啟動超時"
+              docker logs verify-test
+              docker rm -f verify-test
+              exit 1
+            fi
+            sleep 1
+          done
+
+          # 檢查關鍵工具
+          echo ""
+          echo "📋 檢查關鍵轉檔工具..."
+          TOOLS=("libreoffice --version" "pandoc --version" "ffmpeg -version" "tesseract --version" "pdf2zh --help" "mineru --help" "babeldoc --help")
+          
+          for tool_cmd in "${TOOLS[@]}"; do
+            TOOL_NAME=$(echo "$tool_cmd" | cut -d' ' -f1)
+            echo -n "  ${TOOL_NAME}: "
+            if docker exec verify-test $tool_cmd >/dev/null 2>&1; then
+              echo "✅"
+            else
+              echo "⚠️ 不可用或未安裝"
+            fi
+          done
+
+          # 清理
+          echo ""
+          echo "🧹 清理測試容器..."
+          docker rm -f verify-test
+
+          echo ""
+          echo "========================================"
+          echo "✅ 基本功能驗證完成！"
+          echo "========================================"
+
+      - name: Verification Summary
+        run: |
+          echo "## 🔍 Image Verification Results" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "**Image:** \`${{ env.DOCKER_IMAGE }}:${{ steps.tag.outputs.version }}\`" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "### ✅ Verification Passed" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "- 🖥️ Headless Environment: Verified" >> $GITHUB_STEP_SUMMARY
+          echo "- 🤖 Model Download: Checked" >> $GITHUB_STEP_SUMMARY
+          echo "- ⚙️ Basic Functionality: Verified" >> $GITHUB_STEP_SUMMARY
+
+  # ==============================================================================
+  # �📦 Create GitHub Release
   # ==============================================================================
   create-release:
     runs-on: ubuntu-latest
-    needs: build-and-push
+    needs: [build-and-push, verify-image]
     permissions:
       contents: write
 
diff --git a/.github/workflows/upstream-sync.yml b/.github/workflows/upstream-sync.yml
index 350e4b2..c3dccd2 100644
--- a/.github/workflows/upstream-sync.yml
+++ b/.github/workflows/upstream-sync.yml
@@ -233,9 +233,88 @@ jobs:
           echo "✅ All critical tools available"
 
       # ========================================
-      # Test 3: 最小轉換測試 (txt → pdf)
+      # Test 3: Headless 環境驗證
       # ========================================
-      - name: "Test 3: Minimal conversion test"
+      - name: "Test 3: Headless environment verification"
+        run: |
+          echo "🖥️ Verifying headless environment..."
+
+          # 檢查 DISPLAY 環境變數
+          echo ""
+          echo "📋 檢查 DISPLAY 環境變數..."
+          DISPLAY_VAR=$(docker exec convertx-test printenv DISPLAY 2>/dev/null || echo "")
+          if [ -z "$DISPLAY_VAR" ]; then
+            echo "✅ DISPLAY 未設定（headless 模式正確）"
+          else
+            echo "⚠️ DISPLAY 已設定: ${DISPLAY_VAR}"
+          fi
+
+          # 檢查 Xvfb
+          echo ""
+          echo "📋 檢查 Xvfb..."
+          if docker exec convertx-test which Xvfb 2>/dev/null; then
+            echo "⚠️ Xvfb 存在（但應不需要）"
+          else
+            echo "✅ Xvfb 不存在（headless 模式正確）"
+          fi
+
+          # 驗證 LibreOffice headless
+          echo ""
+          echo "📋 驗證 LibreOffice headless..."
+          if docker exec convertx-test libreoffice --headless --version 2>/dev/null | head -1; then
+            echo "✅ LibreOffice headless 模式可用"
+          else
+            echo "❌ LibreOffice headless 模式失敗"
+            exit 1
+          fi
+
+          echo ""
+          echo "✅ Headless environment verification passed"
+
+      # ========================================
+      # Test 4: 模型下載驗證
+      # ========================================
+      - name: "Test 4: Model download verification"
+        run: |
+          echo "🤖 Verifying model downloads..."
+
+          # 檢查 HuggingFace cache
+          echo ""
+          echo "📋 檢查 HuggingFace cache..."
+          HF_CACHE=$(docker exec convertx-test ls -la /root/.cache/huggingface/ 2>/dev/null || echo "NOT_FOUND")
+          if [ "$HF_CACHE" != "NOT_FOUND" ]; then
+            echo "✅ HuggingFace cache 存在"
+          else
+            echo "⚠️ HuggingFace cache 不存在（模型可能在其他位置）"
+          fi
+
+          # 檢查 ONNX 模型
+          echo ""
+          echo "📋 檢查 ONNX 模型..."
+          ONNX_COUNT=$(docker exec convertx-test find /root -name "*.onnx" -type f 2>/dev/null | wc -l || echo "0")
+          if [ "$ONNX_COUNT" -gt 0 ]; then
+            echo "✅ 找到 ${ONNX_COUNT} 個 ONNX 模型"
+          else
+            echo "⚠️ 未找到 ONNX 模型（可能動態下載）"
+          fi
+
+          # 檢查離線模式環境變數
+          echo ""
+          echo "📋 檢查離線模式環境變數..."
+          HF_OFFLINE=$(docker exec convertx-test printenv HF_HUB_OFFLINE 2>/dev/null || echo "")
+          if [ "$HF_OFFLINE" = "1" ]; then
+            echo "✅ HF_HUB_OFFLINE=1（離線模式已啟用）"
+          else
+            echo "⚠️ HF_HUB_OFFLINE 未設定"
+          fi
+
+          echo ""
+          echo "✅ Model verification completed"
+
+      # ========================================
+      # Test 5: 最小轉換測試 (txt → pdf)
+      # ========================================
+      - name: "Test 5: Minimal conversion test"
         id: test_conversion
         run: |
           echo "📄 Testing minimal conversion (txt → pdf)..."
@@ -271,9 +350,9 @@ jobs:
           }
 
       # ========================================
-      # Test 4: API 端點檢查
+      # Test 6: API 端點檢查
       # ========================================
-      - name: "Test 4: API endpoints check"
+      - name: "Test 6: API endpoints check"
         run: |
           echo "🌐 Checking API endpoints..."
 
@@ -321,6 +400,8 @@ jobs:
           echo "|----------|------|" >> $GITHUB_STEP_SUMMARY
           echo "| Container 啟動 | ✅ 通過 (${startup_time:-N/A}s) |" >> $GITHUB_STEP_SUMMARY
           echo "| 工具檢查 (libreoffice, pandoc, ffmpeg, tesseract) | ✅ 通過 |" >> $GITHUB_STEP_SUMMARY
+          echo "| Headless 環境驗證 | ✅ 通過 |" >> $GITHUB_STEP_SUMMARY
+          echo "| 模型下載驗證 | ✅ 通過 |" >> $GITHUB_STEP_SUMMARY
           echo "| 最小轉換測試 | ✅ 通過 |" >> $GITHUB_STEP_SUMMARY
           echo "| API 端點檢查 | ✅ 通過 |" >> $GITHUB_STEP_SUMMARY
 
@@ -403,6 +484,8 @@ jobs:
           echo "|----------|------|" >> $GITHUB_STEP_SUMMARY
           echo "| Container 啟動 | ✅ |" >> $GITHUB_STEP_SUMMARY
           echo "| 工具存在性檢查 | ✅ |" >> $GITHUB_STEP_SUMMARY
+          echo "| Headless 環境驗證 | ✅ |" >> $GITHUB_STEP_SUMMARY
+          echo "| 模型下載驗證 | ✅ |" >> $GITHUB_STEP_SUMMARY
           echo "| 最小轉換測試 | ✅ |" >> $GITHUB_STEP_SUMMARY
           echo "| API 端點檢查 | ✅ |" >> $GITHUB_STEP_SUMMARY
           echo "" >> $GITHUB_STEP_SUMMARY