Zoekt는 코드를 검색하기 위해 특별히 설계된 오픈 소스 검색 엔진입니다.

이 통합을 사용하면 GitLab에서 코드를 검색할 때 고급 검색 대신 정확한 코드 검색을 사용할 수 있습니다. 그룹이나 저장소에서 코드를 검색하기 위해 정확한 일치 및 정규 표현식 모드를 사용할 수 있습니다.

버전 호환성#

각 GitLab 버전에는 특정 gitlab-zoekt-indexer 및 gitlab-zoekt 차트 버전이 포함되어 있습니다.

Zoekt 설치#

사전 요구 사항:

• 관리자 액세스.

GitLab에서 정확한 코드 검색을 활성화하려면 인스턴스에 연결된 Zoekt 노드가 최소 하나 이상 있어야 합니다. Zoekt에 대해 지원되는 설치 방법은 다음과 같습니다:

• Zoekt 차트 (독립 실행형 차트 또는 GitLab Helm 차트의 서브차트)
• GitLab Operator (gitlab-zoekt.install=true 사용)

다음 설치 방법은 프로덕션 사용이 아닌 테스트용입니다:

• Docker Compose
• Ansible 플레이북

정확한 코드 검색 활성화#

GitLab UI에서#

사전 요구 사항:

• 관리자 액세스.
• Zoekt 설치.

GitLab UI에서 정확한 코드 검색을 활성화하려면:

1. 오른쪽 상단 모서리에서 관리를 선택하세요.
2. In the left sidebar, select Settings > Search.
3. 정확한 코드 검색을 확장하세요.
4. 인덱싱 활성화 및 검색 활성화 체크박스를 선택하세요.
5. 변경 사항 저장을 선택하세요.

Rake 태스크 사용#

사전 요구 사항:

• 관리자 액세스.
• Zoekt 설치.

Rake 태스크로 정확한 코드 검색을 관리할 수 있습니다.

인덱싱 및 검색 활성화#

인덱싱 및 검색을 활성화하려면 다음 Rake 태스크를 실행하세요:

gitlab-rake gitlab:zoekt:index

이 태스크는 zoekt_indexing_enabled, zoekt_search_enabled, zoekt_auto_index_root_namespace를 활성화합니다. RolloutWorker가 모든 루트 네임스페이스를 자동으로 인덱싱하고 인덱스가 준비되면 검색을 사용할 수 있습니다.

인덱싱 및 검색 비활성화#

인덱싱 및 검색을 비활성화하려면 다음 Rake 태스크를 실행하세요:

gitlab-rake gitlab:zoekt:disable

이 태스크는 zoekt_indexing_enabled 및 zoekt_search_enabled 모두 비활성화합니다.

인덱싱 일시 중지 및 재개#

인덱싱을 일시 중지하려면(예: 유지 보수 중) 다음 Rake 태스크를 실행하세요:

gitlab-rake gitlab:zoekt:pause_indexing

인덱싱을 재개하려면 다음 Rake 태스크를 실행하세요:

gitlab-rake gitlab:zoekt:resume_indexing

저장소 요구 사항 추정#

Zoekt 노드에 필요한 저장소를 추정하려면 다음 Rake 태스크를 실행하세요:

sudo gitlab-rake gitlab:zoekt:estimate_storage

자세한 내용은 저장소 요구 사항 추정을 참조하세요.

인덱싱 상태 확인#

사전 요구 사항:

• 관리자 액세스.

인덱싱 성능은 Zoekt 인덱서 노드의 CPU 및 메모리 제한에 따라 다릅니다. 인덱싱 상태를 확인하려면:

gitlab-rake gitlab:zoekt:info

gitlab-rake "gitlab:zoekt:info[10]"

Search::Zoekt::Index.group(:state).count
Search::Zoekt::Repository.group(:state).count
Search::Zoekt::Task.group(:state).count

샘플 출력#

gitlab:zoekt:info Rake 태스크는 다음과 유사한 출력을 반환합니다:

