先說結論：可行，但不該承諾零停機

較穩妥的方向是由宿主機執行原生排程，以固定映像摘要部署，再搭配持久化更新狀態與本機舊版回滾，不額外引入更新容器。映像參照可使用 OCI 格式支援的摘要形式。1

不過，跨網路查詢遠端摘要不能保證每次都在一秒內完成；目前是單一網關容器，重建時也不能保證零停機或在途請求完全不受影響。這份內容是設計草案與實作契約，尚未建立檔案、執行測試，也未操作兩台異地 VPS。

對正常運作的宿主機與 Docker，設計目標是更新失敗時自動回復。若宿主機斷電、Docker 無法使用，或回滾映像本身無法啟動，系統應留下錯誤並告警，不能宣稱一定能自行修復。

實作前要先確認的現況

• 發布工作流程接受 v主版本.次版本 格式，例如 v3.12，並發布 latest、3.12、v3.12 與提交短 SHA 等標籤；工作流程沒有自動維護名為 v3.x 的系列別名。流程雖設定四種架構，但這不代表某次發布已經成功。可核對 .github/workflows/build_docker.yml:19。
• 目前網關服務由原始碼建置、綁定本機 8080，並保留唯讀設定目錄；郵件服務使用記憶體儲存。因此更新時只處理網關、不重啟郵件容器，是必要的保護條件。可核對 docker-compose.yml:1。
• 發布映像使用根目錄入口，啟動時依賴本機模型註冊表設定；映像本身沒有包含該設定目錄。遠端部署仍須提供設定檔，不能只準備映像。可核對 Dockerfile:13 與 main.go:21。
• 根入口使用的模型目錄處理器讀取註冊表快照，不會發出真實聊天請求；健康端點則只回傳靜態存活資訊。因此，兩者都不能證明上游帳號已預熱，或真實聊天功能可用。不要把另一套處理器的驗證規則混用。可核對 internal/api/models.go:23、internal/api/chat.go:2078。
• 應用程式收到終止訊號後會取消服務上下文，HTTP 關閉窗口為五秒。只延長容器停止寬限時間，不能單獨保證長時間串流請求完成。可核對 main.go:233。

這次設計不修改郵件服務、不同步執行中的帳號狀態、不升級依賴、不從遠端取得原始碼，也不改變本機開發建置方式。它不保證兩台主機同時切換，也不提供真正無停機更新；若要求無損切換，還須另行設計雙實例、入口切換與連線排空。

更新器應如何運作

預計入口為 scripts/auto-update.sh，目前尚未建立。草案假設宿主機已安裝 Bash、Docker Engine、Compose 插件、curl、jq、flock，以及用來讀取映像清單的原生 Skopeo；實際作業系統與工具版本仍須在實作時確認。

更新器由受保護的宿主機帳號執行，直接操作本機 Docker，不把 Docker socket 或登錄檔憑證掛載到任何容器。要注意的是，能管理 Docker 的帳號仍具備宿主機管理權限；不掛載 socket 不代表消除了這項權限風險。

以摘要與交易狀態管理版本

• 追蹤標籤只用來發現版本；預設追蹤 latest。實際部署則固定使用「映像庫位址＋摘要」，避免標籤後續移動造成版本不確定。1
• 分開記錄多架構索引摘要、平台映像清單摘要，以及 Docker 本機映像 ID；這三種值不能直接互相比較。
• 保存目前已驗收映像、上一個可用映像、未完成交易，以及失敗摘要隔離紀錄。交易資料應包含新舊參照、本機映像 ID、舊容器 ID、設定指紋與目前操作階段。
• 更新前先從實際運作中的容器確認舊映像 ID，替舊映像加上專用本機保留標籤，並確認舊服務健康。回滾不得依賴重新連線下載舊版。
• 狀態檔採嚴格解析的資料格式，不執行檔案中的文字；先寫入同目錄暫存檔，再原子替換，並對關鍵狀態執行檔案與目錄持久化。單靠重新命名，不能當成斷電後仍可復原的保證。

