LibreChat 관리자 패널

LibreChat 관리자 패널은 LibreChat을 위한 독립형 브라우저 기반 관리 인터페이스입니다. 이 패널은 LibreChat과 동일한 데이터베이스에 연결되며, 세분화된 액세스 제어를 구동하는 관리 작업을 위한 GUI를 제공합니다. 여기에는 사용자 및 그룹 관리, 역할 관리, 역할 또는 그룹별로 범위가 지정된 구성 재정의, 시스템 수준의 기능 권한 부여가 포함됩니다.

기능 설명

관리자 패널은 씬 클라이언트(thin client)입니다. 모든 데이터는 LibreChat의 데이터베이스에 저장되며, 모든 작업은 LibreChat API 서버의 버전이 지정된 /api/admin/* 엔드포인트를 통해 이루어집니다. 이를 통해 관리자는 다음 작업을 한곳에서 수행할 수 있습니다.

• 구성 관리: 동적 스키마 기반 폼을 통해 모든 LibreChat 설정을 확인하고 편집하세요. 구성 스키마에 추가된 새 필드는 관리자 패널 릴리스 없이도 자동으로 나타납니다.
• 주체별 재정의 적용: 구성 재정의 범위를 특정 역할이나 그룹으로 지정하며, 사용자가 로그인할 때 각 사용자에게 적용될 최종 값을 결정하는 우선순위 기반의 계단식 방식을 사용합니다.
• 사용자 관리: 인스턴스의 모든 계정을 나열, 검색 및 조회합니다.
• 그룹 관리: 그룹 생성 및 삭제, 멤버 추가/제거, 그리고 ACL 및 재정의(overrides)에서 그룹을 일급 주체(first-class principals)로 사용합니다.
• 역할 관리: 내장된 USER / ADMIN 외에 사용자 지정 역할을 생성하고, 기능 권한 매트릭스를 편집하며, 사용자에게 역할을 할당합니다.
• Issue system grants: 특정 사용자, 그룹 또는 역할에 전체 관리자 권한을 부여하지 않고도 관리 기능(예: manage:users, read:usage, manage:mcpservers)을 위임합니다.
• Authenticate: 로컬 LibreChat 관리자 계정으로 로그인하거나, LibreChat 인스턴스에서 활성화된 경우 OpenID SSO / SAML / 지원되는 OAuth 제공업체를 통해 로그인합니다.

기본 권한 모델(주체, 리소스 ACL, 기능 및 계층 구성 방식)에 대해서는 Access Control 페이지를 참조하세요.

아키텍처

┌──────────────────┐         ┌──────────────────┐         ┌──────────────┐
│  Admin Panel     │ ───────▶│  LibreChat API   │ ───────▶│   MongoDB    │
│  (Bun + Vite)    │  HTTPS  │  /api/admin/*    │         │  (shared DB) │
└──────────────────┘         └──────────────────┘         └──────────────┘
       │                             │
       │ OAuth/OIDC/SAML redirect    │ Verifies admin access
       └─────────────────────────────┘

관리자 패널은 별도의 서비스로 실행되며, LibreChat과 프로세스를 공유하지 않습니다. 관리자 기능은 access:admin 시스템 권한 또는 SystemRoles.ADMIN 역할을 통해 LibreChat 측에서 검증되므로, 패널이 스스로 권한을 부여할 수 없습니다.

LibreChat이 노출하는 관리자 API 표면은 다음과 같습니다:

시작하기

필수 조건

• v0.8.5 이상에서 실행 중인 LibreChat 인스턴스 (이전 버전에서는 관리자 API를 사용할 수 없음)
• admin-panel 컨테이너/호스트에서 LibreChat API로의 네트워크 액세스
• LibreChat의 관리자 계정: 최초 등록된 사용자(자동 관리자), Mongo에서 role: 'ADMIN'으로 설정된 사용자, 또는 access:admin 권한이 부여된 주체 중 하나입니다.

LibreChat과 함께 번들 제공 (권장)

공식 docker-compose.yml 또는 deploy-compose.yml을 사용하여 LibreChat을 실행하면, 관리자 패널이 서비스로 함께 제공되어 LibreChat과 동시에 자동으로 시작됩니다. 별도의 배포는 필요하지 않습니다.

스택을 시작하기 전에 LibreChat의 .env 파일에 패널의 세션 시크릿을 설정하세요. compose 파일은 이를 패널의 SESSION_SECRET으로 전달합니다:

# Min 32 characters. Generate with: openssl rand -hex 32
ADMIN_PANEL_SESSION_SECRET=replace-with-a-32-char-random-string

# Optional: host port for the default docker-compose
# ADMIN_PANEL_PORT=3000

# Optional: set true when the panel is served over HTTPS
# ADMIN_PANEL_SESSION_COOKIE_SECURE=false

compose 파일은 나머지를 자동으로 연결합니다: API_SERVER_URL은 api 서비스를 가리키고, VITE_API_BASE_URL은 브라우저 대상 OAuth 리디렉션을 위해 DOMAIN_CLIENT를 따르며, ADMIN_PANEL_URL은 LibreChat이 SSO 이후 관리자를 패널로 다시 안내하도록 설정됩니다. 이를 사용하지 않으려면 admin-panel 서비스를 제거하거나 Compose profiles 항목 뒤에 배치하여 제한하십시오.

Standalone (별도 배포)

관리자 패널을 별도로 호스팅하여 다른 곳에서 실행 중인 LibreChat 인스턴스를 가리키도록 하려면, GHCR에서 게시된 이미지를 사용하세요:

# 1. Create an env file
cp .env.example .env

# 2. Edit .env and set at minimum:
#    SESSION_SECRET=<random string, min 32 characters>
#    VITE_API_BASE_URL=http://host.docker.internal:3080

# 3. Start it
docker compose up -d   # http://localhost:3000
docker compose down    # stop

독립형 docker run:

docker run -p 3000:3000 \
  --add-host=host.docker.internal:host-gateway \
  -e SESSION_SECRET=replace-with-32-char-random-string \
  -e VITE_API_BASE_URL=http://host.docker.internal:3080 \
  ghcr.io/clickhouse/librechat-admin-panel:latest

개발을 위해 로컬에서 실행하기

git clone https://github.com/ClickHouse/librechat-admin-panel.git
cd librechat-admin-panel
cp .env.example .env    # then edit
bun install
bun dev                 # http://localhost:3000

환경 변수

LibreChat의 번들 Docker 스택에서 관리자 패널은 admin-panel 서비스로 실행됩니다. 기본 docker-compose.yml은 이를 ADMIN_PANEL_PORT로 노출하며, deploy-compose.yml은 nginx를 통해 http://admin.localhost로 라우팅하고 API 서비스를 위해 ADMIN_PANEL_URL을 설정합니다.

LibreChat 리디렉션 URL

관리자 패널이 LibreChat과 별도의 URL에서 호스팅되는 경우, LibreChat API 환경에서 ADMIN_PANEL_URL을 설정하세요. 경로 접두사를 포함한 외부 관리자 패널의 기본 URL을 사용하고, 마지막 슬래시는 생략하세요:

ADMIN_PANEL_URL=https://admin.example.com/admin

Helm 배포의 경우, values 파일에서 librechat.adminPanelUrl을 설정하세요. 차트는 이를 LibreChat의 관리자 OAuth 흐름을 위한 ADMIN_PANEL_URL로 렌더링합니다:

librechat:
  adminPanelUrl: https://admin.example.com/admin

OpenID SSO를 사용하려면 ${DOMAIN_SERVER}/api/admin/oauth/openid/callback을 귀하의 ID 공급자(identity provider)에 등록하십시오.

캐시 제어 (Cache Controls)

이 설정들은 LibreChat의 캐시 환경 변수를 미러링합니다. ADMIN_PANEL_* 변수가 우선순위를 가지며, 설정되지 않은 경우 공유되는 LibreChat 대응 변수로 대체됩니다.

인증

관리자 패널은 LibreChat의 인증 스택을 재사용하며 자체 사용자 데이터베이스를 가지고 있지 않습니다. 두 가지 로그인 경로가 지원됩니다:

• 로컬 계정: 관리자 액세스 확인을 통과한 모든 LibreChat 사용자의 사용자 이름/비밀번호입니다.
• Single sign-on: OpenID Connect, SAML 및 LibreChat 인스턴스에 이미 구성된 소셜 OAuth 제공업체입니다. 비밀번호 양식을 완전히 숨기려면 ADMIN_SSO_ONLY=true로 설정하세요.

LibreChat은 모든 요청에 대해 서버 측에서 관리자 권한을 확인합니다. 계정은 다음 중 하나여야 합니다:

1. MongoDB에서 role: 'ADMIN'을 가지고 있거나, 또는
2. access:admin 시스템 권한을 보유해야 합니다 (관리자 패널 자체를 통해 다른 주체에게 할당됨; System Grants 참조).

세션은 쿠키 기반이며, SESSION_SECRET으로 암호화되고, ADMIN_SESSION_IDLE_TIMEOUT_MS에 따라 유휴 상태에서 만료됩니다.

구성 관리

이 패널은 LibreChat 설정을 설정 스키마에 의해 구동되는 동적 폼으로 렌더링합니다. 여기에는 두 가지 유용한 속성이 있습니다:

• Forward-compatible: LibreChat이 새로운 설정 필드를 출시하면, 패널이 스키마에서 이를 자동으로 감지합니다. 관리자 패널 업그레이드나 재배포가 필요하지 않습니다.
• 계층형 재정의(Layered overrides): 기본 설정(librechat.yaml에서 가져옴)은 역할 또는 그룹별로 범위가 지정된 주체별(per-principal) 재정의에 의해 가려질 수 있습니다. 사용자가 로그인하면 재정의가 우선순위에 따라 해결되고 기본 설정 위에 병합되어 해당 사용자가 보게 될 최종 설정이 생성됩니다.

이것은 LibreChat의 DB-backed per-principal configuration override system을 뒷받침하는 표면입니다. 일반적인 사용 사례는 다음과 같습니다:

• "Research" 그룹에 더 높은 recursionLimit와 추가적인 endpoint를 부여하세요
• "FinanceAdmins" 역할이 MCP 서버를 관리하게 하고 일반 사용자는 이를 사용만 할 수 있도록 설정하세요.
• 외부 계약자 그룹에 대해 더 엄격한 interface 권한을 적용하세요

관련 항목

• Access Control: 관리자 패널이 기반으로 하는 권한 모델
• Interface Configuration: 패널이 편집하는 기능 플래그
• Authentication: LibreChat 사용자 인증
• v0.8.5 변경 로그: admin API 기반 마련
• GitHub: ClickHouse/librechat-admin-panel: 소스, 이슈, 릴리스