极客工场

Appearance

共 2,418 字预计阅读约 8 分钟

Jenkins 权限不足 AccessDeniedException 速查：角色、脚本审批与匿名构建 ​

更新时间：2026-10-24。FAQ 速查页，面向点页面白屏/404、构建日志里躺着 AccessDeniedException、或流水线被 Scripts not permitted 拦下的同学。Jenkins 权限不足的本质是「身份 × 授权矩阵 × 沙箱」三层的任意一层把你拦了：你是谁（登录账号还是匿名）、这个身份被授了什么权（全局/项目/角色三级）、以及脚本里的方法调用有没有过审批。病因收敛在六根轴上：Role-based 角色没给你授权限、连最基础的 Overall/Read 都缺导致登录后白屏、脚本安全插件把未审批的方法签名拦在沙箱里、构建被匿名身份触发拿不到授权、凭据（Credentials）域对当前任务不可见、以及 API 调用没带 crumb 被 CSRF 防护拦下。顺一遍基本必中。如果是节点连不上而不是权限问题，转 Jenkins 节点离线速查。

本文要回答的问题 ​

  • user is missing the Job/Build permission 这类报错，去哪里补权限？
  • 登录成功但首页空白、所有链接 404，是什么权限丢了？
  • Scripts not permitted to use method 是权限不够吗，审批入口在哪？
  • 定时触发的构建为什么比手动触发更容易权限失败？
  • 流水线里 withCredentials 取不到凭据，是凭据坏了还是权限问题？

一、报错原文与典型现象 ​

权限类报错分散在三处：构建日志、页面响应、以及脚本审批队列（控制器地址以 jenkins.example.com 占位，路径以 /proj/demo 占位）：

bash
# 构建日志：授权矩阵拦截
hudson.security.AccessDeniedException2: 张三 is missing
the Job/Build permission
# 或匿名身份触发
hudson.security.AccessDeniedException2: anonymous is missing
the Overall/Read permission
bash
# 流水线日志：脚本安全沙箱拦截
org.jenkinsci.plugins.scriptsecurity.sandbox.RejectedAccessException:
Scripts not permitted to use method groovy.lang.GString plus
java.lang.Object
bash
# 凭据不可见
ERROR: Could not find credentials entry with ID 'deploy-key'
# API 调用被 CSRF 拦截
HTTP 403: No valid crumb was included in the request

读现象先分三层：AccessDeniedException2 + 缺某某 permission 是授权层的问题；Scripts not permitted to use 是沙箱审批层的问题；Could not find credentials 和 crumb 403 是资源可见性/调用姿势层的问题。三层修法互不相干，先定性。

二、病因处置速查表 ​

报错现象 / 场景可能原因快速验证处置
missing the Job/Build permission授权矩阵或角色没给该用户构建权系统管理 → 授权策略页查该用户在全局/项目角色里补对应权限
登录后首页空白、链接全 404缺 Overall/Read 基础权限用管理员账号查该用户的全局权限给「认证用户」组补 Overall/Read
Scripts not permitted to use method沙箱拦了未审批的方法签名系统管理 → In-process Script Approval管理员审批签名；或改用插件步骤
手动能跑、定时/Webhook 触发失败构建以匿名身份触发，匿名无授权对比两次构建日志开头的触发者配置触发令牌/认证，或授权限定身份
Could not find credentials entry凭据所在域对任务/文件夹不可见凭据页确认域与作用范围把凭据放进任务可见的文件夹域
API 调用 403 No valid crumb请求未带 CSRF crumbcurl 加 -u 与 crumb 重试先取 crumb 再发请求，或用 API token

三、排查决策图 ​

下面这张图是标准排查路线，颜色按角色区分：红是报错入口与命中的根因，蓝是排查动作，绿是通过分支，橙是修复动作，紫是防复发沉淀。

engineering/jenkins/ts-jenkins-permission-denied.md D2 示意图

读这张图抓分水岭：报错原文直接告诉你卡在哪一层——看到 AccessDeniedException2 加某个 permission 名字走左支查授权；看到 Scripts not permitted 或凭据找不到走右支查沙箱与域。授权层的问题找管理员补角色，沙箱层的问题走审批队列，不要互相用错药。

四、逐条排查展开 ​

授权拦截：报错里的用户名和权限名就是工单。 张三 is missing the Job/Build permission 已经把缺失项写死。用管理员账号进系统管理的授权策略页（矩阵授权或 Role-Based Strategy 插件页），按用户名找到对应角色，勾上缺的权限。装了 Role-Based Strategy 的团队注意权限是「全局角色 + 项目角色」两层：全局角色管 Overall 级，项目角色按正则匹配任务名管 Job 级——只在项目角色里授权、没给全局 Overall/Read，用户登录后照样白屏。