建議的更新與回復順序

1. 以非阻塞方式取得固定檔案鎖；若已有另一個更新、復原、初始化或清理作業在執行，就安靜退出。所有維護操作共用同一把鎖。
2. 優先處理未完成交易，再查詢遠端。核對固定的 Compose 專案名稱、唯一網關容器、設定指紋與郵件容器身分；如果發現人工變更，就停止，不擅自接管。
3. 只讀取遠端映像清單並計算摘要，不先下載映像層。遇到網路、驗證或解析錯誤時保留現有服務並記錄失敗；不可把空摘要當成新版本。
4. 若摘要與已驗收版本相同，就不拉取、不重建，也不寫入更新紀錄。已隔離的失敗摘要也不應反覆部署，直到遠端出現新摘要或管理員解除隔離。
5. 拉取固定摘要，確認本機平台映像可用且磁碟空間足夠。此時舊網關仍繼續運作；拉取失敗不得觸碰運作中的容器。
6. 保留舊映像與相容設定，先持久化記錄「準備切換」，再只重建網關服務。
7. 檢查新容器使用的映像身分、容器運作狀態與應用程式探針；全部通過後，才將新版本提交為目前已驗收版本。
8. 若重建失敗，或健康檢查窗口結束時仍不合格，就開始回滾：使用本機保留的舊映像與原設定，只重建網關，再執行相同健康檢查。
9. 回滾成功後，恢復持久化部署參照、隔離失敗摘要並記錄事件。若回滾也失敗，保留復原材料、回報失敗並告警，不無限循環重啟。

以下是核心呼叫的草案示意，並非完整或已驗收的安裝腳本；持久化交易、身分核對與復原邏輯仍須補齊：

# 參數須來自經過驗證、一般帳號無法修改的設定。
exec 9>"$LOCK_FILE"
flock -n 9 || exit 0

# 只讀取清單；須先核實 Skopeo 的認證檔與原始清單行為。
timeout --kill-after=2s 15s \\
  skopeo inspect --authfile "$DOCKER_CONFIG/config.json" \\
  --raw "docker://$TRACK_IMAGE" \\
  </dev/null >"$MANIFEST_TMP"
# 先確認指令成功，再計算摘要；不可使用失敗後留下的部分輸出。

# NEW_REF 必須是已驗證的 ghcr.io/映像庫@sha256:摘要。
timeout --kill-after=5s 600s \\
  docker pull "$NEW_REF" </dev/null

# 執行前須已持久化交易紀錄，並確認本機回滾映像有效。
APP_IMAGE="$NEW_REF" timeout --kill-after=5s 60s \\
  docker compose --project-name "$PROJECT" \\
  --project-directory "$DEPLOY_DIR" -f "$COMPOSE_FILE" \\
  up -d --no-deps --no-build --pull never app </dev/null

# 失敗路徑：OLD_LOCAL_REF 是已保留並核驗的本機舊映像標籤。
APP_IMAGE="$OLD_LOCAL_REF" timeout --kill-after=5s 60s \\
  docker compose --project-name "$PROJECT" \\
  --project-directory "$DEPLOY_DIR" -f "$COMPOSE_FILE" \\
  up -d --no-deps --no-build --pull never app </dev/null

Compose 的 --no-deps、--no-build 與 --pull never，分別用來避免啟動相依服務、禁止建置，以及避免重建時額外拉取映像；操作目標也應只列出網關服務。2 不應重啟整個專案、刪除孤兒服務，或停止所有服務。

指令逾時不代表 Docker 背景操作已經停止。遇到逾時，必須先檢查實際容器狀態並協調復原，不能立刻啟動另一個互相競爭的切換程序。強制終止或斷電時，也不能只靠退出陷阱處理；應在下次啟動時依照已落盤的交易狀態優先復原。

健康檢查要驗證什麼

