如何自定义CentOS Jenkins界面与主题

在 CentOS 上自定义 Jenkins 界面与主题

一 准备与环境确认

• 确认 Jenkins 主目录 JENKINS_HOME：常见路径为 /var/lib/jenkins（RPM 安装默认），如自定义过数据目录，请以实际为准。
• 确认 Jenkins URL 与端口：默认 http://服务器IP:8080，后续引用静态资源需使用该地址。
• 准备主题文件：可使用在线 Material Theme 生成器（如 afonsof 的 jenkins-material-theme）下载 jenkins-material-theme.css，或自行编写 custom.css。
• 权限准备：确保运行 Jenkins 的系统用户对 JENKINS_HOME/userContent 具备读写权限（便于放置自定义 CSS/JS/Logo）。

二 安装主题插件与基础配置

• 安装插件：进入 Manage Jenkins → Manage Plugins → Available，搜索并安装 Simple Theme Plugin（部分版本也显示为 Theme Plugin），安装后按提示重启。
• 配置在线主题：进入 Manage Jenkins → Configure System，滚动到 Theme 配置项，在 CSS 字段填入在线 CSS 地址，例如：
  • Material Theme 示例：http://afonsof.com/jenkins-material-theme/dist/material-teal.css
  • 保存后刷新页面即可生效。
• 说明：不同版本 UI 文案略有差异，但核心做法是在系统设置中指定 CSS URL 来覆盖默认样式。

三 使用本地主题文件与徽标

• 放置文件：将主题 CSS（如 jenkins-material-theme-green.css）上传至 JENKINS_HOME/userContent/ 下的子目录（例如 material/），目录不存在请先创建。示例完整路径：/var/lib/jenkins/userContent/material/jenkins-material-theme-green.css。
• 配置本地 CSS：在 Theme → CSS 填入以 /userContent/ 开头的访问路径，例如：
  • /userContent/material/jenkins-material-theme-green.css
• 使用自定义 Logo：将公司 logo.png 一并放入同一目录（如 /userContent/material/logo.png），并在主题 CSS 中按 CSS 规则设置 .jenkins-header-logo 等选择器进行替换；若使用 Material Theme 生成器，可在生成阶段直接上传 Logo 并下载包含 Logo 的 CSS。
• 访问校验：在浏览器直接访问 http://服务器IP:8080/userContent/material/jenkins-material-theme-green.css，确认样式文件可公开读取。

四 进阶自定义与 JCasC 自动化

• 自定义 CSS/JS：在 JENKINS_HOME/userContent/ 下创建 custom.css / custom.js，在 Theme 配置中同时填入：
  • CSS：/userContent/custom.css
  • JS：/userContent/custom.js
  • 示例（custom.css）：设置页面背景色

    body { background-color: #f0f0f0; }
    

• 使用 JCasC 持久化：安装 Configuration as Code (JCasC) 插件，在 jenkins.yaml 中声明主题，例如：

  jenkins:
    theme:
      name: "dark"
  

  并在 Manage Jenkins → Configuration as Code 中应用该 YAML，便于版本化管理与快速恢复。

五 常见问题与排查

• 主题不生效：检查 Jenkins URL 是否为 http://服务器IP:8080（而非 localhost），CSS 路径是否以 /userContent/ 开头且文件可读；必要时重启 Jenkins 后再试。
• 权限问题：确认 Jenkins 用户对 JENKINS_HOME/userContent 及子目录拥有 读/写 权限，避免因权限不足导致 CSS/JS/Logo 无法加载。
• 插件兼容性：不同 Jenkins 版本 对主题插件与 UI 结构支持度不同，如遇样式错位可尝试更新插件、切换主题版本或回退 UI 风格。