NGINX 설정

Tier: Free, Premium, Ultimate Offering: Self-Managed

서비스별 NGINX 설정

사용자는 gitlab.rb를 통해 다른 서비스에 대해 서로 다른 방식으로 NGINX 설정을 구성할 수 있습니다. GitLab Rails 애플리케이션의 설정은 nginx['<some setting>'] 키를 사용하여 구성할 수 있습니다. pages_nginx, mattermost_nginx, registry_nginx와 같은 다른 서비스에 대한 유사한 키가 있습니다. nginx에 대한 모든 구성은 이러한 <service_nginx> 설정에도 동일한 기본값으로 제공되며 GitLab NGINX와 동일한 기본값을 공유합니다.

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

참고: NGINX 구성을 수정하는 경우 잘못된 또는 호환되지 않는 구성은 서비스의 가용성에 영향을 줄 수 있으므로 주의해서 진행해야 합니다.

HTTPS 활성화

기본적으로 Linux 패키지 설치에는 HTTPS가 사용되지 않습니다. gitlab.example.com에 대해 HTTPS를 활성화하려면 다음을 수행할 수 있습니다:

참고: SSL을 종료하기 위해 프록시, 로드 밸런서 또는 다른 외부 장치를 사용하는 경우 외부, 프록시 및 로드 밸런서 SSL 종료를 참조하세요.

기본 프록시 헤더 변경

기본적으로 external_url을 지정하면 Linux 패키지 설치는 대부분의 환경에서 적합하다고 가정되는 몇 가지 NGINX 프록시 헤더를 설정합니다.

예를 들어, Linux 패키지 설치는 다음과 같이 설정합니다: 

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

external_url에서 https 스키마를 지정한 경우입니다.

그러나 GitLab이 역방향 프록시 뒤에 있는 등 복잡한 설정에서는 “원하는 변경 내용이 거부되었습니다” 또는 “CSRF 토큰의 신뢰성을 검증할 수 없습니다”와 같은 오류를 피하려면 프록시 헤더를 조정해야 합니다.

이를 위해 기본 헤더를 무시하도록 할 수 있습니다. 예를 들어 /etc/gitlab/gitlab.rb에 다음과 같이 지정할 수 있습니다: 

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

파일을 저장하고 변경 사항이 적용되도록 GitLab 재구성을 수행하세요.

이렇게 하면 필요한 NGINX에서 지원하는 헤더를 지정할 수 있습니다.

GitLab trusted_proxies 및 NGINX real_ip 모듈 구성

기본적으로 NGINX와 GitLab은 연결된 클라이언트의 IP 주소를 기록합니다.

GitLab이 역방향 프록시 뒤에 있는 경우 프록시의 IP 주소가 클라이언트 주소로 표시되지 않도록 할 수 있습니다.

real_ip_trusted_addresses 목록에 역방향 프록시를 추가하여 NGINX에서 사용할 다른 주소를 찾도록 할 수 있습니다: 

# 각 주소는 NGINX 구성에 'set_real_ip_from <주소>;'로 추가됩니다.
nginx['real_ip_trusted_addresses'] = [ '192.168.1.0/24', '192.168.2.1', '2001:0db8::/32' ]
# 다른 real_ip 구성 옵션
nginx['real_ip_header'] = 'X-Forwarded-For'
nginx['real_ip_recursive'] = 'on'

옵션에 대한 설명:

기본적으로 Linux 패키지 설치는 real_ip_trusted_addresses의 IP 주소를 GitLab 신뢰 프록시로 사용하여 해당 IP에서 로그인한 사용자를 나열하지 않도록 합니다.

파일을 저장하고 변경 사항이 적용되도록 GitLab 재구성을 수행하세요.

PROXY 프로토콜 구성

PROXY 프로토콜을 사용하는 HAProxy와 같은 프록시를 GitLab 앞에 사용하려면 이 설정을 활성화해야 합니다. 필요에 따라 real_ip_trusted_addresses도 설정해야 합니다.

  1. /etc/gitlab/gitlab.rb를 편집합니다: 

    # NGINX에 의한 ProxyProtocol 종료 활성화
