환경 변수

.env 파일을 사용하여 애플리케이션 환경을 구성하기 위한 종합 가이드에 오신 것을 환영합니다. 이 문서는 다양한 상황에서 애플리케이션의 동작을 결정하는 환경 변수를 이해하고 사용자 지정하기 위한 원스톱 리소스입니다.

기본 설정만으로도 표준 docker 설치를 위한 탄탄한 기반을 제공하지만, 이 가이드를 자세히 살펴보면 LibreChat의 잠재력을 완전히 끌어낼 수 있습니다. 이 가이드를 통해 귀하의 필요에 맞춰 LibreChat을 조정할 수 있습니다. 언어 모델 가용성을 조정하고, 소셜 로그인을 통합하며, 자동 조정 시스템을 관리하는 등 다양한 방법을 알아보세요. 이 모든 것은 최적의 사용자 경험을 위해 LibreChat을 세밀하게 조정할 수 있는 제어 권한을 제공하기 위함입니다.

알림: 구성 변경 사항을 적용하려면 LibreChat을 다시 시작해 주세요.

또는, LibreChat의 메인 docker-compose.yml 파일과 동일한 디렉토리에 docker-compose.override.yml이라는 새 파일을 생성할 수 있습니다. 이 파일에서 environment 아래에 필요한 .env 변수를 설정하거나, 전체 파일을 직접 수정하거나 복제할 필요 없이 메인 docker-compose.yml에서 제공하는 기본 구성을 수정할 수 있습니다.

더 자세한 정보는 다음을 참조하세요:

• 빠른 가이드:

  • Docker Override

• 공식 Docker 문서:

  • docker docs - understanding-multiple-compose-files
  • docker docs - merge-compose-files
  • docker docs - specifying-multiple-compose-files

• LibreChat 폴더 및 GitHub에서 LibreChat을 위한 오버라이드 파일 예시를 확인할 수도 있습니다:

  • docker-compose.override.example

---

서버 구성

포트

• 서버는 특정 포트에서 수신 대기합니다.
• PORT 환경 변수는 서버가 수신 대기할 포트를 설정합니다. 기본값은 3080으로 설정되어 있습니다.

Trust proxy

Express 애플리케이션으로부터 최대 n개의 홉(hop) 거리에 있는 주소를 사용합니다. req.socket.remoteAddress는 첫 번째 홉이며, 나머지는 X-Forwarded-For 헤더에서 오른쪽에서 왼쪽으로 탐색합니다. 값이 0이면 첫 번째 신뢰할 수 없는 주소가 req.socket.remoteAddress가 됨을 의미하며, 즉 리버스 프록시가 없음을 뜻합니다. TRUST_PROXY 환경 변수의 기본값은 1로 설정되어 있습니다.

이에 대한 자세한 내용은 Express.js - trust proxy를 참조하세요.

자격 증명(Credentials) 구성

자격 증명을 안전하게 저장하려면 고정된 키와 IV가 필요합니다. prod 및 dev 환경에 대해 여기에서 설정할 수 있습니다.

정적 파일 처리

동작:

정적 파일에 대한 Cache-Control 헤더를 설정합니다. 이 구성은 NODE_ENV가 production으로 설정된 경우에만 트리거됩니다.

• STATIC_CACHE_MAX_AGE의 주석을 해제하여 정적 파일에 대한 로컬 max-age를 변경할 수 있습니다. 기본값은 2일(172800초)로 설정되어 있습니다.
• STATIC_CACHE_S_MAX_AGE의 주석을 해제하여 공유 캐시(CDN 및 프록시)에 대한 s-maxage를 설정하세요. 기본값은 1일(86400초)로 설정되어 있습니다.
• DISABLE_COMPRESSION의 주석을 해제하면 정적 파일에 대한 압축을 비활성화할 수 있습니다. 기본적으로 압축은 활성화되어 있습니다.
• ENABLE_IMAGE_OUTPUT_GZIP_SCAN의 주석을 해제하면 동일한 폴더 내에 동일한 이름과 .gz 확장자로 미리 압축된 이미지가 있을 경우, 해당 gzip 버전의 이미지를 스캔하고 제공할 수 있습니다. 기본적으로 업로드된 이미지에 대한 gzip 스캔은 비활성화되어 있습니다.
• ENABLE_STATIC_ASSET_BROTLI의 주석을 해제하면 존재하는 경우 사전 압축된 .br 버전의 정적 앱 에셋을 제공합니다. 활성화되면 API를 통해 제공되는 정적 파일에 대해 gzip보다 Brotli가 우선적으로 사용됩니다.

Index HTML 캐시 제어

동작:

index.html 응답에 대한 캐싱 헤더를 구체적으로 제어합니다. 기본적으로 이러한 설정은 사용자가 항상 최신 버전의 애플리케이션을 받을 수 있도록 캐싱을 방지합니다.

MongoDB 데이터베이스

