python-appservice-deploy

Python on Azure App Service — 程式碼部署

將 Python（Flask、Django、FastAPI、通用）程式碼部署到 Azure App Service Linux（P0v3、Python 3.14）。若資源群組、方案或 Web 應用程式不存在則自動建立。如需 VNet、Key Vault、資料庫或 IaC，請交由 azure-prepare 處理。

使用的 MCP 工具：mcp_azure_mcp_subscription_list、mcp_azure_mcp_group_list、mcp_azure_mcp_appservice、mcp_azure_mcp_azd（當存在 azure.yaml 時）。

工作流程

1. 解析上下文——智慧預設，最少提示。 僅應用程式名稱需互動輸入；資源群組（<app>-rg）、方案（<app>-plan）、區域（目前 az 預設或 eastus2）、訂用帳戶皆自動推導。詳見 create-app.md §1。
2. 偵測框架（僅供參考，不阻斷流程）。詳見 detect.md。
3. 選擇路徑——若 azure.yaml 的 host 為 appservice，則走 deploy-azd.md；否則走 deploy-azcli.md。
4. 確保資源群組 → 方案（P0v3 --is-linux）→ Web 應用程式（--runtime "PYTHON:3.14"） 存在。若遇到暫時性 ARM 錯誤，請遵循 transient-retry.md。詳見 create-app.md。
5. 設定啟動命令——Flask/Django：無需設定（Oryx 自動偵測）。FastAPI：一律設為 python -m uvicorn main:app --host 0.0.0.0。其他框架：發出警告。詳見 startup-commands.md。
6. 設定 SCM_DO_BUILD_DURING_DEPLOYMENT=true。
7. 部署——執行 azd deploy 或 az webapp deploy --type zip --track-status false。
8. 停止。輸出部署後訊息（詳見 post-deploy-message.md）並結束此回合。

嚴格規則

• ⛔ 禁止部署後驗證——部署指令返回後，請勿執行 az webapp log tail、curl、Invoke-WebRequest 或任何健康檢查。App Service 需要 2–3 分鐘暖機；安靜的日誌或早期的 5xx 錯誤不代表失敗。
• ⛔ Shell 安全——--runtime 參數一律使用 "PYTHON:3.14"（冒號）。切勿使用 "PYTHON|3.14"（管線符號是 shell 運算子）。
• ⛔ 禁止使用 az webapp up——此指令已棄用。請使用步驟 7 的指令。
• ✅ URL 格式——端點請以 https://... URL 呈現。

錯誤處理

完整症狀→原因→解決方案對照表請參閱 errors.md。快速分類：缺少方案或應用程式→重新執行步驟 4；容器在 8000 埠 ping 逾時→修正啟動命令（步驟 5）；部署後出現 ModuleNotFoundError→確認步驟 6 已執行，然後重新部署。