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”。第二层是搜索关键字：在日志页面里按 Ctrl+F 搜索 “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 本身坏了。先强制刷新浏览器（Ctrl+Shift+R），再清一下浏览器缓存。如果是企业内网环境，还要检查有没有安全软件拦截了页面资源请求。偶尔插件更新后也会导致页面核心资源加载异常，这时候可以确认下是不是最近新装了某个插件，先禁用或卸载试试。
6.4 忘记管理员密码怎么从界面层面应急
这个问题发生概率不低。如果你还有别的管理员账号，直接用那个账号登录，在用户管理里把密码重置掉就行。如果所有管理员密码都忘记了，那就只能通过修改 Jenkins 配置文件来处理：先停掉 Jenkins 服务，编辑config.xml文件，把<useSecurity>true</useSecurity>改为<useSecurity>false</useSecurity>，重启服务，访问页面就会暂时跳过安全验证，登录进去后再通过界面重新设置管理员密码和权限。操作完记得把useSecurity改回来，否则所有功能都处于无防护状态，非常危险。
6.5 任务太多时界面卡顿怎么办
当任务数量非常多且历史记录庞大时，Dashboard 加载会变慢。除了用视图拆分，还可以在系统管理里调整“工作目录”下的日志保留大小，或者定期清理过期的构建历史。不过我个人的经验是，界面缓慢很多时候不是任务数量的问题，而是服务器资源不够。可以在 Manage Jenkins -> System Information 里查看当前内存和 CPU 情况，如果资源长期饱和，就应该考虑增加节点或做分布式构建了，单靠清理界面数据解决不了根本问题。
我个人在实际操作中最大的体会就是：别指望靠背菜单记住所有功能，最好带着一个实际操作目标去点界面，比如“我现在要新建一个任务，拉取代码并执行一条命令”，然后跟着目标走一遍，界面里的每一个选项都会变得有含义。Jenkins 的 Web 界面功能虽然多，但它的底层逻辑非常清晰：先创建任务，配置触发条件和构建步骤，然后触发构建，再到日志里看结果。把这几个环节连起来走通，你对整个界面的理解就基本到位了。