다를 경우 이를 귀하의 MongoDB URI로 변경하십시오. URI의 데이터베이스 이름으로 LibreChat 또는 귀하만의 APP_TITLE을 추가해야 합니다.

온라인 데이터베이스를 사용하는 경우, URI 형식은 mongodb+srv://<username>:<password>@<host>/<database>?<options>입니다. 귀하의 MONGO_URI는 다음과 같아야 합니다:

• mongodb+srv://username:[email protected]/LibreChat?retryWrites=true (retryWrites는 온라인 데이터베이스를 사용할 때 필요한 유일한 옵션입니다.)

MongoDB 연결 풀 구성

MongoDB 스키마 구성

또는 mongoDb를 에뮬레이트하는 documentDb를 사용할 수 있지만, 다음 사항이 있습니다:

• retryWrites를 지원하지 않습니다 - retryWrites=false를 사용하세요
• TLS 연결이 필요하므로, tls=true 매개변수를 사용하여 TLS를 활성화하고 tlsCAFile=/path-to-ca/bundle.pem을 사용하여 AWS에서 제공하는 CA 번들 파일을 지정하십시오.

documentDb에 대한 URI는 다음과 같습니다:

• mongodb+srv://username:password@domain/dbname?retryWrites=false&tls=true&tlsCAFile=/path-to-ca/bundle.pem

참고:

• MongoDB Atlas (Docker 없이 사용할 때 유용한 온라인 MongoDB Atlas 데이터베이스 생성 방법에 대한 안내)
• MongoDB Community Server에서 로컬 MongoDB 데이터베이스를 생성하는 방법(Docker 제외)에 대한 지침을 확인하세요.
• MongoDB Authentication Docker에서 MongoDB에 대한 명시적 인증을 활성화합니다.
• Mongo Express로 데이터베이스 관리하기를 통해 Docker MongoDB 데이터베이스에 안전하게 액세스하세요

애플리케이션 도메인

LibreChat을 로컬 환경이나 사용자 지정 도메인에 배포하도록 구성하려면 다음 환경 변수를 설정하세요:

LibreChat을 사용자 지정 도메인에 배포할 때는 http://localhost:3080을 배포한 URL로 교체하세요.

• 예: https://librechat.example.com.

공개 검색 엔진의 인덱싱 방지

기본적으로 귀하의 웹사이트는 공개 검색 엔진(예: Google, Bing 등)에 의해 색인되지 않습니다. 이는 사람들이 이러한 검색 엔진을 통해 귀하의 웹사이트를 찾을 수 없음을 의미합니다. 웹사이트의 가시성을 높이고 검색 가능하게 만들고 싶다면, 다음 설정을 false로 변경할 수 있습니다.

❗참고: 이 방법이 모든 검색 엔진에서 작동한다고 보장할 수는 없으며, 일부 검색 엔진은 캐싱이나 아카이빙과 같은 다른 목적으로 귀하의 웹사이트나 웹 페이지를 여전히 색인화할 수 있습니다. 따라서 웹사이트나 웹 페이지의 민감하거나 기밀인 정보를 보호하기 위해 이 방법만 전적으로 의존해서는 안 됩니다.

로깅

LibreChat은 중앙 집중식 로깅 기능을 내장하고 있습니다. 자세한 내용은 Logging System을 참조하세요.

로그 파일

• 디버그 로깅은 기본적으로 활성화되어 있으며 개발에 매우 중요합니다.
• 문제를 보고하려면 오류를 재현한 후 ./api/logs/debug-%DATE%.log의 로그를 **LibreChat GitHub Issues**에 제출해 주세요.
• 오류 로그는 동일한 위치에 저장됩니다.

환경 변수

참고:

• DEBUG_LOGGING은 DEBUG_CONSOLE 또는 CONSOLE_JSON 중 하나와 함께 사용할 수 있지만, 둘 다 동시에 사용할 수는 없습니다.
• DEBUG_CONSOLE와 CONSOLE_JSON은 상호 배타적입니다.
• CONSOLE_JSON: 클라우드 배포(GCP 또는 AWS 등)에서 콘솔 로그를 처리할 때, 이 옵션을 활성화하면 UTC 타임스탬프가 포함된 JSON 형식으로 로그가 출력됩니다.
  • 참고: feat: Add CONSOLE_JSON

참고: DEBUG_CONSOLE은 출력이 매우 장황할 수 있으므로 권장되지 않으며, 기본적으로 비활성화되어 있습니다.

권한

UID와 GID는 시스템의 각 사용자와 그룹에 할당된 Linux 숫자입니다. 권한 문제가 발생하는 경우, Docker Compose 명령을 실행하는 사용자의 UID와 GID를 여기에 설정하십시오. 컨테이너 내의 애플리케이션은 이 UID/GID로 실행됩니다.

OpenTelemetry Tracing

LibreChat은 일반 API, HTTP, MongoDB, Mongoose, Redis 및 아웃바운드 요청 가시성을 위해 백엔드 OpenTelemetry 추적을 내보낼 수 있습니다. Redis 명령 수준 스팬(span)은 선택 사항이므로 기본 추적은 상위 수준으로 유지됩니다. GenAI 관련 프롬프트/모델 관측 가능성을 위해서는 Langfuse를 사용하세요.

