企业官网建设流程全解析

1. 先搞清楚凭证到底在解决什么问题

1.1 从一次“莫名其妙”的构建失败说起

刚接手 Jenkins 那阵子，我碰到过一个很典型的场景：流水线昨天还跑得好好的，今天早上点进去一看，控制台一片红，卡在git clone那一步，报的是fatal: could not read Username for 'http://git.xxx.com': No such device or address。当时第一反应是网络问题，ping 了一下通了；第二反应是仓库地址写错了，复制粘贴到浏览器能打开；折腾了半小时才反应过来——构建任务是从别的项目复制过来的，作业里配置的凭证 ID 在新环境里根本不存在，Jenkins 拿不到用户名密码，就卡在了这里。

这件事让我彻底意识到，凭证（Credentials）不是 Jenkins 的一个“可选项”，而是流水线能跑起来的地基。只要涉及从代码仓库拉代码，就必然涉及“Jenkins 用什么身份去访问 Git 服务器”这个问题。你当然可以把用户名密码硬编码在 Jenkinsfile 里，仓库是私有的话也能跑通，但这么干的后果，就是你的密码会明晃晃地躺在 Git 历史、构建日志、以及任何一个能看到这个作业配置的人眼前。

Jenkins 凭证机制的核心作用，说白了就三件事：统一存储、按需调用、自动脱敏。第一，把敏感信息集中存放在$JENKINS_HOME/credentials.xml里，并且用 Jenkins 自己的加密密钥做加密，不是明文躺着；第二，流水线里只写一个凭证 ID，真正的密钥在运行时才注入进去，代码里看不到任何敏感字符；第三，Jenkins 会尽量把绑定到环境变量的敏感值在控制台输出中替换成****，降低日志泄露的风险。这三件事合起来，才是“凭证”这两个字真正的分量。

这篇笔记面向的是已经装好 Jenkins、也装好了 Git，但卡在“怎么把 Git 连接配通”这一步的朋友。不管你是用 SSH 密钥还是账号密码，是 Windows 上跑还是 Linux 上跑，是自由风格项目还是声明式 Pipeline，下面这套流程基本都能套用。

1.2 凭证在 Jenkins 内部是怎么存和怎么取的

很多人以为凭证是存在某个数据库里的，其实不是。Jenkins 的凭证默认落在$JENKINS_HOME/credentials.xml，文件长这样：

<com.cloudbees.plugins.credentials.SystemCredentialsProvider> <domainCredentialsMap class="hudson.util.CopyOnWriteMap$Hash"> <entry> <com.cloudbees.plugins.credentials.domains.Domain> <specifications/> </com.cloudbees.plugins.credentials.domains.Domain> <java.util.concurrent.CopyOnWriteArrayList> <com.cloudbees.jenkins.plugins.sshcredentials.impl.BasicSSHUserPrivateKey> <scope>GLOBAL</scope> <id>git-ssh-prod</id> <description>生产仓库 SSH 密钥</description> <username>git</username> <privateKey> <secretBytes>...</secretBytes> </privateKey> </com.cloudbees.jenkins.plugins.sshcredentials.impl.BasicSSHUserPrivateKey> </java.util.concurrent.CopyOnWriteArrayList> </entry> </domainCredentialsMap> </com.cloudbees.plugins.credentials.SystemCredentialsProvider>

注意<secretBytes>这一段，它是被加密过的。加密用的密钥在$JENKINS_HOME/secret.key和$JENKINS_HOME/secrets/目录下。这就解释了一个很常见的问题：为什么把整个 Jenkins 目录拷到另一台机器上，凭证全部失效了。因为密钥文件没一起拷过去，或者拷贝过程中变了，原来的密文自然解不开。

理解这一点，对后面的故障排查非常关键。当你看到java.io.IOException: Unable to decrypt或者凭证列表里显示一坨看不懂的东西，基本就是密钥文件出问题了，而不是凭证本身写错了。

1.3 四类凭证的适用场景对照

Jenkins 默认提供的凭证类型不多，但覆盖了绝大部分 Git 场景。我整理了一张选型表，你在加凭证之前先对号入座，能省掉很多来回试错的时间。

