NGINX 配置

此页面为管理员和 DevOps 工程师提供为极狐GitLab 安装配置 NGINX 的配置信息和方法。它包括针对捆绑的 NGINX（Linux 软件包）、Helm charts 或自定义设置的性能优化和特定于安全性的基本指导。

特定服务 NGINX 配置

如果要为不同服务配置 NGINX 配置，编辑 gitlab.rb 文件即可。

caution 不正确或者不兼容的配置可能会导致服务不可用。

使用 nginx['<some setting>'] 键可以对极狐GitLab Rails 应用进行配置。其它服务也有类似的键，例如 pages_nginx、mattermost_nginx 和 registry_nginx。所有 nginx 的可用配置也同样适用于这些服务的 <service_nginx> 配置，并且与极狐GitLab NGINX 使用相同的默认值。

如果要为一些独立服（诸如 Mattermost）配置 NGINX，使用 gitlab_rails['enable'] = false 而非 nginx['enable'] = false。更多信息，可以查看为极狐GitLab Mattermost 运行独立的服务。

修改 gitlab.rb 时，用户需要为每个服务分别进行 NGINX 配置。nginx['foo'] 的配置不会复制到服务特定的 NGINX 配置（例如 registry_nginx['foo'] 或 mattermost_nginx['foo'] 等等）。例如，要为极狐GitLab、Mattermost 和 Registry 配置 HTTP 到 HTTPS 的重定向，以下配置应添加到 gitlab.rb。

nginx['redirect_http_to_https'] = true
registry_nginx['redirect_http_to_https'] = true
mattermost_nginx['redirect_http_to_https'] = true

启用 HTTPS

默认情况下，Linux 软件包安装不使用 HTTPS。如果您想为 gitlab.example.com 启用 HTTPS，有以下两个选项。

  1. 使用 Let’s Encrypt 免费和自动化的 HTTPS
  2. 使用您自己的证书手动配置 HTTPS
note 如果您使用代理，负载平衡器或其他一些外部设备来终止极狐GitLab 主机名的SSL，请参考外部设备、代理和负载均衡器的 SSL 终止。

更改默认的 proxy headers

默认情况下，当您指定了 external_url，Linux 软件包安装在大多数环境中设置了一些合理的 NGINX proxy headers。

例如，当您在 external_url 中指定了 https 格式，则 Linux 安装包的设置如下：

  "X-Forwarded-Proto" => "https",
  "X-Forwarded-Ssl" => "on"

然而，如果您的实例位于更复杂的设置之中，例如在反向代理之后，您需要调整 proxy headers 来避免如下错误：

  • The change you wanted was rejected
  • Can't verify CSRF token authenticity Completed 422 Unprocessable

如果要覆盖默认 headrs：

  1. 编辑 /etc/gitlab/gitlab.rb

    nginx['proxy_set_headers'] = {
  "X-Forwarded-Proto" => "http",
  "CUSTOM_HEADER" => "VALUE"
}

  2. 保存文件并重新配置GitLab 使更改生效。

通过这种方法，您可以按需指定 NGINX 支持的任何 header。

配置极狐GitLab 信任的代理以及 NGINX real_ip 模块

默认情况下，NGINX 和极狐GitLab 记录所连接客户端的 IP 地址。

如果您的极狐GitLab 实例位于反向代理之后，您可能不需要代理 IP 地址显示为客户地址。

如果要配置 NGINX 来使用不同的地址，将您的反向代理添加到 real_ip_trusted_addresses 列表中：

# Each address is added to the the NGINX config as 'set_real_ip_from <address>;'
nginx['real_ip_trusted_addresses'] = [ '192.168.1.0/24', '192.168.2.1', '2001:0db8::/32' ]
# other real_ip config options
nginx['real_ip_header'] = 'X-Forwarded-For'
nginx['real_ip_recursive'] = 'on'

对于这些选项的描述，可以查看 NGINX realip 模块文档。

默认情况下，Linux 软件包安装使用 real_ip_trusted_addresses 中的 IP 地址作为极狐GitLab 信任代理，用户不会使用那些列表中的 IP 进行登录。

保存文件并重新配置GitLab 使更改生效。

配置 PROXY 协议

如果您想使用 PROXY 协议 在极狐GitLab 前面使用 HAProxy 之类的代理：

  1. 编辑 /etc/gitlab/gitlab.rb：

    # Enable termination of ProxyProtocol by NGINX
nginx['proxy_protocol'] = true
# Configure trusted upstream proxies. Required if `proxy_protocol` is enabled.
nginx['real_ip_trusted_addresses'] = [ "127.0.0.0/8", "IP_OF_THE_PROXY/32"]

  2. 保存文件并重新配置极狐GitLab，使更改生效。

