部署、備份與恢復

正式環境的設定要點、不可變鏡像發佈流程、回滾操作，以及獨立資料備份的邊界。

生產發佈前準備

正式環境的權威設定檔是 infrastructure/alicloud/docker-compose.core.yml，發佈和回滾的入口分別是同目錄下的 deploy.sh 與 rollback.sh。環境變數模板為 env.example。由實例運營者在受保護的位置設定正式環境的值，不應直接複製倉庫的歷史環境檔、資料庫備份或開發預設值。

正式環境需要 Core 資料庫、Redis、物件存儲、私有郵件轉接器、Web、Nginx 和觀測服務。請設定自己的網域、HTTPS、持久卷權限和網路邊界。這份文件不會指定他人的伺服器位址、SSH 身份或部署目標。

核對關鍵設定

設定	用途與要求
`CORE_DATABASE_URL`、`REDIS_URL`	目前 Core 和協調服務的連線資訊；不能用舊拆分式服務的 schema 代替
`CORE_SESSION_SECRET`、`OTP_PEPPER`、`STORAGE_GRANT_SECRET`、`CORE_CALLBACK_SECRET`	正式環境至少 32 個 UTF-8 位元組，四項彼此不同，不能使用開發預設值
`EMAIL_PROVIDER_URL`、`EMAIL_PROVIDER_TOKEN`	Core 到私有郵件投遞轉接器的連線；正式環境 token 至少 32 位元組
`DEFAULT_USER_QUOTA_BYTES`	非負十進位整數，明確定義新使用者的預設額度
`CORE_ADMIN_EMAILS`	新使用者首次建立帳戶時的管理員郵箱設定；不會自動改寫已有角色
`REGISTRY`、`IMAGE_TAG`	已通過發佈門檻的鏡像倉庫與固定提交標籤

郵件轉接器還需要按照它自己的模板設定真實的投遞提供商；fake-email 只適用於測試。不要因為 API 接受了發送請求就宣告真實郵箱的驗收已通過。

部署與發佈證據

先通過品質檢查、隔離 smoke 測試、瀏覽器驗收，並發佈對應的鏡像。IMAGE_TAG 必須是 sha- 加上 40 位小寫十六進位的真實已發佈提交雜湊值，不要用 main、latest 或本地未發佈的提交代替。

: "${IMAGE_TAG:?Set the tested immutable release tag}"
bash infrastructure/alicloud/deploy.sh "$IMAGE_TAG"

腳本會執行發佈鎖、鏡像摘要解析、遷移、啟動、健康檢查和版本核對，並以原子方式記錄 current.env 與歷史 manifest。如果偵測到併發發佈，會以退出碼 75 拒絕——請等待現有發佈結束，不要刪除鎖檔案強行併發。

上線後請核對實際鏡像摘要與 manifest 是否吻合、服務健康狀態，以及版本資訊，並完成真實郵箱登入、小檔案上傳、後台完成、下載內容比對、公開/私有權限檢查等驗收項目。公開的 /healthz 只檢查 Nginx 邊界；/version、/live、/ready、/metrics 和 /api/v1/internal/* 屬於私有或維運介面，不要為了外部探針而將它們公開。

回滾不是恢複資料庫

回滾目標必須存在於歷史 manifest 中。設定好 TARGET_TAG 為那個經過驗證的標籤後執行：

: "${TARGET_TAG:?Set a recorded rollback release tag}"
bash infrastructure/alicloud/rollback.sh "$TARGET_TAG"

腳本同樣遵循不可變鏡像和健康檢查的合約。應用回滾不保證自動逆轉資料遷移或恢復已被覆寫的檔案；遷移的相容性應在發佈前就先確認。絕對不要透過刪除持久卷的方式來「回滾」。

備份與恢復

版本列表、鏡像和發佈 manifest 都不是完整的使用者資料備份。運營者需要分別保護資料庫、物件資料、必要設定和金鑰，定義一致性時間點與恢復順序，並在隔離環境中實際演練。不要將備份提交到原始碼庫或上傳成公開的檔案附件。

目前的指南沒有可驗證的統一一鍵備份命令，也不承諾零資料遺失、固定的 RPO/RTO 或自動災難恢復。每次備份都請記錄其範圍、校驗和、存取權限和實際恢復結果；僅僅有備份檔案不能證明服務可以被恢復。