python:3.8-slim-buster镜像gunicorn命令找不到及虚拟环境配置问题

报错核心是权限和路径不匹配：你切换到非root用户kr1p后执行pip install时，因为系统全局的Python site-packages目录对普通用户无写权限，pip自动触发用户级安装逻辑，把gunicorn等所有依赖装到了/home/kr1p/.local/目录下，这个目录下的可执行文件路径、包路径默认都不在容器的环境变量配置里：

• 可执行文件gunicorn在/home/kr1p/.local/bin/下，该路径不在PATH中，所以直接执行gunicorn会报not found
• 包文件在/home/kr1p/.local/lib/python3.8/site-packages/下，该路径不在Python模块搜索路径中，所以python -m gunicorn也会执行失败
  你看到的两个pip提示也对应这个问题：普通用户写不了全局目录才触发用户安装，不用虚拟环境就会弹非虚拟环境安装的警告。

针对python:3.8-slim-buster镜像里的kr1p用户，三个占位符的真实路径如下：

• default_pip_path：普通用户pip安装可执行文件的目录，值为/home/kr1p/.local/bin
• good_path：普通用户pip安装Python包的site-packages目录，值为/home/kr1p/.local/lib/python3.8/site-packages
• path_already_in_PATH：默认在PATH中的系统级可执行目录，比如/usr/local/bin，但普通用户对这类目录无写权限，强行用--target参数安装包到这里会触发权限错误，不建议使用。

• 用pip --target=path_already_in_PATH install gunicorn：可行性最低，需要给普通用户开放系统目录写权限，违反容器最小权限原则，还可能覆盖系统Python的依赖导致异常，完全不推荐。
• 配置PYTHONPATH追加用户site-packages路径：只能解决python -m gunicorn找不到模块的问题，无法解决直接执行gunicorn命令找不到可执行文件的问题，属于半吊子修复。
• 配置PATH追加用户pip的bin目录：可以直接解决gunicorn命令找不到的问题，改动最小，但依然会触发pip的非虚拟环境安装警告，长期维护容易出现依赖冲突。

容器里用虚拟环境是规避这类权限、路径、依赖冲突问题的通用标准做法，不需要给普通用户开特殊权限，也不会触发pip警告，修改后的Dockerfile如下：

FROM python:3.8-slim-buster
RUN apt-get update \
  && apt-get install -y --no-install-recommends build-essential netcat \
  && apt-get purge -y --auto-remove -o APT::AutoRemove::RecommendsImportant=false \
  && rm -rf /var/lib/apt/lists/*

RUN addgroup --system kr1p \
  && adduser --system --ingroup kr1p kr1p

# 创建独立虚拟环境，授权给业务用户
RUN python -m venv /opt/venv && chown -R kr1p:kr1p /opt/venv
# 将虚拟环境的可执行目录加到PATH最前面，所有python、pip、gunicorn命令优先走虚拟环境
ENV PATH="/opt/venv/bin:$PATH"
ENV PYTHONUNBUFFERED=1

WORKDIR /app
COPY app .
RUN chown -R kr1p:kr1p /app

USER kr1p
# 升级pip后安装依赖，所有包装在虚拟环境内，无权限问题、无警告
RUN pip install --upgrade pip && pip install -r requirements.txt

# 注意替换成你自己项目的gunicorn启动参数，比如wsgi入口、监听地址、worker数等
CMD ["gunicorn", "app:app", "-b", "0.0.0.0:5000"]

配套的docker-compose.yml不需要做任何修改即可正常使用。
如果你只是想临时快速修复不想用虚拟环境，只需要在Dockerfile里USER kr1p这一行之前加一行ENV PATH="/home/kr1p/.local/bin:$PATH"就能解决gunicorn找不到的问题，只是会保留pip的警告提示。

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