GAE自定义运行时部署FastAPI出现gunicorn not found错误如何解决

排查已部署GAE实例的gunicorn路径 #

• 执行SSH命令连接运行中的GAE实例：gcloud app instances ssh <实例ID> --service <你的服务名> --version <版本号>
• 实例内执行搜索命令定位gunicorn可执行文件：find / -name gunicorn -type f 2>/dev/null，返回结果中带/bin/前缀的就是完整可执行路径，常见路径为/usr/local/bin/gunicorn或/root/.local/bin/gunicorn
• 也可以通过Python命令直接获取pip可执行文件目录：echo "$(python3 -m site --user-base)/bin"

修改Dockerfile修复路径问题 #

以下方案按优先度排序：

1. 使用Python模块调用gunicorn（兼容性最高）
   直接修改run.sh脚本内的生产环境启动命令，把gunicorn <启动参数>替换为python -m gunicorn <启动参数>，完全规避PATH环境变量的查找逻辑，无需调整Dockerfile其他配置。

2. 强制全局安装依赖
   修改Dockerfile中依赖安装的指令，避免用户级pip安装导致的路径隔离问题：

# 升级pip后强制全局安装所有依赖
RUN pip install --no-cache-dir --upgrade pip && \
    pip install --no-cache-dir --force-reinstall -r requirements.txt

3. 主动添加Python可执行目录到PATH
   在Dockerfile中添加环境变量配置，永久将pip可执行目录加入系统PATH：

ENV PATH="$PATH:$(python3 -m site --user-base)/bin:/usr/local/bin"

4. 显式指定gunicorn绝对路径
   把排查得到的gunicorn完整路径直接写入run.sh启动命令，例如：

/usr/local/bin/gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker

额外注意事项 #

• 若使用多阶段Docker构建，需确保gunicorn是安装在最终运行的镜像阶段，而非仅存在于构建阶段
• 检查run.sh文件的首行shebang配置，确保为#!/bin/bash或#!/bin/sh，避免脚本执行时环境变量加载异常

内容的提问来源于stack exchange，提问作者Caleb Jay