Zoekt 문제 해결

요약

Zoekt를 사용할 때 다음과 같은 문제가 발생할 수 있습니다. 설정을 활성화하면 새 네임스페이스가 자동으로 인덱싱됩니다. Rails 콘솔 세션에서 다음을 확인할 수 있습니다: Zoekt가 활성화되지 않은 네임스페이스: 네임스페이스를 수동으로 인덱싱하려면 인덱싱 설정을 참조하세요.

Zoekt를 사용할 때 다음과 같은 문제가 발생할 수 있습니다. 예비 디버깅의 경우:

Zoekt 인프라 상태를 이해하려면 상태 확인 실행을 수행하세요.
gitlab-rake gitlab:zoekt:info Rake 태스크로 인덱싱 상태 확인을 하세요.

네임스페이스가 인덱싱되지 않음#

설정을 활성화하면 새 네임스페이스가 자동으로 인덱싱됩니다. 네임스페이스가 자동으로 인덱싱되지 않는 경우 Sidekiq 로그를 검사하여 작업이 처리되고 있는지 확인하세요. Search::Zoekt::SchedulingWorker는 네임스페이스 인덱싱을 담당합니다.

Rails 콘솔 세션에서 다음을 확인할 수 있습니다:

Zoekt가 활성화되지 않은 네임스페이스:

Namespace.group_namespaces.root_namespaces_without_zoekt_enabled_namespace

Zoekt 인덱스 상태:

Search::Zoekt::Index.all.pluck(:state, :namespace_id)

네임스페이스를 수동으로 인덱싱하려면 인덱싱 설정을 참조하세요.

오류: `SilentModeBlockedError`#

정확한 코드 검색을 실행하려고 할 때 SilentModeBlockedError가 발생할 수 있습니다. 이 문제는 GitLab 인스턴스에서 침묵 모드가 활성화된 경우 발생합니다.

이 문제를 해결하려면 침묵 모드가 비활성화되어 있는지 확인하세요.

오류: `connections to all backends failing`#

application_json.log에서 다음 오류가 발생할 수 있습니다:

connections to all backends failing; last error: UNKNOWN: ipv4:1.2.3.4:5678: Trying to connect an http1.x server

이 문제를 해결하려면 프록시를 사용하고 있는지 확인하세요. 프록시를 사용하는 경우 GitLab 서버의 IP 주소를 no_proxy로 설정하세요:

gitlab_rails['env'] = {
  "http_proxy" => "http://proxy.domain.com:1234",
  "https_proxy" => "http://proxy.domain.com:1234",
  "no_proxy" => ".domain.com,IP_OF_GITLAB_INSTANCE,127.0.0.1,localhost"
}

proxy.domain.com:1234는 프록시 인스턴스의 도메인과 포트입니다. IP_OF_GITLAB_INSTANCE는 GitLab 인스턴스의 공개 IP 주소를 가리킵니다.

ip a를 실행하고 다음 중 하나를 확인하여 이 정보를 얻을 수 있습니다:

해당 네트워크 인터페이스의 IP 주소
사용 중인 로드 밸런서의 공개 IP 주소

메모리 부족 오류#

Zoekt 노드는 검색 또는 인덱싱 중에 메모리가 부족해질 수 있습니다. 메모리 부족(OOM) 오류는 웹 서버에서 더 자주 발생합니다. 웹 서버는 검색이 처리될 때 인덱스 샤드를 물리적 메모리에 메모리 매핑하므로 상주 메모리는 인덱스 크기 및 쿼리 볼륨에 따라 증가합니다. OOM 오류의 증상과 필요한 복구 단계는 두 구성 요소 간에 다릅니다. 자세한 내용은 메모리 아키텍처를 참조하세요.

메모리 부족 이벤트 감지#

Kubernetes 배포의 경우 OOM 오류로 인해 컨테이너가 종료되었는지 확인하세요:

kubectl describe pod <your_pod_name> -n <your_namespace>

Last State 섹션에서 OOMKilled와 0이 아닌 Exit Code(보통 137)를 찾으세요:

Last State: Terminated
  Reason: OOMKilled
  Exit Code: 137

모든 Zoekt 포드에서 재시작 횟수도 확인할 수 있습니다:

kubectl get pods -n <your_namespace> -l app=gitlab-zoekt

포드의 높은 RESTARTS 횟수는 반복적인 OOM 종료를 나타냅니다. 레이블 셀렉터 app=gitlab-zoekt는 차트 버전이나 운영자 구성에 따라 다를 수 있습니다.

kube-state-metrics가 설치된 경우 Prometheus 또는 Grafana에서 다음 메트릭을 모니터링할 수 있습니다:

