Jenkins 流水线调用 Docker 构建镜像时权限不足怎么配置？

Jenkins 流水线构建 Docker 镜像报权限不足，通常是因为运行 Jenkins 服务的系统用户没有访问 Docker 守护进程套接字的权限。最推荐的处理方向是将 jenkins 用户加入 docker 用户组并重启服务，适用场景为 Linux 宿主机直接安装 Docker 的环境，风险边界在于加入 docker 组等同于获得 root 权限，需评估安全影响。

先说结论：解决 Jenkins 调用 Docker 权限问题的核心是将 Jenkins 运行用户加入 Docker 用户组，并确保服务重启生效。

适合：Linux 宿主机上直接运行 Docker Daemon 且 Jenkins 以系统服务方式运行的场景。
先准备：确认 Jenkins 服务运行的系统用户名（默认为 jenkins）及 sudo 权限。
验收：执行 docker info 命令无权限报错且流水线构建成功。

命令速用版

以下命令假设 Jenkins 运行用户为 jenkins，且已安装 Docker 并创建了 docker 组。

# 将 jenkins 用户加入 docker 组
sudo usermod -aG docker jenkins

# 重启 Jenkins 服务使组变更生效
sudo systemctl restart jenkins

# 验证用户组 membership
id jenkins

为什么会这样

Docker 守护进程默认监听 Unix 套接字/var/run/docker.sock，该文件权限通常属于 root 用户和 docker 组。Jenkins 服务默认以独立的 jenkins 用户运行，该用户不在 docker 组内，因此无法读写套接字文件。直接以 root 运行 Jenkins 存在安全风险，修改套接字权限会随 Docker 重启还原，加入用户组是官方推荐的持久化方案。

分步处理

按顺序执行以下步骤，确保每一步都有明确的检查点。

步骤 1：确认 Jenkins 运行用户
查看 Jenkins 服务配置文件或进程信息，确认实际运行用户。

ps -ef | grep jenkins
# 或查看服务状态
systemctl status jenkins

如果输出显示用户为 jenkins，则继续下一步；如果用户为 root，则不存在此权限问题，需排查其他原因。

步骤 2：添加用户到 Docker 组
使用 usermod 命令将确认的用户名加入 docker 组，-aG 参数表示追加到附属组而不移除原有组。

sudo usermod -aG docker jenkins

步骤 3：重启 Jenkins 服务
用户组变更不会在当前已登录会话中立即生效，必须重启 Jenkins 服务进程。

sudo systemctl restart jenkins

步骤 4：检查回滚方案
如果配置后出现安全问题或构建异常，可使用 usermod -r 移除组或修改/etc/sudoers 还原权限。

怎么验证是否生效

验证分为系统级验证和流水线级验证，两者都通过才算配置成功。

系统级验证：切换到 jenkins 用户执行 Docker 命令，不应出现 permission denied 报错。

sudo -u jenkins docker info
# 输出应包含 Docker 服务器信息，无报错

流水线级验证：在 Jenkins 中触发一个包含 docker build 或 docker run 步骤的流水线任务。

pipeline {
    agent any
    stages {
        stage('Build') {
            steps {
                script {
                    sh 'docker images'
                }
            }
        }
    }
}

观察控制台输出，若能看到镜像列表且步骤状态为成功，则权限配置生效。

常见坑

配置过程中容易遇到以下问题，需提前规避。

1. 未重启服务导致验证失败
用户组信息在用户登录时加载，仅执行 usermod 而不重启 Jenkins 服务，Jenkins 进程仍持有旧的组信息，导致权限错误依旧存在。

2. 忽略 Docker 根目录权限
部分场景下 Docker 配置了自定义根目录或存储驱动，需确保 jenkins 用户对这些目录也有读取权限，否则构建可能报存储错误。

3. 根less Docker 环境不适用
如果使用的是 Rootless Docker 模式，守护进程套接字路径通常位于用户主目录下（如$XDG_RUNTIME_DIR/docker.sock），此时需调整套接字路径配置而非修改系统用户组。

常见问题

加入 docker 组是否有安全风险？

有安全风险。docker 组用户等同于 root 权限，因为该用户可以挂载宿主机文件系统并逃逸容器限制。建议仅在受信任的内网构建节点使用此方案，生产环境建议采用 Docker-in-Docker 或专用构建代理隔离权限。

使用 Kubernetes 插件构建需要配置此权限吗？

不需要。Kubernetes 插件通常在 Pod 内动态启动构建容器，权限由 K8s ServiceAccount 和 Pod Security Policy 控制，不涉及宿主机 Docker 守护进程权限。

修改/etc/sudoers 允许免密执行 Docker 命令可以吗？

可以但不推荐。配置 sudoers 允许 jenkins 用户免密执行 docker 命令也能解决权限问题，但每次调用需加 sudo 前缀，且日志审计不如用户组方案清晰，维护成本较高。

参考来源

Jenkins 官方文档，Docker Pipeline Plugin 使用说明，URL: https://plugins.jenkins.io/docker-workflow/
Docker 官方文档，Linux 安装后管理步骤，URL: https://docs.docker.com/engine/install/linux-postinstall/