可先把下列數值當作候選設定：總檢查窗口 60 秒、單次連線逾時 1 秒、請求上限 3 秒、每兩秒輪詢一次，連續三次成功才提交。這些是待現場驗證的參數，不是實測結果。

• 呼叫本機模型目錄，要求 HTTP 200 且不跟隨重新導向；同時驗證 JSON 結構，避免把登入頁或代理錯誤頁誤判為成功。
• 確認實際網關容器使用的是候選映像，並檢查重啟計數是否持續增加，避免舊程序仍在回應而造成假通過。
• 是否要求模型目錄至少有一筆資料，應依目前註冊表契約決定，不要硬寫歷史上的十八筆作為門檻。
• 可以補充健康端點檢查，但不應自動發出會消耗額度的真實聊天請求。真實業務可用性應另行驗收。

遠端部署與 GHCR 憑證

只修改異地部署副本中的映像來源，保留原本的連接埠、記憶體限制、日誌、環境變數、唯讀設定掛載與郵件設定；不要覆蓋本機開發用的 docker-compose.yml。原始網關建置欄位可參考 docker-compose.yml:26。

以下只展示要替換的片段，不是完整 Compose 設定：

services:
  app:
    image: "${APP_IMAGE:?必須提供已固定的映像參照}"
    pull_policy: never

遠端部署目錄仍須保留完整服務定義，並移除網關的 build 欄位。持久化的映像參照應是已驗收的摘要或回滾用本機標籤；不要讓人工重啟時自動退回 latest。

• 固定並核對既有 Compose 專案名稱，避免意外建立新網路或改變郵件服務的連線關係。本機與兩台遠端的專案名稱不應假設相同。
• 保留實際遠端環境變數。Compose 插值設定與容器執行環境不同，不能假設變數放進環境檔後就會自動進入容器。
• 目前設定明確啟用兩項實驗功能，而專案事實基線保留預設關閉的界線；這次不替使用者變更開關。部署前應核對遠端值，不能把本機設定視為遠端現況。可參考 docker-compose.yml:38 與 _bmad-output/project-context.md:246。
• 遠端只需部署設定、執行設定與預先建置的映像，不需要檢出原始碼或取得程式碼儲存庫的寫入權限。若新版本需要不相容的設定遷移，必須先提出可逆方案，否則不應自動發布。

若 GHCR 映像庫為私有，拉取可使用具備套件讀取權限的傳統個人存取權杖（PAT），並設定 read:packages；也要確認該帳戶確實有權讀取目標套件。組織若要求 SSO，還須完成相應授權。不要把 CI 的寫入權杖交給 VPS，也不要授予套件寫入、刪除或原始碼寫入權限。9

建議每台 VPS 使用各自可撤銷的唯讀憑證，透過標準輸入完成 Docker 登入，避免把權杖放進命令參數或稽核日誌。登入設定應存放於更新器專用、僅管理員可讀的目錄，並讓更新器與清單讀取工具使用同一份經核驗的認證設定。憑證不應傳入網關或郵件容器；還應設定到期提醒與撤銷流程。驗證失敗時只停止更新，不影響舊服務。

用 systemd 排程，分批更新兩台主機

草案優先採用 systemd，預計提供 deploy/systemd/aurora-update.service 與 deploy/systemd/aurora-update.timer；以下只是安裝示例，尚未安裝或啟用。

[Unit]
Description=Aurora 原生映像更新與復原
After=docker.service network-online.target
Wants=network-online.target

[Service]
Type=oneshot
User=root
WorkingDirectory=/opt/aurora
Environment=DOCKER_CONFIG=/etc/aurora-updater/docker
ExecStart=/opt/aurora/scripts/auto-update.sh
TimeoutStartSec=20min
UMask=0077
Nice=10
IOSchedulingClass=idle
NoNewPrivileges=yes
StandardOutput=journal
StandardError=journal

[Unit]
Description=Aurora 映像更新定時檢查