kube_pod_container_status_last_terminated_reason{reason="OOMKilled"}: OOM으로 종료된 포드.
kube_pod_container_status_waiting_reason{reason="CrashLoopBackOff"}: 크래시 루프에 있는 포드.
kube_pod_container_status_restarts_total: 컨테이너별 누적 재시작 횟수. 급격한 증가는 반복적인 크래시를 나타냅니다.

웹 서버는 포트 6070의 /metrics에서 process_resident_memory_bytes를 노출합니다. 웹 서버 포드를 직접 스크래핑하도록 Prometheus를 구성한 경우 이 메트릭을 사용하여 시간이 지남에 따라 웹 서버 상주 메모리 사용량을 모니터링할 수 있습니다.

VM 및 베어 메탈 배포의 경우 시스템 저널에서 OOM 이벤트를 확인하세요:

sudo journalctl -k | grep -i "oom\|killed process"

메모리 부족 이벤트에서 복구#

복구 단계는 어느 구성 요소가 OOM 오류를 경험하고 있는지에 따라 다릅니다.

인덱서 메모리 부족 오류#

인덱서가 OOM 오류로 반복적으로 종료되는 경우, 조사하는 동안 모든 노드의 새 인덱싱 작업을 중지하기 위해 전역 인덱싱을 일시 중지하세요:

gitlab-rake gitlab:zoekt:pause_indexing

또는 UI에서 인덱싱을 일시 중지하세요:

전제 조건:

관리자 액세스 권한.

오른쪽 상단에서 관리자를 선택하세요.
In the left sidebar, select Settings > Search.
정확한 코드 검색을 확장하세요.
인덱싱 일시 중지 확인란을 선택하세요.
변경 사항 저장을 선택하세요.

노드를 안정화한 후 인덱싱을 재개하세요:

gitlab-rake gitlab:zoekt:resume_indexing

웹 서버 메모리 부족 오류#

웹 서버가 OOM 오류로 반복적으로 종료되는 경우, 조사하는 동안 Zoekt 검색을 비활성화하세요. 이렇게 하면 인덱싱에 영향을 주지 않고 충돌하는 노드로의 검색 트래픽이 중지됩니다.

Warning

Zoekt 검색이 비활성화되면 코드 검색은 기본 검색 모드로 전환됩니다. Elasticsearch를 사용할 수 없는 경우 기본 검색 모드에서는 프로젝트 범위 코드 검색만 가능하며, 이로 인해 Gitaly의 부하가 증가합니다.

전제 조건:

관리자 액세스 권한.

오른쪽 상단에서 관리자를 선택하세요.
In the left sidebar, select Settings > Search.
정확한 코드 검색을 확장하세요.
검색 활성화 확인란을 해제하세요.
변경 사항 저장을 선택하세요.

노드를 안정화한 후 검색을 다시 활성화하세요:

오른쪽 상단에서 관리자를 선택하세요.
In the left sidebar, select Settings > Search.
정확한 코드 검색을 확장하세요.
검색 활성화 확인란을 선택하세요.
변경 사항 저장을 선택하세요.

메모리 압력 줄이기#

노드 크기가 올바르게 설정되어 있지만 여전히 메모리 압력을 경험하는 경우 다음 설정을 조정하여 메모리 사용량을 줄이세요.

병렬 인덱싱 프로세스 줄이기#

전제 조건:

관리자 액세스 권한.

피크 인덱서 메모리를 줄이려면 인덱싱 태스크당 병렬 프로세스 수를 낮추세요:

오른쪽 상단에서 관리자를 선택하세요.
In the left sidebar, select Settings > Search.
정확한 코드 검색을 확장하세요.
인덱싱 태스크당 병렬 프로세스 수를 1로 설정하세요.
변경 사항 저장을 선택하세요.

동시 인덱싱 태스크 줄이기#

전제 조건:

관리자 액세스 권한.

동시에 실행되는 인덱싱 태스크 수를 줄이려면 인덱싱 CPU 대 태스크 승수 값을 낮추세요:

오른쪽 상단에서 관리자를 선택하세요.
In the left sidebar, select Settings > Search.
정확한 코드 검색을 확장하세요.
인덱싱 CPU 대 태스크 승수 값을 낮추세요(예: 0.5로).
변경 사항 저장을 선택하세요.

강제 재인덱싱 확률 높이기#

Zoekt 웹 서버는 인덱스 샤드를 메모리 매핑합니다. 시간이 지남에 따라 증분 인덱싱은 많은 소규모 샤드를 누적하여 열린 mmap 핸들 수를 증가시킵니다. 강제 재인덱싱은 인덱스를 완전히 재구성하여 샤드를 더 적고 더 큰 파일로 통합하며, 이로 인해 메모리 오버헤드가 감소합니다.

