Docker部署Python Dash应用gunicorn命令不存在报错排查

基础环境信息 #

• 技术栈：Python Dash Web应用、Docker、docker-compose、Gunicorn（替换Flask内置开发服务器做生产部署）
• 报错信息：容器启动日志输出

container_api | ./entrypoint.sh: line 3: gunicorn: command not found

• 异常特征：通过requirements.txt安装的Python依赖（包括gunicorn包本身）可在Dash应用内正常导入，仅在entrypoint.sh脚本中直接调用gunicorn命令时触发报错

相关配置 #

api服务Dockerfile #

FROM archlinux:latest

COPY api/requirements.txt ./

RUN pacman-db-upgrade \
&& pacman -Syyu --noconfirm \
&& pacman -S python --noconfirm \
&& pacman -S python-pip --noconfirm \
&& pip install --no-cache-dir -r requirements.txt

WORKDIR /app

CMD chmod a+x entrypoint.sh && ./entrypoint.sh

entrypoint.sh启动脚本 #

#!/bin/bash

gunicorn app:server

docker-compose配置 #

version: "3"
services:
  worker:
    build:
      dockerfile: ./worker/Dockerfile
    container_name: container_worker
    environment:
      - PYTHONUNBUFFERED=1
    volumes:
      - ./api:/app/
      - ./worker:/app2/

  api:
    build:
      dockerfile: ./api/Dockerfile
    container_name: container_api
    volumes:
      - ./api:/app/
      - /var/run/docker.sock:/var/run/docker.sock
    ports:
      - "${API_PORT}:8050"
    depends_on:
      - worker

问题根因 #

Archlinux环境下，root用户通过pip安装Python包时，可执行文件默认会被放到/root/.local/bin目录下，该路径默认不在容器非登录shell的PATH环境变量中：

• 应用内import gunicorn正常：Python导入包时搜索的是site-packages目录，gunicorn包本身已正确安装到系统Python路径，因此导入无异常
• 直接执行gunicorn命令失败：Shell执行外部命令时只会遍历PATH下的目录查找可执行文件，找不到对应路径下的gunicorn程序就会抛出command not found错误
• 之前python app.py能正常运行：python命令本身在系统默认PATH路径（/usr/bin/python）下，启动Flask服务不需要额外查找gunicorn可执行文件，因此无异常

修复方案 #

任选其一即可，优先推荐方案3，无路径依赖兼容性最好：

• 方案1：使用绝对路径调用gunicorn
  先在镜像构建阶段确认gunicorn安装路径，在Dockerfile的pip安装步骤后新增RUN which gunicorn，构建时查看输出的绝对路径（通常为/root/.local/bin/gunicorn），将entrypoint.sh中的启动命令替换为绝对路径即可：

  # 替换为实际查到的绝对路径
  /root/.local/bin/gunicorn app:server
  

• 方案2：将gunicorn所在路径加入全局PATH
  在Dockerfile的pip安装步骤后新增环境变量配置，将gunicorn可执行文件所在目录加入全局PATH：

  ENV PATH="/root/.local/bin:$PATH"
  

  配置后无需修改entrypoint脚本，Shell可直接找到gunicorn命令。
• 方案3：通过Python模块方式启动gunicorn
  直接修改entrypoint.sh中的启动命令，通过Python解释器调用gunicorn模块，完全绕开PATH查找可执行文件的逻辑：

  python -m gunicorn app:server
  

  该方式只要gunicorn包能被Python正常导入就可以运行，不受环境变量、安装路径差异影响，适配所有Linux发行版的Python环境。

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