280 lines
9.3 KiB
Markdown
280 lines
9.3 KiB
Markdown
# 🔄 Upstream 自動同步機制
|
||
|
||
本專案實作了完整的 upstream 自動同步、變更追蹤與 smoke test 機制。
|
||
|
||
## 📋 目錄
|
||
|
||
- [功能概述](#功能概述)
|
||
- [工作流程圖](#工作流程圖)
|
||
- [Workflow 說明](#workflow-說明)
|
||
- [Smoke Test 內容](#smoke-test-內容)
|
||
- [設定說明](#設定說明)
|
||
- [手動操作](#手動操作)
|
||
|
||
---
|
||
|
||
## 功能概述
|
||
|
||
### 1️⃣ 自動同步 Upstream
|
||
|
||
| 功能 | 說明 |
|
||
| ---------- | ---------------------------- |
|
||
| 觸發方式 | 每 6 小時自動檢查 / 手動觸發 |
|
||
| 同步目標 | `dev` 分支 |
|
||
| Merge 策略 | 自動 merge（無衝突時） |
|
||
| 衝突處理 | 自動建立 GitHub Issue 通知 |
|
||
|
||
### 2️⃣ 變更摘要
|
||
|
||
同步完成後自動產生：
|
||
|
||
- ✅ GitHub Issue（詳細變更記錄）
|
||
- ✅ `upstream-changelog.md`（累積變更歷史）
|
||
- ✅ GitHub Actions Summary（快速查看）
|
||
|
||
### 3️⃣ Smoke Test
|
||
|
||
| 測試項目 | 內容 | 時間限制 |
|
||
| -------------- | -------------------------------------- | ------------- |
|
||
| Container 啟動 | 驗證 image 可正常啟動 | 60s |
|
||
| 工具檢查 | libreoffice, pandoc, ffmpeg, tesseract | 30s |
|
||
| 最小轉換 | txt → pdf | 60s |
|
||
| API 端點 | healthcheck, root | 10s |
|
||
| **總計** | | **< 10 分鐘** |
|
||
|
||
---
|
||
|
||
## 工作流程圖
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────────────┐
|
||
│ Upstream 自動同步流程 │
|
||
└─────────────────────────────────────────────────────────────────────────┘
|
||
|
||
┌──────────────┐
|
||
│ Upstream │
|
||
│ (C4illin/ │
|
||
│ ConvertX) │
|
||
└──────┬───────┘
|
||
│
|
||
│ 每 6 小時檢查
|
||
▼
|
||
┌──────────────┐ 無更新 ┌──────────────┐
|
||
│ 檢查是否有 │ ─────────────► │ 結束 │
|
||
│ 新 commits │ └──────────────┘
|
||
└──────┬───────┘
|
||
│ 有更新
|
||
▼
|
||
┌──────────────┐ 衝突 ┌──────────────┐
|
||
│ 自動 Merge │ ─────────────► │ 建立 Issue │
|
||
│ 到 dev 分支 │ │ 需手動處理 │
|
||
└──────┬───────┘ └──────────────┘
|
||
│ 成功
|
||
▼
|
||
┌──────────────┐
|
||
│ 產生變更摘要 │
|
||
│ • Issue │
|
||
│ • Changelog │
|
||
└──────┬───────┘
|
||
│
|
||
▼
|
||
┌──────────────┐
|
||
│ Push 到 dev │
|
||
└──────┬───────┘
|
||
│
|
||
│ 觸發 upstream-sync.yml
|
||
▼
|
||
┌──────────────┐
|
||
│ Build 測試 │
|
||
│ Image (amd64)│
|
||
└──────┬───────┘
|
||
│
|
||
▼
|
||
┌──────────────────────────────────────────────────┐
|
||
│ Smoke Test │
|
||
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ │
|
||
│ │ Container │ │ 工具 │ │ 轉換 │ │
|
||
│ │ 啟動 │ │ 檢查 │ │ 測試 │ │
|
||
│ └─────┬──────┘ └─────┬──────┘ └─────┬──────┘ │
|
||
│ │ │ │ │
|
||
│ └──────────────┼──────────────┘ │
|
||
│ │ │
|
||
└───────────────────────┼──────────────────────────┘
|
||
│
|
||
┌─────────────┴─────────────┐
|
||
│ │
|
||
▼ ▼
|
||
┌────────────┐ ┌────────────┐
|
||
│ ✅ 通過 │ │ ❌ 失敗 │
|
||
└─────┬──────┘ └─────┬──────┘
|
||
│ │
|
||
▼ ▼
|
||
┌────────────┐ ┌────────────┐
|
||
│ Build 並 │ │ Workflow │
|
||
│ Push 到 │ │ 失敗 │
|
||
│ Docker Hub │ │ (不發布) │
|
||
└─────┬──────┘ └────────────┘
|
||
│
|
||
▼
|
||
┌────────────────────────┐
|
||
│ upstream-YYYYMMDD tag │
|
||
│ ❌ 不更新 latest │
|
||
│ ❌ 不打 semver tag │
|
||
└────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## Workflow 說明
|
||
|
||
### `auto-upstream-sync.yml`
|
||
|
||
**用途：** 自動檢測並同步 upstream 更新
|
||
|
||
**觸發條件：**
|
||
|
||
- ⏰ 每 6 小時自動執行
|
||
- 🖱️ 手動觸發
|
||
|
||
**主要步驟：**
|
||
|
||
1. Fetch upstream 最新程式碼
|
||
2. 檢查是否有新 commits
|
||
3. 自動 merge 到 `dev` 分支
|
||
4. 產生變更摘要（Issue + Changelog）
|
||
5. Push 到 `dev`
|
||
|
||
### `upstream-sync.yml`
|
||
|
||
**用途：** 當 `dev` 分支有 push 時，執行 build + smoke test
|
||
|
||
**觸發條件：**
|
||
|
||
- 📦 `dev` 分支有 push
|
||
|
||
**主要步驟：**
|
||
|
||
1. Build 測試用 image（僅 amd64，加速測試）
|
||
2. 執行 Smoke Test（10 分鐘內）
|
||
3. 測試通過後 build multi-arch image
|
||
4. Push 到 Docker Hub（tag: `upstream-YYYYMMDD`）
|
||
|
||
---
|
||
|
||
## Smoke Test 內容
|
||
|
||
### Test 1: Container 啟動測試
|
||
|
||
```bash
|
||
# 啟動 container 並等待 healthcheck 回應
|
||
docker run -d --name convertx-test $IMAGE
|
||
curl http://localhost:3000/healthcheck
|
||
```
|
||
|
||
### Test 2: 關鍵工具檢查
|
||
|
||
```bash
|
||
# 必須通過（任一失敗則整體失敗）
|
||
libreoffice --version
|
||
pandoc --version
|
||
ffmpeg -version
|
||
tesseract --version
|
||
```
|
||
|
||
### Test 3: 最小轉換測試
|
||
|
||
```bash
|
||
# txt → pdf 轉換測試
|
||
echo "test" > test.txt
|
||
libreoffice --headless --convert-to pdf test.txt
|
||
```
|
||
|
||
### Test 4: API 端點檢查
|
||
|
||
```bash
|
||
# 確認服務正常運作
|
||
curl http://localhost:3000/healthcheck
|
||
curl http://localhost:3000/
|
||
```
|
||
|
||
---
|
||
|
||
## 設定說明
|
||
|
||
### 必要的 GitHub Secrets
|
||
|
||
在 Repository Settings → Secrets and variables → Actions 中設定：
|
||
|
||
| Secret 名稱 | 說明 |
|
||
| -------------------- | ----------------------- |
|
||
| `DOCKERHUB_USERNAME` | Docker Hub 帳號 |
|
||
| `DOCKERHUB_TOKEN` | Docker Hub Access Token |
|
||
|
||
### 分支保護規則
|
||
|
||
建議設定：
|
||
|
||
**`main` 分支：**
|
||
|
||
- ✅ Require pull request before merging
|
||
- ✅ Require status checks to pass
|
||
- ❌ Allow force pushes
|
||
|
||
**`dev` 分支：**
|
||
|
||
- ✅ Allow direct pushes (for automation)
|
||
|
||
---
|
||
|
||
## 手動操作
|
||
|
||
### 手動觸發同步
|
||
|
||
1. 前往 Actions → Auto Upstream Sync
|
||
2. 點選 "Run workflow"
|
||
3. 可選擇「強制同步」
|
||
|
||
### 手動處理 Merge 衝突
|
||
|
||
當自動同步發生衝突時：
|
||
|
||
```bash
|
||
# 1. 切換到 dev 分支
|
||
git checkout dev
|
||
|
||
# 2. 添加 upstream remote（如果還沒有）
|
||
git remote add upstream https://github.com/C4illin/ConvertX.git
|
||
|
||
# 3. Fetch upstream
|
||
git fetch upstream main
|
||
|
||
# 4. Merge upstream
|
||
git merge upstream/main
|
||
|
||
# 5. 解決衝突
|
||
# ... 編輯衝突的檔案 ...
|
||
|
||
# 6. 提交並 push
|
||
git add .
|
||
git commit -m "Resolve merge conflicts with upstream"
|
||
git push origin dev
|
||
```
|
||
|
||
---
|
||
|
||
## ⚠️ 注意事項
|
||
|
||
1. **不會自動更新 `latest` tag** - 需要手動發布正式版本
|
||
2. **不會自動打 semver tag** - 需要手動建立 release
|
||
3. **`main` 分支不會被自動修改** - 只有 `dev` 會自動同步
|
||
4. **Smoke test 失敗時不會發布 image** - 確保品質
|
||
|
||
---
|
||
|
||
## 📊 Docker Image Tag 規則
|
||
|
||
| Tag 格式 | 說明 | 自動/手動 |
|
||
| ------------------- | ---------------------------------- | --------- |
|
||
| `upstream-YYYYMMDD` | Upstream 同步版（經過 smoke test） | 自動 |
|
||
| `vX.Y.Z` | 正式版本 | 手動 |
|
||
| `latest` | 最新穩定版 | 手動 |
|