Omnibus GitLab 설치 문제 해결

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

Omnibus GitLab 패키지를 설치하는 동안 사용자들이 마주칠 수 있는 일반적인 문제에 대해 알아보는 페이지입니다.

패키지 다운로드 시 해시 합 불일치

apt-get install이 다음과 같은 출력을 내보냅니다: 

E: Failed to fetch https://packages.gitlab.com/gitlab/gitlab-ce/ubuntu/pool/trusty/main/g/gitlab-ce/gitlab-ce_8.1.0-ce.0_amd64.deb  Hash Sum mismatch

다음을 실행하여 이 문제를 해결할 수 있습니다: 

sudo rm -rf /var/lib/apt/lists/partial/*
sudo apt-get update
sudo apt-get clean

더 많은 정보는 Joe Damato의 Packagecloud 코멘트와 그의 블로그 기사에서 확인할 수 있습니다.

또 다른 해결책은 올바른 패키지를 선택하여 수동으로 패키지를 다운로드하는 것입니다. 이를 위해 CE 패키지 또는 EE 패키지 리포지토리에서 올바른 패키지를 선택합니다: 

curl -LJO "https://packages.gitlab.com/gitlab/gitlab-ce/packages/ubuntu/trusty/gitlab-ce_8.1.0-ce.0_amd64.deb/download"
dpkg -i gitlab-ce_8.1.0-ce.0_amd64.deb

openSUSE 및 SLES 플랫폼에서의 설치 시 알 수 없는 키 서명 경고

Omnibus GitLab 패키지는 패키지 리포지토리가 서명 된 메타데이터를 제공하는 것 외에도 GPG 키로 서명되어 있습니다. 이는 사용자들에게 배포된 패키지의 신뢰성과 무결성을 보장합니다. 그러나 openSUSE 및 SLES 운영 체제에서 사용되는 패키지 관리자는 때로는 이러한 서명과 관련된 잘못된 경고를 유발할 수 있습니다. 예를 들어: 

File 'repomd.xml' from repository 'gitlab_gitlab-ce' is signed with an unknown key '14219A96E15E78F4'. Continue? [yes/no] (no):
File 'repomd.xml' from repository 'gitlab_gitlab-ce' is signed with an unknown key '14219A96E15E78F4'. Continue? [yes/no] (no): yes

이는 zypper에서 gpgkey 키워드를 무시하는 zypper의 알려진 버그입니다. Packagecloud의 나중 버전에서는 이에 대한 개선사항이 있을 수 있지만 현재 사용자들은 패키지 설치에 수동으로 동의해야 합니다.

따라서 openSUSE 또는 SLES 시스템에서 이러한 경고가 표시될 경우, 설치를 계속해도 안전합니다.

apt/yum에서 GPG 서명에 대한 불평

이미 GitLab 리포지토리가 구성되어 있으며 apt-get update, apt-get install 또는 yum install을 실행하고 다음과 유사한 오류를 본 적이 있다면: 

The following signatures couldn’t be verified because the public key is not available: NO_PUBKEY 3F01618A51312F3F

또는 

https://packages.gitlab.com/gitlab/gitlab-ee/el/7/x86_64/repodata/repomd.xml: [Errno -1] repomd.xml signature could not be verified for gitlab-ee

이는 2020년 4월에 GitLab이 Packagecloud 인스턴스를 통해 제공되는 apt 및 yum 리포지토리의 메타데이터를 서명하는 데 사용되는 GPG 키를 변경했기 때문에 발생한 오류입니다. 이 오류가 표시된다면, 이는 일반적으로 현재 사용자의 키링에 리포지토리 메타데이터를 서명하는 데 현재 사용 중인 공개 키가 없다는 것을 의미합니다. 이 오류를 해결하려면 2020년 4월 6일 이후에 사용할 수 있는 새로운 키를 가져오는 단계를 따르세요.

다시 구성 시 오류 표시: NoMethodError - undefined method '[]=' for nil:NilClass

sudo gitlab-ctl reconfigure를 실행하거나 패키지 업그레이드로 인해 다시 구성을 트리거한 후 다음과 유사한 오류가 발생했다면: 

 ================================================================================
 Recipe Compile Error in /opt/gitlab/embedded/cookbooks/cache/cookbooks/gitlab/recipes/default.rb
 ================================================================================

NoMethodError
-------------
undefined method '[]=' for nil:NilClass

Cookbook Trace:
---------------
  /opt/gitlab/embedded/cookbooks/cache/cookbooks/gitlab/recipes/config.rb:21:in 'from_file'
  /opt/gitlab/embedded/cookbooks/cache/cookbooks/gitlab/recipes/default.rb:26:in 'from_file'

Relevant File Content:

이 오류는 /etc/gitlab/gitlab.rb 구성 파일에 유효하지 않거나 지원되지 않는 구성이 포함되어 있는 경우에 발생합니다. 오타가 없는지 또는 구식 구성이 포함되지 않았는지 다시 한 번 확인하세요.

GitLab 8.17부터 사용할 수 있는 sudo gitlab-ctl diff-config를 사용하여 최신 구성을 확인할 수 있으며 또는 최신 gitlab.rb.template을 확인할 수 있습니다.

GitLab 내 브라우저에서 접속할 수 없음

여기서 /etc/gitlab/gitlab.rb에 있는 external_url을 지정해보세요. 또한 방화벽 설정을 확인하세요. GitLab 서버의 포트 80 (HTTP) 또는 443 (HTTPS)가 닫혀 있을 수 있습니다.

external_url를 지정할 때, GitLab이나 다른 번들된 서비스인(Registry 및 Mattermost) 경우 gitlab.rb의 다른 부분에서 따르는 key=value 형식이 아닙니다. 다음 형식으로 설정했는지 확인하세요: 

external_url "https://gitlab.example.com"
registry_external_url "https://registry.example.com"
mattermost_external_url "https://mattermost.example.com"

참고: external_url과 값 사이에 등호 (=)를 추가하지 마십시오.

이메일을 받지 못하는 경우

이메일 전달을 테스트하려면 GitLab 인스턴스에서 사용되지 않은 이메일로 새로운 GitLab 계정을 만들 수 있습니다.

필요한 경우, /etc/gitlab/gitlab.rb에 다음 설정으로 GitLab이 보내는 이메일의 ‘보낸 사람’ 필드를 수정할 수 있습니다. 

gitlab_rails['gitlab_email_from'] = 'gitlab@example.com'

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

GitLab 서비스를 위한 TCP 포트가 이미 사용 중

기본적으로 Puma는 TCP 주소 127.0.0.1:8080에서 수신합니다. NGINX는 모든 인터페이스에서 포트 80 (HTTP) 및/또는 443 (HTTPS)에서 수신합니다.

Redis, PostgreSQL 및 Puma의 포트는 다음과 같이 /etc/gitlab/gitlab.rb에서 변경할 수 있습니다. 

redis['port'] = 1234
postgresql['port'] = 2345
puma['port'] = 3456

NGINX 포트 변경에 대해서는 NGINX 수신 포트 설정을 참조하세요.

Git 사용자가 SSH 액세스를 할 수 없음

SELinux 활성화된 시스템

SELinux 활성화된 시스템에서 Git 사용자의 .ssh 디렉터리나 해당 내용의 보안 컨텍스트가 꼬일 수 있습니다. sudo gitlab-ctl reconfigure를 실행하여 /var/opt/gitlab/.ssh에 gitlab_shell_t 보안 컨텍스트를 설정하여 이를 해결할 수 있습니다.

GitLab 10.0에서는 semanage를 사용하여 컨텍스트를 영구적으로 설정하여 이 동작이 개선되었습니다. RHEL 기반 운영 체제의 경우, RPM 패키지에 policycoreutils-python 런타임 의존성이 추가되어 semanage 명령이 사용 가능함을 보장합니다.

SELinux 문제 진단 및 해결

Omnibus GitLab은 /etc/gitlab/gitlab.rb에서 기본 경로 변경을 감지하고 올바른 파일 컨텍스트를 적용해야 합니다. 사용자 지정 데이터 경로 구성을 사용하는 설치의 경우, 관리자는 SELinux 문제를 수동으로 해결해야 할 수 있습니다.

데이터 경로는 gitlab.rb을 통해 변경될 수 있지만, 일반적인 시나리오에서는 symlink 경로를 사용해야 할 수 있습니다. symlink 경로가 Gitaly 데이터 경로와 같은 모든 시나리오에 지원되지 않기 때문에 관리자는 주의해야 합니다.

예를 들어, /data/gitlab이 기본 데이터 디렉토리로 /var/opt/gitlab을 대체했다면, 다음은 보안 컨텍스트를 수정합니다. 

sudo semanage fcontext -a -t gitlab_shell_t /data/gitlab/.ssh/
sudo semanage fcontext -a -t gitlab_shell_t /data/gitlab/.ssh/authorized_keys
sudo restorecon -Rv /data/gitlab/
sudo semanage fcontext -a -t gitlab_shell_t /data/gitlab/gitlab-shell/config.yml
sudo restorecon -Rv /data/gitlab/gitlab-shell/
sudo semanage fcontext -a -t gitlab_shell_t /data/gitlab/gitlab-rails/etc/gitlab_shell_secret
sudo restorecon -Rv /data/gitlab/gitlab-rails/
sudo semanage fcontext --list | grep /data/gitlab/

정책이 적용된 후에 SSH 액세스가 작동하는지 확인하려면 환영 메시지를 받기 위해 다음을 실행하세요. 

ssh -T git@gitlab-hostname

모든 시스템

Git 사용자는 기본적으로 /etc/shadow에 있는 비밀번호가 잠겨 있어야 합니다. “UsePam yes”가 활성화되지 않은 경우, OpenSSH 데몬은 SSH 키로 식별되더라도 Git 사용자의 인증을 방지합니다. 대체적으로 안전한 해결책은 /etc/shadow에서 '!'을 '*'로 대체하여 비밀번호 잠금을 해제하는 것입니다. 그러나 Git 사용자는 여전히 제한된 셸에서 실행되며 비밀번호 변경을 할 수 없습니다. 따라서 계정은 여전히 비밀번호가 없이 유지됩니다.

Git 사용자는 시스템에 액세스할 수 있는 경우가 있으므로 보안 설정을 검토하고 /etc/security/access.conf에서 Git 사용자가 차단되지 않았는지 확인해야 합니다.

PostgreSQL 오류 FATAL: 공유 메모리 세그먼트를 생성할 수 없음: 메모리를 할당할 수 없음

패키지화된 PostgreSQL 인스턴스는 총 메모리의 25%를 공유 메모리로 할당하려고 시도합니다. 일부 Linux (가상) 서버에서는 사용 가능한 공유 메모리가 부족하여 PostgreSQL을 시작할 수 없습니다. /var/log/gitlab/postgresql/current에서 다음과 같은 오류 메시지를 확인할 수 있습니다: 

  1885  2014-08-08_16:28:43.71000 FATAL: 공유 메모리 세그먼트를 생성할 수 없음: 메모리를 할당할 수 없음
  1886  2014-08-08_16:28:43.71002 DETAIL:  실패한 시스템 호출은 shmget(key=5432001, size=1126563840, 03600)입니다.
  1887  2014-08-08_16:28:43.71003 HINT:  이 오류는 보통 PostgreSQL의 공유 메모리 세그먼트 요청이 사용 가능한 메모리나 스왑 공간을 초과하거나 커널의 SHMALL 매개변수를 초과하는 경우에 발생합니다. 요청 크기를 줄이거나 커널을 더 큰 SHMALL로 다시 구성할 수 있습니다. 요청 크기 (현재 1126563840 바이트)를 줄이려면 PostgreSQL의 공유 메모리 사용량을 줄이십시오. 이를 위해 shared_buffers나 max_connections을 줄이는 등 PostgreSQL 문서에 자세한 정보가 있습니다.
  1888  2014-08-08_16:28:43.71004       PostgreSQL 문서에 공유 메모리 구성에 대한 자세한 정보가 있습니다.

PostgreSQL이 할당하려는 공유 메모리의 양을 수동으로 낮출 수 있습니다. /etc/gitlab/gitlab.rb에서 다음과 같이 설정하세요: 

postgresql['shared_buffers'] = "100MB"

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

PostgreSQL 오류 FATAL: 공유 메모리 세그먼트 "/PostgreSQL.XXXXXXXXXX"를 열 수 없음: 권한 거부됨

기본적으로 PostgreSQL은 사용할 공유 메모리 유형을 감지하려고 시도합니다. 공유 메모리가 활성화되어 있지 않으면 /var/log/gitlab/postgresql/current에서 이러한 오류를 볼 수 있습니다. 이 문제를 해결하려면 PostgreSQL의 공유 메모리 감지를 비활성화하세요. /etc/gitlab/gitlab.rb에서 다음 값을 설정하세요: 

postgresql['dynamic_shared_memory_type'] = 'none'

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

PostgreSQL 오류 FATAL: 남아있는 연결 슬롯은 복제용 수퍼 사용자 연결을 위해 예약되어 있음

PostgreSQL에는 데이터베이스 서버에 대한 최대 동시 연결 수에 대한 설정이 있습니다. 이 오류를 보면 GitLab 인스턴스가 동시 연결 수의 제한을 초과하려고 시도하고 있다는 것을 의미합니다.

이 문제를 해결하려면 두 가지 옵션이 있습니다:

  • 최대 연결 수 값을 늘리세요:

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

      postgresql['max_connections'] = 600

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

      sudo gitlab-ctl reconfigure

  • 또는 PgBouncer를 사용하는 것을 고려할 수 있습니다. PgBouncer는 PostgreSQL을 위한 연결 풀러입니다.

Reconfigure에서 GLIBC 버전을 수정하려고 시도할 때 실패함 

$ gitlab-ctl reconfigure

/opt/gitlab/embedded/bin/ruby: /lib64/libc.so.6: 버전 `GLIBC_2.14'이(가) 없음 (필요한 버전: /opt/gitlab/embedded/lib/libruby.so.2.1에 의해)
/opt/gitlab/embedded/bin/ruby: /lib64/libc.so.6: 버전 `GLIBC_2.17'이(가) 없음 (필요한 버전: /opt/gitlab/embedded/lib/libruby.so.2.1에 의해)

이런 경우가 발생하는 경우는 설치한 omnibus 패키지가 서버의 운영 체제와 다른 운영 체제용으로 빌드된 경우입니다. 사용 중인 운영 체제에 맞는 올바른 Omnibus GitLab 패키지를 다운로드하고 설치했는지 다시 확인하세요.

Reconfigure에서 Git 사용자를 만들지 못한 경우

여기서 발생하는 경우는 Git 사용자로 sudo gitlab-ctl reconfigure를 실행한 경우입니다. 다른 사용자로 전환하세요.

더욱 중요한 것은 Git 사용자나 Omnibus GitLab에서 사용하는 다른 사용자에게 sudo 권한을 주지 않는 것입니다. 시스템 사용자에게 불필요한 권한을 부여하면 시스템의 보안이 약화됩니다.

sysctl로 커널 매개변수를 수정하지 못한 경우

sysctl이 커널 매개변수를 수정할 수 없는 경우 다음과 같은 스택 트레이스 오류가 발생할 수 있습니다: 

 * execute[sysctl] action run
================================================================================
Error executing action `run` on resource 'execute[sysctl]'
================================================================================


Mixlib::ShellOut::ShellCommandFailed
------------------------------------
Expected process to exit with [0], but received '255'
---- Begin output of /sbin/sysctl -p /etc/sysctl.conf ----

이는 가상화된 머신이 아닌 가상 사설 서버(VPS)에서 발생할 가능성이 있습니다. 이 문제의 권장 해결 방법은 호스트에서 필요한 모듈을 활성화하거나, 호스트 OS에서 /etc/sysctl.conf 파일에 필요한 값을 설정하고 호스트에서 cat /etc/sysctl.conf /etc/sysctl.d/*.conf | sysctl -e -p -를 실행한 후 가상 머신에서 gitlab-ctl reconfigure를 다시 실행하는 것입니다. 이를 통해 커널이 필요한 설정으로 실행 중임을 감지하고 오류를 발생시키지 않을 것입니다.

다른 줄에 대해 이 프로세스를 반복해야 할 수 있습니다. 예를 들어, /etc/sysctl.conf에 다음과 같은 내용을 추가한 후 reconfigure가 세 번 실패하는 경우: 

kernel.shmall = 4194304
kernel.sem = 250 32000 32 262
net.core.somaxconn = 2048
kernel.shmmax = 17179869184

Chef 출력의 마지막 줄보다 해당 라인을 찾는 것이 더 쉬울 수 있습니다. 

* file[create /opt/gitlab/embedded/etc/90-omnibus-gitlab-kernel.shmall.conf kernel.shmall] action create
  - create new file /opt/gitlab/embedded/etc/90-omnibus-gitlab-kernel.shmall.conf
  - update content in file /opt/gitlab/embedded/etc/90-omnibus-gitlab-kernel.shmall.conf from none to 6d765d
  --- /opt/gitlab/embedded/etc/90-omnibus-gitlab-kernel.shmall.conf 2017-11-28 19:09:46.864364952 +0000
  +++ /opt/gitlab/embedded/etc/.chef-90-omnibus-gitlab-kernel.shmall.conf kernel.shmall20171128-13622-sduqoj 2017-11-28 19:09:46.864364952 +0000
  @@ -1 +1,2 @@
  +kernel.shmall = 4194304

루트 액세스 없이 Omnibus GitLab을 설치할 수 없습니다

가끔 사람들이 루트 액세스 없이 GitLab을 설치할 수 있는지 물을 때가 있습니다. 이는 여러 가지 이유로 문제가 됩니다.

.deb 또는 .rpm 설치

우리의 알고 있는 바로는 Debian이나 RPM 패키지를 특권이 없는 사용자로 설치하는 깔끔한 방법은 없습니다. Omnibus GitLab RPM을 설치할 수 없습니다. Omnibus 빌드 프로세스는 소스 RPM을 생성하지 않기 때문입니다.

80 및 443 포트에서의 편리한 호스팅

GitLab을 배포하는 가장 흔한 방법은 웹 서버(NGINX/Apache)를 GitLab과 함께 동일한 서버에서 실행하고, 웹 서버가 특권이 필요한(1024 미만) TCP 포트에서 수신 대기하도록 하는 것입니다. Omnibus GitLab에서는 자동으로 구성된 NGINX 서비스를 번들로 제공하여 편리성을 제공하지만, 포트 80 및 443을 열기 위해 그 마스터 프로세스를 루트로 실행해야 합니다.

이것이 문제가 된다면, GitLab을 설치하는 관리자는 번들로 제공되는 NGINX 서비스를 비활성화할 수 있지만, 이로써 GitLab의 애플리케이션 업데이트 중에 NGINX 구성을 조율해야 하는 부담이 생깁니다.

Omnibus 서비스 간의 격리

Omnibus GitLab의 번들로 제공되는 서비스(GitLab 자체, NGINX, PostgreSQL, Redis, Mattermost)는 Unix 사용자 계정을 사용하여 서로 격리됩니다. 이러한 사용자 계정을 생성하고 관리하려면 루트 액세스가 필요합니다. 기본적으로 Omnibus GitLab은 gitlab-ctl reconfigure 중에 필요한 Unix 계정을 생성하지만, 이 동작을 비활성화할 수도 있습니다.

원칙적으로 Omnibus GitLab은 GitLab과 Mattermost 각각에 대해 2개의 사용자 계정으로 충분할 수 있습니다. 각 애플리케이션에 별도의 runit(runsvdir), PostgreSQL 및 Redis 프로세스를 제공한다면 될 것입니다. 그러나 이 작업은 gitlab-ctl reconfigure Chef 코드에 큰 변경이 필요하며, 기존의 Omnibus GitLab 설치에 대해 주요 업그레이드 문제를 야기할 수도 있습니다. (아마도 /var/opt/gitlab 하위의 디렉토리 구조를 재배열해야 할 것입니다.)

운영 체제 성능 향상을 위한 조정

gitlab-ctl reconfigure 중에는 PostgreSQL 성능을 개선하고 연결 제한을 늘리기 위해 여러 sysctl 조정을 설정하고 설치합니다. 이것은 오직 루트 액세스로만 수행할 수 있습니다.

gitlab-rake assets:precompile이 ‘권한 거부’로 실패합니다

일부 사용자들은 omnibus 패키지에서 gitlab-rake assets:precompile을 실행할 수 없다고 보고합니다. 이에 대한 간결한 답은: 그 명령을 실행하지 마십시오. 그것은 소스에서 GitLab을 설치하는 경우에만 해당되는 것입니다.

GitLab 웹 인터페이스는 CSS 및 JavaScript 파일, Ruby on Rails 용어로 ‘assets’라고 불리는 파일을 사용합니다. 이 다운스트림의 GitLab 저장소에서는 이러한 파일을 개발자 친화적인 방식으로 저장합니다. 일반적으로 GitLab의 사용자가 이러한 파일이 개발자 친화적인 형식으로 되어 있기를 원하지 않는데, 그 이유는 GitLab을 느리게 만들기 때문입니다. 이것이 rake assets:precompile 스크립트를 사용하여 애셋을 개발자 친화적인 형식에서 최종 사용자 친화적인(압축된, 빠른) 형식으로 변환하는 것이 GitLab 설정 프로세스의 일부입니다.

omnibus 패키지를 사용하여 GitLab을 설치하는 경우, 변환된 애셋이 이미 존재하기 때문에 rake assets:precompile을 실행할 필요가 없습니다. omnibus 패키지를 통해 GitLab을 설치할 때에는 이미 변환된 애셋이 포함되어 있기 때문입니다.

gitlab-rake assets:precompile이 권한 오류로 실패하는 경우, 보안적인 측면에서 그것이 올바른 이유로 실패합니다. 애셋을 쉽게 덮어쓸 수 없게 만드는 것은, 공격자가 GitLab 서버를 사용하여 악의적인 JavaScript 코드를 GitLab 서버의 방문자들에 대해 제공하는 것을 더 어렵게 만듭니다.

사용자 정의 JavaScript 또는 CSS 코드를 사용하여 GitLab을 실행하려면, 아마도 GitLab을 소스에서 실행하거나 자체 패키지를 빌드하는 것이 더 좋을 것입니다.

만약 실제로 무엇을 하는지 알고 있다면, 다음처럼 gitlab-rake gitlab:assets:compile을 실행할 수 있습니다. 

sudo NO_PRIVILEGE_DROP=true USE_DB=false gitlab-rake gitlab:assets:clean gitlab:assets:compile
# user and path might be different if you changed the defaults of
# user['username'], user['group'] and gitlab_rails['dir'] in gitlab.rb
sudo chown -R git:git /var/opt/gitlab/gitlab-rails/tmp/cache

‘Short read or OOM loading DB’ 오류

이전의 Redis 세션을 정리해 보세요.

Apt 오류 ‘The requested URL returned error: 403’

apt 리포지토리를 사용하여 GitLab을 설치하려고 시도할 때 다음과 유사한 오류가 발생하는 경우: 

W: Failed to fetch https://packages.gitlab.com/gitlab/gitlab-ce/DISTRO/dists/CODENAME/main/source/Sources  The requested URL returned error: 403

서버 앞에 리포지토리 캐쉬가 있는지 확인하십시오. 예를 들어 apt-cacher-ng와 같이.

apt-cacher-ng 구성에 다음 라인을 추가하십시오(예: /etc/apt-cacher-ng/acng.conf): 

PassThroughPattern: (packages\.gitlab\.com|packages-gitlab-com\.s3\.amazonaws\.com|*\.cloudfront\.net)

변경 내용이 필요한 이유 및 apt-cacher-ng에 대해 자세히 알아보려면 packagecloud 블로그를 참조하십시오.

자체 서명된 인증서 또는 사용자 지정 인증 기관 사용

사용자 지정 인증 기관을 사용하거나 자체 서명된 인증서를 사용하여 격리된 네트워크에 GitLab을 설치하는 경우, GitLab이 인증서에 액세스할 수 있는지 확인하십시오. 그렇지 않으면 GitLab이 GitLab Shell과 같은 내부 서비스에 연결하려고 할 때 다음과 같은 오류가 발생할 수 있습니다: 

Faraday::SSLError (SSL_connect returned=1 errno=0 state=SSLv3 read server certificate B: certificate verify failed)

이러한 오류를 수정하려면 사용자 정의 공개 인증서 설치 섹션을 참조하십시오.

error: proxyRoundTripper: XXX failed with: “net/http: timeout awaiting response headers”

GitLab Workhorse가 1분(default) 내에 GitLab에서 응답을 받지 못하면 502 페이지를 제공합니다.

요청이 시간 초과될 수 있는 여러 가지 이유가 있으며, 사용자가 매우 큰 차이 또는 유사한 내용을로드했을 수 있습니다.

기본 시간 초과 값을 /etc/gitlab/gitlab.rb에 설정하여 기본 시간 초과 값을 늘릴 수 있습니다. 

gitlab_workhorse['proxy_headers_timeout'] = "2m0s"

변경 사항이 적용되려면 파일을 저장하고 GitLab 재구성을 진행하십시오.

원하는 변경 사항이 거부되었습니다

아마도 GitLab이 사전에 설정된 기본 프록시 헤더가 환경에 맞지 않은 프록시가 앞에 있는 환경에서 설정되었습니다.

기본 헤더를 재정의하는 방법에 대한 자세한 내용은 NGINX 문서의 기본 프록시 헤더 변경 섹션을 참조하십시오.

CSRF 토큰의 정통성을 확인할 수 없습니다 Completed 422 Unprocessable

아마도 GitLab이 사전에 설정된 기본 프록시 헤더가 환경에 맞지 않은 프록시가 앞에 있는 환경에서 설정되었습니다.

기본 헤더를 재정의하는 방법에 대한 자세한 내용은 NGINX 문서의 기본 프록시 헤더 변경 섹션을 참조하십시오.

확장자가 pg_trgm인 누락

GitLab 8.6부터 GitLab은 PostgreSQL 확장자 pg_trgm이 필요합니다. 번들된 데이터베이스를 사용하는 Omnibus GitLab 패키지를 사용하는 경우, 업그레이드시 확장자가 자동으로 활성화될 것입니다.

그러나 외부(패키지가 아닌) 데이터베이스를 사용하는 경우, 확장자를 수동으로 활성화해야 합니다. 이는 Omnibus GitLab 패키지가 확장자가 존재하는지 확인할 방법이 없으며, 확장자를 활성화할 방법도 없기 때문입니다.

이 문제를 해결하려면 먼저 pg_trgm 확장자를 설치해야 합니다. 이 확장자는 postgresql-contrib 패키지에 있습니다. Debian의 경우: 

sudo apt-get install postgresql-contrib

확장자를 설치한 후, 슈퍼유저로 psql에 액세스하여 확장자를 활성화합니다.

  1. 슈퍼유저로 psql에 액세스: 

    sudo gitlab-psql -d gitlabhq_production

  2. 확장자 활성화: 

    CREATE EXTENSION pg_trgm;
\q

  3. 이제 마이그레이션을 다시 실행하십시오. 

    sudo gitlab-rake db:migrate

Docker를 사용하는 경우 먼저 컨테이너에 액세스한 다음 위의 명령을 실행한 후 컨테이너를 다시 시작해야 합니다.

  1. 컨테이너에 액세스: 

    docker exec -it gitlab bash

  2. 위의 명령을 실행합니다.

  3. 컨테이너를 다시 시작합니다: 

    docker restart gitlab

Errno::ENOMEM: 백업 또는 업그레이드 중 메모리 할당 불가

GitLab은 오류 없이 실행하려면 2GB의 사용 가능한 메모리가 필요합니다. 2GB의 메모리가 설치되어 있더라도 서버의 다른 프로세스의 리소스 사용량에 따라 충분하지 않을 수 있습니다. GitLab이 업그레이드나 백업을 실행하지 않을 때는 문제가 없다면 스왑을 추가하여 문제를 해결할 수 있습니다. 일반적인 사용 중에 서버가 스왑을 사용하는 것을 본다면 성능을 향상시키기 위해 더 많은 RAM을 추가할 수 있습니다.

NGINX 오류: ‘could not build server_names_hash, you should increase server_names_hash_bucket_size’

만약 GitLab의 외부 URL이 기본 버킷 크기(64바이트)보다 길면, NGINX는 작동을 중지하고 로그에 이러한 오류가 나타날 수 있습니다. 더 큰 서버 이름을 허용하려면 /etc/gitlab/gitlab.rb에서 버킷 크기를 두 배로 늘리세요: 

nginx['server_names_hash_bucket_size'] = 128

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

NFS root_squash로 인해 ‘root가 chown할 수 없음’으로 재구성 실패 

$ gitlab-ctl reconfigure

================================================================================
Error executing action `run` on resource 'ruby_block[directory resource: /gitlab-data/git-data]'
================================================================================

Errno::EPERM
------------
'root' cannot chown /gitlab-data/git-data. If using NFS mounts you will need to re-export them in 'no_root_squash' mode and try again.
Operation not permitted @ chown_internal - /gitlab-data/git-data

NFS로 마운트된 디렉토리가 있고 root_squash 모드로 구성된 경우에 발생할 수 있습니다. 재구성은 디렉토리의 소유권을 제대로 설정하지 못합니다. NFS 서버의 NFS 내보내기에서 no_root_squash를 사용하도록 전환하거나 저장소 디렉토리 관리 비활성화를 하고 권한을 직접 관리해야 합니다.

gitlab-runsvdir 시작되지 않음

이는 systemd를 사용하는 운영 체제에 해당합니다 (예: Ubuntu 18.04+, CentOS 등).

GitLab 11.2부터 gitlab-runsvdir은 multi-user.target 대신에 basic.target에서 시작됩니다. GitLab을 업그레이드한 후에 이 서비스를 시작하는 데 문제가 있는 경우, 시스템이 multi-user.target를 위해 필요한 서비스를 올바르게 부팅했는지 확인해야 할 수 있습니다. 이를 위해 다음 명령어를 통해 시스템이 모든 필요한 서비스를 제대로 부팅했는지 확인할 수 있습니다: 

systemctl -t target

모든 것이 제대로 작동하면, 출력은 다음과 같이 보일 것입니다: 

UNIT                   LOAD   ACTIVE SUB    DESCRIPTION
basic.target           loaded active active Basic System
cloud-config.target    loaded active active Cloud-config availability
cloud-init.target      loaded active active Cloud-init target
cryptsetup.target      loaded active active Encrypted Volumes
getty.target           loaded active active Login Prompts
graphical.target       loaded active active Graphical Interface
local-fs-pre.target    loaded active active Local File Systems (Pre)
local-fs.target        loaded active active Local File Systems
multi-user.target      loaded active active Multi-User System
network-online.target  loaded active active Network is Online
network-pre.target     loaded active active Network (Pre)
network.target         loaded active active Network
nss-user-lookup.target loaded active active User and Group Name Lookups
paths.target           loaded active active Paths
remote-fs-pre.target   loaded active active Remote File Systems (Pre)
remote-fs.target       loaded active active Remote File Systems
slices.target          loaded active active Slices
sockets.target         loaded active active Sockets
swap.target            loaded active active Swap
sysinit.target         loaded active active System Initialization
time-sync.target       loaded active active System Time Synchronized
timers.target          loaded active active Timers

LOAD   = Reflects whether the unit definition was properly loaded.
ACTIVE = The high-level unit activation state, i.e. generalization of SUB.
SUB    = The low-level unit activation state, values depend on unit type.

22 loaded units listed. Pass --all to see loaded but inactive units, too.
To show all installed unit files use 'systemctl list-unit-files'.

모든 줄이 loaded active active을 보여야합니다. 아래의 줄에서 보이는 것처럼 inactive dead를 본다면, 이는 문제가 있을 수 있다는 것을 의미합니다: 

multi-user.target      loaded inactive dead   start Multi-User System

systemd에 의해 대기 중인 작업이 있는지 확인하려면 다음을 실행하세요: 

systemctl list-jobs

running 작업이 보인다면, 서비스가 멈춰 있을 수 있으므로 GitLab의 시작을 차단할 수 있습니다. 예를 들어, 일부 사용자는 Plymouth가 시작되지 않는 문제가 있었습니다: 

  1 graphical.target                     start waiting
107 plymouth-quit-wait.service           start running
  2 multi-user.target                    start waiting
169 ureadahead-stop.timer                start waiting
121 gitlab-runsvdir.service              start waiting
151 system-getty.slice                   start waiting
 31 setvtrgb.service                     start waiting
122 systemd-update-utmp-runlevel.service start waiting

이 경우 Plymouth를 제거하는 것을 고려하세요.

비-Docker 컨테이너에서 init 데몬 감지

Docker 컨테이너에서는 GitLab 패키지가 /.dockerenv 파일의 존재를 감지하고 init 시스템의 자동 감지를 건너뛰게 됩니다. 그러나 비-Docker 컨테이너(예: containerd, cri-o 등)에서는 그 파일이 존재하지 않고 패키지가 sysvinit으로 되돌아가며 설치에 문제가 발생할 수 있습니다. 이를 방지하기 위해 사용자는 gitlab.rb 파일에 다음과 같은 설정을 추가하여 init 데몬 감지를 명시적으로 비활성화할 수 있습니다: 

package['detect_init'] = false

이 구성을 사용하는 경우, runsvdir-start 명령을 사용하여 gitlab-ctl reconfigure를 실행하기 전에 runit 서비스를 시작해야 합니다: 

/opt/gitlab/embedded/bin/runsvdir-start &

gitlab-ctl reconfigure이 AWS Cloudformation을 사용하는 동안 hang이 걸립니다.

기본적으로 GitLab systemd 유닛 파일은 After와 WantedBy 필드 모두에 대해 multi-user.target을 사용합니다. 이렇게 함으로써 서비스가 remote-fs 및 network 타겟 이후에 실행되고 따라서 GitLab이 올바르게 작동하도록 합니다.

그러나 이는 AWS Cloudformation에서 사용하는 cloud-init의 유닛 순서 지정과 상호작용이 잘못됩니다.

이를 해결하기 위해 사용자는 gitlab.rb의 package['systemd_wanted_by'] 및 package['systemd_after'] 설정을 활용하여 올바른 순서를 지정하고 sudo gitlab-ctl reconfigure를 실행해야 합니다. 다시구성이 완료되면 변경사항이 적용되도록 gitlab-runsvdir 서비스를 재시작해야 합니다. 

sudo systemctl restart gitlab-runsvdir

Errno::EAFNOSUPPORT: 프로토콜에서 지원하지 않는 주소 패밀리 - socket(2)

GitLab을 시작할 때, 다음과 유사한 오류가 발생하는 경우: 

FATAL: Errno::EAFNOSUPPORT: Address family not supported by protocol - socket(2)

사용 중인 호스트명이 해결되고 IPv4 주소가 반환되는지 확인하세요: 

getent hosts gitlab.example.com
# 예시 IPv4 출력: 192.168.1.1 gitlab.example.com
# 예시 IPv6 출력: 2002:c0a8:0101::c0a8:0101 gitlab.example.com

getent hosts localhost
# 예시 IPv4 출력: 127.0.0.1 localhost
# 예시 IPv6 출력: ::1 localhost

만약 IPv6 주소 형식이 반환된다면, 네트워크 인터페이스에서 IPv6 프로토콜 지원 (키워드 ipv6)이 활성화되어 있는지 추가로 확인하세요: 

ip addr # 또는 오래된 운영체제의 경우 'ifconfig'

IPv6 네트워크 프로토콜 지원이 없거나 비활성화되어 있는 경우, 하지만 DNS 구성이 호스트명을 IPv6 주소로 해결한다면, GitLab 서비스는 네트워크 연결을 설정할 수 없을 것입니다.

이를 해결하기 위해 DNS 구성 (또는 /etc/hosts)을 수정하여 호스트를 IPv6 대신 IPv4 주소로 해결하도록 해야 합니다.

URI::InvalidComponentError (bad component(expected host component: my_url.tld)에서 external_url에 언더스코어가 포함되어 있을 때

external_url에 언더스코어를 포함하여 설정한 경우 (예: https://my_company.example.com), CI/CD에 다음과 같은 문제가 발생할 수 있습니다:

  • 프로젝트의 Settings > CI/CD 페이지를 열 수 없을 것입니다.
  • 실행 중인 작업을 픽업하고 오류 500으로 실패하게 될 것입니다.

그런 경우, production.log에 다음과 같은 오류가 포함될 것입니다: 

Completed 500 Internal Server Error in 50ms (ActiveRecord: 4.9ms | Elasticsearch: 0.0ms | Allocations: 17672)

URI::InvalidComponentError (bad component(expected host component): my_url.tld):

lib/api/helpers/related_resources_helpers.rb:29:in `expose_url'
ee/app/controllers/ee/projects/settings/ci_cd_controller.rb:19:in `show'
ee/lib/gitlab/ip_address_state.rb:10:in `with'
ee/app/controllers/ee/application_controller.rb:44:in `set_current_ip_address'
app/controllers/application_controller.rb:486:in `set_current_admin'
lib/gitlab/session.rb:11:in `with_session'
app/controllers/application_controller.rb:477:in `set_session_storage'
lib/gitlab/i18n.rb:73:in `with_locale'
lib/gitlab/i18n.rb:79:in `with_user_locale'

일시적인 해결책으로는 external_url에서 언더스코어를 피하는 것입니다. 이에 관한 오픈 이슈가 있습니다: Setting external_url with underscore results in a broken GitLab CI/CD functionality.

timeout: run: /opt/gitlab/service/gitaly 오류로 인해 업그레이드가 실패하는 경우

패키지 업그레이드가 다음과 같은 오류와 함께 재구성 실행 시 실패하는 경우, 모든 Gitaly 프로세스가 중지되어 있는지 확인하고, 그 후에 sudo gitlab-ctl reconfigure를 다시 실행해야 합니다. 

---- Begin output of /opt/gitlab/embedded/bin/sv restart /opt/gitlab/service/gitaly ----
STDOUT: timeout: run: /opt/gitlab/service/gitaly: (pid 4886) 15030s, got TERM
STDERR:
---- End output of /opt/gitlab/embedded/bin/sv restart /opt/gitlab/service/gitaly ----
Ran /opt/gitlab/embedded/bin/sv restart /opt/gitlab/service/gitaly returned 1

자세한 내용은 이슈 341573를 참조하세요.

GitLab 다시 설치 중 재구성이 멈춘 경우

알려진 이슈로 인해 GitLab을 제거한 후 다시 설치하려고 할 때 ruby_block[wait for logrotate service socket] action run에서 재구성 프로세스가 멈춰 있는 것을 볼 수 있습니다. 이 문제는 GitLab을 삭제한 후 Linux 패키지 옴니버스를 다시 설치할 때 systemctl 명령 중 하나가 실행되지 않을 때 발생합니다.

이 문제를 해결하려면:

  • GitLab을 제거할 때 모든 단계를 따랐는지 확인하고 필요한 경우 실행합니다.
  • 이슈 7776의 해결책을 따릅니다.

Pulp 또는 Red Hat Satellite로 GitLab yum 리포지토리를 미러링하는 경우 실패

https://packages.gitlab.com/gitlab/에 위치한 Omnibus GitLab yum 리포지토리를 Pulp 또는 Red Hat Satellite로 직접 미러링하려고 할 때 동기화에 실패합니다. 서로 다른 소프트웨어에 의해 다양한 오류가 발생합니다:

  • Pulp 2 또는 Satellite 6.10 미만은 "Malformed repository: metadata is specified for different set of packages in filelists.xml and in other.xml" 오류로 실패합니다.
  • Satellite 6.10은 "pkgid" 오류로 실패합니다.
  • Pulp 3 또는 Satellite 6.10 이상은 성공하는 것으로 보이지만 리포지토리 메타데이터만 동기화됩니다.

이 동기화 실패는 GitLab yum 미러 리포지토리의 메타데이터 문제로 인해 발생합니다. 이 메타데이터에는 일반적으로 리포지토리의 각 RPM에 대한 파일 목록이 포함된 filelists.xml.gz 파일이 포함되어 있습니다. GitLab yum 리포지토리는 이 파일을 대부분 비어 둬서 파일이 완전히 채워지면 발생할 크기 문제를 해결하려고 합니다.

각 GitLab RPM에는 막대한 수의 파일이 포함되어 있으며, 리포지토리의 많은 RPM에 곱해지면 막대한 filelists.xml.gz 파일이 결과로 나올 것입니다. 저장 공간 및 빌드 제약으로 인해 파일을 생성하지만 채우지는 않습니다. 빈 파일은 Pulp 및 Pulp를 사용하는 RedHat Satellite 리포지토리 미러링에 실패시킵니다.

자세한 내용은 이슈 2766을 참조하세요.

문제 해결하기

이 문제를 해결하려면:

  1. reposync 또는 createrepo와 같은 대체 RPM 리포지토리 미러링 도구를 사용하여 공식 GitLab yum 리포지토리의 로컬 사본을 만듭니다. 이러한 도구는 로컬 데이터에 리포지토리 메타데이터를 다시 생성하며, 이는 완전히 채워진 filelists.xml.gz 파일을 생성하는 것을 포함합니다.
  2. Pulp 또는 Satellite를 로컬 미러를 가리키도록 설정합니다.

로컬 미러 예시

다음은 로컬 미러링을 수행하는 방법에 대한 예시입니다. 예시에서는 다음을 사용합니다:

  • 웹 서버로 Apache를 사용합니다.
  • reposync 및 createrepo를 사용하여 GitLab 리포지토리를 로컬 미러에 동기화합니다. 이 로컬 미러는 나중에 Pulp 또는 RedHat Satellite의 원본으로 사용할 수 있습니다. Cobbler와 같은 다른 도구도 사용할 수 있습니다.

이 예시에서:

  • 로컬 미러는 RHEL 8, Rocky 8, 또는 AlmaLinux 8 시스템에서 실행됩니다.
  • 웹 서버의 호스트 이름은 mirror.example.com입니다.
  • Pulp 3는 로컬 미러에서 동기화됩니다.
  • 미러링은 GitLab Enterprise Edition 리포지토리를 대상으로 합니다.

Apache 서버 만들고 구성하기

다음 예시는 기본 Apache 2 서버를 설치하고 구성하여 하나 이상의 Yum 리포지토리 미러를 호스트하는 방법을 보여줍니다. 웹 서버의 구성 및 보안 설정에 대한 자세한 내용은 Apache 문서를 참조하세요.

  1. httpd 설치: 

    sudo dnf install httpd

  2. /etc/httpd/conf/httpd.conf에 Directory 구문 추가: 

    <Directory “/var/www/html/repos“>
Options All Indexes FollowSymLinks
Require all granted
</Directory>

  3. httpd 구성 완료: 

    sudo rm -f /etc/httpd/conf.d/welcome.conf
sudo mkdir /var/www/html/repos
sudo systemctl enable httpd --now

미러링된 Yum 리포지토리 URL 가져오기

  1. GitLab 리포지토리 yum 구성 파일 설치: 

    curl "https://packages.gitlab.com/install/repositories/gitlab/gitlab-ee/script.rpm.sh" | sudo bash
sudo dnf config-manager --disable gitlab_gitlab-ee gitlab_gitlab-ee-source

  2. 리포지토리 URL 가져오기: 

    sudo dnf config-manager --dump gitlab_gitlab-ee | grep baseurl
baseurl = https://packages.gitlab.com/gitlab/gitlab-ee/el/8/x86_64

    baseurl의 내용을 로컬 미러의 소스로 사용합니다. 예를 들어, https://packages.gitlab.com/gitlab/gitlab-ee/el/8/x86_64입니다.

로컬 미러 생성하기

  1. createrepo 패키지를 설치합니다. 

    sudo dnf install createrepo

  2. reposync를 실행하여 RPM을 로컬 미러로 복사합니다. 

    sudo dnf reposync --arch x86_64 --repoid=gitlab_gitlab-ee --download-path=/var/www/html/repos --newest-only

    --newest-only 옵션은 최신 RPM만을 다운로드합니다. 이 옵션을 제외하면 리포지토리의 모든 RPM(약 1GB씩)이 다운로드됩니다.

  3. createrepo를 실행하여 리포지토리 메타데이터를 다시 생성합니다. 

    sudo createrepo -o /var/www/html/repos/gitlab_gitlab-ee /var/www/html/repos/gitlab_gitlab-ee

로컬 미러 리포지토리는 이제 http://mirror.example.com/repos/gitlab_gitlab-ee/에서 사용할 수 있어야 합니다.

로컬 미러 업데이트하기

로컬 미러는 주기적으로 업데이트되어야 새로운 GitLab 버전의 RPM을 얻을 수 있습니다. 이를 수행하는 한 가지 방법은 cron을 사용하는 것입니다.

다음 내용으로 /etc/cron.daily/sync-gitlab-mirror를 생성합니다. 

#!/bin/sh

dnf reposync --arch x86_64 --repoid=gitlab_gitlab-ee --download-path=/var/www/html/repos --newest-only --delete
createrepo -o /var/www/html/repos/gitlab_gitlab-ee /var/www/html/repos/gitlab_gitlab-ee

dnf reposync 명령어에서 사용된 --delete 옵션은 해당하는 GitLab 리포지토리에 더 이상 존재하지 않는 RPM을 로컬 미러에서 삭제합니다.

로컬 미러 사용하기

  1. Pulp repository와 remote를 생성합니다. 

    pulp rpm repository create --retain-package-versions=1 --name "gitlab-ee"
pulp rpm remote create --name gitlab-ee --url "http://mirror.example.com/repos/gitlab_gitlab-ee/" --policy immediate
pulp rpm repository update --name gitlab-ee --remote gitlab-ee

  2. 리포지토리를 동기화합니다. 

    pulp rpm repository sync --name gitlab-ee

    이 명령은 주기적으로 실행되어 GitLab 리포지토리의 변경 사항을 로컬 미러에 업데이트해야 합니다.

리포지토리를 동기화한 후, 해당 리포지토리를 사용할 수 있도록 게시 및 배포를 생성할 수 있습니다. 자세한 내용은 https://docs.pulpproject.org/pulp_rpm/을 참조하십시오.

에러: E: connection refused to d20rj4el6vkp4c.cloudfront.net 443

packages.gitlab.com의 패키지 리포지토리에 호스팅된 패키지를 설치할 때 클라이언트는 d20rj4el6vkp4c.cloudfront.net로의 리디렉션을 받고 이를 따를 것입니다. 공기 차단 환경의 서버는 다음과 같은 오류를 받을 수 있습니다: 

E: connection refused to d20rj4el6vkp4c.cloudfront.net 443

Failed to connect to d20rj4el6vkp4c.cloudfront.net port 443: Connection refused

이 문제를 해결하기 위해 세 가지 옵션이 있습니다:

  • 도메인을 허용할 수 있는 경우 방화벽 설정에 엔드포인트 d20rj4el6vkp4c.cloudfront.net를 추가합니다.
  • 도메인을 허용할 수 없는 경우 방화벽 설정에 CloudFront IP 주소 범위를 추가합니다. 이 목록은 변경될 수 있으므로 방화벽 설정과 동기화를 유지해야 합니다.
  • 패키지 파일을 수동으로 다운로드하여 서버에 업로드합니다.

net.core.somaxconn을 증가해야 할까요?

다음은 net.core.somaxconn 값이 너무 낮게 설정되었는지 확인하는 데 도움이 될 수 있습니다: 

$ netstat -ant | grep -c SYN_RECV
4

netstat -ant | grep -c SYN_RECV의 반환 값은 설정되지 않은 연결의 수입니다. 이 값이 net.core.somaxconn보다 크다면: 

$ sysctl net.core.somaxconn
net.core.somaxconn = 1024

이 값을 증가시키는 것이 권장되며, 이는 gitlab.rb의 puma['somaxconn'] 변수를 업데이트함으로써 수행할 수 있습니다.