[Timer]
OnBootSec=1min
OnUnitInactiveSec=5min
RandomizedDelaySec=30s
AccuracySec=1s
Unit=aurora-update.service

[Install]
WantedBy=timers.target

啟用排程前，先安裝依賴、核對設定、建立健康的舊版錨點並完成演練；這份草案不會自動執行安裝或啟動排程。採用前一次服務結束後再計時，並搭配檔案鎖；兩台主機應錯開執行，避免同時下載或一起承受升級故障。

排程代表最終會同步，不代表原子同步。若某台主機回滾後暫時停留在舊版，這是保護措施，不應為了版本一致而強迫重試有問題的映像。降低更新器優先權也不代表 Docker 解壓縮映像時的 CPU 峰值一定受控，低規格主機仍須實測資源門檻。

「無更新時保持安靜」可定義為不輸出業務訊息、不新增更新歷史；systemd 仍可能記錄服務啟動與結束等生命週期事件。

稽核紀錄與映像清理

稽核紀錄建議包含 UTC 時間、節點識別、交易識別、新舊摘要、操作階段、耗時、健康檢查結果與回滾結果。不得記錄憑證、完整環境變數、郵件帳號或回應本文。

更新器專用日誌可考慮使用 logrotate 每週輪替，超過 1 MB 時提前輪替，壓縮並保留 26 份；這是待確認的保留政策，不應順帶修改宿主機的全域日誌設定。

映像清理不要使用全域清理或卷清理。每週作業只處理更新器登記為自有的歷史映像，並共用更新交易鎖。永久保留目前版本、上一個可用版本，以及未完成交易會用到的映像。刪除前還要排除任何現存容器正在使用的映像與其他用途的標籤。

對超過候選保留期十四天的自有歷史映像，先移除自有保留標籤，再嘗試非強制刪除；刪除失敗就保留並記錄，不強制移除。即使映像顯示為懸空，也不能直接認定它不是人工保留的回滾材料。若拉取前磁碟不足，應放棄升級，而不是刪除唯一的回滾錨點來騰出空間。

分階段驗收：先在一台主機演練

1. 確認部署條件： 核對兩台 VPS 的實際平台、工具版本、Compose 專案名稱、設定掛載、憑證讀取權限與目前健康映像，建立可復原的初始錨點。
2. 完成更新器： 實作摘要檢查、持久化交易、單一服務切換、健康輪詢、回滾與失敗摘要隔離；先在獲准的隔離環境演練，不直接操作正式環境。
3. 接上維護機制： 加入定時器、稽核輪替與限範圍清理，再驗證重入、逾時、異常終止與重新開機後的復原。
4. 逐台灰度： 第一台完成真實更新與回滾驗收後，再啟用第二台。

驗收至少應包括：

• 摘要不變： 不下載映像層、不重建、不新增更新紀錄；分別量測網路檢查與本機比對時間。沒有現場數據，就不能宣稱每次端到端檢查都能在一秒內完成。
• 服務隔離： 成功升級與失敗回滾前後，郵件容器 ID、啟動時間及預置郵件均保持一致。
• 回滾能力： 以壞映像、非 200 回應、健康檢查逾時與重建失敗做測試；也要確認切斷 GHCR 連線後仍能從本機舊映像回復。
• 中斷後復原： 在交易各關鍵階段終止更新器，確認下次啟動會先復原，且不會反覆部署已隔離的壞摘要。
• 安全與資源： 確認沒有建置、沒有 socket 掛載、沒有憑證外洩；並發觸發時只有一筆交易，清理也不會刪除受保護映像。

最後的判斷

在接受網關切換時可能短暫中斷、把「每次一秒內完成」改為現場效能目標，並先核實遠端部署現況的前提下，宿主機原生排程加上摘要固定與本機回滾，是值得實作的方案。

但目前沒有兩台 VPS 的實際執行回報，因此兼容性、檢查速度與完整回滾流程都還未獲驗證。本次只完成方案草案，沒有產生 ADR、修改部署檔案或覆蓋既有計畫。