Exact Code Search
GitLab version:                                      19.0.0
Enable indexing:                                     yes
Enable searching:                                    yes
Pause indexing:                                      no
Index root namespaces automatically:                 yes
Cache search results for five minutes:               yes
Indexing CPU to tasks multiplier:                    1.0
Probability of random force reindexing (percentage): 0.25
Number of parallel processes per indexing task:      1
Number of namespaces per indexing rollout:           32
Offline nodes automatically deleted after:           20m
Indexing timeout per project:                        30m
Maximum number of files per project to be indexed:   500000
Maximum file size for indexing:                      1MB
Maximum trigrams per file:                           20000
Retry interval for failed namespaces:                1d
Number of replicas per namespace:                    1
Maximum projects for legacy search:                  1000

Nodes
# Number of Zoekt nodes and their status
Node count:                   2 (online: 2, offline: 0)
Last seen at:                 2026-04-16 22:58:09 UTC (less than a minute ago)
Max schema_version:           2601
Storage reserved / usable:    71.1 MiB / 124 GiB (0.06%)
Storage indexed / reserved:   42.7 MiB / 71.1 MiB (60.0%)
Storage used / total:         797 GiB / 921 GiB (86.54%)
Online node watermark levels: 2
  - low: 2

Indexing status
Group count:                      8
# Number of enabled namespaces and their status
EnabledNamespace count:           8 (without indices: 0, rollout blocked: 0, with search disabled: 0)
Replicas count:                   8
  - ready: 8
Indices count:                    8
  - ready: 8
Indices watermark levels:         8
  - healthy: 8
Repositories count:               10
  - ready: 10
Tasks count:                      10
  - done: 10
Tasks pending/processing by type: (none)

Feature Flags (Non-Default Values)
- zoekt_offset_pagination:      disabled

Storage buffer factor:            0.831× [dynamic (observed)]
Feature Flags (Non-Default Values)
- zoekt_batch_update_index_storage_bytes:  disabled
- zoekt_cap_file_match_results:            disabled

Node Details
Node 1 - test-zoekt-hostname-1:
  Status:                       Online
  Last seen at:                 2026-04-16 22:58:09 UTC (less than a minute ago)
  Disk utilization:             86.54%
  Unclaimed storage:            62 GiB
  # Zoekt build version on the node. Must match GitLab version.
  Zoekt version:                2026.04.15-v1.4.0-1-g89a8871
  Schema version:               2601
Node 2 - test-zoekt-hostname-2:
  Status:                       Online
  Last seen at:                 2026-04-16 22:58:09 UTC (less than a minute ago)
  Disk utilization:             86.54%
  Unclaimed storage:            62 GiB
  Zoekt version:                2026.04.15-v1.4.0-1-g89a8871
  Schema version:               2601

상태 확인 실행#

사전 요구 사항:

• 관리자 액세스.

다음을 포함한 Zoekt 인프라 상태를 이해하기 위해 상태 확인을 실행하세요:

• 온라인 및 오프라인 노드
• 인덱싱 및 검색 설정
• 검색 API 엔드포인트
• JSON 웹 토큰 생성

상태 확인을 실행하려면 다음 태스크를 실행하세요:

gitlab-rake gitlab:zoekt:health

이 태스크는 다음을 제공합니다:

• 전체 상태: HEALTHY, DEGRADED 또는 UNHEALTHY
• 감지된 문제 해결을 위한 권장 사항
• 자동화 및 모니터링 통합을 위한 종료 코드: 0=healthy, 1=degraded 또는 2=unhealthy

자동으로 확인 실행#

10초마다 자동으로 상태 확인을 실행하려면 다음 태스크를 실행하세요:

gitlab-rake "gitlab:zoekt:health[10]"

출력에는 색상 상태 표시기가 포함되며 다음을 표시합니다:

• 온라인 및 오프라인 노드 수, 저장소 사용 경고 및 연결 문제
• 코어 설정 검증 및 네임스페이스와 저장소 인덱싱 상태
• 종합 상태 평가를 포함한 전체 상태: HEALTHY, DEGRADED 또는 UNHEALTHY
• 문제 해결을 위한 권장 사항

프로젝트 강제 재인덱싱#

사전 요구 사항:

• 관리자 액세스.

프로젝트 범위를 강제로 재인덱싱하려면 다음 Rake 태스크를 실행합니다:

gitlab-rake gitlab:zoekt:reindex_projects ID_FROM=10 ID_TO=20

ID_FROM 및 ID_TO는 프로젝트 ID 범위를 나타냅니다.

단일 프로젝트만 강제로 재인덱싱하려면 ID_FROM과 ID_TO에 동일한 값을 사용합니다. 모든 프로젝트를 강제로 재인덱싱하려면 이 환경 변수를 사용하지 않습니다.