전제 조건:

관리자 액세스 권한.

샤드 누적을 줄이려면 강제 재인덱싱 확률을 높이세요:

오른쪽 상단에서 관리자를 선택하세요.
In the left sidebar, select Settings > Search.
정확한 코드 검색을 확장하세요.
랜덤 강제 재인덱싱 확률(백분율) 값을 높이세요. 기본값은 0.25(0.25%)입니다. 예를 들어 인덱싱 태스크 100개 중 약 1개를 강제 재인덱싱하려면 1로 설정하세요.
변경 사항 저장을 선택하세요.

노드 크기 조정#

설정 조정으로 반복적인 OOM 이벤트가 해결되지 않는 경우 노드에 더 많은 메모리가 필요합니다. 인덱스 크기에 따른 메모리 할당 지침은 크기 조정 권장 사항을 참조하세요.

Kubernetes 배포의 경우 Helm 차트 values.yaml에서 메모리 요청 및 제한을 늘리세요. 메모리 제한이 디스크 계층에 대한 크기 조정 테이블의 값 이상인지 확인하세요.

VM 및 베어 메탈 배포의 경우 크기 조정 테이블에서 더 큰 인스턴스 유형으로 이전하거나 더 많은 머신에 인덱스를 분산하기 위해 추가 노드를 추가하세요.

크기 조정 후 상태 확인을 실행하여 노드가 복구되는지 확인하세요:

gitlab-rake gitlab:zoekt:health

Zoekt 노드 연결 확인#

Zoekt 노드가 올바르게 구성되고 연결되었는지 확인하려면 Rails 콘솔 세션에서:

구성된 Zoekt 노드의 총 수 확인:
```
Search::Zoekt::Node.count
```
온라인 노드 수 확인:
```
Search::Zoekt::Node.online.count
```

또는 gitlab:zoekt:info Rake 태스크를 사용할 수 있습니다.

온라인 노드 수가 구성된 노드 수보다 적거나 노드가 구성되어 있는데 0인 경우 GitLab과 Zoekt 노드 간에 연결 문제가 있을 수 있습니다.

Zoekt 연결 오류 디버그#

Zoekt와 연결 문제가 발생하는 경우 요청 흐름을 이해하고 아키텍처의 각 구성 요소를 체계적으로 확인하는 것이 중요합니다.

Zoekt 아키텍처#

Zoekt는 두 가지 모드로 작동할 수 있는 통합 바이너리(gitlab-zoekt)를 사용합니다:

Gitaly에서 저장소를 인덱싱하는 인덱서 모드
검색 요청을 제공하는 웹 서버 모드

기본 검색 흐름은:

GitLab Rails → Zoekt webserver

Helm 차트(Kubernetes) 배포의 경우 아키텍처에 로드 밸런싱을 위한 추가 게이트웨이 구성 요소가 포함됩니다:

GitLab Rails → external gateway (NGINX) → internal gateway (NGINX) → Zoekt webserver

이러한 게이트웨이 구성 요소는 내부 Zoekt 구성 요소가 아닌 Helm 차트 배포의 일부입니다. 여러 Zoekt 웹 서버 인스턴스에 요청을 분산하고 라우팅, 로드 밸런싱 및 선택적 TLS 종료를 처리하는 NGINX 프록시입니다.

Zoekt 아키텍처 설계에 대한 자세한 내용은 코드 검색에 Zoekt 사용을 참조하세요.

네트워크 도달 가능성 확인#

GitLab Rails 포드에서 Zoekt 게이트웨이에 접근할 수 있는지 확인하려면 상태 확인 실행:

gitlab-rake gitlab:zoekt:health

이 태스크는 Rails에서 Zoekt까지의 연결을 확인하고 전체 상태를 HEALTHY, DEGRADED 또는 UNHEALTHY로 보고합니다. 상태 확인이 실패하면 GitLab과 Zoekt 인프라 사이에 네트워크 연결 문제가 있을 수 있습니다.

노드 상태 및 구성을 확인하려면 다음 Rake 태스크를 실행하세요:

gitlab-rake gitlab:zoekt:info

URL을 포함한 자세한 노드 정보를 보려면 Rails 콘솔에서 다음 명령을 실행하세요:

# View all node attributes including URLs
Search::Zoekt::Node.all.map(&:attributes)