先說結論：可行，但不該承諾零停機

較穩妥的方向是由宿主機執行原生排程，以固定映像摘要部署，再搭配持久化更新狀態與本機舊版回滾，不額外引入更新容器。映像參照可使用 OCI 格式支援的摘要形式。1

不過，跨網路查詢遠端摘要不能保證每次都在一秒內完成；目前是單一網關容器，重建時也不能保證零停機或在途請求完全不受影響。這份內容是設計草案與實作契約，尚未建立檔案、執行測試，也未操作兩台異地 VPS。

對正常運作的宿主機與 Docker，設計目標是更新失敗時自動回復。若宿主機斷電、Docker 無法使用，或回滾映像本身無法啟動，系統應留下錯誤並告警，不能宣稱一定能自行修復。

實作前要先確認的現況

• 發布工作流程接受 v主版本.次版本 格式，例如 v3.12，並發布 latest、3.12、v3.12 與提交短 SHA 等標籤；工作流程沒有自動維護名為 v3.x 的系列別名。流程雖設定四種架構，但這不代表某次發布已經成功。可核對 .github/workflows/build_docker.yml:19。
• 目前網關服務由原始碼建置、綁定本機 8080，並保留唯讀設定目錄；郵件服務使用記憶體儲存。因此更新時只處理網關、不重啟郵件容器，是必要的保護條件。可核對 docker-compose.yml:1。
• 發布映像使用根目錄入口，啟動時依賴本機模型註冊表設定；映像本身沒有包含該設定目錄。遠端部署仍須提供設定檔，不能只準備映像。可核對 Dockerfile:13 與 main.go:21。
• 根入口使用的模型目錄處理器讀取註冊表快照，不會發出真實聊天請求；健康端點則只回傳靜態存活資訊。因此，兩者都不能證明上游帳號已預熱，或真實聊天功能可用。不要把另一套處理器的驗證規則混用。可核對 internal/api/models.go:23、internal/api/chat.go:2078。
• 應用程式收到終止訊號後會取消服務上下文，HTTP 關閉窗口為五秒。只延長容器停止寬限時間，不能單獨保證長時間串流請求完成。可核對 main.go:233。

這次設計不修改郵件服務、不同步執行中的帳號狀態、不升級依賴、不從遠端取得原始碼，也不改變本機開發建置方式。它不保證兩台主機同時切換，也不提供真正無停機更新；若要求無損切換，還須另行設計雙實例、入口切換與連線排空。

更新器應如何運作

預計入口為 scripts/auto-update.sh，目前尚未建立。草案假設宿主機已安裝 Bash、Docker Engine、Compose 插件、curl、jq、flock，以及用來讀取映像清單的原生 Skopeo；實際作業系統與工具版本仍須在實作時確認。

更新器由受保護的宿主機帳號執行，直接操作本機 Docker，不把 Docker socket 或登錄檔憑證掛載到任何容器。要注意的是，能管理 Docker 的帳號仍具備宿主機管理權限；不掛載 socket 不代表消除了這項權限風險。

以摘要與交易狀態管理版本

• 追蹤標籤只用來發現版本；預設追蹤 latest。實際部署則固定使用「映像庫位址＋摘要」，避免標籤後續移動造成版本不確定。1
• 分開記錄多架構索引摘要、平台映像清單摘要，以及 Docker 本機映像 ID；這三種值不能直接互相比較。
• 保存目前已驗收映像、上一個可用映像、未完成交易，以及失敗摘要隔離紀錄。交易資料應包含新舊參照、本機映像 ID、舊容器 ID、設定指紋與目前操作階段。
• 更新前先從實際運作中的容器確認舊映像 ID，替舊映像加上專用本機保留標籤，並確認舊服務健康。回滾不得依賴重新連線下載舊版。
• 狀態檔採嚴格解析的資料格式，不執行檔案中的文字；先寫入同目錄暫存檔，再原子替換，並對關鍵狀態執行檔案與目錄持久化。單靠重新命名，不能當成斷電後仍可復原的保證。