실제 사용자 모니터링 (브라우저)

LibreChat은 브라우저 RUM(Real User Monitoring) 텔레메트리를 HyperDX 호환 OTLP 수집기로 게시할 수 있습니다. RUM은 기본적으로 비활성화되어 있습니다.

publicToken 모드에서 브라우저는 RUM_PUBLIC_TOKEN과 함께 RUM_URL로 원격 분석(telemetry) 데이터를 직접 전송합니다. proxy 모드에서 브라우저는 LibreChat을 통해 원격 분석 데이터를 전송하며, 백엔드는 사용자 세션을 검증하고 앱 인증 헤더를 제거한 뒤 RUM_PROXY_TARGET_URL로 데이터를 전달합니다. 유효하지 않거나 만료된 세션은 204 응답과 함께 삭제되므로 브라우저의 원격 분석 실패가 일반적인 API 인증 오류로 나타나지 않습니다. 프록시 결과는 LibreChat API /metrics 엔드포인트에서 endpoint 및 result 레이블이 지정된 rum_proxy_requests_total로 집계됩니다.

구성 경로 - librechat.yaml

LibreChat 설정 파일의 대체 위치를 지정합니다.

절대 경로, 상대 경로 또는 URL을 지정할 수 있습니다. 경로 내의 파일 이름은 유연하게 설정할 수 있으며 반드시 librechat.yaml일 필요는 없습니다. 유효한 설정 파일이라면 무엇이든 작동합니다.

참고: LibreChat이 루트 디렉토리에서 설정 파일을 검색하도록 하려면(기본 동작), 이 옵션을 주석 처리된 상태로 두면 됩니다.

배포 기술

Deployment Skills는 시작 시 파일 시스템에서 읽기 전용으로 로드되며, Skills 기능이 활성화된 사용자에게 노출됩니다.

이 디렉토리나 그 안의 파일을 변경한 후에는 LibreChat을 재시작하십시오. 배포 시 제공된 Skills는 동일한 이름을 가진 영구 저장된 Skills보다 우선합니다.

구성 유효성 검사

기본적으로 LibreChat은 librechat.yaml 구성 파일에 유효성 검사 오류가 포함되어 있으면 오류(종료 코드 1)와 함께 종료됩니다. 이러한 빠른 실패(fail-fast) 동작은 배포 파이프라인 초기에 구성 문제를 포착하고 의도하지 않은 기본 설정으로 실행되는 것을 방지하는 데 도움이 됩니다.

Uncaught Exception Handling

기본적으로 LibreChat은 처리되지 않은 예외가 발생하면 프로세스를 종료하며, 이는 표준 Node.js 동작 방식입니다. 처리되지 않은 예외 발생 후에도 앱이 계속 실행되도록 이 설정을 재정의할 수 있습니다.

Endpoints

이 섹션에서는 엔드포인트 및 모델 선택, API 키, 그리고 이를 지원하는 엔드포인트에 대한 프록시 및 리버스 프록시 설정을 구성할 수 있습니다.

일반 설정

ENDPOINTS의 주석을 해제하여 LibreChat에서 사용 가능한 endpoint를 사용자 지정하세요.

알려진 엔드포인트 - librechat.yaml

• 참고: Custom Endpoints & Configuration

웹 검색

웹 검색 기능은 LibreChat 내에서 인터넷 검색 기능을 활성화합니다.

중요: 아래에 표시된 정확한 환경 변수 이름은 기본 참조이며, librechat.yaml 구성 파일을 통해 원하는 변수 이름을 사용하도록 사용자 지정할 수 있습니다.

자세한 구성 및 사용자 지정 옵션은 다음을 참조하세요: Web Search Configuration

참고: 이 변수 이름들은 librechat.yaml 구성 파일에서 사용자 지정할 수 있습니다. 예를 들어, 웹 검색 설정에서 구성하여 SERPER_API_KEY 대신 CUSTOM_SERPER_KEY를 사용할 수 있습니다. 변수 이름 사용자 지정에 대한 자세한 내용은 Web Search Configuration 문서를 참조하세요.

Anthropic

참고: Anthropic Endpoint

• https://platform.claude.com/ 에서 액세스 키를 요청할 수 있습니다.
• ANTHROPIC_API_KEY=를 비워두면 이 endpoint가 비활성화됩니다.
• ANTHROPIC_API_KEY=를 "user_provided"로 설정하여 사용자가 WebUI에서 자신의 API 키를 직접 입력할 수 있도록 합니다.
• Anthropic에 대한 리버스 프록시(reverse proxy) 접근 권한이 있는 경우, ANTHROPIC_REVERSE_PROXY=를 사용하여 설정할 수 있습니다.
  • 기본 base url을 사용하려면 비워두거나 주석 처리하세요

