通过GitHub Actions部署Python FastAPI到Azure App Service时卡住

启动脚本与启动命令问题 #

• 检查run.sh是否存在阻塞逻辑：比如脚本里有无无限循环、等待用户输入的指令，或者启动命令未适配Azure运行环境的要求。
• 确认启动命令格式正确：Azure Python环境推荐用gunicorn作为生产服务器，若用uvicorn需确保命令为uvicorn main:app --host 0.0.0.0 --port $PORT，必须使用Azure提供的$PORT环境变量，不能硬编码端口。
• 验证run.sh执行权限：部署时若脚本未添加执行权限（未执行chmod +x run.sh），会导致无法启动服务，部署进程持续等待。

依赖安装异常 #

• 查看GitHub Actions部署日志：即使任务卡住，也要检查前期依赖安装步骤是否有失败提示——比如requirements.txt包含无法在Azure环境编译的包、版本冲突，导致pip安装进程挂起。
• 核对依赖完整性：确认requirements.txt包含fastapi、uvicorn（或gunicorn）等核心包，缺失依赖会导致服务启动失败，部署进程因等待服务就绪而卡住。
• 对齐Python版本：本地Python版本需与Azure App Service配置的版本一致，版本不匹配可能导致依赖包安装失败或启动异常。

部署配置与环境变量冲突 #

• 确认SCM_DO_BUILD_DURING_DEPLOYMENT=1生效：查看GitHub Actions日志是否有构建阶段输出，若环境变量未正确设置，会导致构建步骤未触发或异常执行。
• 排查启动命令冲突：若Azure门户同时配置了启动命令和项目内的run.sh，可能出现命令覆盖，导致执行错误指令卡住部署。
• 检查缺失的环境变量：FastAPI依赖的配置变量若未设置，可能导致服务启动时等待配置输入，进而拖慢部署。

流水线与权限问题 #

• 检查默认部署配置文件：比如azure-webapps-python.yml是否存在超时设置过短、冗余等待逻辑等问题。
• 验证Azure权限：确认GitHub Actions使用的服务主体拥有足够的Azure App Service操作权限，权限不足可能导致部署卡在验证环节。
• 排查网络阻塞：GitHub Actions Runner与Azure之间的网络延迟或限制，可能导致部署包传输、解压过程超时。

资源限制问题 #

• 升级App Service实例规格：免费层实例内存、CPU资源有限，依赖安装或服务启动时容易因资源不足卡住，可临时升级到基础层测试。
• 精简部署包：移除代码中不必要的静态文件、测试依赖或大体积资源，过大的部署包会延长传输、解压时间，触发超时。

针对你提供的示例文件的额外检查 #

• 示例服务器代码（main.py）：确认启动阶段有无耗时初始化操作（比如批量加载数据），这类操作会导致服务无法快速响应Azure的健康检查，平台会持续等待服务就绪。
• requirements.txt：避免添加azure-cli这类非生产必要包，同时避免版本号过于宽泛（比如只写fastapi而不指定版本），防止安装不稳定版本引发问题。
• run.sh：推荐使用更适配Azure生产环境的启动命令，比如：

#!/bin/bash
pip install -r requirements.txt
gunicorn main:app --workers 4 --worker-class uvicorn.workers.UvicornWorker --bind 0.0.0.0:$PORT

内容的提问来源于stack exchange，提问作者John Szatmari