启用后，NGINX 仅接受这些侦听器上的 PROXY 协议流量。 确保调整您可能拥有的任何其他环境，例如监控检查。

使用非捆绑的网络服务器

默认情况下，Linux 软件包安装捆绑有 NGINX 的极狐GitLab 实例。Linux 软件包安装允许 gitlab-www 用户访问网络服务器，gitlab-www 用户位于同名的群组中。要允许外部网络服务器访问极狐GitLab 实例，需要将外部网络服务器用户添加到 gitlab-www 群组。

要使用其它 Web 服务器，例如 Apache 或已有的 NGINX 实例，您需要执行以下步骤：

  1. 禁用捆绑的 NGINX。

    在 /etc/gitlab/gitlab.rb 中设置：

       nginx['enable'] = false

  2. 设置非捆绑网络服务器用户的用户名。

    Linux 软件包安装没有针对外部网络服务器用户的默认设置。您必须在配置中进行指定。比如：

    • Debian/Ubuntu：对 Apache 和 NGINX 来说，默认用户都是 www-data。
    • RHEL/CentOS：NGINX 用户是 nginx。

    确保您提前安装了 Apache/NGINX，这样已创建了网络服务器用户，否则重新配置时 Linux 软件包安装会失败。

    例如网络服务器用户是 www-data。在 /etc/gitlab/gitlab.rb 中设置：

    ```ruby
web_server['external_users'] = ['www-data']
```

    该设置是一个数组，您可以指定添加多个用户到 gitlab-www 群组。

    执行 sudo gitlab-ctl reconfigure 命令以使更改生效。

    如果您使用 SELinux，并且您的 Web 服务器在 SELinux 限制文件下运行，您可能需要放宽对 Web 服务器的限制。

    确保网络服务器用户对外部网络服务器使用的所有目录具有正确的权限，否则您将收到 failed (XX: Permission denied) while reading upstream 错误。

  3. 将非捆绑的网络服务器添加到受信任代理列表中。

    通常 Linux 软件包安装的可信列表默认为捆绑的 NGINX 配置中，real_ip 模块的配置内容。

    对于非捆绑的网络服务器，需要直接配置该列表，如果网络服务器与极狐GitLab 实例不在同一台机器上，列表中需要包括您的网络服务器 IP 地址。否则，用户将显示为从您的网络服务器的 IP 地址登录。

    ```ruby
gitlab_rails['trusted_proxies'] = [ '192.168.1.0/24', '192.168.2.1', '2001:0db8::/32' ]
```

  4. （可选）使用 Apache 时，设置正确的极狐GitLab Workhorse。

    Apache 需要连接到 TCP 端口而不是 UNIX 套接字。要允许极狐GitLab Workhorse 监听 TCP 端口（默认为 8181），编辑 /etc/gitlab/gitlab.rb：

    ```ruby
gitlab_workhorse['listen_network'] = "tcp"
gitlab_workhorse['listen_addr'] = "127.0.0.1:8181"
```

    执行 sudo gitlab-ctl reconfigure 命令以使更改生效。

  5. 下载正确的网络服务器配置。

    转到极狐GitLab 仓库并下载所需的配置。根据您是否使用 SSL 为极狐GitLab 提供服务，选择正确的配置文件。您可能需要进行一些更改，例如：

    • 将 YOUR_SERVER_FQDN 的值设置为您的 FQDN。
    • 如果您使用 SSL，则更改您的 SSL 密钥的位置。
    • 更改您的日志文件的位置。

NGINX 配置选项

GitLab 提供了多种配置选项，以便为您的具体需求定制 NGINX 行为。使用这些参考项来微调您的 NGINX 设置，并优化极狐GitLab 的性能和安全性。

设置 NGINX 监听地址

默认情况下，NGINX 将接受所有本地 IPv4 地址上的传入连接。

您可以更改地址列表。

  1. 编辑 /etc/gitlab/gitlab.rb

    # Listen on all IPv4 and IPv6 addresses
nginx['listen_addresses'] = ["0.0.0.0", "[::]"]
registry_nginx['listen_addresses'] = ['*', '[::]']
mattermost_nginx['listen_addresses'] = ['*', '[::]']
pages_nginx['listen_addresses'] = ['*', '[::]']

  2. 保存文件并重新配置极狐GitLab，使更改生效。

设置 NGINX 监听端口