인덱싱 일시 중지#

사전 요구 사항:

• 관리자 액세스.

정확한 코드 검색에 대한 인덱싱을 일시 중지하려면:

1. 오른쪽 상단 모서리에서 관리를 선택하세요.
2. In the left sidebar, select Settings > Search.
3. 정확한 코드 검색을 확장하세요.
4. 인덱싱 일시 중지 체크박스를 선택하세요.
5. 변경 사항 저장을 선택하세요.

정확한 코드 검색에 대한 인덱싱을 일시 중지하면 저장소의 모든 변경 사항이 대기열에 추가됩니다. 인덱싱을 재개하려면 정확한 코드 검색에 대한 인덱싱 일시 중지 체크박스를 선택 취소하세요.

루트 네임스페이스 자동 인덱싱#

사전 요구 사항:

• 관리자 액세스.

기존 및 새 루트 네임스페이스를 자동으로 인덱싱할 수 있습니다. 모든 루트 네임스페이스를 자동으로 인덱싱하려면:

1. 오른쪽 상단 모서리에서 관리를 선택하세요.
2. In the left sidebar, select Settings > Search.
3. 정확한 코드 검색을 확장하세요.
4. 루트 네임스페이스 자동 인덱싱 체크박스를 선택하세요.
5. 변경 사항 저장을 선택하세요.

이 설정을 활성화하면 GitLab은 다음에 있는 모든 프로젝트에 대한 인덱싱 태스크를 만듭니다:

• 모든 그룹 및 서브그룹
• 모든 새 루트 네임스페이스

프로젝트가 인덱싱된 후 GitLab은 저장소 변경이 감지될 때만 증분 인덱싱을 만듭니다.

이 설정을 비활성화하면:

• 기존 루트 네임스페이스는 인덱싱된 상태로 유지됩니다.
• 새 루트 네임스페이스는 더 이상 인덱싱되지 않습니다.

검색 결과 캐시#

사전 요구 사항:

• 관리자 액세스.

더 나은 성능을 위해 검색 결과를 캐시할 수 있습니다. 이 기능은 기본적으로 활성화되어 있으며 5분 동안 결과를 캐시합니다.

검색 결과를 캐시하려면:

1. 오른쪽 상단 모서리에서 관리를 선택하세요.
2. In the left sidebar, select Settings > Search.
3. 정확한 코드 검색을 확장하세요.
4. 5분 동안 검색 결과 캐시 체크박스를 선택하세요.
5. 변경 사항 저장을 선택하세요.

동시 인덱싱 태스크 설정#

사전 요구 사항:

• 관리자 액세스.

CPU 용량에 비해 Zoekt 노드에 대한 동시 인덱싱 태스크 수를 설정할 수 있습니다.

더 높은 승수는 더 많은 태스크가 동시에 실행될 수 있음을 의미하며, CPU 사용 증가를 대가로 인덱싱 처리량을 향상시킵니다. 기본값은 1.0(CPU 코어당 하나의 태스크)입니다.

노드의 성능 및 워크로드에 따라 이 값을 조정할 수 있습니다. 동시 인덱싱 태스크 수를 설정하려면:

1. 오른쪽 상단 모서리에서 관리를 선택하세요.

2. In the left sidebar, select Settings > Search.

3. 정확한 코드 검색을 확장하세요.

4. 인덱싱 CPU 대 태스크 승수 텍스트 상자에 값을 입력하세요.

   예를 들어 Zoekt 노드에 4개의 CPU 코어가 있고 승수가 1.5이면 노드에 대한 동시 태스크 수는 6입니다.

5. 변경 사항 저장을 선택하세요.

무작위 강제 재인덱싱 확률 정의#

사전 요구 사항:

• 관리자 액세스.

프로젝트가 증분 인덱싱 대신 강제 재인덱싱될 확률을 정의할 수 있습니다. 기본값은 0.25(0.25%)입니다.

강제 재인덱싱은 주기적으로 인덱스를 처음부터 재구축하여 메모리 맵(mmap) 핸들러가 고갈되는 것을 방지하는 데 도움이 됩니다. 더 높은 비율은 특히 매우 큰 저장소에서 인덱싱 부하를 증가시킵니다.

무작위 강제 재인덱싱 확률을 정의하려면:

