- 서비스별 NGINX 설정
- HTTPS 활성화
- 기본 프록시 헤더 변경
- GitLab
trusted_proxies
및 NGINXreal_ip
모듈 구성 - PROXY 프로토콜 구성
- 비번들 웹 서버 사용
- NGINX 수신 주소 또는 주소 설정
- NGINX 수신 포트 설정
- NGINX 로그의 상세도 수준
- Referrer-Policy 헤더 설정
- Gzip 압축 비활성화
- 프록시 요청 버퍼링 비활성화
robots.txt
구성- GitLab 서버 블록에 사용자 정의 NGINX 설정 삽입
- NGINX 구성에 사용자 정의 설정 삽입
- 커스텀 오류 페이지
- 기존 Passenger/NGINX 설치 사용하기
-
nginx_status
활성화/비활성화 - 템플릿
-
문제 해결
- 400 Bad Request: too many Host headers
javax.net.ssl.SSLHandshakeException: Received fatal alert: handshake_failure
- 개인 키와 인증서 간 불일치
- Request Entity Too Large
- 보안 스캔에서 “NGINX HTTP 서버 탐지” 경고가 나타납니다
- SELinux 및 외부 NGINX를 사용할 때
502: Bad Gateway
오류가 발생하는 경우 - Web IDE 및 외부 NGINX를 사용할 때
Branch 'branch_name' was not found in this project's repository
오류가 발생하는 경우 - GitLab이 로그에서 502 오류와
worker_connections are not enough
를 표시하는 문제
NGINX 설정
서비스별 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를 활성화하려면 다음을 수행할 수 있습니다:
- 무료 자동화된 HTTPS를 위해 Let’s Encrypt 사용하기: Let’s Encrypt 통합 활성화.
- 자체 인증서를 사용하여 수동으로 HTTPS 구성하기: 고유한 인증서로 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
도 설정해야 합니다.
-
/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"]
-
파일을 저장하고 변경 사항이 적용되도록 GitLab 재구성을 수행하세요.
활성화된 경우, NGINX는 이러한 청취기에서만 PROXY 프로토콜 트래픽을 수락합니다. 모니터링 확인과 같이 기타 환경도 조정해야 합니다.
비번들 웹 서버 사용
기본적으로 Linux 패키지는 NGINX가 번들링된 상태로 GitLab을 설치합니다.
Linux 패키지 설치는 gitlab-www
사용자를 통해 웹 서버에 액세스할 수 있도록 허용하며, 이 사용자는 동일한 그룹에 속해 있습니다. GitLab에 외부 웹 서버에 액세스하려면 외부 웹 서버 사용자를 gitlab-www
그룹에 추가해야 합니다.
아파치나 기존 NGINX 설치와 같은 다른 웹 서버를 사용하려면 다음 단계를 수행해야 합니다.
-
번들링된 NGINX 비활성화
/etc/gitlab/gitlab.rb
에서 다음을 설정합니다:nginx['enable'] = false
-
번들링되지 않은 웹 서버 사용자 이름 설정
기본적으로 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
오류가 발생합니다. -
번들링되지 않은 웹 서버를 신뢰하는 프록시 목록에 추가
일반적으로 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' ]
-
(선택 사항) 아파치를 사용하는 경우 올바른 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
를 실행하십시오. -
올바른 웹 서버 구성 다운로드
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
를 변경함으로써 특정 위치를 선택적으로 프록시 요청 버퍼링을 비활성화할 수 있습니다.
-
/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$"
-
GitLab을 다시 구성하고, HUP을 통해 NGINX를 다시 불러와 업데이트된 구성을 원만하게 적용시킵니다:
sudo gitlab-ctl reconfigure sudo gitlab-ctl hup nginx
robots.txt
구성
인스턴스에 대한 robots.txt
를 구성하려면, custom NGINX configuration을 추가하여 사용자 정의 robots.txt
파일을 지정하세요.
-
/etc/gitlab/gitlab.rb
파일을 편집합니다:nginx['custom_gitlab_server_config'] = "\nlocation =/robots.txt { alias /path/to/custom/robots.txt; }\n"
-
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
디렉토리에 만들어야 합니다:
-
/etc/gitlab/nginx/sites-enabled
디렉토리를 생성합니다. -
다음 명령을 실행합니다:
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 오류 페이지가 수정됩니다.
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
를 증가시키려면 다음과 같이 할 수 있습니다:
-
/etc/gitlab/gitlab.rb
을 편집하고 원하는 값으로 설정하세요:nginx['client_max_body_size'] = '250m'
-
GitLab을 재구성하고 HUP하도록 NGINX를 구성을 재로드하세요:
sudo gitlab-ctl reconfigure sudo gitlab-ctl hup nginx
보안 스캔에서 “NGINX HTTP 서버 탐지” 경고가 나타납니다
일부 보안 스캐너는 Server: nginx
HTTP 헤더를 볼 때 문제가 되는 것으로 감지합니다. 이와 관련된 대부분의 스캐너는 Low
또는 Info
심각성으로 알립니다. 예시로 Nessus를 참조하세요.
이 경고를 무시하는 것을 권장합니다. 왜냐하면 헤더를 제거하는 이점이 적고, 해당 헤더의 존재는 NGINX 프로젝트의 사용 통계에 도움이 됩니다. hide_server_tokens
를 사용하여 헤더를 끄는 방법을 제공합니다:
-
/etc/gitlab/gitlab.rb
파일을 편집하고 다음 값을 설정하세요:nginx['hide_server_tokens'] = 'on'
-
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 구성 파일을 확인하고 제거하세요:
-
NGINX 구성 파일을 편집하세요:
proxy_pass https://1.2.3.4;
-
NGINX를 재시작하세요:
sudo systemctl restart nginx
GitLab이 로그에서 502 오류와 worker_connections are not enough
를 표시하는 문제
로그에서 worker_connections are not enough
오류가 발생하는 경우, NGINX 워커 연결을 더 높은 값으로 구성하세요:
-
/etc/gitlab/gitlab.rb
파일을 편집하세요:gitlab['nginx']['worker_connections'] = 10240
-
GitLab을 다시 구성하세요:
sudo gitlab-ctl reconfigure
기본값은 10240 연결입니다.