nginx['proxy_protocol'] = true
# 필요한 경우 `proxy_protocol`이 활성화되어 있는 경우 신뢰할 수 있는 상위 스트림 프록시 구성
nginx['real_ip_trusted_addresses'] = [ "127.0.0.0/8", "PROXY의 IP/32"]

  2. 파일을 저장하고 변경 사항이 적용되도록 GitLab 재구성을 수행하세요.

활성화된 경우, NGINX는 이러한 청취기에서만 PROXY 프로토콜 트래픽을 수락합니다. 모니터링 확인과 같이 기타 환경도 조정해야 합니다.

비번들 웹 서버 사용

기본적으로 Linux 패키지는 NGINX가 번들링된 상태로 GitLab을 설치합니다. Linux 패키지 설치는 gitlab-www 사용자를 통해 웹 서버에 액세스할 수 있도록 허용하며, 이 사용자는 동일한 그룹에 속해 있습니다. GitLab에 외부 웹 서버에 액세스하려면 외부 웹 서버 사용자를 gitlab-www 그룹에 추가해야 합니다.

아파치나 기존 NGINX 설치와 같은 다른 웹 서버를 사용하려면 다음 단계를 수행해야 합니다.

  1. 번들링된 NGINX 비활성화

    /etc/gitlab/gitlab.rb에서 다음을 설정합니다: 

    nginx['enable'] = false

  2. 번들링되지 않은 웹 서버 사용자 이름 설정

    기본적으로 Linux 패키지 설치에는 외부 웹 서버 사용자에 대한 기본 설정이 없으며, 구성에서 지정해야 합니다. Debian/Ubuntu의 경우 기본 사용자는 www-data이며, 아파치/NGINX 모두에 해당되고, RHEL/CentOS의 경우 NGINX 사용자는 nginx입니다.

    웹 서버 사용자가 생성되도록 먼저 아파치/NGINX를 설치했는지 확인하십시오. 그렇지 않으면 Linux 패키지 설치 중 재구성이 실패합니다.

    웹 서버 사용자가 www-data인 경우 다음을 /etc/gitlab/gitlab.rb에 설정합니다: 

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

    이 설정은 배열이므로 gitlab-www 그룹에 추가할 수 있는 사용자를 여러 명 지정할 수 있습니다.

    변경 사항이 적용되려면 sudo gitlab-ctl reconfigure를 실행하십시오.

    만약 SELinux를 사용하고 웹 서버가 제한된 SELinux 프로필에서 실행된다면 웹 서버의 제한을 완화해야 할 수 있습니다.

    외부 웹 서버가 사용하는 모든 디렉토리에 대해 웹 서버 사용자가 올바른 권한을 갖도록 확인하십시오. 그렇지 않으면 failed (XX: Permission denied) while reading upstream 오류가 발생합니다.

  3. 번들링되지 않은 웹 서버를 신뢰하는 프록시 목록에 추가

    일반적으로 Linux 패키지 설치는 번들링된 NGINX의 real_ip 모듈로 구성된 신뢰할 수 있는 프록시 목록을 기본값으로 설정합니다.

    번들링되지 않은 웹 서버의 경우 목록을 직접 구성해야 하며, 만약 웹 서버가 GitLab과 동일한 기계가 아니라면 웹 서버의 IP 주소도 포함해야 합니다.

    다음을 /etc/gitlab/gitlab.rb에 설정합니다(웹 서버가 GitLab과 동일한 기계에 있지 않은 경우 웹 서버의 IP 주소를 포함해야 합니다): 

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

  4. (선택 사항) 아파치를 사용하는 경우 올바른 GitLab Workhorse 설정 지정

    아파치는 UNIX 소켓에 연결할 수 없고 대신 TCP 포트에 연결해야 합니다. GitLab Workhorse가 기본적으로 TCP(기본 포트 8181)에서 수신하도록 허용하려면 /etc/gitlab/gitlab.rb를 편집합니다: 

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

    변경 사항이 적용되려면 sudo gitlab-ctl reconfigure를 실행하십시오.

  5. 올바른 웹 서버 구성 다운로드

    GitLab 저장소에 이동하여 필요한 구성을 다운로드하십시오. GitLab을 SSL로 제공하는지 아니면 그렇지 않은지에 따라 올바른 구성 파일을 선택해야 할 수 있습니다. 다음을 변경해야 할 수도 있습니다:

    • YOUR_SERVER_FQDN의 값은 FQDN으로 설정합니다.
    • SSL을 사용하는 경우 SSL 키의 위치.
    • 로그 파일의 위치.

