Jenkins使用Docker Agent部署Python项目的权限错误原因及优雅解决方法

在Ubuntu虚拟机部署Jenkins服务器，通过Docker Jenkins插件实现对宿主机Docker环境的访问。针对FastAPI应用编写Jenkins流水线时，执行依赖包安装步骤遇到权限错误。

错误信息 #

ERROR: Could not install packages due to an OSError: [Errno 13] Permission denied: '/.local'Check the permissions.

Jenkinsfile配置 #

pipeline {
agent {
    docker {
          image 'python:3.9-slim'
    }
      }
triggers {
    githubPush()
}
stages {
    
    stage('Setup'){
       steps{   
          sh 'python -m venv .venv'
          sh '. .venv/bin/activate'
          sh 'pip install -r requirements.txt'  
        }
     }
       stage('Unit Tests'){ 

       steps{
           sh 'pytest'
        }
     }        

  }
}

已尝试的无效解决方案 #

• 为pip添加--user参数：pip install --user -r requirements.txt
• 将jenkins用户加入docker组：usermod -aG docker jenkins
• 将jenkins用户加入sudo组：usermod -aG sudo jenkins

关键日志片段 #

...
+ pip install -r requirements.txt
WARNING: The directory '/.cache/pip' or its parent directory is not owned or is not writable by the current user. The cache has been disabled. Check the permissions and owner of that directory. If executing pip with sudo, you should use sudo's -H flag.
Defaulting to user installation because normal site-packages is not writeable
....
ERROR: Could not install packages due to an OSError: [Errno 13] Permission denied: '/.local'
Check the permissions.
...

临时可行但不够优雅的方案 #

修改Docker Agent配置，指定以root用户运行：

agent {
    docker {
         image 'python:3.8'
         args '-u root --privileged'
    }
}

咨询问题 #

1. 该权限错误的根本原因是什么？
2. 是否存在更优雅的解决方式？

根本原因 #

1. 容器内用户权限不匹配：官方Python镜像（如python:3.9-slim）默认以非root用户（通常是python用户）运行，但容器根目录下的.local、.cache等目录属于root用户，当前运行用户无写入权限。
2. 虚拟环境激活失效：Jenkins的每个sh步骤都是独立进程，. .venv/bin/activate的激活状态无法传递到下一个sh命令，导致pip install实际未使用虚拟环境，转而尝试写入系统/用户目录触发权限错误。

优雅解决方案 #

方案1：正确在同一进程内使用虚拟环境 #

将虚拟环境激活和依赖安装放在同一个sh块中，确保环境生效：

stage('Setup'){
   steps{   
      sh '''
         python -m venv .venv
         . .venv/bin/activate && pip install -r requirements.txt
      '''
   }
}
stage('Unit Tests'){ 
   steps{
      sh '''
         . .venv/bin/activate && pytest
      '''
   }
}

此方案让依赖安装到项目目录下的.venv中，完全避开系统目录的权限问题。

方案2：自定义Python镜像配置非root用户 #

构建包含专属非root用户的自定义镜像，确保用户对工作目录有完整权限：

自定义Dockerfile

FROM python:3.9-slim
RUN useradd -m appuser
WORKDIR /app
USER appuser

Jenkinsfile使用自定义镜像

agent {
    docker {
          image 'your-custom-python:3.9-slim'
          args '-v $WORKSPACE:/app'
    }
}

方案3：指定pip安装目录 #

直接让pip将依赖安装到项目内的指定目录，避免写入系统/用户目录：

stage('Setup'){
   steps{   
      sh 'pip install --target ./deps -r requirements.txt'
   }
}
stage('Unit Tests'){ 
   steps{
      sh 'PYTHONPATH=./deps pytest'
   }
}

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