默认情况下，NGINX 将监听 external_url 中的指定端口，或使用正确的端口（HTTP 为 80，HTTPS 为 443）。如果您在反向代理后运行极狐GitLab，您可能想要使用其它的监听端口。

要修改监听端口：

  1. 编辑 /etc/gitlab/gitlab.rb。比如使用 8081 端口：

    nginx['listen_port'] = 8081

  2. 保存文件并重新配置极狐GitLab，使更改生效。

NGINX 日志的详细级别

默认情况下，NGINX 会以 error 详细级别记录日志。您可以通过更改日志级别以不同的级别登录。

要改变日志级别：

  1. 编辑 /etc/gitlab/gitlab.rb。

    nginx['error_log_level'] = "debug"

  2. 保存文件并重新配置极狐GitLab，使更改生效。

可以从 NGINX 文档中找到有效值。

设置 Referrer-Policy header

默认情况下，极狐GitLab 将所有响应的 Referrer-Policy header 设置为 strict-origin-when-cross-origin。这使得客户端：

  • 在发出同源请求时，发送完整的 URL 作为 referrer。
  • 仅在发出跨域请求时发送源。

如果要修改 header：

  1. 编辑 /etc/gitlab/gitlab.rb。

    nginx['referrer_policy'] = 'same-origin'

    您也可以禁用该 header，使客户端使用默认设置：

    nginx['referrer_policy'] = false

  2. 保存文件并重新配置极狐GitLab，使更改生效。

注意，将其设置为 origin 或 no-referrer，会破坏极狐GitLab 中需要完整引用 URL 的某些功能。

禁用 Gzip 压缩

默认情况下，极狐GitLab 对超过 10240 字节的文本数据启用 Gzip 压缩。要禁用此行为：

  1. 编辑 /etc/gitlab/gitlab.rb。

    nginx['gzip_enabled'] = false

  2. 保存文件并重新配置极狐GitLab，使更改生效。

note gzip 设置仅适用于极狐GitLab 主应用，不适用于其它服务。

禁用代理请求缓冲

可以通过更改 request_buffering_off_path_regex 在特定位置选择性地禁用请求缓冲。

  1. 编辑 /etc/gitlab/gitlab.rb：

    nginx['request_buffering_off_path_regex'] = "/api/v\\d/jobs/\\d+/artifacts$|/import/gitlab_project$|\\.git/git-receive-pack$|\\.git/gitlab-lfs/objects|\\.git/info/lfs/objects/batch$"

  2. 重新配置极狐GitLab，并 HUP NGINX，使其优雅地重新加载更新的配置：

    sudo gitlab-ctl reconfigure
sudo gitlab-ctl hup nginx

配置 robots.txt

要为您的实例配置 robots.txt：

  1. 创建一个自定义的 robots.txt 文件并记住它的路径。

  2. 编辑 /etc/gitlab/gitlab.rb：

    nginx['custom_gitlab_server_config'] = "\nlocation =/robots.txt { alias /path/to/custom/robots.txt; }\n"

    用您自定义的 robots.txt 文件路径替换 /path/to/custom/robots.txt。

  3. 保存文件并重新配置极狐GitLab，使更改生效。

此项配置会增加一个自定义 NGINX 配置来为您自定义的 robots.txt 文件服务。

在 server block 中添加自定义 NGINX 设置

要想在极狐GitLab NGINX server 块中加入自定义设置：

  1. 编辑 /etc/gitlab/gitlab.rb：

    # Example: block raw file downloads from a specific repository
nginx['custom_gitlab_server_config'] = "location ^~ /foo-namespace/bar-project/raw/ {\n deny all;\n}\n"

  2. 保存文件并重新配置极狐GitLab，使更改生效。

定义的字符串将被插入到 /var/opt/gitlab/nginx/conf/gitlab-http.conf 中的 server block 末尾。

caution 如果在您的 gitlab.rb 文件中定义了相同的设置，这些自定义设置可能会发生冲突。

注意

  • 如果您在添加新的 location，需要在字符串中包含以下内容，或已包含在 NGINX 配置中。

    proxy_cache off;
proxy_http_version 1.1;
proxy_pass http://gitlab-workhorse;

    没有以上配置，任何 sub-location 将返回 404。

  • 不能添加根路径 / location 或 /assets location，因为已经存在于 gitlab-http.conf。

在 NGINX 配置中插入自定义设置

如果要在 NGINX 配置中添加自定义设置：

  1. 编辑 /etc/gitlab/gitlab.rb：

    # Example: include a directory to scan for additional config files
nginx['custom_nginx_config'] = "include /etc/gitlab/nginx/sites-enabled/*.conf;"

  2. 保存文件并重新配置极狐GitLab，使更改生效。