1. 오른쪽 상단 모서리에서 관리를 선택하세요.
2. In the left sidebar, select Settings > Search.
3. 정확한 코드 검색을 확장하세요.
4. 무작위 강제 재인덱싱 확률(백분율) 텍스트 상자에 0에서 100 사이의 숫자를 입력하세요.
5. 변경 사항 저장을 선택하세요.

인덱싱 태스크당 병렬 프로세스 수 설정#

사전 요구 사항:

• 관리자 액세스.

인덱싱 태스크당 병렬 프로세스 수를 설정할 수 있습니다.

더 높은 수는 CPU 및 메모리 사용 증가를 대가로 인덱싱 시간을 향상시킵니다. 기본값은 1(인덱싱 태스크당 하나의 프로세스)입니다.

노드의 성능 및 워크로드에 따라 이 값을 조정할 수 있습니다. 인덱싱 태스크당 병렬 프로세스 수를 설정하려면:

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

인덱싱 롤아웃당 네임스페이스 수 설정#

사전 요구 사항:

• 관리자 액세스.

초기 인덱싱을 위한 RolloutWorker 작업당 네임스페이스 수를 설정할 수 있습니다. 기본값은 32입니다. 노드의 성능 및 워크로드에 따라 이 값을 조정할 수 있습니다.

인덱싱 롤아웃당 네임스페이스 수를 설정하려면:

1. 오른쪽 상단 모서리에서 관리를 선택하세요.
2. In the left sidebar, select Settings > Search.
3. 정확한 코드 검색을 확장하세요.
4. 인덱싱 롤아웃당 네임스페이스 수 텍스트 상자에 0보다 큰 숫자를 입력하세요.
5. 변경 사항 저장을 선택하세요.

오프라인 노드가 자동으로 삭제되는 시점 정의#

사전 요구 사항:

• 관리자 액세스.

특정 기간 후에 관련 인덱스, 저장소 및 태스크와 함께 오프라인 Zoekt 노드를 자동으로 삭제할 수 있습니다. 기본값은 12h(12시간)입니다.

이 설정을 사용하여 Zoekt 인프라를 관리하고 고아 리소스를 방지하세요. 오프라인 노드가 자동으로 삭제되는 시점을 정의하려면:

1. 오른쪽 상단 모서리에서 관리를 선택하세요.
2. In the left sidebar, select Settings > Search.
3. 정확한 코드 검색을 확장하세요.
4. 오프라인 노드 자동 삭제 시간 텍스트 상자에 값을 입력하세요 (예: 30m(30분), 2h(2시간) 또는 1d(1일)). 자동 삭제를 비활성화하려면 0으로 설정하세요.
5. 변경 사항 저장을 선택하세요.

프로젝트에 대한 인덱싱 타임아웃 정의#

사전 요구 사항:

• 관리자 액세스.

프로젝트에 대한 인덱싱 타임아웃을 정의할 수 있습니다. 기본값은 30m(30분)입니다.

프로젝트에 대한 인덱싱 타임아웃을 정의하려면:

1. 오른쪽 상단 모서리에서 관리를 선택하세요.
2. In the left sidebar, select Settings > Search.
3. 정확한 코드 검색을 확장하세요.
4. 프로젝트당 인덱싱 타임아웃 텍스트 상자에 값을 입력하세요 (예: 30m(30분), 2h(2시간) 또는 1d(1일)).
5. 변경 사항 저장을 선택하세요.

인덱싱할 프로젝트의 최대 파일 수 설정#

사전 요구 사항:

• 관리자 액세스.

인덱싱할 수 있는 프로젝트의 최대 파일 수를 설정할 수 있습니다. 기본 브랜치에서 이 제한보다 많은 파일이 있는 프로젝트는 인덱싱되지 않습니다.

기본값은 500,000입니다.

노드의 성능 및 워크로드에 따라 이 값을 조정할 수 있습니다. 인덱싱할 프로젝트의 최대 파일 수를 설정하려면:

1. 오른쪽 상단 모서리에서 관리를 선택하세요.
2. In the left sidebar, select Settings > Search.
3. 정확한 코드 검색을 확장하세요.
4. 인덱싱할 프로젝트당 최대 파일 수 텍스트 상자에 0보다 큰 숫자를 입력하세요.
5. 변경 사항 저장을 선택하세요.