判断逻辑其实很简单：看你的仓库地址是http://开头还是git@开头。git@开头的走 SSH 密钥，http://或https://开头的走用户名密码或者令牌。这两条路的选择不是随便定的，而是由 Git 客户端的协议决定的，用错了必然连不上。

2. 动手之前，先把 Git 侧的事情理顺

2.1 确认 Jenkins 主机和 Git 服务器是通的

这一步听起来像废话，但实际排查中，至少三成的“凭证无效”最后都定位到了网络层。Jenkins 跑在容器里、跑在内网隔离区、跑在另一台云主机上，这些情况都会导致它能打开管理页面，但连不上代码仓库。

先做最基本的连通性测试。SSH 方式的话，用 Jenkins 运行账户去测，不是用你自己的账号：

# Linux，先切到 jenkins 用户 sudo su -s /bin/bash jenkins ssh -T -p 22 git@git.example.com # 成功的话一般会返回类似 welcome 的提示，并明确告诉你认证通过

HTTP(S) 方式的话：

curl -I -u yourname:yourpass http://git.example.com/group/repo.git/info/refs?service=git-upload-pack # 返回 200 说明账号密码没问题，返回 401 说明认证不过

注意：Windows 上以服务方式安装的 Jenkins，默认运行账户是Local System，它的家目录是C:\Windows\System32\config\systemprofile，跟你当前登录用户的家目录完全不是一回事。你在自己账号下生成密钥、配好 known_hosts，对 Jenkins 服务来说等于不存在。这是 Windows 环境最容易踩的第一个坑。

2.2 生成 SSH 密钥对并完成服务端授权

如果你决定走 SSH 密钥路线，密钥的生成姿势有讲究。我一般这么干：

ssh-keygen -t ed25519 -C "jenkins@ci-host" -f /var/lib/jenkins/.ssh/id_ed25519_ci -N ""

几个参数解释一下，都是有意为之的：

• -t ed25519：比 RSA 更短更快，现代 Git 服务端基本都支持。如果你的服务端比较老只认 RSA，那就换-t rsa -b 4096。
• -C：注释，写上用途和主机名，将来在服务端看授权列表的时候能一眼认出是谁的密钥，别写个xxx@xxx这种没信息量的。
• -f：指定文件名。千万不要用默认的id_rsa覆盖，很多环境下 Jenkins 主机还跑着别的东西，覆盖默认密钥会连带把别的服务搞挂。单独起个名字，比如id_ed25519_ci。
• -N ""：空口令。这里要解释一下，不是说不该设口令，而是 Jenkins 凭证里如果填了带口令的私钥，得把口令也一起填进去，多一层管理成本。规范做法是私钥本身设口令、然后 Jenkins 凭证里把 Passphrase 也填上；嫌麻烦的话空口令也行，但前提是这台主机的访问权限要收紧到只有运维能登。

生成完，公钥内容复制出来：

cat /var/lib/jenkins/.ssh/id_ed25519_ci.pub

粘到 Git 服务端的部署密钥（Deploy Key）或者用户 SSH Keys 里。这两者选哪个，看你的场景：只读单个仓库，用 Deploy Key，权限最小；要读多个仓库，用机器用户（比如叫ci-bot）的 SSH Keys，一把钥匙开多扇门。我倾向后者，因为跨项目复用一个凭证，管理成本低得多。

2.3 Jenkins 运行账户与家目录对照表

前面提过 Windows 的坑，这里给一张跨平台对照表，把它彻底说清楚。你可以照着表去确认“我的密钥到底该放哪”。

确认方法很简单，在 Jenkins 里新建一个自由风格任务，构建步骤写一条命令：

whoami echo $HOME

Windows 上就写whoami和echo %USERPROFILE%。跑一次看输出，比自己猜靠谱一百倍。我第一次遇到 Windows 那个坑的时候，就是靠这招五分钟定位的。

3. 添加 SSH 类型凭证：字段逐个拆开讲

3.1 从管理界面点到添加页

路径是固定的：Manage Jenkins → Credentials → System → Global credentials (unrestricted) → Add Credentials。

