aca-web-publish

ACA Web Publish

使用此技能將私有靜態內容部署到 Azure，而無需公開 Blob Storage。預設模式為：

1. 靜態內容上傳至私人 Azure Blob Storage 並設定為 Cold 層。
2. 一個小型 Docker 映像在 Azure Container Apps (ACA) 中執行。
3. 該容器實作應用層級驗證，並透過 ACA 串流 Blob 內容。
4. ACA 使用系統指派的受控識別，並具有 Storage Blob Data Reader 角色。
5. 瀏覽器使用者永遠不會收到 blob 金鑰、SAS URL、直接 blob URL 或儲存體帳戶金鑰。
6. 不使用 ACA Easy Auth。

強制性的互動模式

除非使用者已明確提供所有選擇，否則請在實作前使用 ask_user 工具。收集以下資訊：

決策項目	建議預設值
驗證提供者	GitHub
允許的使用者	無預設值；若留空，則無人能登入
登錄模式	若儲存庫可託管公開套件，則使用 GHCR 公開映像；若解決方案須為私有/獨立，則使用 ACR
自訂 DNS	若使用者有 Azure DNS 區域，則優先使用自訂 DNS
內容目錄	詢問本機路徑
Azure 資源名稱	產生安全的預設值，但若變更既有基礎結構須先詢問

在詢問任何 OAuth 用戶端 ID 或密碼之前，先確定最終的公開主機名稱是否已知：

• 使用自訂 DNS 時，先詢問主機名稱和 DNS 區域。然後，在收集用戶端 ID/密碼之前，提供使用者該自訂主機名稱的提供者入口網站連結和確切重新導向 URL。
• 使用 ACA 內建主機名稱時，由於主機名稱在 ACA 建立前未知，請勿先詢問 OAuth 用戶端 ID/密碼。先建立一個引導 ACA 端點，擷取其 https://<app>.<region>.azurecontainerapps.io URL，然後在收集用戶端 ID/密碼之前，提供使用者該提供者入口網站連結和確切重新導向 URL。

切勿要求使用者從佔位 URL 建立 OAuth 應用程式。使用 ask_user 收集用戶端 ID/密碼；切勿在最終回應中回顯密碼，也絕不提交它們。

主要預設值

• 驗證提供者預設為 github。
• 支援的驗證提供者：github、google、entra、none。
• none 僅用於明確公開或內部測試部署。
• 若啟用驗證但未設定允許的使用者，則拒絕所有人。
• 使用逗號分隔允許的使用者：
  • GitHub：使用者代號，例如 tkubica12,octocat。
  • Google：電子郵件地址。
  • Entra：物件識別碼或 UPN/電子郵件地址，視實作而定。
• 可選擇為 GitHub 使用電子郵件允許清單作為深度防禦，但使用者代號是主要的 GitHub 身分識別。
• 儲存體帳戶必須保持 publicNetworkAccess=Enabled，除非 ACA 具有通往 Blob 的 VNet/私人端點路由。保持 allowBlobPublicAccess=false 和 allowSharedKeyAccess=false。
• ACA 應小型化：從 0.25 CPU 和 0.5Gi 記憶體開始。
• 在支援的 ACA/KEDA CLI 範圍內，ACA 應縮放至零，並具有 60 分鐘的冷卻/閒置行為；否則使用最小複本 0 並記錄限制。

登錄選擇

GHCR 模式

當映像僅包含 Proxy/驗證程式碼且不含內容時，使用 GHCR。映像/套件必須是公開的，以便 ACA 無需憑證即可提取。從 assets/publish-web-image.yml 建立 GitHub Actions 工作流程，以建置並推送映像。

ACR 模式

當使用者想要完全私有且獨立的 Azure 解決方案時，使用 ACR。建立 ACR，於其中建置或推送映像，並授予 ACA 受控識別 AcrPull 權限。

對於 ACR，請避免在設定 AcrPull 之前直接從私有映像建立 ACA。首先使用公開引導映像和系統指派身分識別建立應用程式，授予該身分識別 AcrPull 權限，使用 --identity system 設定登錄，然後將應用程式更新為 ACR 映像。

