환경변수 레퍼런스

환경변수 레퍼런스 (Environment Variables)

Weaviate의 동작은 환경변수로 제어돼요. Docker 컴포즈든 Kubernetes든, 환경변수에 값을 넣어서 인스턴스가 어떻게 움직일지 정합니다. 여기 있는 목록 전부를 외울 필요는 없고, 운영할 때 자주 쓰이는 변수 몇 개의 의미와 기본값만 짚고 가면 돼요.

출처: 공식문서 — Environment Variables Reference

주요 일반 변수

변수	설명	타입	예시 값
`EXPORT_DEFAULT_BUCKET`	컬렉션 내보내기용 스토리지 버킷 이름. S3·GCS·Azure 백엔드에 필수. `v1.37`에 추가	`string`	`my-export-bucket`
`EXPORT_DEFAULT_PATH`	내보내기 파일이 버킷 안에 놓일 선택적 기본 경로 접두사	`string`	—
`EXPORT_PARALLELISM`	컬렉션 내보내기의 동시 스캔 워커 수. `0`이면 GOMAXPROCS 사용. 기본 `0`, `v1.37` 추가	`string - number`	`4`
`EXPORT_SKIP_ACCESS_CHECK`	컬렉션 내보내기 백엔드 초기화 시 실행되는 쓰기-삭제 접근 검사를 건너뜀	`boolean`	—
`MAXIMUM_ALLOWED_COLLECTIONS_COUNT`	Weaviate 노드에서 허용되는 최대 컬렉션 수. `-1`이면 제한 해제. 기본 `-1`(무제한)	`integer`	—
`MCP_SERVER_WRITE_ACCESS_ENABLED`	MCP 서버에서 쓰기 도구(`weaviate-objects-upsert`) 활성화. `false`면 읽기·쿼리 도구만. 기본 `false`. `v1.37.1` 추가, `v1.38`부터 런타임 구성 가능	`boolean`	`true`
`MEMORY_WARNING_PERCENTAGE`	메모리 사용이 해당 %보다 높아지면 영향받는 노드의 모든 샤드가 경고 로그. 기본 `0`(제한 없음)	`string - number`	`85`
`MODULES_CLIENT_TIMEOUT`	Weaviate 모듈로의 요청 타임아웃. `v1.36` 추가	`string - number`	`3`
`OPERATIONAL_MODE`	인스턴스의 동작 모드를 설정해 선택한 모드에 따라 가능한 작업 제한. 옵션: `ReadWrite`(기본), `ReadOnly`, `WriteOnly`, `ScaleOut`. 대소문자 구분해 정확히 매칭. `READ_ONLY`처럼 인식할 수 없는 값은 경고·오류 없이 조용히 기본 `ReadWrite`로 빠짐 — 제한하려던 노드가 계속 완전 쓰기 가능한 상태가 되므로 주의	`string`	`ReadWrite`
`ORIGIN`	Weaviate의 http(s) origin 설정	`string - HTTP origin`	`https://my-weaviate-deployment.com`
`PERSISTENCE_DATA_PATH`	Weaviate 데이터 저장소 경로. 기본 `./data`	`string - file path`	`/var/lib/weaviate`
`PERSISTENCE_HNSW_DISABLE_SNAPSHOTS`	`v1.39`에서 디프리케이트. 무시되며 시작 시 경고 로그. `v1.31` 추가	`boolean`	`false`
`PERSISTENCE_HNSW_MAX_LOG_SIZE`	HNSW 쓰기-선행 로그(write-ahead-log) 최대 크기. 로그 컴팩션 효율을 높이려면 키우고, 메모리 요구를 줄이려면 줄임	`string`	—
`TENANT_ACTIVITY_WRITE_LOG_LEVEL`	테넌트 쓰기 활동의 로그 레벨. 분석·디버깅에 유용. 기본 `debug`	`string`	`info`
`USE_GSE`	`GSE` 토크나이저 사용. (`ENABLE_TOKENIZER_GSE`와 동일. 다른 토크나이저와 명명 일관성을 위해 `ENABLE_TOKENIZER_GSE`를 권장)	`boolean`	`true`

모듈 관련 변수

변수	설명	타입	예시 값
`BACKUP_*`	백업 제공자 모듈용 여러 구성 변수. 자세한 내용은 백업 페이지에서	—	—
`OFFLOAD_S3_BUCKET`	오프로드에 쓸 S3 버킷(기본 `weaviate-offload`)	`string`	`my-custom-offload-bucket`
`USE_GOOGLE_AUTH`	Google Cloud 자격증명을 자동 탐색하고, 필요할 때 Weaviate가 쓸 Vertex AI 접근 토큰 생성(기본 `false`)	`boolean`	`true`
`CLIP_WAIT_FOR_STARTUP`	`true`면 Weaviate가 `multi2vec-clip` 모듈 시작을 기다렸다가 시작(기본 `true`)	`boolean`	`true`
`GPT4ALL_WAIT_FOR_STARTUP`	`true`면 `text2vec-gpt4all` 모듈 시작을 기다림(기본 `true`)	`boolean`	`true`
`TRANSFORMERS_WAIT_FOR_STARTUP`	`true`면 `text2vec-transformers` 모듈 시작을 기다림(기본 `true`)	`boolean`	`true`
`USAGE_GCS_BUCKET`	GCS 사용 시 필수인 GCS 버킷 이름	`string`	`my-weaviate-usage-bucket`
`USAGE_GCS_PREFIX`	GCS 보고서의 선택적 객체 접두사	`string`	`usage-reports`
`USAGE_S3_BUCKET`	S3 사용 시 필수인 S3 버킷 이름	`string`	`my-weaviate-usage-bucket`
`USAGE_S3_PREFIX`	S3 보고서의 선택적 객체 접두사	`string`	`usage-reports`
`RUNTIME_OVERRIDES_ENABLED`	런타임 오버라이드 구성 활성화	`boolean`	`true`
`RUNTIME_OVERRIDES_PATH`	런타임 오버라이드 구성 파일 경로	`string`	`${PWD}/tools/dev/config.runtime-overrides.yaml`

멀티 노드 인스턴스 — 비동기 복제

변수	설명	타입	예시 값
`ASYNC_REPLICATION_PROPAGATION_CONCURRENCY`	한 배치의 객체를 동시에 전파할 워커 수. 기본 `5`, 최소 `1`, 최대 `20`	`string - number`	`10`
`ASYNC_REPLICATION_PROPAGATION_BATCH_SIZE`	단일 배치로 전파할 최대 객체 수. 기본 `100`, 최소 `1`, 최대 `1000`	`string - number`	`200`

비동기 복제 관련 전체 변수 목록과 설명은 복제(Replication) 페이지에서 더 자세히 다룹니다.

더 알아보기 (Learn more)