建議的更新與回復順序

1. 以非阻塞方式取得固定檔案鎖；若已有另一個更新、復原、初始化或清理作業在執行，就安靜退出。所有維護操作共用同一把鎖。
2. 優先處理未完成交易，再查詢遠端。核對固定的 Compose 專案名稱、唯一網關容器、設定指紋與郵件容器身分；如果發現人工變更，就停止，不擅自接管。
3. 只讀取遠端映像清單並計算摘要，不先下載映像層。遇到網路、驗證或解析錯誤時保留現有服務並記錄失敗；不可把空摘要當成新版本。
4. 若摘要與已驗收版本相同，就不拉取、不重建，也不寫入更新紀錄。已隔離的失敗摘要也不應反覆部署，直到遠端出現新摘要或管理員解除隔離。
5. 拉取固定摘要，確認本機平台映像可用且磁碟空間足夠。此時舊網關仍繼續運作；拉取失敗不得觸碰運作中的容器。
6. 保留舊映像與相容設定，先持久化記錄「準備切換」，再只重建網關服務。
7. 檢查新容器使用的映像身分、容器運作狀態與應用程式探針；全部通過後，才將新版本提交為目前已驗收版本。
8. 若重建失敗，或健康檢查窗口結束時仍不合格，就開始回滾：使用本機保留的舊映像與原設定，只重建網關，再執行相同健康檢查。
9. 回滾成功後，恢復持久化部署參照、隔離失敗摘要並記錄事件。若回滾也失敗，保留復原材料、回報失敗並告警，不無限循環重啟。

以下是核心呼叫的草案示意，並非完整或已驗收的安裝腳本；持久化交易、身分核對與復原邏輯仍須補齊：

# 參數須來自經過驗證、一般帳號無法修改的設定。
exec 9>"$LOCK_FILE"
flock -n 9 || exit 0

# 只讀取清單；須先核實 Skopeo 的認證檔與原始清單行為。
timeout --kill-after=2s 15s \\
  skopeo inspect --authfile "$DOCKER_CONFIG/config.json" \\
  --raw "docker://$TRACK_IMAGE" \\
  </dev/null >"$MANIFEST_TMP"
# 先確認指令成功，再計算摘要；不可使用失敗後留下的部分輸出。

# NEW_REF 必須是已驗證的 ghcr.io/映像庫@sha256:摘要。
timeout --kill-after=5s 600s \\
  docker pull "$NEW_REF" </dev/null

# 執行前須已持久化交易紀錄，並確認本機回滾映像有效。
APP_IMAGE="$NEW_REF" timeout --kill-after=5s 60s \\
  docker compose --project-name "$PROJECT" \\
  --project-directory "$DEPLOY_DIR" -f "$COMPOSE_FILE" \\
  up -d --no-deps --no-build --pull never app </dev/null

# 失敗路徑：OLD_LOCAL_REF 是已保留並核驗的本機舊映像標籤。
APP_IMAGE="$OLD_LOCAL_REF" timeout --kill-after=5s 60s \\
  docker compose --project-name "$PROJECT" \\
  --project-directory "$DEPLOY_DIR" -f "$COMPOSE_FILE" \\
  up -d --no-deps --no-build --pull never app </dev/null

Compose 的 --no-deps、--no-build 與 --pull never，分別用來避免啟動相依服務、禁止建置，以及避免重建時額外拉取映像；操作目標也應只列出網關服務。2 不應重啟整個專案、刪除孤兒服務，或停止所有服務。

指令逾時不代表 Docker 背景操作已經停止。遇到逾時，必須先檢查實際容器狀態並協調復原，不能立刻啟動另一個互相競爭的切換程序。強制終止或斷電時，也不能只靠退出陷阱處理；應在下次啟動時依照已落盤的交易狀態優先復原。

健康檢查要驗證什麼