• ANTHROPIC_TITLE_MODEL은 이제 더 이상 사용되지 않으며 향후 버전에서 제거될 예정입니다. 대신 librechat.yaml 설정의 titleModel 엔드포인트 설정을 사용하세요.

참고: Anthropic endpoint와 호환되어야 합니다. 또한, Claude 2 및 Claude 3 모델이 이 작업에서 가장 뛰어난 성능을 발휘하며, claude-3-haiku 모델이 가장 저렴합니다.

Claude Fable 5는 기본 Anthropic 모델 목록에 포함되어 있습니다. Fable/Mythos급 모델은 LibreChat에서 최신 Anthropic 동작을 사용합니다: 1M 컨텍스트, 적응형 사고(adaptive thinking) 지원, 프롬프트 캐싱 지원, 그리고 요약되거나 생략된 추론 출력을 위한 thinkingDisplay 처리가 포함됩니다.

Vertex AI를 통한 Anthropic

Google Cloud Vertex AI를 통해 Anthropic Claude 모델을 사용할 수도 있습니다. 자세한 YAML 구성 옵션은 다음을 참조하세요: Anthropic Vertex AI 구성

참고: Vertex AI를 사용할 때는 Vertex AI User 역할이 있는 서비스 계정으로 GOOGLE_SERVICE_KEY_FILE을 구성해야 합니다(Google 구성 참조).

AWS Bedrock

참고: AWS Bedrock 설정

참고: 액세스 키를 생략하면 기본 AWS 자격 증명 체인(환경 변수, SSO 자격 증명, 공유 자격 증명 파일 또는 EC2/ECS 인스턴스 메타데이터 서비스)을 사용할 수 있습니다. 자세한 내용은 AWS Bedrock Setup을 참조하세요.

Bedrock의 Claude Fable/Mythos 클래스 모델은 추론 프로필(inference-profile) 전용입니다. us.anthropic.claude-fable-5와 같은 프로필 ID를 사용하고, 모델을 호출하기 전에 Bedrock 콘솔 또는 Data Retention API에서 필요한 Anthropic 데이터 공유 설정을 활성화하십시오.

BingAI

Bing (Sydney, jailbreak, 및 Bing Image Creator에도 사용됨)

참고: "user_provided"로 두고 WebUI에서 토큰을 입력하는 것을 권장합니다.

Google

Google Endpoint을 설정하려면 다음 지침을 따르세요.

사용 가능한 모델을 쉼표로 구분하여 지정하세요. 공백은 포함하지 마세요. 첫 번째 모델이 기본값으로 설정됩니다. 내부 설정을 사용하려면 비워두거나 주석 처리하세요.

• GOOGLE_TITLE_MODEL은 이제 더 이상 사용되지 않으며 향후 버전에서 제거될 예정입니다. 대신 librechat.yaml 설정의 titleModel 엔드포인트 설정을 사용하세요.

참고: Vertex AI GOOGLE_SAFETY 변수의 경우, 기본적으로 BLOCK_NONE 설정에 액세스할 수 없습니다. 이 제한된 HarmBlockThreshold 설정을 사용하려면 다음 중 하나를 수행해야 합니다:

• (a) Google 계정 팀을 통해 허용 목록(allowlist)에 대한 액세스 권한을 얻으세요
• (b) 다음 지침에 따라 계정 유형을 월별 청구서 발행 방식으로 전환하세요: https://cloud.google.com/billing/docs/how-to/invoiced-billing

Gemini 이미지 생성

Gemini Image Generation은 Gemini API와 Vertex AI를 모두 지원하는 에이전트용 도구입니다. 자세한 내용은 다음을 참조하세요: Gemini Image Generation

참고: API 키가 구성되지 않은 경우, 도구는 GOOGLE_SERVICE_KEY_FILE의 서비스 계정을 사용하여 자동으로 Vertex AI로 대체됩니다. 해당 서비스 계정에는 반드시 Vertex AI User 역할이 할당되어 있어야 합니다.

OpenAI

참고: OpenAI Setup

• OPENAI_TITLE_MODEL은 이제 더 이상 사용되지 않으며 향후 버전에서 제거될 예정입니다. 대신 librechat.yaml 설정의 titleModel 엔드포인트 설정을 사용하세요.
• OPENAI_REVERSE_PROXY는 이제 더 이상 사용되지 않으며 향후 버전에서 제거될 예정입니다. 대신 custom endpoint를 사용하세요.

Assistants

참고: Assistants Setup

참고: 사용 가능한 모델을 쉼표로 구분하여 공백 없이 사용자 지정할 수 있습니다. 첫 번째 모델이 기본값으로 설정됩니다. 비워두거나 주석 처리하면 내부 설정을 사용합니다.

Tavily

다음에서 API 키를 받으세요: https://tavily.com/#api

환경 변수:

Traversaal

설명: LLM 강화 검색 도구.

API 키는 여기서 받으세요: https://api.traversaal.ai/dashboard

환경 변수:

WolframAlpha

자세한 지침은 여기를 참조하세요: Wolfram Alpha

