Appearance
升級與遷移
Argus 用 語意化版號：MAJOR.MINOR.PATCH。 升級分三種風險級別：Patch（低）／ Minor（中）／ Major（高）。
升級類型
| 類型 | 範例 | 含 schema migration？ | 含破壞性變更？ | 風險 |
|---|---|---|---|---|
| Patch | 3.18.2 → 3.18.5 | 否 | 否 | 低 |
| Minor | 3.17.x → 3.18.x | 可能 | 否（向後相容） | 中 |
| Major | 3.x → 4.x | 是 | 可能 | 高 |
| 跨多 Minor 跳版 | 3.16 → 3.18 | 是（連跑） | — | 中-高（不建議） |
一律逐 minor 升級。跨 minor 跳版時 schema migration 串連執行，途中失敗很難回頭。
通用 SOP
text
┌─────────────────────────────────────────────────┐
│ 1. 讀 release notes │
│ 2. 在 staging / pre-prod 完整驗證 │
│ 3. 安排升級窗口 + 公告 │
│ 4. 備份 metastore（必須） │
│ 5. 凍結變更（暫停 in-flight rollout） │
│ 6. 升級 binary / image │
│ 7. 啟動，自動跑 migration │
│ 8. Smoke test │
│ 9. 解除凍結 │
│ 10. 觀察 24h │
└─────────────────────────────────────────────────┘每一步都不可省。
1. 讀 release notes
對應版本的 release notes 通常含：
- 新功能
- Bug fix
- 破壞性變更（即便是 minor 升級也可能有 deprecate-notice）
- 必要的 schema migration
- 升級後需手動執行的動作（rare）
2. 在 staging 驗證
完整流程：
bash
# 在隔離環境
docker compose pull argus:<new-version>
docker compose up -d argus
# 跑 smoke test
docs-site/getting-started/first-plan.md 列出的步驟
# 驗證主要 user 流程
- 登入 / SSO
- 提交 plan + plan check
- 審批
- 執行 rollout
- 查 audit log任何一步異常 → STOP，不要升 production。
3. 安排升級窗口
- 走 高風險變更窗口 — Argus 自身升級視同高風險變更
- 在 #ops 公告：版本號、預估時長、回退計畫
- 通知所有相依的 user（DBA / 開發者 / 稽核）
4. 備份
bash
# 必跑：metastore 全量備份
docs-site/operations/backup-restore.md 列出的步驟備份完做完整性檢查：
bash
pg_restore --list <backup-file> > /tmp/check.toc
wc -l /tmp/check.toc # 對比歷史備份的 line count沒備份就升級 = 沒回退選項。永遠先備份。
5. 凍結變更
Settings → Emergency Pause 切 ON，或：
bash
curl -X PATCH -H "Authorization: Bearer $TOKEN" \
-d '{"value":{"emergencyPause":{"enabled":true,"reason":"upgrade-3.18"}}}' \
"$ARGUS/v1/settings/EMERGENCY_PAUSE?updateMask=emergencyPause"確認所有 running task 結束或被暫停。
6. 升級 binary / image
bash
# 改 docker-compose.yml 的 image tag
sed -i.bak 's|argus:3\.17\.5|argus:3.18.2|' docker-compose.yml
# 拉新 image + 重啟
docker compose pull argus
docker compose up -d argusbash
kubectl set image deploy/argus argus=<registry>/argus:3.18.2
# 等 rollout 完成
kubectl rollout status deploy/argus --timeout=10mbash
# 備份舊 binary
mv /usr/local/bin/argus /usr/local/bin/argus.old
# 安裝新版
curl -L https://<release-url>/argus-3.18.2-linux-amd64.tar.gz | tar xz
mv argus /usr/local/bin/argus
# 重啟
systemctl restart argus7. 啟動 + migration
Argus 啟動時自動跑 metastore migration。觀察 startup log：
bash
journalctl -u argus -f | grep -i 'migration'
# 或
docker compose logs -f argus | grep -i 'migration'預期看到：
INFO migrator: applying 3.18/9006##audit_rls_and_roles.sql
INFO migrator: applied 3.18 (8 files)
INFO argus: server listening on :8080⚠️ 看到 migration failed → 不要 嘗試重啟，先做以下排查：
- 看完整 error
- 連 metastore 確認 schema 處於哪個狀態
- 必要時走 復原
8. Smoke test
bash
# Health
curl -fs https://argus.corp.example/healthz
curl -fs https://argus.corp.example/readyz
# 版本
curl -s https://argus.corp.example/v1/actuator/info | jq '.version'
# 主流程（手動或自動）
- 登入
- 提交一個 dry-run plan
- 看 audit log 有寫進新 entry9. 解除凍結
bash
curl -X PATCH -H "Authorization: Bearer $TOKEN" \
-d '{"value":{"emergencyPause":{"enabled":false}}}' \
"$ARGUS/v1/settings/EMERGENCY_PAUSE?updateMask=emergencyPause"10. 觀察 24h
關鍵 metric：
- 5xx 率
- p99 latency
- task 失敗率
- 登入失敗率
任何異常 → 評估是否需 回退。
升級失敗的復原
降級不被支援（schema 不可降）。回退 = 從備份還原 + 跑舊版 binary。
text
1. 凍結新版 server (stop)
2. 把 metastore 從步驟 4 的備份還原（[備份與災備](/operations/backup-restore)）
3. 啟動舊版 binary / image
4. Smoke test
5. 公告事故 + 排升級失敗覆盤因此第 4 步備份不能省。
Major 升級的額外注意
例：3.x → 4.x。本節為 roadmap reference。
- 通常含多版 migration 串連
- 通常含 proto 破壞性變更（重新生成 client）
- 建議雙 minor接力升級：先升 3.x 最後一版（補 deprecate notice），確認所有 client 都跑得動，再跨到 4.x
- 升級窗口拉長到至少 4 小時
- 提前一週通知，公告完整變更清單
不要做的事
| 反模式 | 為什麼 |
|---|---|
| 跨多 minor 跳版 | migration 串連執行，途中失敗很難回頭 |
| 跳過 staging 直接升 prod | 沒驗證的升級 = 賭運氣 |
| 升級當下不備份 | 還原是唯一回退路徑 |
| 升級期間照常開放變更 | 升級進行中跑 rollout = 二次事故 |
用 --force / --no-verify 繞過 migration error | 會留下永久 schema drift，往後每次升級都地雷 |