search_base_url은 Zoekt 웹 서버 또는 Kubernetes의 외부 게이트웨이를 가리켜야 합니다 (예: http://gitlab-zoekt:8080/).
index_base_url은 Zoekt 인덱서를 가리켜야 합니다.

검색 시 404 응답을 받으면 요청이 올바르게 라우팅되지 않을 수 있습니다. 이 오류는 네트워크 연결보다 게이트웨이 구성에 문제가 있음을 나타냅니다.

Zoekt 로그 모니터링#

Helm 차트(Kubernetes) 배포의 경우 Zoekt 구성 요소 로그를 모니터링하여 연결 문제를 식별하세요.

StatefulSet에는 세 개의 컨테이너가 있습니다:

# Monitor webserver logs (search requests from Rails)
kubectl logs -f statefulset/gitlab-zoekt -c zoekt-webserver -n your_namespace

# Monitor indexer logs (repository indexing)
kubectl logs -f statefulset/gitlab-zoekt -c zoekt-indexer -n your_namespace

# Monitor internal gateway logs (NGINX proxy between the external gateway and webserver)
kubectl logs -f statefulset/gitlab-zoekt -c zoekt-internal-gateway -n your_namespace

외부 게이트웨이 배포를 사용하는 경우 외부 게이트웨이 로그도 모니터링할 수 있습니다:

# Monitor external gateway logs (NGINX proxy for incoming requests from Rails)
kubectl logs -f deployment/gitlab-zoekt-gateway -c zoekt-external-gateway -n your_namespace

이 로그를 모니터링하는 동안 GitLab UI에서 테스트 검색을 실행하세요. 로그에 요청이 처리되는 것이 표시되어야 합니다. 로그에 요청이 나타나지 않으면 Rails와 Zoekt 간에 네트워크 라우팅 문제가 있을 수 있습니다.

UI에서 테스트 검색 실행#

Zoekt 로그를 모니터링하는 동안 GitLab UI에서 테스트 검색을 실행할 수 있습니다:

특정 노드에 대한 프로젝트에서 검색.
여러 노드를 쿼리하기 위해 그룹에서 검색.
모든 노드를 쿼리하기 위해 전역 검색.

검색이 실패하면 자세한 오류 메시지를 위해 Rails 애플리케이션 로그를 확인하세요:

# For installations that use the Linux package
tail -f /var/log/gitlab/gitlab-rails/application_json.log | grep -i zoekt

# For self-compiled installations
tail -f log/application_json.log | grep -i zoekt

GitLab과 Zoekt 인프라 간의 네트워크 문제를 나타낼 수 있는 연결 오류, 타임아웃 또는 인증 실패를 찾으세요.

포드 및 서비스 상태 확인#

Helm 차트(Kubernetes) 배포의 경우 Zoekt 포드 및 서비스 상태를 확인하세요:

# Check pod status
kubectl get pods -n your_namespace -l app=gitlab-zoekt

# Check `StatefulSet` status
kubectl get statefulset gitlab-zoekt -n your_namespace

# Check service endpoints
kubectl get endpoints gitlab-zoekt -n your_namespace

# Describe the service to see the configuration
kubectl describe service gitlab-zoekt -n your_namespace

모든 포드가 실행 중 상태이고 서비스에 유효한 엔드포인트가 있는지 확인하세요. 포드가 실행되지 않거나 엔드포인트가 없는 경우 Zoekt 배포에 구성 문제가 있을 수 있습니다.

배포 아키텍처에 대한 자세한 내용은 다음을 참조하세요:

오류: `TaskRequest responded with [401]`#

Zoekt 인덱서 로그에서 TaskRequest responded with [401]이 표시될 수 있습니다. 이 오류는 Zoekt 인덱서가 GitLab으로 인증하는 데 실패함을 나타냅니다.

이 문제를 해결하려면 gitlab-shell-secret이 올바르게 구성되어 GitLab 인스턴스와 Zoekt 인덱서 간에 일치하는지 확인하세요. 예를 들어 다음 명령의 출력이 gitlab.rb의 gitlab-shell-secret과 일치해야 합니다:

kubectl get secret gitlab-shell-secret -o jsonpath='{.data.secret}' -n your_zoekt_namespace | base64 -d

오류: `missing selected ALPN property`#

Zoekt 게이트웨이 앞에 외부 로드 밸런서를 사용하는 경우 GitLab 로그에서 다음 오류가 표시될 수 있습니다:

rpc error: code = Unavailable desc = connection error: desc = "transport: authentication handshake failed: credentials: cannot check peer: missing selected ALPN property"

이 오류는 로드 밸런서가 HTTP/2와 함께 ALPN(Application-Layer Protocol Negotiation)을 지원하거나 광고하지 않을 때 발생합니다. Zoekt는 HTTP/2 지원이 필요한 gRPC를 노드 간 통신에 사용합니다.

이 문제를 해결하려면 다음 중 하나를 수행하세요:

로드 밸런서에서 HTTP/2 지원 활성화(권장):
1. ALPN을 통해 HTTP/2를 지원하고 광고하도록 로드 밸런서를 구성하세요:
  - HAProxy의 경우 백엔드에서 alpn h2,http/1.1이 구성되어 있는지 확인하세요.
  - NGINX의 경우 서버 블록에서 다음을 사용하세요:
    - NGINX 1.25.1 이상: http2 on;.
    - NGINX 1.25.0 이하: listen 443 ssl http2;.
2. HTTP/2 지원 확인:
```
curl --verbose --http2 "https://your-zoekt-gateway-url/health" 2>&1 | grep ALPN
```
  다음과 유사한 출력이 표시되어야 합니다:
```
* ALPN, server accepted to use h2
```
TLS 패스스루 사용:

로드 밸런서가 HTTP/2를 지원할 수 없는 경우 TLS 패스스루를 위해 밸런서를 구성하세요. 그런 다음 Zoekt 게이트웨이가 TLS 종료를 직접 처리하여 적절한 ALPN 협상을 보장할 수 있습니다. TLS 패스스루를 사용하려면 Zoekt 게이트웨이에 유효한 TLS 인증서를 구성하세요:
1. Helm 차트 배포의 경우 values.yaml에서 인증서를 구성하세요:
```
gateway:
  tls:
    certificate:
      enabled: true
      secretName: zoekt-gateway-cert
```
2. 로드 밸런서를 TLS를 종료하지 않고 암호화된 트래픽을 통과시키도록 구성하세요.

Zoekt 문제 해결

Tier: Premium, Ultimate
Offering: GitLab.com, GitLab Self-Managed

원문 보기

번역일: 2026-05-22

요약

Zoekt를 사용할 때 다음과 같은 문제가 발생할 수 있습니다. 예비 디버깅의 경우:

Zoekt 인프라 상태를 이해하려면 상태 확인 실행을 수행하세요.
gitlab-rake gitlab:zoekt:info Rake 태스크로 인덱싱 상태 확인을 하세요.

네임스페이스가 인덱싱되지 않음#

Rails 콘솔 세션에서 다음을 확인할 수 있습니다:

Zoekt가 활성화되지 않은 네임스페이스:

Namespace.group_namespaces.root_namespaces_without_zoekt_enabled_namespace

Zoekt 인덱스 상태:

Search::Zoekt::Index.all.pluck(:state, :namespace_id)

네임스페이스를 수동으로 인덱싱하려면 인덱싱 설정을 참조하세요.

오류: `SilentModeBlockedError`#

이 문제를 해결하려면 침묵 모드가 비활성화되어 있는지 확인하세요.

오류: `connections to all backends failing`#

application_json.log에서 다음 오류가 발생할 수 있습니다:

connections to all backends failing; last error: UNKNOWN: ipv4:1.2.3.4:5678: Trying to connect an http1.x server

이 문제를 해결하려면 프록시를 사용하고 있는지 확인하세요. 프록시를 사용하는 경우 GitLab 서버의 IP 주소를 no_proxy로 설정하세요:

gitlab_rails['env'] = {
  "http_proxy" => "http://proxy.domain.com:1234",
  "https_proxy" => "http://proxy.domain.com:1234",
  "no_proxy" => ".domain.com,IP_OF_GITLAB_INSTANCE,127.0.0.1,localhost"
}

proxy.domain.com:1234는 프록시 인스턴스의 도메인과 포트입니다. IP_OF_GITLAB_INSTANCE는 GitLab 인스턴스의 공개 IP 주소를 가리킵니다.

ip a를 실행하고 다음 중 하나를 확인하여 이 정보를 얻을 수 있습니다:

해당 네트워크 인터페이스의 IP 주소
사용 중인 로드 밸런서의 공개 IP 주소

메모리 부족 오류#

메모리 부족 이벤트 감지#

Kubernetes 배포의 경우 OOM 오류로 인해 컨테이너가 종료되었는지 확인하세요:

kubectl describe pod <your_pod_name> -n <your_namespace>

Last State 섹션에서 OOMKilled와 0이 아닌 Exit Code(보통 137)를 찾으세요:

Last State: Terminated
  Reason: OOMKilled
  Exit Code: 137

모든 Zoekt 포드에서 재시작 횟수도 확인할 수 있습니다:

kubectl get pods -n <your_namespace> -l app=gitlab-zoekt

포드의 높은 RESTARTS 횟수는 반복적인 OOM 종료를 나타냅니다. 레이블 셀렉터 app=gitlab-zoekt는 차트 버전이나 운영자 구성에 따라 다를 수 있습니다.

kube-state-metrics가 설치된 경우 Prometheus 또는 Grafana에서 다음 메트릭을 모니터링할 수 있습니다:

kube_pod_container_status_last_terminated_reason{reason="OOMKilled"}: OOM으로 종료된 포드.
kube_pod_container_status_waiting_reason{reason="CrashLoopBackOff"}: 크래시 루프에 있는 포드.
kube_pod_container_status_restarts_total: 컨테이너별 누적 재시작 횟수. 급격한 증가는 반복적인 크래시를 나타냅니다.

VM 및 베어 메탈 배포의 경우 시스템 저널에서 OOM 이벤트를 확인하세요:

sudo journalctl -k | grep -i "oom\|killed process"

메모리 부족 이벤트에서 복구#

복구 단계는 어느 구성 요소가 OOM 오류를 경험하고 있는지에 따라 다릅니다.

인덱서 메모리 부족 오류#

인덱서가 OOM 오류로 반복적으로 종료되는 경우, 조사하는 동안 모든 노드의 새 인덱싱 작업을 중지하기 위해 전역 인덱싱을 일시 중지하세요:

gitlab-rake gitlab:zoekt:pause_indexing

또는 UI에서 인덱싱을 일시 중지하세요:

전제 조건:

관리자 액세스 권한.

오른쪽 상단에서 관리자를 선택하세요.
In the left sidebar, select Settings > Search.
정확한 코드 검색을 확장하세요.
인덱싱 일시 중지 확인란을 선택하세요.
변경 사항 저장을 선택하세요.

노드를 안정화한 후 인덱싱을 재개하세요:

gitlab-rake gitlab:zoekt:resume_indexing

웹 서버 메모리 부족 오류#

Warning

전제 조건:

관리자 액세스 권한.

오른쪽 상단에서 관리자를 선택하세요.
In the left sidebar, select Settings > Search.
정확한 코드 검색을 확장하세요.
검색 활성화 확인란을 해제하세요.
변경 사항 저장을 선택하세요.

노드를 안정화한 후 검색을 다시 활성화하세요:

오른쪽 상단에서 관리자를 선택하세요.
In the left sidebar, select Settings > Search.
정확한 코드 검색을 확장하세요.
검색 활성화 확인란을 선택하세요.
변경 사항 저장을 선택하세요.

메모리 압력 줄이기#

노드 크기가 올바르게 설정되어 있지만 여전히 메모리 압력을 경험하는 경우 다음 설정을 조정하여 메모리 사용량을 줄이세요.

병렬 인덱싱 프로세스 줄이기#

전제 조건:

관리자 액세스 권한.

피크 인덱서 메모리를 줄이려면 인덱싱 태스크당 병렬 프로세스 수를 낮추세요:

오른쪽 상단에서 관리자를 선택하세요.
In the left sidebar, select Settings > Search.
정확한 코드 검색을 확장하세요.
인덱싱 태스크당 병렬 프로세스 수를 1로 설정하세요.
변경 사항 저장을 선택하세요.

동시 인덱싱 태스크 줄이기#

전제 조건:

관리자 액세스 권한.

동시에 실행되는 인덱싱 태스크 수를 줄이려면 인덱싱 CPU 대 태스크 승수 값을 낮추세요:

오른쪽 상단에서 관리자를 선택하세요.
In the left sidebar, select Settings > Search.
정확한 코드 검색을 확장하세요.
인덱싱 CPU 대 태스크 승수 값을 낮추세요(예: 0.5로).
변경 사항 저장을 선택하세요.

강제 재인덱싱 확률 높이기#

전제 조건:

관리자 액세스 권한.

샤드 누적을 줄이려면 강제 재인덱싱 확률을 높이세요:

오른쪽 상단에서 관리자를 선택하세요.
In the left sidebar, select Settings > Search.
정확한 코드 검색을 확장하세요.
랜덤 강제 재인덱싱 확률(백분율) 값을 높이세요. 기본값은 0.25(0.25%)입니다. 예를 들어 인덱싱 태스크 100개 중 약 1개를 강제 재인덱싱하려면 1로 설정하세요.
변경 사항 저장을 선택하세요.

노드 크기 조정#

크기 조정 후 상태 확인을 실행하여 노드가 복구되는지 확인하세요:

gitlab-rake gitlab:zoekt:health

Zoekt 노드 연결 확인#

Zoekt 노드가 올바르게 구성되고 연결되었는지 확인하려면 Rails 콘솔 세션에서:

구성된 Zoekt 노드의 총 수 확인:
```
Search::Zoekt::Node.count
```
온라인 노드 수 확인:
```
Search::Zoekt::Node.online.count
```

또는 gitlab:zoekt:info Rake 태스크를 사용할 수 있습니다.

온라인 노드 수가 구성된 노드 수보다 적거나 노드가 구성되어 있는데 0인 경우 GitLab과 Zoekt 노드 간에 연결 문제가 있을 수 있습니다.

Zoekt 연결 오류 디버그#

Zoekt와 연결 문제가 발생하는 경우 요청 흐름을 이해하고 아키텍처의 각 구성 요소를 체계적으로 확인하는 것이 중요합니다.

Zoekt 아키텍처#

Zoekt는 두 가지 모드로 작동할 수 있는 통합 바이너리(gitlab-zoekt)를 사용합니다:

Gitaly에서 저장소를 인덱싱하는 인덱서 모드
검색 요청을 제공하는 웹 서버 모드

기본 검색 흐름은:

GitLab Rails → Zoekt webserver

Helm 차트(Kubernetes) 배포의 경우 아키텍처에 로드 밸런싱을 위한 추가 게이트웨이 구성 요소가 포함됩니다:

GitLab Rails → external gateway (NGINX) → internal gateway (NGINX) → Zoekt webserver

Zoekt 아키텍처 설계에 대한 자세한 내용은 코드 검색에 Zoekt 사용을 참조하세요.

네트워크 도달 가능성 확인#

GitLab Rails 포드에서 Zoekt 게이트웨이에 접근할 수 있는지 확인하려면 상태 확인 실행:

gitlab-rake gitlab:zoekt:health

노드 상태 및 구성을 확인하려면 다음 Rake 태스크를 실행하세요:

gitlab-rake gitlab:zoekt:info

URL을 포함한 자세한 노드 정보를 보려면 Rails 콘솔에서 다음 명령을 실행하세요:

# View all node attributes including URLs
Search::Zoekt::Node.all.map(&:attributes)

search_base_url은 Zoekt 웹 서버 또는 Kubernetes의 외부 게이트웨이를 가리켜야 합니다 (예: http://gitlab-zoekt:8080/).
index_base_url은 Zoekt 인덱서를 가리켜야 합니다.

Zoekt 로그 모니터링#

Helm 차트(Kubernetes) 배포의 경우 Zoekt 구성 요소 로그를 모니터링하여 연결 문제를 식별하세요.

StatefulSet에는 세 개의 컨테이너가 있습니다:

# Monitor webserver logs (search requests from Rails)
kubectl logs -f statefulset/gitlab-zoekt -c zoekt-webserver -n your_namespace

# Monitor indexer logs (repository indexing)
kubectl logs -f statefulset/gitlab-zoekt -c zoekt-indexer -n your_namespace

# Monitor internal gateway logs (NGINX proxy between the external gateway and webserver)
kubectl logs -f statefulset/gitlab-zoekt -c zoekt-internal-gateway -n your_namespace

외부 게이트웨이 배포를 사용하는 경우 외부 게이트웨이 로그도 모니터링할 수 있습니다:

# Monitor external gateway logs (NGINX proxy for incoming requests from Rails)
kubectl logs -f deployment/gitlab-zoekt-gateway -c zoekt-external-gateway -n your_namespace

UI에서 테스트 검색 실행#

Zoekt 로그를 모니터링하는 동안 GitLab UI에서 테스트 검색을 실행할 수 있습니다:

특정 노드에 대한 프로젝트에서 검색.
여러 노드를 쿼리하기 위해 그룹에서 검색.
모든 노드를 쿼리하기 위해 전역 검색.

검색이 실패하면 자세한 오류 메시지를 위해 Rails 애플리케이션 로그를 확인하세요:

# For installations that use the Linux package
tail -f /var/log/gitlab/gitlab-rails/application_json.log | grep -i zoekt

# For self-compiled installations
tail -f log/application_json.log | grep -i zoekt

GitLab과 Zoekt 인프라 간의 네트워크 문제를 나타낼 수 있는 연결 오류, 타임아웃 또는 인증 실패를 찾으세요.

포드 및 서비스 상태 확인#

Helm 차트(Kubernetes) 배포의 경우 Zoekt 포드 및 서비스 상태를 확인하세요:

# Check pod status
kubectl get pods -n your_namespace -l app=gitlab-zoekt

# Check `StatefulSet` status
kubectl get statefulset gitlab-zoekt -n your_namespace

# Check service endpoints
kubectl get endpoints gitlab-zoekt -n your_namespace

# Describe the service to see the configuration
kubectl describe service gitlab-zoekt -n your_namespace

배포 아키텍처에 대한 자세한 내용은 다음을 참조하세요:

오류: `TaskRequest responded with [401]`#

Zoekt 인덱서 로그에서 TaskRequest responded with [401]이 표시될 수 있습니다. 이 오류는 Zoekt 인덱서가 GitLab으로 인증하는 데 실패함을 나타냅니다.

kubectl get secret gitlab-shell-secret -o jsonpath='{.data.secret}' -n your_zoekt_namespace | base64 -d

오류: `missing selected ALPN property`#

Zoekt 게이트웨이 앞에 외부 로드 밸런서를 사용하는 경우 GitLab 로그에서 다음 오류가 표시될 수 있습니다:

rpc error: code = Unavailable desc = connection error: desc = "transport: authentication handshake failed: credentials: cannot check peer: missing selected ALPN property"

이 문제를 해결하려면 다음 중 하나를 수행하세요:

로드 밸런서에서 HTTP/2 지원 활성화(권장):
1. ALPN을 통해 HTTP/2를 지원하고 광고하도록 로드 밸런서를 구성하세요:
  - HAProxy의 경우 백엔드에서 alpn h2,http/1.1이 구성되어 있는지 확인하세요.
  - NGINX의 경우 서버 블록에서 다음을 사용하세요:
    - NGINX 1.25.1 이상: http2 on;.
    - NGINX 1.25.0 이하: listen 443 ssl http2;.
2. HTTP/2 지원 확인:
```
curl --verbose --http2 "https://your-zoekt-gateway-url/health" 2>&1 | grep ALPN
```
  다음과 유사한 출력이 표시되어야 합니다:
```
* ALPN, server accepted to use h2
```
TLS 패스스루 사용:

로드 밸런서가 HTTP/2를 지원할 수 없는 경우 TLS 패스스루를 위해 밸런서를 구성하세요. 그런 다음 Zoekt 게이트웨이가 TLS 종료를 직접 처리하여 적절한 ALPN 협상을 보장할 수 있습니다. TLS 패스스루를 사용하려면 Zoekt 게이트웨이에 유효한 TLS 인증서를 구성하세요:
1. Helm 차트 배포의 경우 values.yaml에서 인증서를 구성하세요:
```
gateway:
  tls:
    certificate:
      enabled: true
      secretName: zoekt-gateway-cert
```
2. 로드 밸런서를 TLS를 종료하지 않고 암호화된 트래픽을 통과시키도록 구성하세요.

Zoekt 문제 해결

네임스페이스가 인덱싱되지 않음#

오류: SilentModeBlockedError#

오류: connections to all backends failing#

메모리 부족 오류#

메모리 부족 이벤트 감지#

메모리 부족 이벤트에서 복구#

인덱서 메모리 부족 오류#

웹 서버 메모리 부족 오류#

메모리 압력 줄이기#

병렬 인덱싱 프로세스 줄이기#

동시 인덱싱 태스크 줄이기#

강제 재인덱싱 확률 높이기#

노드 크기 조정#

Zoekt 노드 연결 확인#

Zoekt 연결 오류 디버그#

Zoekt 아키텍처#

네트워크 도달 가능성 확인#

Zoekt 로그 모니터링#

UI에서 테스트 검색 실행#

포드 및 서비스 상태 확인#

오류: TaskRequest responded with [401]#

오류: missing selected ALPN property#

네임스페이스가 인덱싱되지 않음#

오류: SilentModeBlockedError#

오류: connections to all backends failing#

메모리 부족 오류#

메모리 부족 이벤트 감지#

메모리 부족 이벤트에서 복구#

인덱서 메모리 부족 오류#

웹 서버 메모리 부족 오류#

메모리 압력 줄이기#

병렬 인덱싱 프로세스 줄이기#

동시 인덱싱 태스크 줄이기#

강제 재인덱싱 확률 높이기#

노드 크기 조정#

Zoekt 노드 연결 확인#

Zoekt 연결 오류 디버그#

Zoekt 아키텍처#

네트워크 도달 가능성 확인#

Zoekt 로그 모니터링#

UI에서 테스트 검색 실행#

포드 및 서비스 상태 확인#

오류: TaskRequest responded with [401]#

오류: missing selected ALPN property#

오류: `SilentModeBlockedError`#

오류: `connections to all backends failing`#

오류: `TaskRequest responded with [401]`#

오류: `missing selected ALPN property`#

오류: `SilentModeBlockedError`#

오류: `connections to all backends failing`#

오류: `TaskRequest responded with [401]`#

오류: `missing selected ALPN property`#