NGINX 수신 주소 또는 주소 설정

기본적으로 NGINX는 모든 로컬 IPv4 주소에서 들어오는 연결을 수락합니다. 주소 목록을 변경하려면 /etc/gitlab/gitlab.rb를 편집하십시오. 

 # 모든 IPv4 및 IPv6 주소에서 수신
nginx['listen_addresses'] = ["0.0.0.0", "[::]"]
registry_nginx['listen_addresses'] = ['*', '[::]']
mattermost_nginx['listen_addresses'] = ['*', '[::]']
pages_nginx['listen_addresses'] = ['*', '[::]']

NGINX 수신 포트 설정

기본적으로 NGINX는 external_url에 지정된 포트에서 수신하거나 암시적으로 올바른 포트를 사용합니다(HTTP의 경우 80, HTTPS의 경우 443). 리버스 프록시 뒤에서 GitLab을 실행하는 경우 수신 포트를 다른 값으로 재정의해야 할 수 있습니다. 예를 들어, 포트 8081을 사용하려면: 

nginx['listen_port'] = 8081

NGINX 로그의 상세도 수준

기본적으로 NGINX는 error 상세도 수준에서 로그를 기록합니다. 로그 수준을 변경하여 다른 수준에서 로그를 남길 수 있습니다. 예를 들어, debug 로깅을 활성화하려면 다음과 같이 설정할 수 있습니다: 

nginx['error_log_level'] = "debug"

유효한 값은 NGINX 문서에서 찾을 수 있습니다.

Referrer-Policy 헤더 설정

기본적으로 GitLab은 모든 응답에 대해 Referrer-Policy 헤더를 strict-origin-when-cross-origin으로 설정합니다.

이는 클라이언트가 동일 출처 요청을 할 때 완전한 URL을 리퍼러로 보내지만, 교차 출처 요청을 할 때는 출처만을 보내도록 합니다.

이 헤더를 다른 값으로 설정하려면 다음과 같이 할 수 있습니다: 

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

또는 클라이언트가 기본 설정을 사용하도록 이 헤더를 비활성화할 수도 있습니다: 

nginx['referrer_policy'] = false

이를 origin 또는 no-referrer로 설정하는 것은 전체 리퍼러 URL이 필요한 GitLab의 일부 기능을 손상시킬 수 있다는 점에 유의하십시오.

Gzip 압축 비활성화

기본적으로 GitLab은 10240바이트 이상의 텍스트 데이터에 대해 Gzip 압축을 활성화합니다. 이 동작을 비활성화하려면 다음과 같이 할 수 있습니다: 

nginx['gzip_enabled'] = false

참고: 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를 구성하려면, custom NGINX configuration을 추가하여 사용자 정의 robots.txt 파일을 지정하세요.

  1. /etc/gitlab/gitlab.rb 파일을 편집합니다: 

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

  2. GitLab을 다시 구성합니다: 

    sudo gitlab-ctl reconfigure

GitLab 서버 블록에 사용자 정의 NGINX 설정 삽입

동일한 설정이 gitlab.rb 파일에 정의되어 있는 경우, 이러한 사용자 정의 설정이 충돌을 일으킬 수 있음에 유의하십시오.

어떤 이유로든 GitLab의 NGINX server 블록에 사용자 정의 설정을 추가해야 하는 경우, 다음 설정을 사용할 수 있습니다. 

# 예시: 특정 저장소로부터의 원시 파일 다운로드 차단
nginx['custom_gitlab_server_config'] = "location ^~ /foo-namespace/bar-project/raw/ {\n deny all;\n}\n"

NGINX 구성을 다시 작성하고 NGINX를 재시작하려면 gitlab-ctl reconfigure를 실행하십시오.

이를 통해 지정된 문자열이 /var/opt/gitlab/nginx/conf/gitlab-http.conf의 server 블록 끝에 삽입됩니다.