환경 변수:

Zapier

설명: - Zapier 계정이 필요합니다. 다음 링크에서 API 키를 받으세요: Zapier

• 허용된 작업 생성 - Zapier의 이 시작 가이드에서 3단계를 따르세요

참고: Zapier는 특정 작업에서 까다로운 것으로 알려져 있습니다. 이메일 초안 작성이 아마도 가장 적합한 활용 사례일 것입니다.

환경 변수:

OpenWeather

자세한 지침은 여기를 참조하세요: OpenWeather

Code Interpreter

Code Interpreter API는 코드를 실행하고 파일을 관리하기 위한 안전한 환경을 제공합니다. 참조: Code Interpreter API

Artifacts

Artifacts는 HTML/JS 코드를 안전하게 렌더링하기 위해 CodeSandbox 라이브러리를 활용합니다. 기본적으로 CodeSandbox에서 호스팅하는 공개 CDN이 사용됩니다.

다행히도 내부 네트워크 요구 사항이 있는 경우, 프론트엔드 코드를 컴파일하는 번들러를 직접 호스팅하고 Sandpack을 위한 사용자 지정 번들러 URL을 지정할 수 있습니다.

메트릭 요청이 제거된 자가 호스팅용 사전 제작 컨테이너 이미지를 포함한 자세한 정보는 다음을 참조하세요: https://github.com/LibreChat-AI/codesandbox-client

검색 (Meilisearch)

메시지 및 대화 내 검색을 활성화합니다:

참고: Docker를 사용하지 않는 경우, 무료 자체 호스팅 Meilisearch 또는 유료 원격 플랜을 설치해야 합니다.

MeiliSearch에 대한 익명화된 원격 분석(telemetry) 분석을 완전히 비활성화하여 개인정보를 보호하려면, 다음을 true로 설정하세요:

API 서버가 검색 서버에 연결하기 위함입니다. Docker Compose로 MeiliSearch를 서비스하는 경우 '0.0.0.0'을 'meilisearch'로 교체하세요.

이 마스터 키는 최소 16바이트 이상이어야 하며, 유효한 UTF-8 문자로 구성되어야 합니다. 마스터 키가 제공되지 않거나 16바이트 미만일 경우 MeiliSearch는 오류를 발생시키며 실행을 거부합니다. MeiliSearch는 안전하게 자동 생성된 마스터 키를 제안할 것입니다. 이는 docker-compose를 위한 즉시 사용 가능한 보안 키이며, 사용자의 키로 교체할 수 있습니다.

LibreChat이 Meilisearch와 데이터베이스 인덱싱 동기화를 시도하지 않도록 하려면, 다음 환경 변수를 true로 설정할 수 있습니다. 이는 하나의 인스턴스만 인덱싱을 담당해야 하는 노드 클러스터 또는 다중 노드 설정에서 유용합니다.

RAG API

문서 인덱싱 및 문맥 인식 응답을 위한 Retrieval-Augmented Generation(RAG)을 구성하세요. 자세한 내용은 다음을 참조하세요: RAG API Configuration

참고: 기본 Docker 설정을 사용할 때 .env 파일은 LibreChat과 RAG API 간에 공유됩니다. 전체 구성 옵션은 RAG API 문서를 참조하세요.

음성 인식(Speech to Text) 및 음성 합성(Text to Speech)

Speech-to-Text (STT) 및 Text-to-Speech (TTS) 서비스를 구성합니다. 자세한 내용은 다음을 참조하세요: Speech Settings

참고: STT 및 TTS는 주로 librechat.yaml의 speech: 섹션을 통해 구성됩니다. 이러한 환경 변수는 해당 구성에서 참조됩니다. 전체 YAML 구성 옵션은 Speech Settings를 참조하세요.

공유 링크

공유 대화 링크 기능을 구성합니다.

ALLOW_SHARED_LINKS는 기능 전체에 대한 스위치입니다. 이제 역할 권한(Role permissions)을 통해 누가 공유 링크를 생성할 수 있는지, 인증된 사용자와 공유할 수 있는지, 또는 모든 사람에게 공개할 수 있는지 제어할 수 있습니다. interface.sharedLinks를 참조하세요. ALLOW_SHARED_LINKS_PUBLIC은 공개적으로 공유된 링크를 인증 없이 볼 수 있는지 여부만 제어합니다. SHARED_LINKS_SNAPSHOT_FILES는 공유 링크 파일 스냅샷에 대한 전역 재정의(global override)이며, false로 설정하면 모든 링크에 대해 스냅샷 제공을 비활성화할 수 있습니다.

사용자 시스템

이 섹션에는 다음을 위한 구성이 포함되어 있습니다:

• 자동화된 중재
• 잔액/토큰 사용량
• 등록 및 소셜 로그인
• 이메일 비밀번호 재설정

중재 (Moderation)

