CI/CD / 系统课时
把密码和令牌存入凭据库
把密码和令牌存入凭据库
流水线需要访问 Git、镜像仓库或部署 API 时,不应把密码和令牌直接写进 Jenkinsfile。Jenkins Credentials 可以集中保存秘密,再通过凭据 ID 在流水线运行时注入,从而把流水线代码与真实敏感值分离。
学习目标
- 根据秘密形态选择合适的 Jenkins 凭据类型
- 理解凭据作用范围与凭据 ID 的职责
- 在 Pipeline 中安全绑定令牌而不输出秘密值
先选择正确的凭据类型
创建凭据时应先看外部系统实际需要什么认证材料。常见类型包括用户名与密码、Secret text、Secret file,以及用于 SSH 认证的 SSH Username with private key。
例如,单个 API Token 通常保存为 Secret text;需要用户名和密码组合认证时使用 Username with password;SSH 私钥不要拆成普通文本变量保存,而应使用对应的 SSH 私钥凭据类型。
凭据的 ID 是流水线引用秘密的稳定标识,例如 prod-api-token。Jenkinsfile 应保存这个 ID,而不是秘密本身。Description 则适合写用途,例如“生产部署 API Token”,方便管理员识别。
保存凭据并控制作用范围
在 Jenkins 管理界面进入凭据管理位置,选择合适的凭据 Store 和 Domain 后新增凭据。具体菜单名称和布局可能随 Jenkins 版本、权限以及已安装插件变化,因此应以当前实例实际界面为准。

常见的 Scope 包括 Global 与 System。Global 凭据可供允许使用该凭据的 Jenkins 作业等消费者使用;System 凭据面向 Jenkins 系统自身使用,不应因为名称看起来“更安全”就把普通 Pipeline 所需凭据设为 System。
Domain 可以进一步描述凭据适用的主机、协议等要求,但它不是完整的权限隔离机制。真正决定谁能查看、创建或使用凭据的能力,还需要结合 Jenkins 的权限配置、凭据 Store 以及 Folder 等组织方式设计。
在 Pipeline 中绑定 Secret text
假设已经创建一个 Secret text 凭据,ID 为 prod-api-token。下面使用 Credentials Binding 提供的 withCredentials,只在代码块范围内把秘密绑定到环境变量 API_TOKEN。示例故意不打印变量内容,只检查它是否存在。
pipeline {
agent any
stages {
stage('Check credential') {
steps {
withCredentials([
string(credentialsId: 'prod-api-token', variable: 'API_TOKEN')
]) {
sh '''
test -n "$API_TOKEN"
echo 'credential loaded'
'''
}
}
}
}
}预期输出
credential loaded如果凭据 ID 不存在、当前上下文无法使用该凭据,或 Credentials Binding 等所需能力不可用,流水线会失败,而不是得到一个可用的 API_TOKEN。实际错误日志会随 Jenkins 和插件版本不同而变化。
避免秘密进入日志和源码
凭据绑定只解决“如何把秘密交给步骤”,并不意味着后续命令天然安全。不要执行 echo $API_TOKEN,也不要开启会回显展开后命令的调试方式。调用外部工具时还要检查该工具是否会把请求头、参数或环境变量写入日志。
Jenkinsfile 可以进入版本控制,真实密码、令牌和私钥则应留在受权限控制的凭据系统中。流水线只引用稳定的凭据 ID,并把秘密的可见范围压缩到真正需要它的步骤,这样轮换令牌时通常无需修改流水线源码。