참고 사항

  • 새로운 위치를 추가하는 경우, 다음을 포함해야 할 수 있습니다. 

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

    이러한 설정을 문자열이나 포함된 NGINX 구성에 추가하지 않으면 하위 위치는 404를 반환합니다. GitLab CE Issue #30619를 참조하십시오.

  • / 위치나 /assets 위치를 추가할 수 없습니다. 이미 gitlab-http.conf에 존재하기 때문입니다.

NGINX 구성에 사용자 정의 설정 삽입

기존 서버 블록을 포함하는 등 NGINX 구성에 사용자 정의 설정을 추가해야 하는 경우, 다음 설정을 사용할 수 있습니다. 

# 예시: 추가 구성 파일을 스캔하기 위한 디렉토리 포함
nginx['custom_nginx_config'] = "include /etc/gitlab/nginx/sites-enabled/*.conf;"

이 설정을 적용하려면 /etc/gitlab/nginx/sites-available 디렉토리에 사용자 정의 서버 블록을 생성해야 합니다. 이를 활성화하려면 해당 서버 블록에 심볼릭 링크를 /etc/gitlab/nginx/sites-enabled 디렉토리에 만들어야 합니다:

  1. /etc/gitlab/nginx/sites-enabled 디렉토리를 생성합니다.

  2. 다음 명령을 실행합니다: 

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

사용자 정의 서버 블록에 대한 변경 사항을 만들 때마다 NGINX 구성을 다시 작성하고 NGINX를 다시 시작해야 합니다(gitlab-ctl hup nginx 또는 gitlab-ctl restart nginx).

이를 통해 지정된 문자열이 /var/opt/gitlab/nginx/conf/nginx.conf의 http 블록 끝에 삽입됩니다.

/etc/gitlab/ 디렉토리 내의 사용자 정의 NGINX 설정은 업그레이드 시에 /etc/gitlab/config_backup/에 백업됩니다. 수동으로 sudo gitlab-ctl backup-etc를 실행할 때도 백업됩니다.

커스텀 오류 페이지

기본 GitLab 오류 페이지의 텍스트를 수정하려면 custom_error_pages를 사용할 수 있습니다. 이는 유효한 HTTP 오류 코드(예: 404, 502)에 대해 사용할 수 있습니다.

다음은 기본 404 오류 페이지를 수정하는 예시입니다. 

nginx['custom_error_pages'] = {
  '404' => {
    'title' => '예시 제목',
    'header' => '예시 헤더',
    'message' => '예시 메시지'
  }
}

이로 인해 아래와 같이 404 오류 페이지가 수정됩니다.

커스텀 404 오류 페이지

NGINX 구성을 다시 작성하고 NGINX를 재시작하려면 gitlab-ctl reconfigure를 실행하세요.

기존 Passenger/NGINX 설치 사용하기

일부 경우에는 기존 Passenger/NGINX 설치를 사용하여 GitLab을 호스팅하고 싶지만 Linux 패키지를 사용하여 업데이트하고 설치하는 편의성을 갖고 싶을 수 있습니다.

참고: NGINX를 비활성화하면 Mattermost와 같은 Linux 패키지 설치에 포함된 다른 서비스에 액세스할 수 없습니다. 이를 수동으로 nginx.conf에 추가해야 합니다.

구성

먼저, /etc/gitlab/gitlab.rb를 설정하여 기본 NGINX와 Puma를 비활성화해야 합니다. 

# 외부 URL 정의
external_url 'http://git.example.com'

# 내장 NGINX 비활성화
nginx['enable'] = false

# 내장 Puma 비활성화
puma['enable'] = false

# 내부 API URL 정의
gitlab_rails['internal_api_url'] = 'http://git.example.com'

# 웹 서버 프로세스 사용자 정의 (ubuntu/nginx)
web_server['external_users'] = ['www-data']

변경 사항이 적용되려면 sudo gitlab-ctl reconfigure를 실행하세요.

참고: 8.16.0 이전 버전을 실행 중이라면, 재구성이 성공하려면 (일치하는 경우) 수동으로 Unicorn 서비스 파일(/opt/gitlab/service/unicorn)을 제거해야 합니다.

Vhost (서버 블록)

참고: GitLab 13.5에서 기본 workhorse 소켓 위치가 /var/opt/gitlab/gitlab-workhorse/socket에서 /var/opt/gitlab/gitlab-workhorse/sockets/socket로 변경되었습니다. 따라서 13.5 이전 버전에서 업그레이드하는 경우 해당 구성을 업데이트하세요.

