AppEngine Flex自定义运行时部署失败：gunicorn未找到求助

正在构建包含Python 3.11和Firefox的App Engine Flex自定义运行时实例，最初以root身份运行pip安装依赖时收到警告，于是修改Dockerfile添加普通用户并创建虚拟环境安装依赖。本地容器运行正常，但部署到App Engine Flex环境时失败，报错：

ERROR: (gcloud.app.deploy) Error Response: [9] An internal error occurred while processing task /app-engine-flex/flex_await_healthy/flex_await_healthy>2023-12-29T14:42:11.900Z145758.jc.2: /bin/sh: gunicorn: not found

尝试过以下操作但均失败：

• 在app.yaml中指定虚拟环境内gunicorn的完整路径作为入口点
• 将gunicorn安装到系统Python包

目前发现安装系统级Python依赖可解决问题，但纠结应该坚持使用虚拟环境还是通过参数忽略pip的root运行警告。另外，即使移除虚拟环境并回滚到之前成功的配置，仍出现相同的gunicorn: not found错误。

附当前Dockerfile：

FROM python:3.11.7-alpine

RUN apk update
RUN apk add firefox
RUN adduser -h /app -g "" -D appuser
USER appuser
WORKDIR /app
ADD --chown=appuser ./app/requirements.txt /app
RUN python -m venv venv
ENV PATH="/app/venv/bin:$PATH"
RUN pip install -r requirements.txt
ADD --chown=appuser ./app /app/
EXPOSE 8080
ENTRYPOINT /app/venv/bin/gunicorn -b :$PORT main:app

核心问题排查 #

1. 环境变量PATH未生效 #

App Engine Flex在启动容器时可能会重置环境变量，导致设置的PATH="/app/venv/bin:$PATH"失效；即使指定完整路径仍报错，也可能是$PORT变量未被正确解析，或者ENTRYPOINT的执行方式未触发shell环境变量解析。

2. 回滚后仍报错的原因 #

大概率是之前的部署缓存未清理，App Engine Flex会复用历史镜像层，导致旧的错误配置残留。可以尝试添加参数强制重新构建部署：

gcloud app deploy --no-cache

解决办法 #

方法一：修复虚拟环境的ENTRYPOINT配置 #

修改Dockerfile的ENTRYPOINT为shell执行模式，确保环境变量和路径被正确解析：

# 替换原ENTRYPOINT为以下内容
ENTRYPOINT ["sh", "-c", "/app/venv/bin/gunicorn -b :$PORT main:app"]

这种方式会让shell主动解析$PORT变量，同时确保虚拟环境内的gunicorn路径被正确识别。

方法二：调整虚拟环境创建顺序 #

将虚拟环境创建和PATH设置放在切换普通用户之前，避免权限和环境变量传递问题：

FROM python:3.11.7-alpine

RUN apk update
RUN apk add firefox
RUN adduser -h /app -g "" -D appuser
WORKDIR /app
ADD --chown=appuser ./app/requirements.txt /app
# 先以root身份创建虚拟环境并设置全局PATH
RUN python -m venv venv
ENV PATH="/app/venv/bin:$PATH"
# 再切换普通用户安装依赖
USER appuser
RUN pip install -r requirements.txt
ADD --chown=appuser ./app /app/
EXPOSE 8080
ENTRYPOINT ["gunicorn", "-b", ":$PORT", "main:app"]

方法三：忽略pip的root警告（简洁方案） #

如果不需要严格的环境隔离，可直接使用系统级安装，在pip命令中添加参数忽略警告：

# 移除虚拟环境相关步骤，保留root用户执行安装
RUN pip install -r requirements.txt --no-warn-script-location

这种方式无需配置虚拟环境，减少部署复杂度，App Engine Flex的运行环境本身具备较好的隔离性，不会出现全局依赖冲突问题。

选择建议 #

• 优先虚拟环境：如果项目依赖版本复杂、需要严格环境隔离，建议修复虚拟环境的PATH和ENTRYPOINT配置，确保环境变量在容器启动时正确生效。
• 忽略警告：如果项目依赖简单、追求部署效率，直接使用系统级安装并忽略pip警告是更高效的方案，适合App Engine Flex的运行场景。

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