인덱싱할 최대 파일 크기 설정#

사전 요구 사항:

• 관리자 액세스.

인덱싱할 파일의 최대 크기를 설정할 수 있습니다. 기본값은 1MB입니다.

지정된 크기를 초과하는 파일은 파일 이름만 인덱싱됩니다. 이러한 파일은 파일 이름으로만 검색할 수 있습니다.

인덱싱할 최대 파일 크기를 설정하려면:

1. 오른쪽 상단 모서리에서 관리를 선택하세요.
2. In the left sidebar, select Settings > Search.
3. 정확한 코드 검색을 확장하세요.
4. 인덱싱할 최대 파일 크기 텍스트 상자에 값을 입력하세요 (예: 512B, 50KB, 2MB 또는 1GB). 소문자로도 입력할 수 있습니다.
5. 변경 사항 저장을 선택하세요.

인덱싱을 위한 최대 트라이그램 수 설정#

사전 요구 사항:

• 관리자 액세스.

인덱싱할 파일의 최대 트라이그램 수를 설정할 수 있습니다. 기본값은 20,000입니다.

트라이그램은 Zoekt가 효율적인 코드 검색에 사용하는 세 문자 시퀀스입니다. 이 트라이그램 제한을 초과하는 파일은 파일 이름만 인덱싱됩니다. 더 높은 제한은 인덱싱 및 검색 성능 모두에 영향을 미칩니다.

인덱싱을 위한 최대 트라이그램 수를 설정하려면:

1. 오른쪽 상단 모서리에서 관리를 선택하세요.
2. In the left sidebar, select Settings > Search.
3. 정확한 코드 검색을 확장하세요.
4. 파일당 최대 트라이그램 수 텍스트 상자에 0보다 큰 숫자를 입력하세요.
5. 변경 사항 저장을 선택하세요.

실패한 네임스페이스의 재시도 간격 정의#

사전 요구 사항:

• 관리자 액세스.

이전에 실패한 네임스페이스의 재시도 간격을 정의할 수 있습니다. 기본값은 1d(1일)입니다. 값이 0이면 실패한 네임스페이스는 절대 재시도하지 않습니다.

실패한 네임스페이스의 재시도 간격을 정의하려면:

1. 오른쪽 상단 모서리에서 관리를 선택하세요.
2. In the left sidebar, select Settings > Search.
3. 정확한 코드 검색을 확장하세요.
4. 실패한 네임스페이스 재시도 간격 텍스트 상자에 값을 입력하세요 (예: 30m(30분), 2h(2시간) 또는 1d(1일)).
5. 변경 사항 저장을 선택하세요.

네임스페이스당 복제본 수 설정#

사전 요구 사항:

• 관리자 액세스.

네임스페이스당 복제본 수를 설정할 수 있습니다. 기본값은 1(네임스페이스당 하나의 복제본)입니다.

네임스페이스당 복제본 수를 늘리면 여러 Zoekt 노드에 부하를 분산시켜 검색 가용성이 향상됩니다. 복제본이 많을수록 저장소 요구 사항이 증가합니다.

네임스페이스당 복제본 수를 설정하려면:

1. 오른쪽 상단 모서리에서 관리를 선택하세요.
2. In the left sidebar, select Settings > Search.
3. 정확한 코드 검색을 확장하세요.
4. 네임스페이스당 복제본 수 텍스트 상자에 0보다 큰 숫자를 입력하세요.
5. 변경 사항 저장을 선택하세요.

별도 서버에서 Zoekt 실행#

사전 요구 사항:

• 관리자 액세스.

GitLab과 다른 서버에서 Zoekt를 실행하려면:

1. Gitaly 수신 인터페이스를 변경하세요.
2. Zoekt를 설치하세요.

크기 조정 권장 사항#

다음 권장 사항은 일부 배포에서 과도하게 프로비저닝될 수 있습니다. 다음을 보장하기 위해 배포를 모니터링해야 합니다:

• 메모리 부족 이벤트가 발생하지 않습니다.
• CPU 스로틀링이 과도하지 않습니다.
• 인덱싱 성능이 요구 사항을 충족합니다.

다음을 포함한 특정 워크로드 특성에 따라 리소스를 조정하세요:

• 저장소 크기 및 복잡성
• 활성 개발자 수
• 코드 변경 빈도
• 인덱싱 패턴

노드#