그런 다음, 사용자 정의 Passenger/NGINX 설치에서 다음과 같은 사이트 구성 파일을 생성하세요. 

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;

  # Passenger가 번들된 Ruby 버전을 사용하도록 보장
  passenger_ruby /opt/gitlab/embedded/bin/ruby;

  # 패키지화된 실행 파일을 사용하기 위해 $PATH 변수 수정
  passenger_env_var PATH "/opt/gitlab/bin:/opt/gitlab/embedded/bin:/usr/local/bin:/usr/bin:/bin";

  # 정확한 사용자 및 그룹으로 Passenger 실행하도록
  passenger_user git;
  passenger_group git;

  # Passenger 활성화 및 항상 최소한 하나의 인스턴스를 실행하도록
  passenger_enabled on;
  passenger_min_instances 1;

  location ~ ^/[\w\.-]+/[\w\.-]+/(info/refs|git-upload-pack|git-receive-pack)$ {
    # '에러' 418은 @gitlab-workhorse 블록 재사용을 위한 해킹 방법
    error_page 418 = @gitlab-workhorse;
    return 418;
  }

  location ~ ^/[\w\.-]+/[\w\.-]+/repository/archive {
    # '에러' 418은 @gitlab-workhorse 블록 재사용을 위한 해킹 방법
    error_page 418 = @gitlab-workhorse;
    return 418;
  }

  location ~ ^/api/v3/projects/.*/repository/archive {
    # '에러' 418은 @gitlab-workhorse 블록 재사용을 위한 해킹 방법
    error_page 418 = @gitlab-workhorse;
    return 418;
  }

  # Build artifacts는 이 위치로 제출되어야 함
  location ~ ^/[\w\.-]+/[\w\.-]+/builds/download {
      client_max_body_size 0;
      # '에러' 418은 @gitlab-workhorse 블록 재사용을 위한 해킹 방법
      error_page 418 = @gitlab-workhorse;
      return 418;
  }

  # Build artifacts는 이 위치로 제출되어야 함
  location ~ /ci/api/v1/builds/[0-9]+/artifacts {
      client_max_body_size 0;
      # '에러' 418은 @gitlab-workhorse 블록 재사용을 위한 해킹 방법
      error_page 418 = @gitlab-workhorse;
      return 418;
  }

  # Build artifacts는 이 위치로 제출되어야 함
  location ~ /api/v4/jobs/[0-9]+/artifacts {
      client_max_body_size 0;
      # '에러' 418은 @gitlab-workhorse 블록 재사용을 위한 해킹 방법
      error_page 418 = @gitlab-workhorse;
      return 418;
  }

  # HTTP/1.0에서 HTTP/1.1로 프로토콜 업그레이드 시 Host 헤더가 누락된 경우
  if ($http_host = "") {
  # 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
    ## 일부 요청이 30초 이상 소요됩니다.
    proxy_read_timeout      3600;
    proxy_connect_timeout   300;
    proxy_redirect          off;

    # Git HTTP 응답을 버퍼링하지 않음
    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;

    ## 아래 설정은 NGINX 1.7.11 이상에서만 작동합니다
    #
    ## 청크 요청 바디를 그대로 gitlab-workhorse로 전달
    # proxy_request_buffering off;
    # proxy_http_version 1.1;
  }

  ## gzip 압축을 rails 가이드에 따라 활성화:
  ## http://guides.rubyonrails.org/asset_pipeline.html#gzip-compression
  ## 경고: 상대적인 URL을 사용하는 경우 아래 블록 제거
  ## 상대적인 URL 지원에 대한 자세한 정보는 config/application.rb의 "상대적인 URL 지원" 참조
  location ~ ^/(assets)/ {
    root /opt/gitlab/embedded/service/gitlab-rails/public;
    gzip_static on; # 사전 압축 버전 제공
    expires max;
    add_header Cache-Control public;
  }

  error_page 502 /502.html;
}

상기 예제에서 git.example.com을 서버 URL로 업데이트하는 것을 잊지 마세요.

403 금지 상태로 끝날 경우, /etc/nginx/nginx.conf에서 passenger를 활성화하지 않은 것일 수 있습니다. 다음을 주석 처리하여 sudo service nginx reload를 실행하세요. 