자동화된 조정 시스템(Automated Moderation System)은 점수 매기기 메커니즘을 사용하여 사용자 위반 사항을 추적합니다. 사용자가 과도한 로그인, 등록 또는 메시지 전송과 같은 행동을 하면 위반 점수가 누적됩니다. 설정된 임계값에 도달하면 해당 사용자와 IP는 일시적으로 차단됩니다. 이 시스템은 급격하거나 의심스러운 활동을 모니터링하고 제재함으로써 플랫폼 보안을 보장합니다.

참고: Automated Moderation

기본 조정 설정

차단 설정

로그인 및 등록 속도 제한

로그인 시도 및 신규 계정 등록 횟수를 제한하여 무차별 대입 공격(brute force attacks)과 스팸 등록을 방지합니다.

각 위반 사항에 대한 점수

참고: 브라우저를 통하지 않은 접근 및 비정상적인 모델 요청은 거의 항상 악의적인 것으로 간주되는데, 이는 제3자가 자동화된 스크립트를 통해 서버에 접근하려고 시도하고 있음을 의미합니다.

메시지 속도 제한 (사용자 및 IP별)

Limiters

참고: 두 제한기를 모두 활용할 수 있지만, 기본값은 IP로만 제한하는 것입니다.

IP Limiter:

사용자 제한기 (User Limiter):

대화 가져오기 속도 제한(rate limiting)

사용자가 대화를 가져올 수 있는 빈도를 제한하여 남용을 방지합니다.

참고: 두 제한기를 모두 활용할 수 있지만, 기본값은 IP로만 제한하는 것입니다.

IP Limiter:

사용자 제한기 (User Limiter):

대화 포킹(forking) 속도 제한

사용자가 대화를 포크(fork)할 수 있는 빈도를 제한하여 남용을 방지합니다.

참고: 두 제한기를 모두 활용할 수 있지만, 기본값은 IP로만 제한하는 것입니다.

IP Limiter:

사용자 제한기 (User Limiter):

파일 업로드 속도 제한

사용자가 파일을 업로드할 수 있는 빈도를 제한하여 남용을 방지합니다.

참고: 이 설정은 librechat.yaml의 rateLimits.fileUploads 섹션을 통해서도 구성할 수 있습니다.

IP Limiter:

사용자 제한기 (User Limiter):

TTS (Text-to-Speech) 속도 제한

사용자가 남용을 방지하기 위해 텍스트 음성 변환(Text-to-Speech)을 사용할 수 있는 빈도를 제한합니다.

참고: 이 설정은 librechat.yaml의 rateLimits.tts 섹션을 통해서도 구성할 수 있습니다.

IP Limiter:

사용자 제한기 (User Limiter):

STT (Speech-to-Text) 속도 제한

사용자가 음성 인식(Speech-to-Text) 기능을 남용하지 못하도록 사용 빈도를 제한합니다.

참고: 이 설정은 librechat.yaml의 rateLimits.stt 섹션을 통해서도 구성할 수 있습니다.

IP Limiter:

사용자 제한기 (User Limiter):

잔액

다음 기능은 시스템의 endpoint 내에서 사용자 잔액을 관리할 수 있게 해줍니다. 잔액을 수동으로 추가하거나, 사용자를 위해 자동으로 잔액을 누적하는 시스템을 구현할 수 있습니다. 구성에서 특정 초기 잔액이 정의된 경우, 사용자가 등록할 때 토큰이 사용자 잔액으로 자동 적립됩니다.

참고: Token Usage

잔액 관리

• npm run add-balance를 실행하여 잔액을 수동으로 추가하세요.
  • 또한 이메일과 추가할 토큰 크레딧 금액을 지정할 수도 있습니다. 예: npm run add-balance [email protected] 1000
• npm run set-balance를 실행하여 add-balance와 유사하게 잔액을 수동으로 설정합니다.
• npm run list-balances를 실행하여 모든 사용자의 잔액을 확인하세요.

참고: 1000 크레딧 = $0.001 (0.1 센트 USD)

등록 및 로그인

참고: Authentication System

• 일반 설정:

빠른 팁: 등록 기능이 비활성화된 경우에도 npm run create-user를 사용하여 데이터베이스에 사용자를 직접 추가할 수 있습니다.

빠른 팁: 등록 기능이 비활성화된 경우 npm run delete-user [email protected]을 사용하여 사용자를 삭제할 수 있습니다.

• 세션 및 리프레시 토큰 설정:

• 더 많은 정보는 다음을 참조하세요: Refresh Token

• JWT 설정:

새롭고 안전한 값을 사용해야 합니다. 제공된 예시는 32바이트 키(16진수 64자)입니다. 다음 replit을 사용하여 빠르게 생성할 수 있습니다: JWT Keys

소셜 로그인

더 자세한 내용은 다음을 참조하세요: OAuth2-OIDC

Apple 인증

더 자세한 정보는 다음을 참조하세요: Apple Authentication

Discord 인증

더 많은 정보를 원하시면: Discord

Facebook 인증

더 자세한 정보는 다음을 참조하세요: Facebook Authentication

GitHub 인증