可先把下列數值當作候選設定：總檢查窗口 60 秒、單次連線逾時 1 秒、請求上限 3 秒、每兩秒輪詢一次，連續三次成功才提交。這些是待現場驗證的參數，不是實測結果。

• 呼叫本機模型目錄，要求 HTTP 200 且不跟隨重新導向；同時驗證 JSON 結構，避免把登入頁或代理錯誤頁誤判為成功。
• 確認實際網關容器使用的是候選映像，並檢查重啟計數是否持續增加，避免舊程序仍在回應而造成假通過。
• 是否要求模型目錄至少有一筆資料，應依目前註冊表契約決定，不要硬寫歷史上的十八筆作為門檻。
• 可以補充健康端點檢查，但不應自動發出會消耗額度的真實聊天請求。真實業務可用性應另行驗收。

遠端部署與 GHCR 憑證

只修改異地部署副本中的映像來源，保留原本的連接埠、記憶體限制、日誌、環境變數、唯讀設定掛載與郵件設定；不要覆蓋本機開發用的 docker-compose.yml。原始網關建置欄位可參考 docker-compose.yml:26。

以下只展示要替換的片段，不是完整 Compose 設定：

services:
  app:
    image: "${APP_IMAGE:?必須提供已固定的映像參照}"
    pull_policy: never

遠端部署目錄仍須保留完整服務定義，並移除網關的 build 欄位。持久化的映像參照應是已驗收的摘要或回滾用本機標籤；不要讓人工重啟時自動退回 latest。

• 固定並核對既有 Compose 專案名稱，避免意外建立新網路或改變郵件服務的連線關係。本機與兩台遠端的專案名稱不應假設相同。
• 保留實際遠端環境變數。Compose 插值設定與容器執行環境不同，不能假設變數放進環境檔後就會自動進入容器。
• 目前設定明確啟用兩項實驗功能，而專案事實基線保留預設關閉的界線；這次不替使用者變更開關。部署前應核對遠端值，不能把本機設定視為遠端現況。可參考 docker-compose.yml:38 與 _bmad-output/project-context.md:246。
• 遠端只需部署設定、執行設定與預先建置的映像，不需要檢出原始碼或取得程式碼儲存庫的寫入權限。若新版本需要不相容的設定遷移，必須先提出可逆方案，否則不應自動發布。

若 GHCR 映像庫為私有，拉取可使用具備套件讀取權限的傳統個人存取權杖（PAT），並設定 read:packages；也要確認該帳戶確實有權讀取目標套件。組織若要求 SSO，還須完成相應授權。不要把 CI 的寫入權杖交給 VPS，也不要授予套件寫入、刪除或原始碼寫入權限。9

建議每台 VPS 使用各自可撤銷的唯讀憑證，透過標準輸入完成 Docker 登入，避免把權杖放進命令參數或稽核日誌。登入設定應存放於更新器專用、僅管理員可讀的目錄，並讓更新器與清單讀取工具使用同一份經核驗的認證設定。憑證不應傳入網關或郵件容器；還應設定到期提醒與撤銷流程。驗證失敗時只停止更新，不影響舊服務。

用 systemd 排程，分批更新兩台主機

草案優先採用 systemd，預計提供 deploy/systemd/aurora-update.service 與 deploy/systemd/aurora-update.timer；以下只是安裝示例，尚未安裝或啟用。

[Unit]
Description=Aurora 原生映像更新與復原
After=docker.service network-online.target
Wants=network-online.target

[Service]
Type=oneshot
User=root
WorkingDirectory=/opt/aurora
Environment=DOCKER_CONFIG=/etc/aurora-updater/docker
ExecStart=/opt/aurora/scripts/auto-update.sh
TimeoutStartSec=20min
UMask=0077
Nice=10
IOSchedulingClass=idle
NoNewPrivileges=yes
StandardOutput=journal
StandardError=journal

[Unit]
Description=Aurora 映像更新定時檢查