# include /etc/nginx/passenger.conf;

nginx_status 활성화/비활성화

기본적으로 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
  • 활성 연결 – 총 열려 있는 연결
  • 3개의 숫자가 표시됩니다.
    • 수락된 모든 연결
    • 처리된 모든 연결
    • 처리된 총 요청 수
  • Reading: NGINX가 요청 헤더를 읽음
  • Writing: NGINX가 요청 본문을 읽거나 요청을 처리하거나 클라이언트에 대한 응답을 작성함
  • Waiting: Keep-alive 연결. 이 숫자는 keepalive-timeout에 따라 달라집니다.

구성 옵션

/etc/gitlab/gitlab.rb 파일을 편집하세요: 

nginx['status'] = {
  "listen_addresses" => ["127.0.0.1"],
  "fqdn" => "dev.example.com",
  "port" => 9999,
  "options" => {
    "access_log" => "on", # 통계용 로그를 비활성화합니다
    "allow" => "127.0.0.1", # 로컬호스트에서의 액세스만 허용합니다
    "deny" => "all" # 다른 사람에 대한 액세스를 거부합니다
  }
}

현재 인프라에 이 서비스를 유용하지 않다고 판단된다면 다음과 같이 비활성화할 수 있습니다: 

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

변경 사항이 적용되려면 sudo gitlab-ctl reconfigure를 실행해야 합니다.

주의

사용자 업로드가 액세스 가능하도록 하려면 NGINX 사용자(보통 www-data)를 gitlab-www 그룹에 추가해야 합니다. 다음 명령을 사용하여 이 작업을 수행할 수 있습니다: 

sudo usermod -aG gitlab-www www-data

템플릿

Puma 대신 Passenger 구성 및 HTTPS의 부재를 제외하고 이 파일들은 대부분 다음과 유사합니다:

새 구성을 로드하기 위해 NGINX를 재시작하는 것을 잊지 마세요 (Debian 기반 시스템에서는 sudo service nginx restart).

문제 해결

400 Bad Request: too many Host headers

nginx['custom_gitlab_server_config'] 설정에서 proxy_set_header 구성이 없는지 확인하고 대신 gitlab.rb 파일에서 ‘proxy_set_headers’ 구성을 사용하세요.

javax.net.ssl.SSLHandshakeException: Received fatal alert: handshake_failure

리눅스 패키지 설치는 기본적으로 TLSv1 프로토콜을 지원하지 않습니다. 이는 GitLab 인스턴스와 상호 작용할 때 일부 이전 Java 기반 IDE 클라이언트와의 연결 문제를 유발할 수 있습니다. 당사는 이 사용자 코멘트에서 언급된 것과 유사하게 서버의 암호를 업그레이드할 것을 강력히 권장합니다.

이 서버 변경이 불가능한 경우 /etc/gitlab/gitlab.rb의 값을 변경하여 이전 동작으로 복원할 수 있습니다: 

nginx['ssl_protocols'] = "TLSv1 TLSv1.1 TLSv1.2 TLSv1.3"

개인 키와 인증서 간 불일치

NGINX 로그(/var/log/gitlab/nginx/current - Omnibus의 기본 설정)에서 x509 certificate routines:X509_check_private_key:key values mismatch)을 찾으면, 개인 키와 인증서 간에 불일치가 있습니다.

이를 해결하려면 올바른 개인 키와 인증서를 매치해야 합니다.

올바른 키와 인증서를 보장하기 위해 개인 키와 인증서의 모듈러스가 일치하는지 확인할 수 있습니다: 

/opt/gitlab/embedded/bin/openssl rsa -in /etc/gitlab/ssl/gitlab.example.com.key -noout -modulus | /opt/gitlab/embedded/bin/openssl sha256

/opt/gitlab/embedded/bin/openssl x509 -in /etc/gitlab/ssl/gitlab.example.com.crt -noout -modulus| /opt/gitlab/embedded/bin/openssl sha256

일치하는 것을 확인한 후 NGINX를 재구성하고 다시 로드해야 합니다: 

sudo gitlab-ctl reconfigure
sudo gitlab-ctl hup nginx

Request Entity Too Large