최적의 성능을 위해 Zoekt 노드의 적절한 크기 조정이 중요합니다. 리소스가 할당되고 관리되는 방식 때문에 크기 조정 권장 사항은 Kubernetes와 VM 배포 간에 다릅니다.

Kubernetes 배포#

다음 표는 인덱스 저장소 요구 사항을 기반으로 Kubernetes 배포의 노드당(StatefulSet 포드당) 권장 리소스를 보여줍니다. StatefulSet의 각 포드는 독립적인 리소스 할당과 인덱스 저장소를 위한 자체 영구 볼륨으로 자체 웹 서버 및 인덱서 컨테이너를 실행합니다. 여러 노드를 실행하는 경우 총 클러스터 리소스를 계산하기 위해 이러한 리소스에 노드 수를 곱하세요.

더 세밀하게 리소스를 관리하려면 다른 컨테이너에 CPU 및 메모리를 별도로 할당할 수 있습니다.

Kubernetes 배포의 경우:

• Zoekt 컨테이너에 CPU 제한을 설정하지 마세요. CPU 제한은 인덱싱 급증 시 불필요한 스로틀링을 일으킬 수 있으며 이는 성능에 상당한 영향을 미칩니다. 대신 최소 CPU 가용성을 보장하고 사용 가능하고 필요할 때 컨테이너가 추가 CPU를 사용할 수 있도록 리소스 요청에 의존하세요.
• 리소스 경합 및 메모리 부족 상태를 방지하기 위해 적절한 메모리 제한을 설정하세요.
• 더 나은 인덱싱 성능을 위해 고성능 스토리지 클래스를 사용하세요. GitLab.com은 GCP에서 성능과 비용의 균형을 맞추는 pd-balanced를 사용합니다. 동급 옵션으로는 AWS의 gp3 및 Azure의 Premium_LRS가 있습니다.

VM 및 베어 메탈 배포#

다음 표는 인덱스 저장소 요구 사항을 기반으로 VM 및 베어 메탈 배포의 노드당 권장 리소스를 보여줍니다. 여러 노드를 실행하는 경우 총 클러스터 리소스를 계산하기 위해 이러한 리소스에 노드 수를 곱하세요.

이러한 리소스는 전체 노드에만 할당할 수 있습니다.

VM 및 베어 메탈 배포의 경우:

• 병목 지점을 식별하기 위해 CPU, 메모리 및 디스크 사용량을 모니터링하세요. 웹 서버와 인덱서 프로세스는 동일한 CPU 및 메모리 리소스를 공유합니다.
• 더 나은 인덱싱 성능을 위해 SSD 스토리지를 사용하는 것을 고려하세요.
• GitLab과 Zoekt 노드 간의 데이터 전송을 위해 충분한 네트워크 대역폭을 보장하세요.

저장소#

Zoekt 저장소 요구 사항은 Git 저장소의 크기와 복제본 구성에 따라 다릅니다. Zoekt는 Git 객체 데이터(소스 코드 및 커밋 기록)만 인덱싱합니다. LFS 파일, CI/CD 아티팩트, 패키지, 위키 또는 기타 저장소 구성 요소는 인덱싱하지 않습니다.

요구 사항 추정#

저장소 요구 사항을 추정하려면 다음 Rake 태스크를 실행하세요:

sudo gitlab-rake gitlab:zoekt:estimate_storage

이 태스크는 GitLab 데이터베이스를 쿼리하고 현재 저장소 크기 및 복제본 구성을 기반으로 저장소 추정값을 출력합니다.

저장소 요구 사항을 수동으로 계산하려면 대신 다음 공식을 사용하세요:

storage_per_replica = sum(repository_git_size) × 3
total_cluster_storage = storage_per_replica × number_of_replicas

repository_git_size는 각 저장소의 Git 객체 크기입니다. 이 값에는 LFS 객체, 위키, 아티팩트 또는 패키지가 포함되지 않습니다. buffer_factor는 초기 인덱싱 중 여유 공간입니다. 이 값은 Search::Zoekt::Index.global_buffer_factor로 계산할 수 있으며 기본값은 주로 3입니다.

repository_git_size를 보려면:

1. 오른쪽 상단 모서리에서 관리를 선택하세요.
2. In the left sidebar, select Overview > Projects.
3. 저장소 열에서 Git 객체 크기를 확인하세요.