这里有两个层级的坑需要提醒。第一，System下面的Global credentials是全局域，任何作业都能用；如果你建了自定义 Domain，凭证就只能在对应域里可见，作业里写 ID 会报“找不到凭证”。第二，Store 选默认的Jenkins就行，除非你装了 HashiCorp Vault 之类的插件，那另说。

选类型的时候挑SSH Username with private key，然后字段是这些：

• Scope：Global意味着所有节点、所有作业可用；System意味着只有 Jenkins 自身（比如拉取 Jenkins 配置仓库）能用，普通作业看不到。没特殊需求就选 Global。
• ID：这是关键字段，流水线里就是靠它引用的。建议用可读性强的命名，别用系统自动生成的那串 UUID。我的命名习惯是git-ssh-<用途>-<环境>，比如git-ssh-deploy-prod、git-ssh-readonly-dev。UUID 那种a1b2c3d4-...过两个月你自己都认不出来。
• Description：写清楚这把钥匙对应哪个 Git 服务、哪个机器用户、什么权限。比如“GitLab 生产组 ci-bot 只读密钥，2024-06 轮换”。
• Username：这里填的是 SSH 连接时的用户名，不是 Jenkins 用户名，也不是你的 Git 账号名。GitLab/Gitea 走 SSH 时统一是git；Bitbucket 也是git；极少数自建服务可能用别的，去 Git 服务的 SSH 克隆地址里看@前面那一段，是什么就填什么。
• Private Key：选Enter directly，把私钥文件全部内容粘进去，包括-----BEGIN OPENSSH PRIVATE KEY-----和结尾那一行。或者选From the Jenkins master ~/.ssh，让 Jenkins 自己去读文件。我一般推荐 Enter directly，因为凭证跟着 Jenkins 配置走，备份迁移的时候不会漏文件。

注意：粘贴私钥的时候极度容易出问题。一是别把.pub公钥粘进去，公钥粘进去必然认证失败，而且报错信息不会直接告诉你“你粘错了”。二是别丢换行或加多余空格，有些编辑器会自动给文件末尾加空行，一般没事，但中间被自动格式化过就废了。粘完检查一下行数，ed25519 私钥通常 3 到 4 行。

3.2 known_hosts 这个坎，三种处理姿势

凭证加完了，很可能第一次构建还是失败，报Host key verification failed。原因是 SSH 客户端第一次连陌生主机会要求确认主机指纹，而 Jenkins 是无交互的，确认不了就断了。

处理方式有三种，按推荐度从高到低排：

第一种，ssh-keyscan 预置指纹（最推荐）。用 Jenkins 运行账户执行，把目标 Git 服务器的公钥写进 known_hosts：

sudo su -s /bin/bash jenkins mkdir -p ~/.ssh && chmod 700 ~/.ssh ssh-keyscan -p 22 git.example.com >> ~/.ssh/known_hosts 2>/dev/null chmod 644 ~/.ssh/known_hosts

这么做的逻辑是：指纹是通过一个相对可信的通道预先固定的，之后每次连接都会比对。安全性和便利性平衡得最好。

第二种，用 Jenkins Git 插件自带的 Host Key Verification 配置。新版本的 Git 插件在全局安全配置里提供了主机密钥校验策略，可以选“接受首次连接的主机密钥”或者“手动维护已知主机列表”。这个方案的好处是跨节点统一，坏处是它只对 Git 插件发起的连接生效，你在 Pipeline 里手写sh 'git clone'是走不到这个逻辑的。

第三种，-o StrictHostKeyChecking=no（不推荐，但要知道它的存在）。可以在 Jenkinsfile 里这么写：

sh 'GIT_SSH_COMMAND="ssh -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null" git clone git@git.example.com:group/repo.git'

这东西能用，但它意味着你放弃了对主机身份的校验，中间人攻击是拦不住的。只在临时排查时用，不要写进正式的流水线。我见过太多团队把这一行抄进模板，一用就是三年。

3.3 验证凭证是否真的通了

加完凭证别急着往流水线里塞，先单独验一次。最直接的办法是建一个一次性的自由风格任务，源码管理选 Git，URL 填git@git.example.com:group/repo.git，Credentials 选你刚建的那个，然后直接点构建。