더 자세한 정보는 다음을 참조하세요: GitHub Authentication

Google 인증

더 많은 정보를 원하시면: Google Authentication

OpenID Connect

더 많은 정보는 다음을 참조하세요:

• Auth0
• AWS Cognito
• Azure Entra/AD
• Keycloak

OpenID Connect 토큰 재사용

LibreChat은 사용자 인증 상태를 관리하기 위해 OpenID Connect 공급자(Azure Entra ID 또는 Auth0 등)가 발급한 액세스 및 새로 고침 토큰 재사용을 지원합니다. 이 기능이 활성화되면, 쿠키로 사용자에게 전달되는 새로 고침 토큰은 LibreChat이 아닌 귀하의 OpenID 공급자가 발급합니다.

OPENID_REUSE_MAX_SESSION_AGE_MS는 SESSION_EXPIRY와 같은 산술 표현식을 허용합니다. 공급자가 갱신 시 이전 액세스 토큰을 취소하는 경우, MCP 서버와 같은 다운스트림 소비자가 여전히 유효한 베어러 토큰을 계속 사용할 수 있도록 이 값을 IdP 액세스 토큰 수명에 가깝게 늘리십시오.

Microsoft Graph API / Entra ID 통합

Azure Entra ID(이전 명칭 Azure AD)를 OpenID 공급자로 사용할 때, 권한 및 공유 시스템 내에서 향상된 사용자 및 그룹 검색 기능을 위해 추가적인 Microsoft Graph API 기능을 활성화할 수 있습니다.

SharePoint 통합

LibreChat은 SharePoint Online 및 OneDrive for Business와의 직접적인 통합을 지원하여, 사용자가 대화 내에서 SharePoint 라이브러리의 파일을 직접 선택하고 첨부할 수 있도록 합니다. 이 엔터프라이즈 기능은 기존 Azure Entra ID 인증을 활용합니다.

자세한 SharePoint 구성 지침은 다음을 참조하세요: SharePoint Integration Guide

SAML

더 많은 정보는 다음을 참조하세요:

• Auth0

LDAP/AD 인증

더 자세한 정보는 다음을 참조하세요: LDAP/AD Authentication

비밀번호 재설정

이메일은 계정 인증 및 비밀번호 재설정에 사용됩니다. LibreChat은 Mailgun API와 기존 SMTP 서비스를 모두 지원합니다. 참조: Email setup

중요 참고: 이메일 기능을 사용하려면 Mailgun(SMTP를 차단하는 서버에 권장) 또는 SMTP 중 하나를 구성해야 합니다.

경고: Mailgun 또는 SMTP에 유효한 값을 설정하지 않으면 LibreChat이 보안되지 않은 비밀번호 재설정을 사용하게 됩니다!

Mailgun 구성 (권장)

Mailgun은 SMTP 포트를 차단하는 서버에 배포할 때 특히 유용합니다. MAILGUN_API_KEY와 MAILGUN_DOMAIN이 모두 설정되면, LibreChat은 SMTP 대신 Mailgun을 사용합니다.

SMTP 설정

Mailgun이 구성되지 않은 경우, LibreChat은 SMTP 설정으로 대체됩니다.

경고: EMAIL_SERVICE를 사용하는 경우, 다음의 확장 연결 매개변수를 설정하지 마십시오: HOST, PORT, ENCRYPTION, ENCRYPTION_HOSTNAME, ALLOW_SELFSIGNED.

참고: nodemailer well-known-services

Firebase CDN

참고: Firebase CDN Configuration

Amazon S3 및 CloudFront

참고: Amazon S3 구성 및 CloudFront와 S3

참고: Kubernetes 배포(예: EKS)의 경우, 명시적인 자격 증명을 제공하는 대신 IRSA(IAM Roles for Service Accounts)를 사용할 수 있습니다. 이 경우 AWS_REGION 및 AWS_BUCKET_NAME만 필요합니다.

Azure Blob Storage CDN

참고: Azure Blob Storage CDN 구성

참고: AZURE_STORAGE_CONNECTION_STRING(옵션 A) 또는 Managed Identity를 사용하는 AZURE_STORAGE_ACCOUNT_NAME(옵션 B) 중 하나만 사용하십시오. 두 가지를 동시에 사용해서는 안 됩니다.

UI

도움말 및 FAQ 버튼

동작:

정적 파일에 대한 Cache-Control 헤더를 설정합니다. 이 구성은 NODE_ENV가 production으로 설정된 경우에만 트리거됩니다.

캐시 헤더를 올바르게 설정하는 것은 웹 애플리케이션의 성능과 효율성을 최적화하는 데 매우 중요합니다. 브라우저와 CDN이 정적 파일의 복사본을 저장하는 기간을 제어함으로써 서버 부하를 크게 줄이고, 페이지 로드 시간을 단축하며, 전반적인 사용자 경험을 향상시킬 수 있습니다.