这将在 /var/opt/gitlab/nginx/conf/nginx.conf 中的 http 块的末尾插入已定义的字符串。

例如，如果要创建并开启自定义 server 块：

  1. 在 /etc/gitlab/nginx/sites-available 目录中创建自定义 server 块。
  2. 如果 /etc/gitlab/nginx/sites-enabled 目录不存在，创建此目录。

  3. 为了开启自定义 server 块，创建软连接：

    sudo ln -s /etc/gitlab/nginx/sites-available/example.conf /etc/gitlab/nginx/sites-enabled/example.conf

  4. 重新加载 NGINX 配置：

    sudo gitlab-ctl hup nginx

    或者，您可以重启 NGINX

    sudo gitlab-ctl restart nginx

您可以将服务器块的域作为备用名称>添加到生成的 Let’s Encrypt SSL 证书中。

在升级期间以及手动执行 sudo gitlab-ctl backup-etc 时，/etc/gitlab/ 目录中的自定义 NGINX 设置将备份到 /etc/gitlab/config_backup/。

自定义错误页面

如果要修改默认极狐GitLab 错误页面上的文本：

  1. 编辑 /etc/gitlab/gitlab.rb：

    nginx['custom_error_pages'] = {
 '404' => {
   'title' => 'Example title',
   'header' => 'Example header',
   'message' => 'Example message'
 }
}

    上述示例修改了默认的 404 错误页面。您可以用这种方式修改任何有效的 HTTP 错误码，比如 404 或者 502.

  2. 保存文件并重新配置极狐GitLab，使更改生效。

将生成下方的 404 页面。

custom 404 error page

使用已有的 Passenger 和 NGINX 安装

在某些情况下，您可能想要极狐GitLab 实例使用已有的 Passenger 和 NGINX 安装，但同时保留使用 Linux 软件包进行升级和安装时的便利性。

当禁用 NGINX 时，您将无法访问 Linux 软件包安装的其它服务，例如 Mattermost，除非您在 nginx.conf 中手动添加。

配置

为了配置极狐GitLab 以使用已有的 Passenger 和 NGINX 安装：

  1. 编辑 /etc/gitlab/gitlab.rb：

    # Define the external url
external_url 'http://git.example.com'

# Disable the built-in NGINX
nginx['enable'] = false

# Disable the built-in Puma
puma['enable'] = false

# Set the internal API URL
gitlab_rails['internal_api_url'] = 'http://git.example.com'

# Define the web server process user (ubuntu/nginx)
web_server['external_users'] = ['www-data']

  2. 保存文件并重新配置极狐GitLab，使更改生效。

配置 Vhost (server block)

在您的自定义 Passenger/NGINX 实例中：

  1. 创建以下站点配置文件：

    upstream gitlab-workhorse {
server unix://var/opt/gitlab/gitlab-workhorse/sockets/socket fail_timeout=0;
}