还有一个更轻的办法，在 Jenkins 的脚本控制台（Manage Jenkins → Script Console）里跑一段 Groovy，确认凭证存在且可读：

import jenkins.model.Jenkins import com.cloudbees.plugins.credentials.CredentialsProvider def creds = CredentialsProvider.lookupCredentials( com.cloudbees.jenkins.plugins.sshcredentials.SSHUserPrivateKey.class, Jenkins.instance, null, null ) creds.each { c -> println "ID: ${c.id} | User: ${c.username} | Desc: ${c.description}" }

提示：只在测试环境用脚本控制台做验证，生产环境的脚本控制台权限要收好，因为它本质上相当于 Jenkins 的 root shell。

4. 账号密码 / 令牌类型凭证的配置要点

4.1 什么时候绕不开 HTTP(S) 方式

有些团队就是不用 SSH，原因多种多样：防火墙只开了 443、Git 服务侧没开放 SSH、或者干脆是为了审计方便想走统一的 HTTP 网关。这个时候就得上用户名密码或者令牌。

选类型的时候，Username with password和Secret text两者差别在于：前者在 Pipeline 里能同时拿到用户名和密码两个变量，适合拼 URL 的场景；后者只有一个字符串，适合直接当令牌用。如果 Git 服务端已经禁用了密码认证、强制要求访问令牌，那老老实实用Secret text，把令牌整串填进去。

4.2 用访问令牌替代密码的具体做法

以常见的自建 Git 服务为例，先去个人设置里生成一个访问令牌，权限勾选read_repository就够了，用于拉代码不需要write_repository。生成出来的令牌通常只显示一次，复制走。

然后回到 Jenkins 加凭证，类型选Username with password，用户名填你的账号，密码字段填令牌串，不是登录密码。很多服务端在禁用密码认证后，你填登录密码会直接返回 401，而且日志里只告诉你认证失败，不告诉你是密码还是令牌的问题，白白浪费排查时间。

如果就是要用Secret text类型，那在 Pipeline 里拼接的方式会不太一样：

withCredentials([string(credentialsId: 'git-token-prod', variable: 'GIT_TOKEN')]) { sh ''' git clone http://oauth2:${GIT_TOKEN}@git.example.com/group/repo.git ''' }

注意这里的用户名占位符，不同服务端要求不一样：GitLab 常用oauth2，Gitea 用你的用户名也行，具体看你服务端的文档。

4.3 ID 命名的统一规范

凭证多了以后，命名混乱是灾难。我给自己定的规矩是四段式：<系统>-<协议>-<用途>-<环境>。举几个实际的例子：

• git-ssh-deploy-prod
• git-http-readonly-dev
• git-token-release-staging
• nexus-http-publish-prod

好处很直接：在流水线里看到credentialsId: 'git-ssh-deploy-prod'，不用点进凭证页面就知道这是干啥的、挂在哪个环境。换环境部署的时候，把后缀从prod改成staging就行，不用去翻密码本。

5. 在流水线里把凭证真正用起来

5.1 自由风格项目的配置位置

自由风格任务最简单，源码管理 → Git → Credentials下拉框选一个就行，URL 填 SSH 或 HTTP 地址，Jenkins 会自动匹配对应类型的凭证。如果是 SSH 地址但下拉框里只有密码类型凭证，它会连不上，反过来也一样。

这里有个容易忽略的点：下拉框里显示的是 Description，不是 ID。所以 Description 写得清楚非常重要，尤其是凭证数量上双之后。另外就是前面提到的那次翻车——复制任务的时候，凭证 ID 在新机器上不存在，下拉框会显示成红色报错，但构建按钮还是能点，点了就失败。

5.2 声明式 Pipeline 的两种写法

声明式 Pipeline 里，拉代码主要有两种方式。

第一种，用checkout scm，让 Jenkins 自己去读作业配置里的源码管理设置：

pipeline { agent any stages { stage('Checkout') { steps { checkout scm } } } }

这种写法适合代码仓库固定不变的情况，简单省事。

第二种，显式指定仓库和凭证，适合一个流水线要拉多个仓库的场景：