• STATIC_CACHE_MAX_AGE의 주석을 해제하여 정적 파일에 대한 max-age를 변경할 수 있습니다. 기본값은 4주로 설정되어 있습니다.
• STATIC_CACHE_S_MAX_AGE의 주석을 해제하여 정적 파일에 대한 s-maxage를 변경하세요. 기본값은 1주로 설정되어 있습니다.
  • 이는 CDN 및 프록시에서 사용하는 _shared cache_를 위한 것입니다.

앱 제목 및 푸터

동작:

• CUSTOM_FOOTER의 주석을 해제하여 사용자 지정 푸터를 추가하세요.
• CUSTOM_FOOTER의 주석을 해제하고 비워두면 푸터를 제거할 수 있습니다.
• You can now add one or more links in the CUSTOM_FOOTER value using the following format: [Anchor text](URL). Each link should be delineated with a pipe (|).

Markdown 예시: CUSTOM_FOOTER=[Link 1](http://example1.com) | [Link 2](http://example2.com)

생일 모자

동작:

• 생일 모자 아이콘은 2월 11일(LibreChat의 생일)에 자동으로 표시됩니다.
• SHOW_BIRTHDAY_ICON을 false로 설정하여 생일 모자 아이콘을 비활성화하세요.
• SHOW_BIRTHDAY_ICON을 true로 설정하면 생일 모자를 항상 표시할 수 있습니다.

분석

Google Tag Manager

LibreChat은 분석을 위해 Google Tag Manager를 지원합니다. LibreChat에서 이를 활성화하려면 Google Tag Manager ID가 필요합니다. 이 가이드를 따라 Google Tag Manager ID를 생성하고 Google Analytics를 구성하세요. 그런 다음 ANALYTICS_GTM_ID 환경 변수를 귀하의 Google Tag Manager ID로 설정하세요.

참고: ANALYTICS_GTM_ID가 설정되지 않은 경우, Google Tag Manager는 활성화되지 않습니다. 잘못 설정된 경우, gtm.js에 대한 요청 실패가 발생합니다.

대화 가져오기

메모리 문제를 방지하기 위해 대화 파일 가져오기 제한을 구성하세요.

인라인 파일 미리보기

LibreChat이 인라인 미리보기 추출을 건너뛰고 다운로드 전용으로 남겨둘 생성된 파일의 최대 크기를 제어합니다.

MCP (Model Context Protocol)

향상된 서버 관리 및 OAuth 지원을 위해 MCP 설정을 구성하세요.

MCP Server Configuration

기타

Redis

Redis는 LibreChat에 상당한 성능 향상을 제공하며 수평적 확장 기능을 가능하게 합니다.

참고: Redis 지원은 실험적인 기능이므로, 사용 시 몇 가지 문제가 발생할 수 있습니다.

중요: Redis를 사용하는 경우, LibreChat 설정을 변경한 후에는 캐시를 비워야 합니다.

자세한 구성 및 예시는 다음을 참조하세요: Redis Configuration Guide

참고:

• USE_REDIS=true일 때, REDIS_URI를 제공해야 하며 그렇지 않으면 애플리케이션에서 오류가 발생합니다.
• Redis Cluster 모드의 경우, 여러 개의 URI를 제공하십시오: redis://node1:7001,redis://node2:7002,redis://node3:7003 (클러스터 모드는 자동으로 감지됩니다).
• 내부적으로 키를 샤딩하는 단일 엔드포인트 관리형 Redis 서비스의 경우, USE_REDIS_CLUSTER=false를 유지하고 캐시 삭제 시 CROSSSLOT 오류가 발생하면 REDIS_CLUSTER_SAFE_DELETE=true로 설정하십시오.
• TLS 연결에는 rediss:// 프로토콜을 사용하고, CA가 공개적으로 신뢰되지 않는 경우 REDIS_CA를 설정하세요.
• REDIS_KEY_PREFIX_VAR와 REDIS_KEY_PREFIX는 상호 배타적입니다.
• AWS Elasticache with TLS: Elasticache는 TLS 연결을 위해 대체 dnsLookup을 사용해야 할 수 있습니다. TLS가 적용된 Elasticache를 사용하는 경우 REDIS_USE_ALTERNATIVE_DNS_LOOKUP=true로 설정하세요. 자세한 내용은 ioredis documentation을 참조하세요.

리더 선출 (Leader Election)

Redis를 사용하여 다중 인스턴스 배포를 위한 분산 리더 선출(distributed leader election)을 구성하세요. 리더 선출은 예약된 작업과 같은 특정 작업을 하나의 인스턴스만 수행하도록 보장합니다.

참고:

• 리더 선출(Leader election)을 사용하려면 Redis가 활성화(USE_REDIS=true)되어 있어야 합니다.
• 이 설정은 다중 인스턴스 배포에만 관련이 있습니다.
• 리더십을 유지하려면 만료되기 전에 리더 임대(leader lease)를 갱신해야 합니다.
• 최대 시도 횟수 이후에도 임대 갱신에 실패하면, 해당 인스턴스는 리더십을 포기합니다.