server {
listen *:80;
server_name git.example.com;
server_tokens off;
root /opt/gitlab/embedded/service/gitlab-rails/public;

client_max_body_size 250m;

access_log  /var/log/gitlab/nginx/gitlab_access.log;
error_log   /var/log/gitlab/nginx/gitlab_error.log;

# Ensure Passenger uses the bundled Ruby version
passenger_ruby /opt/gitlab/embedded/bin/ruby;

# Correct the $PATH variable to included packaged executables
passenger_env_var PATH "/opt/gitlab/bin:/opt/gitlab/embedded/bin:/usr/local/bin:/usr/bin:/bin";

# Make sure Passenger runs as the correct user and group to
# prevent permission issues
passenger_user git;
passenger_group git;

# Enable Passenger & keep at least one instance running at all times
passenger_enabled on;
passenger_min_instances 1;

location ~ ^/[\w\.-]+/[\w\.-]+/(info/refs|git-upload-pack|git-receive-pack)$ {
   # 'Error' 418 is a hack to re-use the @gitlab-workhorse block
   error_page 418 = @gitlab-workhorse;
   return 418;
}

location ~ ^/[\w\.-]+/[\w\.-]+/repository/archive {
   # 'Error' 418 is a hack to re-use the @gitlab-workhorse block
   error_page 418 = @gitlab-workhorse;
   return 418;
}

location ~ ^/api/v3/projects/.*/repository/archive {
   # 'Error' 418 is a hack to re-use the @gitlab-workhorse block
   error_page 418 = @gitlab-workhorse;
   return 418;
}

# Build artifacts should be submitted to this location
location ~ ^/[\w\.-]+/[\w\.-]+/builds/download {
      client_max_body_size 0;
      # 'Error' 418 is a hack to re-use the @gitlab-workhorse block
      error_page 418 = @gitlab-workhorse;
      return 418;
}

# Build artifacts should be submitted to this location
location ~ /ci/api/v1/builds/[0-9]+/artifacts {
      client_max_body_size 0;
      # 'Error' 418 is a hack to re-use the @gitlab-workhorse block
      error_page 418 = @gitlab-workhorse;
      return 418;
}

# Build artifacts should be submitted to this location
location ~ /api/v4/jobs/[0-9]+/artifacts {
      client_max_body_size 0;
      # 'Error' 418 is a hack to re-use the @gitlab-workhorse block
      error_page 418 = @gitlab-workhorse;
      return 418;
}


# For protocol upgrades from HTTP/1.0 to HTTP/1.1 we need to provide Host header if its missing
if ($http_host = "") {
# use one of values defined in server_name
   set $http_host_with_default "git.example.com";
}

if ($http_host != "") {
   set $http_host_with_default $http_host;
}

location @gitlab-workhorse {

   ## https://github.com/gitlabhq/gitlabhq/issues/694
   ## Some requests take more than 30 seconds.
   proxy_read_timeout      3600;
   proxy_connect_timeout   300;
   proxy_redirect          off;

   # Do not buffer Git HTTP responses
   proxy_buffering off;

   proxy_set_header    Host                $http_host_with_default;
   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_http_version 1.1;
   proxy_pass http://gitlab-workhorse;

   ## The following settings only work with NGINX 1.7.11 or newer
   #
   ## Pass chunked request bodies to gitlab-workhorse as-is
   # proxy_request_buffering off;
   # proxy_http_version 1.1;
}

## Enable gzip compression as per rails guide:
## http://guides.rubyonrails.org/asset_pipeline.html#gzip-compression
## WARNING: If you are using relative urls remove the block below
## See config/application.rb under "Relative url support" for the list of
## other files that need to be changed for relative url support
location ~ ^/(assets)/ {
   root /opt/gitlab/embedded/service/gitlab-rails/public;
   gzip_static on; # to serve pre-gzipped version
   expires max;
   add_header Cache-Control public;
}

error_page 502 /502.html;
}

不要忘记将上面示例中的 git.example.com 更新为您的服务器 URL。

如果您收到 403 forbidden 返回，确保在 /etc/nginx/nginx.conf 中启用了 passenger：

  1. 取消这行注释：

    # include /etc/nginx/passenger.conf;

  2. 重新加载 NGINX 配置：

    sudo service nginx reload

配置 NGINX 状态监控

默认情况下，NGINX 健康检查端点配置在 127.0.0.1:8060/nginx_status，以监控您的 NGINX 服务器状态。

端点展示的信息如下：

Active connections: 1
server accepts handled requests
 18 18 36
Reading: 0 Writing: 1 Waiting: 0
  • Active connections - 开放的连接总数。
  • 展示 3 个指标数字。
    • 所有接受的连接。
    • 所有处理的连接。
    • 处理的请求总数。
  • Reading：NGINX 读取的请求 header。
  • Writing：NGINX 读取请求体，处理请求，或将响应写入客户端。
  • Waiting：Keep-alive 连接。该数字取决于 keepalive-timeout。

配置 NGINX 状态选项

要配置 NGINX 状态选项：

  1. 编辑 /etc/gitlab/gitlab.rb：

    nginx['status'] = {
"listen_addresses" => ["127.0.0.1"],
"fqdn" => "dev.example.com",
"port" => 9999,
"options" => {
   "access_log" => "on", # Disable logs for stats
   "allow" => "127.0.0.1", # Only allow access from localhost
   "deny" => "all" # Deny access to anyone else
}
}

    如果要禁用 NGINX 状态选项：

    nginx['status'] = {
'enable' => false
}

  2. 保存文件并重新配置极狐GitLab，使更改生效。

配置用户上传权限

为了确保可以访问用户上传的内容，您的 NGINX 用户（通常为 www-data）应被添加到 gitlab-www 群组中。使用以下命令：

sudo usermod -aG gitlab-www www-data

模板

配置文件和捆绑的极狐GitLab NGINX 配置类似，但有一下区别：

  • 使用 Passenger 而不是 Puma 的配置。
  • 默认情况下 HTTPS 并未开启，但是您可以开启它。

对 NGINX 配置做完变更后：

  • 对基于 Debian 的系统，重启 NGINX
  sudo service nginx restart
  • 对其他操作系统，参考操作系统的文档以找到正确的命令重启 NGINX。