pipeline { agent any stages { stage('拉取主仓库') { steps { checkout([ $class: 'GitSCM', branches: [[name: '*/main']], userRemoteConfigs: [[ url: 'git@git.example.com:group/main-repo.git', credentialsId: 'git-ssh-deploy-prod' ]] ]) } } stage('拉取配置仓库') { steps { checkout([ $class: 'GitSCM', branches: [[name: '*/master']], userRemoteConfigs: [[ url: 'http://git.example.com/group/config-repo.git', credentialsId: 'git-http-readonly-prod' ]] ]) } } } }

第二种写法里，$class: 'GitSCM'这一坨看起来吓人，但套路固定，抄一次改改 URL 和凭证 ID 就能反复用。关键是每个userRemoteConfigs里都要单独指定credentialsId，不能指望它复用第一个的。我踩过这个坑，第二个仓库没写凭证 ID，构建日志里报“没有权限”，查了半天才发现两处配置不一样。

5.3 脚本式 Pipeline 与 withCredentials 的细节

脚本式 Pipeline 里最常见的两种模式，sshagent和withCredentials。

// 模式一：sshagent，把私钥临时加载进 ssh-agent node { sshagent(credentials: ['git-ssh-deploy-prod']) { sh 'git clone git@git.example.com:group/repo.git' } } // 模式二：withCredentials，把用户名密码注入环境变量 node { withCredentials([usernamePassword( credentialsId: 'git-http-readonly-prod', usernameVariable: 'GIT_USER', passwordVariable: 'GIT_PASS' )]) { sh 'git clone http://${GIT_USER}:${GIT_PASS}@git.example.com/group/repo.git' } }

两者的区别值得说清楚。sshagent是把私钥交给 ssh-agent 进程托管，Git 在需要的时候通过 agent 完成认证，私钥本身不会出现在环境变量或命令行里，安全边界更干净。withCredentials是把明文值注入环境变量，虽然 Jenkins 会尝试在日志里做脱敏替换，但如果你的脚本把变量重定向到文件再cat出来，脱敏就绕过去了，这一点必须心里有数。

注意：用withCredentials拼 URL 的时候，变量一定要用单引号包裹的 shell 脚本或者 Groovy 字符串插值，混用会导致变量没展开。sh "git clone http://${GIT_USER}..."这种双引号写法里，${GIT_USER}是 Groovy 先插值的，值在 Jenkins 侧展开，容易和 shell 变量搞混；用单引号写sh 'git clone http://${GIT_USER}...'才是让 shell 去展开环境变量，行为更符合预期。

更稳妥的做法是避免把密码塞进 URL，改用 Git 的凭证助手：

withCredentials([usernamePassword( credentialsId: 'git-http-readonly-prod', usernameVariable: 'GIT_USER', passwordVariable: 'GIT_PASS' )]) { sh ''' git config --global credential.helper '!f() { echo "username=${GIT_USER}"; echo "password=${GIT_PASS}"; }; f' git clone http://git.example.com/group/repo.git ''' }

这样密码不会出现在进程命令行参数里（ps看不到），比直接拼 URL 干净得多。

5.4 那些和 Git 相关、值得记住的环境变量

Jenkins 的 Git 插件在拉完代码后，会往构建环境里注入一批变量，写脚本的时候很有用：

判断分支的时候有个小坑：GIT_BRANCH带origin/前缀，直接跟main比是不相等的。我一般这么处理：

