1. 第一次打开 Jenkins解锁与初始化向导Jenkins 装好之后最让人懵的不是命令行而是打开浏览器、输入http://localhost:8080那一刻。满屏英文各种输入框还有一个神秘的初始密码要填。很多人在这里就开始怀疑人生我之前是不是装错了其实不是这是 Jenkins 第一次启动时故意设置的一道门槛目的是防止实例还在初始化时被无关人员动配置。这篇保姆教程就围绕 Web 界面本身来展开把你能看到的每个区域、每个按钮是干什么用的讲清楚看完你再去点任何地方心里都有底不会再乱猜。我习惯把 Jenkins 的 Web 界面分成三层去理解最外层是全局导航和系统管理入口中间是任务列表和视图最里面是单个任务的详情页和构建记录页。这套层级从很早就没变过哪怕界面换了几代主题核心逻辑还是这样。所以只要你明白了这个分层思路以后无论 Jenkins 升级到什么版本换个皮肤你也能马上认出来。1.1 解锁 Jenkins初始管理员密码去哪里找首次通过浏览器访问 Jenkins页面会提示“Unlock Jenkins”要求输入管理员初始密码。这个密码不是你自己设置的而是 Jenkins 在第一次启动时随机生成的一段字符串写在一台机器的某个路径下面。如果你用的是 Linux 服务器执行以下命令就能拿到sudo cat /var/lib/jenkins/secrets/initialAdminPassword如果用的是 macOS路径通常在sudo cat ~/.jenkins/secrets/initialAdminPasswordWindows 上默认安装的话一般在C:\ProgramData\Jenkins\.jenkins\secrets\initialAdminPassword也可能在 Jenkins 用户主目录下的.jenkins目录中。实在找不到的话就在整个磁盘上搜initialAdminPassword这个文件名一般几秒就能定位。如果是用 Docker 部署的进容器查更直接docker exec 容器名 cat /var/lib/jenkins/secrets/initialAdminPassword注意这个 initialAdminPassword 只用于首次解锁。解锁成功并且你创建了自己的管理员账号之后这个文件就没有实际用途了。如果你在页面上填了密码提示错误多半是你复制的时候带了空格或者换行符粘贴的时候清理一下即可。解锁进入到下一步之后界面会让你选择“Install suggested plugins”安装推荐插件还是“Select plugins to install”自己选择插件。新手第一次用我的建议非常明确选推荐插件别自己挑。推荐的插件列表已经覆盖了 Git、Pipeline、邮件通知这些最常用的功能能保证你一开始的体验是完整的。自己选插件不是不行但刚接触 Jenkins 的时候你还不一定知道自己需要什么少选一个关键插件后面会绕很多弯路多选一堆又可能让页面加载变慢。选择插件后页面会进入安装进度界面。这里会实时显示插件下载进度、当前安装到哪个插件、以及有没有失败。如果进度界面上出现了一堆红字或者卡住不动通常不是 Jenkins 本身出了问题而是下载插件的网络连接不稳定。这时候别反复重试可以直接关掉页面上的“Retry”或者等一等再试。后面第五章我会专门讲插件下载出问题怎么处理。1.2 初始化向导的最后一步创建管理员账号与实例地址插件安装完成后页面会跳到一个表单让你创建第一个管理员用户。这里要填用户名、密码、全名、邮箱地址。这个账号是 Jenkins 实例里的管理员不是系统用户也不是 Git 仓库的账号它只对 Jenkins 本身生效。邮箱地址建议填真实的常用邮箱因为 Jenkins 发构建通知时要靠它来标识发送人填个假地址会影响邮件插件的正常使用。接下来还有一个非常容易被忽略的步骤确认 Jenkins URL。默认填的是http://localhost:8080/也就是当前访问地址。如果你只是本机试用这个地址没有任何问题直接点保存即可。但如果 Jenkins 是装在一台远程服务器上其他同事也要通过浏览器访问这里就要填一个服务器能对外访问的地址否则后面配置 Git 回调、Webhook 这些功能时回调地址会一直指向 localhost造成各种“能构建但通知不过来”的诡异问题。初始化向导结束后你会正式进入 Jenkins 的主面板。到了这一步真正的界面了解才刚刚开始。后面的内容我会按照实际使用频率从高到低把主面板、系统管理、任务详情、构建记录这几个页面逐个拆开讲。2. 认识主面板Dashboard 布局与高频入口Jenkins 的主页面官方叫 Dashboard中文环境里对应“仪表盘”或者“主面板”。它是一切的起点你每天打开 Jenkins 看到的第一个页面就是它同时它也是信息密度最高的一个页面。如果你能搞懂 Dashboard 上每块区域分别代表什么后面的操作基本就顺了。2.1 顶部导航栏全局入口Dashboard 最上方是一条全局导航栏。左侧的 Jenkins 标志点击后可以随时回到 Dashboard。紧接着是几个核心菜单项新建任务、用户、构建历史、凭据、Manage Jenkins系统管理。这几个入口是整个 Jenkins 使用频率最高的功能我把它们逐个说明一下。“新建任务”就是创建 Job 的入口点击后会进入我们常说的 New Item 页面选择任务类型并命名。这一步是搭建自动化流程的起点几乎所有自动化场景都是从“新建任务”开始的。“用户”菜单可以查看当前实例里的用户列表以及每个用户的权限、最近操作记录。管理员在这边可以新建用户、修改密码、分配权限。如果你所在团队的 Jenkins 只有你一个人用这个页面可能很少打开但多用户团队里它和权限管理直接挂钩。“构建历史”是一个按时间倒序排列的全局构建记录列表能看到所有任务是何时触发的、构建结果是什么。当任务很多时这个页面能帮你快速定位某一段时间内是否有构建失败也是排查问题的好帮手。“凭据”菜单是 Jenkins 存储用户名密码、SSH Key、Token 等敏感信息的地方。界面看起来像个简单的列表但它是连接 Git 仓库、服务器、镜像仓库的枢纽。刚开始接触 Jenkins 的人经常搞不清“页面上的账号密码”和“凭据”的关系——简单来说你在任务配置里写死密码是一次性使用而把密码存成凭据后可以被多个任务反复引用并且不会明文暴露在配置里。这个概念后面做自动化部署时必须掌握。最右边的 Manage Jenkins 是整个 Jenkins 的管理后台入口有没有权限都要从这里进。插件安装、全局工具配置、节点管理、系统设置全都在这个页面里。这一块我会在第三章单独详细讲。2.2 页面主体节点、队列与构建执行器状态Dashboard 中间主体区域的第一大块是“构建队列”和“构建执行器状态”这个区域很多新手直接无视但它其实直观反映了 Jenkins 当前的繁忙程度。“构建队列”显示正在等待执行的任务列表。当你同时触发了很多个构建而可用的执行器数量不够时新触发的任务不会立刻开始而是排队等待。任务在队列里本身没有时间限制但如果长时间不跑就要考虑是不是执行器被占满了或者任务配置有问题。“构建执行器状态”显示当前实例有几个执行器Executor每个执行器空闲还是忙碌。可以把执行器理解成 Jenkins 用来干活的临时工一个执行器同时只能跑一个构建任务。默认安装时主节点上有 2 个执行器意思是同一时间最多能并行跑 2 个构建。如果你经常需要并发构建可以在节点配置里调大执行器数量但也不是越大越好机器 CPU 和内存有限开太多执行器反而会把服务器拖垮。页面往下是任务列表区。默认情况下你新建的任务会直接显示在 Dashboard 上每个任务前面会有一个彩色圆球图标。圆球颜色代表任务最近一次构建的结果状态蓝色代表成功黄色代表不稳定红色代表失败灰色代表任务从未构建过。这套颜色标识贯穿整个 Jenkins 界面记住之后看哪都方便。2.3 搜索框与视图View机制Dashboard 右上角有一个不起眼的搜索框它不只是用来搜任务名称的。你可以在里面输入网址路径或已安装插件的关键字也可以直接输入任务名称跳转到对应页面。这个搜索框在任务数量很多的时候非常实用比在列表里滚动快很多。再来说视图。如果你管理的任务数量多了比如超过 50 个全堆在 Dashboard 上会显得又长又乱。此时可以点击 Dashboard 左上角的“”创建一个新视图。视图本质上是一个任务筛选列表你可以把一组相关联的任务放进同一个视图里比如“前端项目”“后端服务”“定时备份”。任务本身只会创建一次但在多个视图里都能看到视图只是入口不复制任务本体。对团队使用来说按项目划分视图是很有必要的不然大家找任务全靠翻列表效率非常低。另外Dashboard 右上角的登录用户名旁边有个下拉菜单里面可以退出登录、查看你的权限信息。如果界面显示语言不是中文也可以在系统管理里安装本地化插件把界面切成中文这个后面讲插件的时候会提到。3. Manage Jenkins 系统管理面板不是所有设置都在这里但入口在这里Manage Jenkins 是每个主题里最绕不开的页面。很多新手打开这个页面后看到一大排分类和图标会立刻头大这也太多了到底该点哪一个其实它是有规律的新版 Jenkins 把管理功能分成了四组System Configuration系统配置、Security安全、Status Information状态信息、Tools and Actions工具和操作。理解了这四组各自的职责你就不会再在管理后台里迷路。3.1 系统配置与全局安全System Configuration 这一组是日常管理里最常用的。点进“System”配置页面你可以设置 Jenkins 的系统环境变量、执行者数量、邮件通知服务器、时区、全局属性等。这里有一个高频使用场景配置邮件通知。页面底部有“邮件通知”区域填好 SMTP 服务器和账号密码再勾选“通过发送测试邮件测试配置”就能验证邮件是否能发出来。自动化构建加上邮件通知这是 Jenkins 用得最多的组合之一。“Security”组里主要是全局安全配置和凭据管理。全局安全配置控制着用户登录方式、权限策略、CSRF 保护等。一般小团队保持默认即可但如果接入了 LDAP 或统一身份认证就需要在这里调整认证方式。凭据管理前面已经提过是存放各种密码和密钥的地方强烈建议所有密码都通过“凭据”功能存储而不是硬编码在任务配置里。3.2 插件管理安装、更新与可用插件Manage Jenkins 页面里被点得最多的大概率是“Plugin Manager”插件管理。它的界面分为几个标签页Updates有更新、Available可用插件、Installed已安装插件、Advanced高级。日常操作主要集中在前三个。Available 页面里你可以搜索并安装新插件。安装插件时Jenkins 会先下载插件文件然后重启实例才能生效。如果网络下载超时或者失败页面会报红字错误。有时候在 Available 里搜不到某个插件并不是那个插件不存在而是更新源Update Site没有刷新。Jenkins 默认的更新源地址是官方源在国内访问经常不稳定这也是插件安装失败最常见的原因之一。解决办法是在 Advanced 标签页里把更新站点地址替换为一个可用的镜像源然后点击“Check now”检查更新再去搜索就能找到了。这个操作我在后面的排查部分再详细说。Installed 页面会列出所有已安装的插件及其版本。有些插件安装后没生效可以先在这里确认它是否已安装、版本是否符合要求。排查构建报错时插件版本信息也是非常重要的线索。3.3 全局工具配置与节点管理Tools and Actions 组里的“Global Tool Configuration”全局工具配置是另一个高频入口。这里配置的是 JDK、Maven、Git 等工具的路径或自动安装方式。Jenkins 执行构建任务时脚本里用到的mvn、java、git命令都依赖于这里的配置。如果你在任务里配置了 Maven 命令但构建时报“mvn: command not found”十有八九就是这里没配置好。还有一个很实用的管理入口是“Nodes and Clouds”节点管理。你可以在里面添加新的构建节点也可以查看主节点的状态。当单台机器构建压力大或者要在不同操作系统上分别执行构建时通过这里添加 Agent 节点就能实现分布式构建。节点的在线/离线状态、执行器数量、标签Label都在这个页面管理。Status Information 组里主要是系统信息、系统日志、负载统计。系统日志页面在排错时很关键如果某个插件运行时报错错误信息一般会记录在本机日志中而在界面上不一定看得到。有时候构建失败但控制台输出没有明确异常先来这里看系统日志往往能发现插件抛出的堆栈信息。4. 任务Job详情页构建任务的核心工作台任务详情页也就是你在任务列表点击某个具体任务名称后进入的页面是日常操作最密集的地方。很多人在任务配置里设置了一堆参数却搞不清楚详情页上的各种状态和按钮分别对应什么导致“构建明明触发成功了但不知道去哪看结果”。这一章就把任务详情页面从头到尾讲明白。4.1 任务详情的状态区域进入一个任务的详情页右边主要显示的是任务的概要信息包括最近一次构建的状态、最近几次构建的结果、任务健康程度趋势以及相关的变化记录。如果你是刚创建了一个任务但从未构建过这里会显示“No builds”之类的提示状态球是灰色。任务健康度是 Jenkins 根据一段时期内构建成功比例计算出的一个百分比并以天气图标直观展示太阳代表健康阴天代表一般暴雨代表频繁失败。这个设计很有用尤其当你管理多个任务时扫一眼天气图标就能知道哪些任务最近老出问题根本不需要逐个点进去看构建历史。4.2 左侧菜单配置、立即构建、工作区与删除任务任务详情页左侧有一列功能菜单不同任务类型菜单略有差异但核心入口基本一致。“Configure”配置是修改任务设置的地方点击进去会回到任务配置页面可以调整 Git 仓库地址、分支、构建步骤、构建参数、触发器、邮件通知等所有设置。这是任务生命周期里使用频率最高的入口之一。很多新手把“创建任务”当成唯一重点其实任务的绝大多数修订动作都是在 Configure 里完成的。“Build Now”立即构建用于手动触发一次构建。点一下之后页面下方会立刻多出一条构建记录状态可能是排队或者运行中。这也是快速验证配置是否正确的首选方式——改完配置后点一下 Build Now看控制台输出就能判断环境通了没有。“Workspace”工作区可以浏览当前任务在节点上拉取代码、构建后生成的文件目录。当你需要确认构建产物在什么位置、或者临时查看某个文件时很有用。注意工作区是构建节点上的实际目录不是浏览器里的虚拟页面。“Changes”显示当前构建与上次构建之间涉及到的代码变更记录前提是你使用了 Git 等 SCM 插件。这条信息在排查“某个构建突然挂了是不是因为某次代码提交引入的问题”时非常高效。“Delete Project”用来删除整个任务包括历史构建记录。这个操作没有二次确认弹窗之前要小心如果确实想删记得提前备份任务配置而不是事后拍大腿。对于 Pipeline 类型的任务左侧菜单还会多出“Pipeline Syntax”等辅助入口用于生成流水线脚本代码这个后面讲流水线时再展开。4.3 新建任务时的类型选择第一次点击“新建任务”时会看到“Enter an item name”输入框和下面几个类型选项。类型有 Freestyle project自由风格项目、Pipeline流水线、Multi-branch Pipeline多分支流水线、Folder文件夹等。Freestyle 是最简单的类型适合通过界面勾选配置构建步骤比如从 Git 拉代码、执行 Shell 命令、归档产物。对新手来说用 Freestyle 入门最友好相当于 Jenkins 的可视化编排模式。Pipeline 则是通过 Groovy 脚本定义整个构建过程配置保存在 Jenkinsfile 中适合复杂流程和版本化管理。它灵活但要求会写脚本。我的建议是先从 Freestyle 做起熟悉界面和构建过程再逐步迁移到 Pipeline。一上来就折腾 Pipeline 容易因为脚本语法问题被劝退。本质上任务类型没有好坏只有合不合适当前场景。5. 构建记录与控制台输出读懂构建结果的关键任务触发后最重要的就是判断构建到底跑得怎么样。很多人第一次点进构建记录看到一堆日志就慌了不知道看哪里、哪些是关键内容。这一章用来解决“日志恐惧症”。5.1 控制台输出怎么读点击任务详情页下方某个构建编号进入构建详情页左侧菜单里有一个“Console Output”控制台输出点进去就能看到完整的构建日志。日志是按执行时间顺序排列的记录了从开始拉取代码到最终结束的每一步动作。读日志时我一般按三个层次去看。第一层是看末尾如果构建成功日志最后通常会出现“BUILD SUCCESS”“Finished: SUCCESS”这样的标志如果失败则是“BUILD FAILURE”或“ERROR”。第二层是搜索关键字在日志页面里按 CtrlF 搜索 “ERROR”“Exception”“fatal”“Could not” 这些关键词往往能直接定位到出错的位置。第三层是回看上下文确定错误出现在哪个步骤后往上翻几十行看看这一步是在执行什么是克隆代码失败、编译报错还是测试失败。这样基本能判断 80% 以上的构建问题。5.2 构建状态颜色和稳定性构建状态除了我们前面说的成功、失败、不稳定还有一个容易被忽略的状态叫“中止Aborted”。它一般表示构建被人为中断或者构建超时被系统结束。中止不一定代表代码有问题有可能是你误点了操作。“不稳定”状态也值得说明一下。Jenkins 里构建成功但不稳定通常与测试结果有关单元测试有失败用例或者代码静态分析产生了警告构建可能标记为黄色但不会显示为红色失败。所以看到黄色时要留个心眼不一定是大问题但需要去看测试报告。在构建详情页还能看到本次构建的参数、耗时、触发原因、变更集。这些信息在回看一下“这个构建为什么会被触发”时很有用。比如构建是手动点触发的还是因为代码 Push 触发的还是定时构建触发的页面都会有记录。排查问题时先确认触发原因能省去很多猜疑。5.3 构建历史保留策略Jenkins 默认会保存很多构建历史记录时间久了会占用磁盘空间。在任务配置页面有一个“Discard old builds”选项可以设置保留构建的天数或数量。比如设置只保留最近 30 天的构建或者最多保留 10 次构建超过的会自动清理。这个设置很有必要因为大型项目的构建产物和历史日志可能动辄几个 GB不清理的话磁盘很快会满Jenkins 界面也会因为数据量过大变慢。如果你构建完需要保留一些产物供后续下载使用可以在配置里勾选“Archive the artifacts”这样构建完成后会有一个“已归档产物”的区域方便直接下载。这比自己去服务器上翻文件目录要快捷得多。6. 实际使用中的界面问题与排查技巧到这里Jenkins 的 Web 界面基本算是过了一遍。但实际操作中总有一些频率很高、界面上的信息又不会直接告诉你的事情。这一章列几个我经常被问到的问题以及对应的排查经验。6.1 构建时间显示总是差 8 小时Jenkins 默认使用服务器时区如果你的服务器时区没设置正确界面上所有构建时间都会和本地时间对不上。在系统管理-系统配置里的“全局属性”中勾选“用户自定义时区”填上Asia/Shanghai再保存刷新页面时间显示就正常了。这个坑在你做定时构建Build periodically时尤其明显因为定时表达式是基于服务器本地时间的不调时区的话调度时刻会完全跟预期错开。6.2 插件下载慢或安装失败前面提到过插件安装失败大概率是更新源问题。打开 Manage Jenkins - Plugin Manager - Advanced页面底部有一个“Update Site”把默认地址改成可用的镜像源然后点击“Check now”刷新更新列表再回到 Available 页面搜索插件安装。换源后下载速度提升非常明显实测插件安装基本不会再有超时。注意修改更新站点后Jenkins 可能会提示部分依赖插件版本冲突。这种情况下不要一股脑全选升级而是只安装你需要的插件避免破坏现有环境的稳定。6.3 页面只有局部刷新或样式错乱如果你碰到 Jenkins 页面排版错乱、按钮点了没反应、菜单消失这类问题优先不要怀疑 Jenkins 本身坏了。先强制刷新浏览器CtrlShiftR再清一下浏览器缓存。如果是企业内网环境还要检查有没有安全软件拦截了页面资源请求。偶尔插件更新后也会导致页面核心资源加载异常这时候可以确认下是不是最近新装了某个插件先禁用或卸载试试。6.4 忘记管理员密码怎么从界面层面应急这个问题发生概率不低。如果你还有别的管理员账号直接用那个账号登录在用户管理里把密码重置掉就行。如果所有管理员密码都忘记了那就只能通过修改 Jenkins 配置文件来处理先停掉 Jenkins 服务编辑config.xml文件把useSecuritytrue/useSecurity改为useSecurityfalse/useSecurity重启服务访问页面就会暂时跳过安全验证登录进去后再通过界面重新设置管理员密码和权限。操作完记得把useSecurity改回来否则所有功能都处于无防护状态非常危险。6.5 任务太多时界面卡顿怎么办当任务数量非常多且历史记录庞大时Dashboard 加载会变慢。除了用视图拆分还可以在系统管理里调整“工作目录”下的日志保留大小或者定期清理过期的构建历史。不过我个人的经验是界面缓慢很多时候不是任务数量的问题而是服务器资源不够。可以在 Manage Jenkins - System Information 里查看当前内存和 CPU 情况如果资源长期饱和就应该考虑增加节点或做分布式构建了单靠清理界面数据解决不了根本问题。我个人在实际操作中最大的体会就是别指望靠背菜单记住所有功能最好带着一个实际操作目标去点界面比如“我现在要新建一个任务拉取代码并执行一条命令”然后跟着目标走一遍界面里的每一个选项都会变得有含义。Jenkins 的 Web 界面功能虽然多但它的底层逻辑非常清晰先创建任务配置触发条件和构建步骤然后触发构建再到日志里看结果。把这几个环节连起来走通你对整个界面的理解就基本到位了。
深度解析：底层原理、避坑指南与替代方案)