NGINX 로그에서 Request Entity Too Large를 발견하면 Client Max Body Size를 증가해야 합니다. Max import size를 증가시켰을 경우에도 이 오류가 발생할 수 있습니다. Kubernetes 기반의 GitLab 설치에서는 다르게 명명되어 있습니다.

client_max_body_size를 늘리려면 /etc/gitlab/gitlab.rb에서 값을 설정해야 합니다: 

nginx['client_max_body_size'] = '250m'

변경된 구성을 사용하기 위해 sudo gitlab-ctl reconfigure 및 sudo gitlab-ctl hup nginx 명령을 실행하여 NGINX가 업데이트된 구성으로 다시 로드하도록 하세요.

client_max_body_size를 증가시키려면 다음과 같이 할 수 있습니다:

  1. /etc/gitlab/gitlab.rb을 편집하고 원하는 값으로 설정하세요: 

    nginx['client_max_body_size'] = '250m'

  2. GitLab을 재구성하고 HUP하도록 NGINX를 구성을 재로드하세요: 

    sudo gitlab-ctl reconfigure
sudo gitlab-ctl hup nginx

보안 스캔에서 “NGINX HTTP 서버 탐지” 경고가 나타납니다

일부 보안 스캐너는 Server: nginx HTTP 헤더를 볼 때 문제가 되는 것으로 감지합니다. 이와 관련된 대부분의 스캐너는 Low 또는 Info 심각성으로 알립니다. 예시로 Nessus를 참조하세요.

이 경고를 무시하는 것을 권장합니다. 왜냐하면 헤더를 제거하는 이점이 적고, 해당 헤더의 존재는 NGINX 프로젝트의 사용 통계에 도움이 됩니다. hide_server_tokens를 사용하여 헤더를 끄는 방법을 제공합니다:

  1. /etc/gitlab/gitlab.rb 파일을 편집하고 다음 값을 설정하세요: 

    nginx['hide_server_tokens'] = 'on'

  2. GitLab을 다시 구성하고 hup을 실행하여 업데이트된 구성으로 NGINX를 안전하게 다시로드하세요: 

    sudo gitlab-ctl reconfigure
sudo gitlab-ctl hup nginx

SELinux 및 외부 NGINX를 사용할 때 502: Bad Gateway 오류가 발생하는 경우

SELinux가 활성화된 Linux 서버에서 외부 NGINX를 설정한 후 GitLab UI에 액세스할 때 502: Bad Gateway 오류가 발생할 수 있습니다. 또한 NGINX 로그에서도 이 오류를 볼 수 있습니다: 

connect() to unix:/var/opt/gitlab/gitlab-workhorse/sockets/socket failed (13:Permission denied) while connecting to upstream

다음 옵션 중 하나를 선택하여 수정하세요:

  • 업데이트된 SELinux 정책이 포함된 GitLab 14.3 이상으로 업데이트하세요.

  • 정책을 수동으로 가져오고 업데이트하세요: 

    wget https://gitlab.com/gitlab-org/omnibus-gitlab/-/raw/a9d6b020f81d18d778fb502c21b2c8f2265cabb4/files/gitlab-selinux/rhel/7/gitlab-13.5.0-gitlab-shell.pp
semodule -i gitlab-13.5.0-gitlab-shell.pp

Web IDE 및 외부 NGINX를 사용할 때 Branch 'branch_name' was not found in this project's repository 오류가 발생하는 경우

이 오류가 발생하는 경우, proxy_pass에서 끝에 슬래시가 있는지 NGINX 구성 파일을 확인하고 제거하세요:

  1. NGINX 구성 파일을 편집하세요: 

    proxy_pass https://1.2.3.4;

  2. NGINX를 재시작하세요: 

    sudo systemctl restart nginx

GitLab이 로그에서 502 오류와 worker_connections are not enough를 표시하는 문제

로그에서 worker_connections are not enough 오류가 발생하는 경우, NGINX 워커 연결을 더 높은 값으로 구성하세요:

  1. /etc/gitlab/gitlab.rb 파일을 편집하세요: 

    gitlab['nginx']['worker_connections'] = 10240

  2. GitLab을 다시 구성하세요: 

    sudo gitlab-ctl reconfigure

기본값은 10240 연결입니다.