def branch = env.GIT_BRANCH.replaceFirst('^origin/', '') if (branch == 'main') { // 走发布流程 }

还有一点，这些变量只有在 Git 插件真正执行过 checkout 之后才存在。如果你的流水线第一步是别的操作就去读env.GIT_COMMIT，拿到的是空字符串，然后后面拼出来的镜像 Tag 就是一个空串，问题会延后到部署阶段才暴露，排查起来更费劲。

6. 报错排查实录与速查表

6.1 六个高频报错的现象、原因和处置

下面这张表里的每一条，都是我或者身边同事真实遇到过的，不是从文档里抄的。

注意第 5 条，这是我见过最隐蔽的一类问题。表面上看起来是凭证内容有问题，实际上是密钥体系坏了。这种情况下如果你直接去删凭证重建，会连累所有依赖这些凭证的作业。正确顺序是先确认secret.key在不在、secrets/目录下的文件是否完整，再决定要不要重建。

6.2 我自己习惯的排查顺序

每次遇到拉代码失败，我基本是按这个顺序走的，平均五分钟能定位：

第一步，看构建日志里的第一行 git 命令。Jenkins 的 Git 插件实际上执行的是类似git -c diff.mnemonicprefix=false -c core.quotepath=false --no-optional-locks fetch ...这样的命令，看清楚它实际用的是哪个地址、哪个协议，别被你在界面上填的东西迷惑，有时候作业配置和实际执行不一致。

第二步，在 Jenkins 主机上用同一个运行账户手动敲一遍等价命令。这是最有效的办法，因为它把 Jenkins 的干扰因素全排掉了，剩下的就是纯 SSH/HTTP 的问题。手动能通，Jenkins 不通，那就是凭证注入环节的问题；手动也不通，那就是密钥或网络的问题。

第三步，看凭证的作用域和域。前面说过，Domain 和 Scope 配错了会导致作业根本看不到这个凭证，表现是下拉框里压根没这一项，或者流水线报 “Could not find credentials”。

第四步，才去看密钥内容本身。公钥私钥是否配对，公钥有没有过期或被移除，服务端账号有没有被禁用。这一步放最后，因为概率最低，但很多人一上来就怀疑这个，来回折腾。

6.3 几条踩过坑才记住的经验

第一条，凭证轮换要提前想好。密钥是有有效期的，团队里人离职了要换，服务端策略变更了要换。我给自己定的规矩是，凭证 ID 一旦确定就永远不改，轮换的时候只更新内容不更新 ID。这样所有流水线都不用动，改一处生效全部。如果反过来，每次轮换都换个新 ID，那你得去全量搜索所有 Jenkinsfile 和作业配置，漏一个就炸一个。

第二条，节点上的凭证是各自独立的。Jenkins 支持多节点，凭证虽然配置在 master 上，但实际使用是在 slave 上完成的。SSH 密钥会被传输过去，但 known_hosts 不会——slave 上得单独配。这个坑在多节点环境下几乎是必踩的，表现就是 master 上跑得好好的任务，一到某个 agent 上就报主机指纹错误。

第三条，日志脱敏不是万能的，不要依赖它。Jenkins 的脱敏机制是基于字符串匹配的，它会尝试把绑定的敏感值替换成星号。但如果你在脚本里对密码做了编码、拼接、或者写进文件再读出来，脱敏很容易失效。真正的安全原则是：敏感值尽可能不要出现在标准输出里，而不是赌脱敏一定生效。

第四条，Windows 上优先改用非服务方式启动 Jenkins 来做调试。服务方式的账户隔离问题会带来大量难以理解的认证失败。调试阶段用java -jar jenkins.war直接跑，跑通了再改成服务方式，并且把服务登录账户显式改成生成密钥的那个账户，比在 Local System 那套家目录里摸索要省事得多。

第五条，插件镜像和学习路径。升级站点在国内访问有时会比较慢，可以换成国内高校或云厂商提供的镜像源来加速插件下载，这跟凭证本身没关系，但配置凭证前如果先装好了 Git 插件、Credentials Binding 插件、SSH Agent 插件这几个必备项，后面的步骤会顺畅很多。Git 客户端本身也要装，并且确保git --version在 Jenkins 主机的命令行里能执行——Jenkins 自己不带 Git，它只是个调用者。

这些经验听起来琐碎，但都是那种“不知道就得卡半天，知道了三分钟搞定”的东西。凭证配置这件事本身没有多高深的技术含量，真正的门槛在于左右依赖的环境细节太多，任何一环错位都会表现为同一个模糊的认证失败。把上面这套流程走一遍，把每步的验证点都过一遍，后面的流水线开发才会真正顺畅起来。

我自己现在带新人的时候，都会让他们先独立把这条链路配通一遍：生成密钥、加授权、建凭证、跑通一次 checkout、再故意制造一次失败去读日志。走完这一轮，后面遇到再花哨的 Jenkins 报错，基本都能顺着这条线摸到根上。