白屏 = 丢了 Overall/Read。 症状极具迷惑性：登录成功、页面能开，但首页空无一物、所有任务链接 404。这不是网络问题，是身份连「读」权限都没有。常见触发：管理员清理授权矩阵时把「authenticated（认证用户）」组的 Overall/Read 勾掉了。修法：管理员进授权矩阵给认证用户组补 Overall/Read；更稳的做法是建一个「基础角色」只含 Overall/Read，所有用户默认挂上。

沙箱拦截不是权限不够，是方法没备案。 Scripts not permitted to use method 来自 Script Security 插件：流水线脚本默认跑在 Groovy 沙箱里，沙箱只允许「已批准白名单」内的方法签名。处置入口在系统管理 → In-process Script Approval：队列里躺着被拦的签名，管理员审一眼确认无害后点 Approve，重跑即过。要警惕的是「大量审批单」信号——说明脚本写了太多裸 Groovy/Java 调用，应优先改用插件提供的 Pipeline 步骤（如用 readJSON 步骤而不是 new JsonSlurper()）。给任务勾掉「Use Groovy Sandbox」等于拆防盗门，只作为管理员的临时后门。

匿名触发是定时/Webhook 构建权限失败的固定剧本。 手动点「立即构建」用的是你的登录身份，定时器或 Webhook 触发的构建常以匿名身份启动——匿名身份在授权矩阵里通常什么都没有，于是「手动能跑、自动就挂」。处置两条路：一是给触发通道配置认证（Webhook 带 token、远端触发配置身份验证令牌）；二是装了 Authorize Project 类插件时，显式指定「构建以哪个身份运行」。排查时先看构建页顶部的「Started by …」字段，触发者是谁一目了然。

凭据不可见：域与作用范围对不上。 Could not find credentials entry with ID 'deploy-key' 多数不是凭据被删了，而是凭据建在「全局域」之外的某个文件夹域里，或者作用范围（System/Global）与使用场景不匹配。Jenkins 凭据按文件夹分层：定义在文件夹 A 的凭据，文件夹 B 的任务看不到；System 范围的凭据只给 Jenkins 自身（如节点连接）用，流水线里 withCredentials 取不到。修法：把凭据建在任务所在文件夹或全局域、范围选 Global，然后在流水线里按 ID 引用。

API 403 crumb：调用姿势问题不是授权问题。 脚本直接 curl Jenkins API 报 No valid crumb was included，是 CSRF 防护在生效。标准姿势：先 curl -u user:apitoken 'https://jenkins.example.com/crumbIssuer/api/json' 取 crumb，再带着 crumb 头（如 Jenkins-Crumb: xxx）发真正请求；全程用 API token 而不是登录口令。

五、规范做法与预防 ​

  • 角色模板化：预定义「只读 / 开发者 / 发布员 / 管理员」四档角色，新人按档挂，不逐人勾权限。
  • 认证用户组保底 Overall/Read：授权矩阵改动后第一时间验证普通用户登录不白屏。
  • 脚本审批留痕：Script Approval 的每条批准记录进评审，批量出现同类审批时推动改用插件步骤。
  • 触发身份显式化：Webhook 与定时触发的任务统一配置触发令牌，关键任务用 Authorize Project 钉死运行身份。
  • 凭据按文件夹就近建：任务在哪个文件夹，凭据就建在哪个文件夹的域里；System 范围只留给 Jenkins 自身用途。
  • 最小权限原则：能给 Job/Read 就不给 Job/Configure，能给文件夹级就不给全局级。

这一篇在知识体系里的位置 ​

本篇是 Jenkins 排错速查簇的权限入口篇，定位「身份与授权」：权限通了但流水线步骤报不存在看 No such DSL method 速查；权限配置因升级插件而错乱看 Jenkins 插件版本不兼容速查；构建能触发但排不到执行器看 Jenkins 节点离线速查。「报错定层 → 授权层补角色、沙箱层走审批、资源层查域」这条主线对一切权限类报错通用。

一句话总结 ​

Jenkins 权限不足先按报错原文定层：AccessDeniedException2 加 permission 名字走授权层——管理员在矩阵/角色页补权限，登录白屏就是丢了 Overall/Read；Scripts not permitted to use method 走沙箱层——In-process Script Approval 里管理员审批签名，裸 Groovy 调用多的要改用插件步骤；凭据找不到走资源层——凭据要建在任务可见的文件夹域且范围选对。定时与 Webhook 触发的构建以匿名身份跑是权限失败的固定剧本，触发令牌与运行身份要显式配置。角色模板化、审批留痕、最小权限入库，权限类报错基本绝迹。