18.1.4 插件安装与初始化向导

本节介绍 Jenkins 初次启动后的插件安装与初始化向导流程，确保具备可用的基础能力与安全配置，并提供可执行示例、排错思路与练习。

初始化向导概览#

Jenkins 首次启动后，通过浏览器向导完成解锁、插件安装、管理员创建与 URL 配置。

解锁 Jenkins（含命令解释）#

访问 http://<host>:8080。
查看解锁密钥文件并填入页面。

# 查看解锁密钥（JENKINS_HOME 默认路径）
sudo cat /var/lib/jenkins/secrets/initialAdminPassword
# 预期输出：一行随机字符串，将其复制到 Web 页面解锁框

命令解释：cat 读取解锁密钥文件，解锁后该文件仍可保留用于审计。

插件安装策略与示例#

选择方式
- 安装推荐插件：适合快速入门。
- 选择插件安装：适合生产环境最小化安装。

建议的基础插件清单
- Pipeline：workflow-aggregator、pipeline-stage-view
- SCM：git（按需：github、gitlab-plugin）
- 凭据：credentials、ssh-credentials
- 日志增强：timestamper、ansicolor

离线安装示例（生产无公网）#

预先下载插件 .hpi/.jpi，保存到 JENKINS_HOME/plugins。
设置权限并重启 Jenkins。

# 假设已下载 git.hpi、workflow-aggregator.hpi
sudo cp git.hpi workflow-aggregator.hpi /var/lib/jenkins/plugins/
sudo chown jenkins:jenkins /var/lib/jenkins/plugins/*.hpi
sudo systemctl restart jenkins
# 预期效果：重启后在 Manage Jenkins -> Plugins 中可见插件已启用

在线安装示例（含镜像源配置）#

# 设置 Jenkins 更新中心（以清华源为例）
sudo sed -i 's#updates.jenkins.io#mirrors.tuna.tsinghua.edu.cn/jenkins#' \
  /var/lib/jenkins/updates/default.json

sudo systemctl restart jenkins
# 预期效果：插件页面可从镜像源下载

创建管理员账户#

在向导中设置管理员用户名与强密码，避免使用默认 admin。
建议启用后续“基于角色”的权限控制。

配置 Jenkins URL（反向代理环境）#

Jenkins URL: https://jenkins.example.com/

该 URL 用于 webhook、通知与构建回调；反代或 HTTPS 必须与实际外部访问一致。

初始化后基础验证（示例）#

验证插件是否生效：创建一个最小化 Pipeline 任务。

pipeline {
  agent any
  stages {
    stage('Hello') {
      steps {
        sh 'echo "Jenkins ready"'
      }
    }
  }
}

预期效果：控制台输出 Jenkins ready，说明 Pipeline 插件已可用。

常见问题与排错（含命令）#

1）插件无法下载

# 检查 DNS
cat /etc/resolv.conf
# 测试连接
curl -I https://updates.jenkins.io/update-center.json

2）初始化卡住或页面报错

# 查看 Jenkins 日志
sudo tail -n 200 /var/log/jenkins/jenkins.log

3）启动失败（疑似插件冲突）

# 暂时禁用可疑插件（重命名）
sudo mv /var/lib/jenkins/plugins/git.jpi /var/lib/jenkins/plugins/git.jpi.disabled
sudo systemctl restart jenkins

练习#

完成解锁与插件安装，记录解锁密钥文件路径与用途。
用离线方式安装 workflow-aggregator 插件并验证是否生效。
创建一个最小化 Pipeline 任务，运行后截图控制台输出。
故意禁用一个插件并重启，观察日志与 UI 变化，恢复插件并验证。