從 Windows 終端機使用 az acr build 建置時，請使用 --no-logs 以避免 Azure CLI 日誌串流發生 Unicode/主控台編碼失敗；請改為查詢建置結果。

OAuth 主機名稱時機

OAuth 應用程式註冊必須在首頁/原始 URL 和回呼 URL 中使用最終瀏覽器可見的主機。

自訂 DNS 流程

1. 詢問自訂主機名稱和 DNS 區域。
2. 顯示提供者註冊連結和確切 URL，例如 https://site.example.com 和 https://site.example.com/oauth/github/callback。
3. 收集用戶端 ID 和密碼。
4. 部署 ACA、DNS、驗證設定、內容和憑證綁定。

ACA 內建主機名稱流程

1. 先部署引導 ACA 端點以探索內建主機名稱。使用帶有 -BootstrapOnly 參數的部署腳本，或手動建立 ACA/容器應用程式殼層。
2. 使用發現的主機名稱顯示提供者註冊連結和確切 URL，例如 https://<fqdn> 和 https://<fqdn>/oauth/github/callback。
3. 收集用戶端 ID 和密碼。
4. 透過套用驗證設定、上傳內容，以及若應用程式是引導的則切換至 Proxy 映像，來完成部署。

需要複製或調整的檔案

使用這些資產作為實作起點：

• assets/blob_proxy_app.py：具有 Blob Proxy 和提供者切換功能的 FastAPI 應用程式。
• assets/requirements.txt：Python 執行時期相依性。
• assets/Dockerfile：ACA 的最小映像。
• assets/deploy-aca-web.ps1：具特定觀點的 Azure 部署腳本。
• assets/publish-web-image.yml：用於 GHCR 發佈的 GitHub Actions 工作流程。

需要時閱讀以下參考資料：

• references/architecture.md：架構、儲存規則和擴展注意事項。
• references/auth.md：OAuth 註冊步驟和環境變數。
• references/day-2.md：新增使用者、輪換密碼、上傳內容和疑難排解。

實作檢查清單

1. 確認內容目錄和產生的網站進入點。
2. 選擇自訂 DNS 或 ACA 內建主機名稱。
3. 選擇驗證提供者。
4. 若主機名稱已知，提供使用者特定提供者的應用程式註冊連結和確切回呼 URL；若使用 ACA 內建主機名稱，先引導 ACA，然後提供那些 URL。
5. 收集應用程式註冊值。
6. 收集允許的使用者。
7. 選擇 GHCR 或 ACR。
8. 將範例應用程式和 Dockerfile 複製/調整到目標儲存庫。
9. 若為 GHCR 模式，新增工作流程並使結果套件公開。
10. 部署 ACA、私人 Blob Storage、RBAC、密碼、環境變數和可選的 DNS。
11. 將內容上傳至 Blob 並設定為 Cold 層。
12. 冒煙測試：
    • 未經驗證的請求會重新導向至提供者，除非 AUTH_PROVIDER=none；
    • 允許的使用者可以載入 index.html；
    • 不允許的使用者會收到 403；
    • 媒體範圍請求傳回 206 Partial Content；
    • Blob 的直接匿名存取失敗。

Day-2 任務處理

對於「新增使用者」，僅更新 ALLOWED_USERS 或特定提供者的允許清單環境變數，然後重新啟動/更新 ACA。

對於「上傳新內容」，重新產生本機靜態輸出，執行啟用刪除功能的 Blob 同步（僅在本地輸出是權威來源時），然後設定為 Cold 層。

對於大型網站或多個檔案，偏好使用 AzCopy。若 AzCopy 不可用且網站較小，Azure CLI 的 az storage blob upload-batch --auth-mode login 是可接受的替代方案；對於大型網站，請先安裝 AzCopy 或使用帶有 -InstallAzCopy 參數的部署腳本。

對於「切換驗證提供者」，先建立新的提供者註冊，設定密碼/環境變數，驗證登入，然後移除舊的提供者密碼。

對於「從 GHCR 遷移至 ACR」，部署 ACR，授予 AcrPull 權限，更新映像參考，並保持 Blob 內容不變。