초기 프로비저닝 대상의 경우 복제본 수를 곱한 총 repository_git_size의 세 배로 시작하세요. 예를 들어:

• 100 GB의 Git 저장소 데이터 및 1개의 복제본: 300 GB의 Zoekt 저장소.
• 100 GB의 Git 저장소 데이터 및 2개의 복제본: 600 GB의 Zoekt 저장소.

GitLab은 인덱싱 중에 Zoekt에 여유 공간을 확보하기 위해 내부적으로 이 버퍼를 예약합니다. 초기 인덱싱이 완료된 후 실제 디스크 사용량은 일반적으로 GitLab.com의 관찰된 데이터를 기반으로 repository_git_size의 절반에 더 가깝습니다. 필요한 경우에만 수직 또는 수평으로 확장하세요.

현재 버퍼 인수를 보려면 다음 Rake 태스크를 실행하세요:

gitlab-rake gitlab:zoekt:info

출력에는 플래너가 사용 중인 동적 값을 보여주는 Storage buffer factor가 포함됩니다.

Zoekt 노드 저장소를 모니터링하려면 인덱싱 상태 확인을 참조하세요. 디스크 공간 부족으로 네임스페이스가 인덱싱되지 않으면 노드를 추가하거나 디스크 용량을 늘리세요.

메모리 아키텍처#

웹 서버와 인덱서는 서로 다른 메모리 사용 패턴을 가집니다.

웹 서버는 디스크의 인덱스 샤드를 가상 메모리에 메모리 매핑합니다. 운영 체제는 검색이 처리될 때 물리 메모리에서 샤드 데이터를 페이지인/아웃합니다. 상주 메모리 사용량은 활성 워킹 셋에 따라 증가합니다.

인덱서는 인덱스를 빌드하거나 재빌드할 때 메모리에서 Git 객체 데이터를 처리합니다. 대규모 저장소를 인덱싱하거나 여러 태스크가 병렬로 실행될 때 메모리 사용량이 급증합니다. 인덱싱 태스크당 병렬 프로세스 수와 동시 인덱싱 태스크를 조정하여 최대 인덱서 메모리를 제어할 수 있습니다.

VM 및 베어 메탈 배포에서는 웹 서버와 인덱서가 동일한 시스템 메모리를 공유합니다.

보안 및 인증#

Zoekt는 GitLab, Zoekt 인덱서 및 Zoekt 웹 서버 구성 요소 간의 통신을 보호하기 위해 다계층 인증 시스템을 구현합니다. 인증은 모든 통신 채널에서 강제 적용됩니다.

모든 인증 방법은 GitLab Shell 시크릿을 사용합니다. 인증 실패 시도는 401 Unauthorized 응답을 반환합니다.

Zoekt 인덱서에서 GitLab으로#

Zoekt 인덱서는 인덱싱 태스크를 검색하고 완료 콜백을 전송하기 위해 JSON 웹 토큰(JWT)으로 GitLab에 인증합니다.

이 방법은 서명 및 검증에 .gitlab_shell_secret을 사용합니다. 토큰은 Gitlab-Shell-Api-Request 헤더로 전송됩니다. 다음 엔드포인트를 사용할 수 있습니다:

• GET /internal/search/zoekt/:uuid/heartbeat (태스크 검색용)
• POST /internal/search/zoekt/:uuid/callback (상태 업데이트용)

이 방법은 Zoekt 인덱서 노드와 GitLab 간의 태스크 배포 및 상태 보고를 위한 안전한 폴링을 보장합니다.

GitLab에서 Zoekt 웹 서버로#

JWT 인증#

GitLab은 검색 쿼리를 실행하기 위해 JSON 웹 토큰(JWT)으로 Zoekt 웹 서버에 인증합니다. JWT 토큰은 다른 GitLab 인증 패턴과 일관된 시간 제한, 암호화 서명된 인증을 제공합니다.

이 방법은 Gitlab::Shell.secret_token과 HS256 알고리즘(HMAC와 SHA-256)을 사용합니다. 노출을 제한하기 위해 토큰은 Authorization: Bearer <jwt_token> 헤더로 전송되고 5분 후에 만료됩니다.

엔드포인트에는 /webserver/api/search 및 /webserver/api/v2/search가 포함됩니다. JWT 클레임은 발급자(gitlab) 및 대상(gitlab-zoekt)입니다.