深入探讨 Jenkins 中 HTML 格式无法正常显示的现象及解决方案

项目场景：

在现代软件开发中，Jenkins 作为一款流行的持续集成（CI）和持续交付（CD）工具，广泛应用于自动化构建、测试和部署流程。然而，许多用户在使用 Jenkins 时可能会遇到一个棘手的问题：在生成的构建报告中，HTML 格式无法正常显示，导致页面样式丢失。这不仅影响用户体验，还可能对开发流程造成不必要的干扰。本文将深入探讨这个问题的原因，并提供临时和永久解决方案。

问题描述：为何 HTML 格式无法正常显示？

Jenkins 在其默认设置中实施了严格的内容安全策略（Content Security Policy，CSP），这是为了增强安全性，防止潜在的跨站脚本攻击（XSS）。然而，这种严格的策略有时会意外阻止某些 HTML 内容（如 CSS、JavaScript 文件等）的加载，从而导致页面样式不正确。

以下是常见的 CSP 设置示例：

Content-Security-Policy: default-src 'self'; style-src 'self'; script-src 'self';

这种配置只允许从同一源加载资源，当某些必要的资源未被允许加载时，页面样式可能无法正常显示。

临时生效（不重启生效，但重启失效）

在 Jenkins 中，临时配置 Content-Security-Policy (CSP) 可以快速解决样式无法加载的问题，这种方法不需要重启 Jenkins，但在 Jenkins 重启后将失效。

进入 Jenkins 系统设置：在左侧导航栏点击 系统管理（Manage Jenkins）。
进入“脚本命令”页面：
中文版：选择 脚本命令（Script Console）。
英文版：选择 Script Console。
执行临时脚本：在脚本窗口中输入以下代码，然后点击运行（Run）：


System.setProperty("hudson.model.DirectoryBrowserSupport.CSP", "default-src 'self'; style-src 'self' 'unsafe-inline';")

这条命令会即时生效，并且允许加载本地 CSS 文件和内联样式，临时解决 HTML 样式显示问题。

永久生效（重启生效/永久生效）

Windows 部署

要实现重启后也生效的永久解决方案，可以在 Jenkins 的 jenkins.xml 文件中添加 CSP 配置，使得设置随 Jenkins 启动生效。

找到 Jenkins 安装目录中的 jenkins.xml 文件：

如果 Jenkins 作为服务安装在 Windows 上，jenkins.xml 文件一般位于 C:\Program Files (x86)\Jenkins\jenkins.xml。

编辑 jenkins.xml 文件：

打开 jenkins.xml 文件，在 <arguments> 部分添加 CSP 设置。将以下参数添加到 <arguments> 标签中：

    <arguments>-Dhudson.model.DirectoryBrowserSupport.CSP=default-src 'self'; style-src 'self' 'unsafe-inline';</arguments>

重启 Jenkins 服务：

保存 jenkins.xml 文件，重启 Jenkins 服务以应用该配置。
这样设置后，每次 Jenkins 启动时都会自动加载该 CSP 配置，实现样式显示永久生效。

Linux 部署

步骤1：编辑 Jenkins 启动配置文件

在 Linux 上，Jenkins 的启动配置通常位于 /etc/default/jenkins 文件中（基于 Debian 系列）或其他系统配置文件中。如果你用的是其他方式安装 Jenkins（比如通过 systemd 服务管理），启动配置可能会在 /etc/systemd/system/jenkins.service。

找到配置文件：

Debian/Ubuntu：/etc/default/jenkins
Red Hat/CentOS：/etc/sysconfig/jenkins
如果是通过 systemd 启动的 Jenkins，文件路径可能是 /etc/systemd/system/jenkins.service。

修改配置文件： 在找到的配置文件中，添加 CSP 设置。

在 /etc/default/jenkins 或 /etc/sysconfig/jenkins 中，找到 JAVA_ARGS 或 JENKINS_JAVA_OPTIONS，在参数中添加 CSP 规则：
```
JAVA_ARGS="$JAVA_ARGS -Dhudson.model.DirectoryBrowserSupport.CSP=\"default-src 'self'; style-src 'self' 'unsafe-inline';\""
```