[Timer]
OnBootSec=1min
OnUnitInactiveSec=5min
RandomizedDelaySec=30s
AccuracySec=1s
Unit=aurora-update.service

[Install]
WantedBy=timers.target

啟用排程前，先安裝依賴、核對設定、建立健康的舊版錨點並完成演練；這份草案不會自動執行安裝或啟動排程。採用前一次服務結束後再計時，並搭配檔案鎖；兩台主機應錯開執行，避免同時下載或一起承受升級故障。

排程代表最終會同步，不代表原子同步。若某台主機回滾後暫時停留在舊版，這是保護措施，不應為了版本一致而強迫重試有問題的映像。降低更新器優先權也不代表 Docker 解壓縮映像時的 CPU 峰值一定受控，低規格主機仍須實測資源門檻。

「無更新時保持安靜」可定義為不輸出業務訊息、不新增更新歷史；systemd 仍可能記錄服務啟動與結束等生命週期事件。

稽核紀錄與映像清理

稽核紀錄建議包含 UTC 時間、節點識別、交易識別、新舊摘要、操作階段、耗時、健康檢查結果與回滾結果。不得記錄憑證、完整環境變數、郵件帳號或回應本文。

更新器專用日誌可考慮使用 logrotate 每週輪替，超過 1 MB 時提前輪替，壓縮並保留 26 份；這是待確認的保留政策，不應順帶修改宿主機的全域日誌設定。

映像清理不要使用全域清理或卷清理。每週作業只處理更新器登記為自有的歷史映像，並共用更新交易鎖。永久保留目前版本、上一個可用版本，以及未完成交易會用到的映像。刪除前還要排除任何現存容器正在使用的映像與其他用途的標籤。

對超過候選保留期十四天的自有歷史映像，先移除自有保留標籤，再嘗試非強制刪除；刪除失敗就保留並記錄，不強制移除。即使映像顯示為懸空，也不能直接認定它不是人工保留的回滾材料。若拉取前磁碟不足，應放棄升級，而不是刪除唯一的回滾錨點來騰出空間。

分階段驗收：先在一台主機演練

1. 確認部署條件： 核對兩台 VPS 的實際平台、工具版本、Compose 專案名稱、設定掛載、憑證讀取權限與目前健康映像，建立可復原的初始錨點。
2. 完成更新器： 實作摘要檢查、持久化交易、單一服務切換、健康輪詢、回滾與失敗摘要隔離；先在獲准的隔離環境演練，不直接操作正式環境。
3. 接上維護機制： 加入定時器、稽核輪替與限範圍清理，再驗證重入、逾時、異常終止與重新開機後的復原。
4. 逐台灰度： 第一台完成真實更新與回滾驗收後，再啟用第二台。

驗收至少應包括：

• 摘要不變： 不下載映像層、不重建、不新增更新紀錄；分別量測網路檢查與本機比對時間。沒有現場數據，就不能宣稱每次端到端檢查都能在一秒內完成。
• 服務隔離： 成功升級與失敗回滾前後，郵件容器 ID、啟動時間及預置郵件均保持一致。
• 回滾能力： 以壞映像、非 200 回應、健康檢查逾時與重建失敗做測試；也要確認切斷 GHCR 連線後仍能從本機舊映像回復。
• 中斷後復原： 在交易各關鍵階段終止更新器，確認下次啟動會先復原，且不會反覆部署已隔離的壞摘要。
• 安全與資源： 確認沒有建置、沒有 socket 掛載、沒有憑證外洩；並發觸發時只有一筆交易，清理也不會刪除受保護映像。

最後的判斷

在接受網關切換時可能短暫中斷、把「每次一秒內完成」改為現場效能目標，並先核實遠端部署現況的前提下，宿主機原生排程加上摘要固定與本機回滾，是值得實作的方案。

但目前沒有兩台 VPS 的實際執行回報，因此兼容性、檢查速度與完整回滾流程都還未獲驗證。本次只完成方案草案，沒有產生 ADR、修改部署檔案或覆蓋既有計畫。