如何配置 Nginx 作为 Jenkins 的反向代理并启用 SSL 加密

简介

默认情况下，Jenkins 自带内置的 Web 服务器，监听在 8080 端口上。这对于运行私有 Jenkins 实例或者只是需要快速启动而不关心安全性的用户来说很方便。但是一旦您的主机上有真实的生产数据，使用更安全的 Web 服务器（如 Nginx）来处理流量是个不错的主意。

本文将详细介绍如何使用 Nginx Web 服务器作为 Jenkins 实例的反向代理，为您的站点添加 SSL。本教程假设您对 Linux 命令、已安装的 Jenkins 和 Ubuntu 20.04 安装有一定的了解。

如果您尚未安装 Jenkins，您可以在本教程中安装它。

先决条件

本指南假设您正在使用 Ubuntu 20.04。在开始之前，您应该在系统上设置一个具有 sudo 权限的非root用户帐户。您可以按照 Ubuntu 20.04 初始服务器设置教程来学习如何做到这一点。您还需要安装 Nginx 服务器并托管您的域。您可以按照《在 Ubuntu 20.04 上安装 Nginx》教程来学习如何做到这一点。

另外，通过 SSL 保护您的 Jenkins 实例非常重要。如果它在互联网上可见，您可以使用 Let’s Encrypt 来保护它。您可以按照《如何在 Ubuntu 22.04 上使用 Let’s Encrypt 保护 Nginx》教程来学习如何做到这一点。

正如前面所述，本教程假设 Jenkins 已经安装。本教程将向您展示如何安装 Jenkins（如果需要）。您可能需要切换到 root 用户来完成该文章。

步骤 1 — 配置 Nginx

近年来，Nginx 凭借其速度和灵活性成为了一个受欢迎的 Web 服务器，这使得它成为我们应用的理想选择。

编辑配置

接下来，您需要编辑默认的 Nginx 配置文件。以下示例使用 nano。

sudo nano etc/nginx/sites-enabled/default

以下是最终配置的样例；下面简要解释了各个部分。您可以更新或替换现有的配置文件，不过您可能需要先备份一份。

server {
    listen 80;
    return 301 https://$host$request_uri;
}
server {
    listen 443;
    server_name jenkins.domain.com;
    access_log            /var/log/nginx/jenkins.access.log;
    location / {
        proxy_set_header        Host $host;
        proxy_set_header        X-Real-IP $remote_addr;
        proxy_set_header        X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header        X-Forwarded-Proto $scheme;
        proxy_pass          http://localhost:8080;
        proxy_read_timeout  90;
        proxy_redirect      http://localhost:8080 https://jenkins.domain.com;
    }
    
    ...
}

您需要使用您自己的域名更新 server_name 和 proxy_redirect 行。还有一些额外的 Nginx 魔法，告诉请求在 Nginx 上被读取并在响应端被重写，以确保反向代理正常工作。

保存并关闭文件。如果您使用的是 nano，您可以按 Ctrl + X，然后按 Y，最后按 Enter 来完成。

第一部分告诉 Nginx 服务器监听在 80 端口（默认 HTTP）上的任何请求，并将它们重定向到 HTTPS。

...
server {
   listen 80;
   return 301 https://$host$request_uri;
}
...

之后，代理开始工作。它基本上接收任何传入的请求，并将它们代理到绑定/监听在本地网络接口的 8080 端口上的 Jenkins 实例。

...
location / {
    proxy_set_header        Host $host;
    proxy_set_header        X-Real-IP $remote_addr;
    proxy_set_header        X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header        X-Forwarded-Proto $scheme;
    proxy_pass          http://localhost:8080;
    proxy_read_timeout  90;
    proxy_redirect      http://localhost:8080 https://jenkins.domain.com;
}
...

这里有几个要点需要指出。如果您没有一个解析到您的 Jenkins 服务器的域名，那么上面的 proxy_redirect 语句在没有修改的情况下将无法正确运行，所以请记住这一点。另外，如果您错误配置了 proxy_pass（例如添加了尾随斜杠），您将在 Jenkins 配置页面中看到类似以下内容的错误。

!Jenkins error: Reverse proxy set up is broken

因此，如果您看到此错误，请再次检查 Nginx 配置中的 proxy_pass 和 proxy_redirect 设置！

步骤 2 — 配置 Jenkins

为了让 Jenkins 与 Nginx 协同工作，我们需要更新 Jenkins 配置，使其仅监听本地地址而不是所有地址（0.0.0.0），以确保流量得到正确处理。这是一个重要的安全步骤，因为如果 Jenkins 仍然在所有地址上监听，那么它仍然可能通过其原始端口（8080）访问。我们将修改 /etc/default/jenkins 配置文件以进行这些调整。

sudo nano /etc/default/jenkins

找到 JENKINS\_ARGS 行并将其更新如下：

JENKINS_ARGS="--webroot=/var/cache/jenkins/war --httpListenAddress=127.0.0.1 --httpPort=$HTTP_PORT -ajp13Port=$AJP_PORT"

请注意，–httpListenAddress=127.0.0.1 设置必须要么添加，要么修改。

然后继续重启 Jenkins 和 Nginx。

sudo service jenkins restart
sudo service nginx restart

现在您应该能够通过 HTTPS 访问您的域名，并且 Jenkins 站点将被安全地提供。

可选 — 更新 OAuth URL

如果您正在使用 GitHub 或其他 OAuth 插件进行身份验证，此时它可能已经失效。例如，当尝试访问 URL 时，您将收到一个类似 http://jenkins.domain.com:8080/securityRealm/finishLogin?code=random-string 的“无法打开页面”的错误。

为了解决这个问题，您需要更新 Jenkins 中的一些设置，包括 OAuth 插件设置。首先在 Jenkins GUI 中更新 Jenkins URL；它可以在 Jenkins -> 管理 Jenkins -> 配置系统 -> Jenkins 位置 菜单中找到。

将 Jenkins URL 更新为使用 HTTPS - https://jenkins.domain.com/

!Jenkins URL

接下来，更新您的 OAuth 设置与外部提供者。以下示例是针对 GitHub 的。在 GitHub 上，这可以在 设置 -> 应用程序 -> 开发人员应用程序 下找到。

应该有一个条目为 Jenkins。将 主页 URL 和 授权回调 URL 更新以反映 HTTPS 设置。它可能类似于以下内容：

!GitHub 上的 Jenkins 设置；两个 URL 都使用了 https://

结论

唯一剩下的事情就是验证一切是否正确工作。如上所述，您现在应该能够通过新配置的 URL - jenkins.domain.com - 使用 HTTP 或 HTTPS 浏览。您应该被重定向到安全站点，并且应该看到一些站点信息，包括您新更新的 SSL 设置。如前所述，如果您没有通过 DNS 使用主机名，则您的重定向可能无法按预期工作。在这种情况下，您需要修改 Nginx 配置文件中的 proxy_pass 部分。