如果使用的是 systemd，编辑 /etc/systemd/system/jenkins.service 文件，在 [Service] 下的 Environment 添加：

Environment="JAVA_OPTS=-Dhudson.model.DirectoryBrowserSupport.CSP=default-src 'self'; style-src 'self' 'unsafe-inline';"

步骤3：保存配置并重启 Jenkins 服务

保存并关闭文件。
重载 systemd 配置（如果是 systemd 管理 Jenkins）：

sudo systemctl daemon-reload

重启 Jenkins 服务：

sudo systemctl restart jenkins

容器部署（Docker）

容器部署的 Jenkins 通常使用 Docker 环境变量来传递 JVM 参数，从而设置 CSP 配置。

1. 修改 `docker run` 命令（若使用 `docker run` 直接启动）

如果是直接通过 docker run 命令启动 Jenkins，可以在启动命令中增加环境变量 JAVA_OPTS。

docker run -d \-p 8080:8080 \-p 50000:50000 \-e JAVA_OPTS="-Dhudson.model.DirectoryBrowserSupport.CSP=default-src 'self'; style-src 'self' 'unsafe-inline';" \--name jenkins \jenkins/jenkins:lts

上述命令中的 -e JAVA_OPTS="..." 将 CSP 设置传递给 Jenkins 实例，这样可以实现样式文件的正常加载，并且该配置会在容器重启后依然生效。

2. 使用 Docker Compose 配置（如果使用 docker-compose.yml 文件）

如果使用 docker-compose.yml 文件来管理 Jenkins 容器，可以在 environment 中添加 JAVA_OPTS。

version: '3'
services:jenkins:image: jenkins/jenkins:ltsports:- "8080:8080"- "50000:50000"environment:- JAVA_OPTS=-Dhudson.model.DirectoryBrowserSupport.CSP=default-src 'self'; style-src 'self' 'unsafe-inline';volumes:- jenkins_home:/var/jenkins_home
volumes:jenkins_home:

保存 docker-compose.yml 文件后，重新启动 Jenkins 服务即可。

3. 检查效果

Jenkins 启动后，尝试访问 HTML 报告页面，确认样式是否正常显示。通过这种方式添加的 CSP 配置会在 Jenkins 容器重启时自动加载，实现永久生效。

部署例子（Kubenetes）

比如，我的 deployment.yaml 如下：

apiVersion: apps/v1
kind: Deployment
metadata:name: jenkinsnamespace: <namespace>
spec:replicas: 1selector:matchLabels:app: jenkinstemplate:metadata:name: jenkinslabels:app: jenkinsspec:nodeSelector:group: itcontainers:- name: jenkinsimage: jenkins/jenkins:ltsports:- name: jenkinsprotocol: TCPcontainerPort: 8080volumeMounts:- name: jenkinsmountPath: /var/jenkins_homesubPath: jenkins_homeenv:- name: JAVA_OPTSvalue: "-Djava.util.logging.config.file=/var/jenkins_home/log.properties"volumes:- ...

要追加 -Dhudson.model.DirectoryBrowserSupport.CSP 的配置，将 yaml 修改为如下：

apiVersion: apps/v1
kind: Deployment
metadata:name: jenkinsnamespace: <namespace>
spec:replicas: 1selector:matchLabels:app: jenkinstemplate:metadata:name: jenkinslabels:app: jenkinsspec:nodeSelector:group: itcontainers:- name: jenkinsimage: jenkins/jenkins:ltsports:- name: jenkinsprotocol: TCPcontainerPort: 8080volumeMounts:- name: jenkinsmountPath: /var/jenkins_homesubPath: jenkins_homeenv:- name: JAVA_OPTSvalue: "-Djava.util.logging.config.file=/var/jenkins_home/log.properties -Dhudson.model.DirectoryBrowserSupport.CSP=\"default-src 'self'; style-src 'self' 'unsafe-inline';\""volumes:- ...