Ahtesham-Latif/Tie-Breaker-App

Azure App Service 部署 (Node.js)

本技能概述了將 Node.js 應用程式完美且符合最佳實務地部署至 Azure App Service (Linux)，並透過受控識別安全連線至 Azure AI Foundry 代理的完整路徑。

1. 雲端基礎設施設定

• App Service 方案： 生產環境一律選擇專用層級 (例如 Basic B1)。免費 (F1) 層級有嚴格的每日 60 分鐘 CPU 配額，會強制關閉應用程式 (導致 403 Stopped 錯誤)。

2. 驗證與受控識別 (無密碼)

1. 程式碼： 在 Node.js 後端使用 @azure/identity 套件中的 DefaultAzureCredential。
2. 啟用識別： 在 Azure App Service 入口網站中，前往 設定 > 身分識別 並啟用 系統指派。
3. IAM 權限： 在目標 Azure AI 專案中，前往 存取控制 (IAM) 並將 Azure AI 開發人員 角色指派給 App Service 的受控識別。(注意：Cognitive Services OpenAI User 角色的權限不足，無法用於 Azure Foundry Orchestration Agents。)

3. 環境變數 (前端與後端的陷阱)

當透過 GitHub Actions 部署全端應用程式 (React/Vite + Node.js) 時，環境變數必須依邏輯拆開設定：

前端 (Vite)

• 以 VITE_ 為前綴的變數 (例如 Supabase 金鑰) 會在建置時間被嵌入靜態 HTML/JS 中。
• 應在何處設定： 它們必須存放在 GitHub Secrets 中，並在 .github/workflows 檔案的 env: 區塊中，針對 npm run build 步驟明確對應。
• 陷阱： 如果這些變數只存在於 Azure 而未設定在 GitHub Actions 中，Vite 將會以前端變數為空的狀態建置。

後端 (Node.js)

• 執行中的 server.js 檔案會在執行時期從雲端容器讀取環境變數。
• 應在何處設定： 直接在 Azure 入口網站的 設定 > 環境變數 下設定變數 (例如 Azure AI 端點、後端 Supabase 金鑰)。
• 陷阱： Azure App Service 後端並不會繼承你的 GitHub Actions Secrets。你必須手動在 Azure 入口網站中進行設定。
• 至關重要： 變數在 Node.js 程序啟動時只會載入記憶體一次。如果新增或變更了某個變數，你必須明確點擊 App Service 概觀頁面上的重新啟動按鈕。
• 若要信任 Azure 負載平衡器 (為 express-rate-limit 所需)，請確保 Express 應用程式已設定 app.set('trust proxy', 1);。

4. GitHub Actions CI/CD 管線

最安全的部署策略是避免建置引擎衝突 (GitHub vs. Azure Oryx)。讓 GitHub 負責 100% 的建置與打包工作。

工作流程最佳實務：

1. GitHub 執行 npm install 以及前端建置 (npm run build)。
2. GitHub 上傳包含編譯後輸出 (dist)、後端檔案 (server.js) 以及至關重要的 node_modules 資料夾的成品。
   • 為什麼？ 如果省略了 node_modules，Azure 的 Oryx 引擎會嘗試透過執行 npm run build 來自行建置應用程式，但由於原始碼檔案 (index.html) 並未上傳，此舉將會崩潰。
3. 使用 azure/webapps-deploy@v3，並搭配儲存在 GitHub Secret 中的發行設定檔。