LibreChat Admin-Panel

Das LibreChat Admin Panel ist eine eigenständige, browserbasierte Verwaltungsoberfläche für LibreChat. Sie verbindet sich mit derselben Datenbank wie LibreChat selbst und bietet eine grafische Benutzeroberfläche für die administrativen Aufgaben, die die granulare Zugriffskontrolle ermöglichen: Benutzer- und Gruppenverwaltung, Rollenmanagement, Konfigurationsüberschreibungen mit Gültigkeitsbereich für Rollen oder Gruppen sowie die Vergabe von Berechtigungen auf Systemebene.

Was es bewirkt

Das Admin-Panel ist ein Thin Client: Alle Daten befinden sich in der Datenbank von LibreChat, und jede Aktion erfolgt über die versionierten /api/admin/* Endpoints auf dem LibreChat API-Server. Es bietet Administratoren einen zentralen Ort, um:

• Konfiguration verwalten: Zeigen Sie alle LibreChat-Einstellungen über ein dynamisches, schema-basiertes Formular an und bearbeiten Sie diese. Neue Felder, die dem Konfigurationsschema hinzugefügt werden, erscheinen automatisch; eine Veröffentlichung des Admin-Panels ist nicht erforderlich.
• Anwendung von Überschreibungen pro Principal: Begrenzen Sie Konfigurationsüberschreibungen auf bestimmte Rollen oder Gruppen, mit einer prioritätsbasierten Kaskade, die den endgültigen aufgelösten Wert bestimmt, den jeder Benutzer bei der Anmeldung sieht.
• Benutzer verwalten: Alle Konten auf der Instanz auflisten, suchen und anzeigen.
• Gruppen verwalten: Gruppen erstellen und löschen, Mitglieder hinzufügen/entfernen und Gruppen als erstklassige Prinzipale in ACLs und Overrides verwenden.
• Rollen verwalten: Erstellen Sie benutzerdefinierte Rollen über die integrierten USER / ADMIN hinaus, bearbeiten Sie deren Funktionsberechtigungsmatrix und weisen Sie Benutzern Rollen zu.
• Issue system grants: Delegieren Sie Administrator-Funktionen (z. B. manage:users, read:usage, manage:mcpservers) an bestimmte Benutzer, Gruppen oder Rollen, ohne ihnen volle Administratorrechte zu erteilen.
• Authentifizierung: Melden Sie sich mit einem lokalen LibreChat-Administratorkonto an oder über OpenID SSO / SAML / unterstützte OAuth-Anbieter, sofern diese auf der LibreChat-Instanz aktiviert sind.

Für das zugrunde liegende Berechtigungsmodell (Principals, Ressourcen-ACLs, Capabilities und wie sich die Ebenen zusammensetzen), siehe die Seite Access Control.

Architektur

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

Das Admin-Panel läuft als separater Dienst; es teilt sich keinen Prozess mit LibreChat. Admin-Funktionen werden auf der LibreChat-Seite über die access:admin-Systemberechtigung oder die SystemRoles.ADMIN-Rolle verifiziert, sodass das Panel sich selbst keine Privilegien gewähren kann, die es nicht haben sollte.

Die von LibreChat bereitgestellte Admin-API-Oberfläche ist:

Erste Schritte

Voraussetzungen

• Eine laufende LibreChat-Instanz auf v0.8.5 oder höher (Admin-APIs sind in früheren Versionen nicht verfügbar)
• Netzwerkzugriff vom admin-panel Container/Host auf die LibreChat API
• Ein Admin-Konto auf LibreChat: entweder der zuerst registrierte Benutzer (Auto-Admin), ein Benutzer mit role: 'ADMIN', der in Mongo festgelegt wurde, oder ein Principal, dem die access:admin-Berechtigung erteilt wurde.

Gebündelt mit LibreChat (empfohlen)

Wenn Sie LibreChat mit der offiziellen docker-compose.yml oder deploy-compose.yml ausführen, wird das Admin-Panel als Dienst mitgeliefert und startet automatisch zusammen mit LibreChat -- es ist keine separate Bereitstellung erforderlich.

Legen Sie das Session-Secret des Panels in der .env von LibreChat fest, bevor Sie den Stack starten; die compose-Dateien übergeben es als SESSION_SECRET des Panels:

# 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

Die Compose-Dateien verknüpfen den Rest automatisch: API_SERVER_URL verweist auf den api-Dienst, VITE_API_BASE_URL folgt DOMAIN_CLIENT für browserseitige OAuth-Weiterleitungen, und ADMIN_PANEL_URL ist so eingestellt, dass LibreChat Administratoren nach dem SSO zum Panel zurückleitet. Um dies zu deaktivieren, entfernen Sie den admin-panel-Dienst oder schützen Sie ihn durch einen Compose profiles-Eintrag.

Standalone (separate deployment)

Um das Admin-Panel separat zu hosten – und auf eine anderweitig laufende LibreChat-Instanz zu verweisen –, verwenden Sie das veröffentlichte Image von 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

Eigenständiges 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

Lokal für die Entwicklung ausführen

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

Umgebungsvariablen

In den gebündelten Docker-Stacks von LibreChat läuft das Admin-Panel als admin-panel-Dienst. Die standardmäßige docker-compose.yml macht es über ADMIN_PANEL_PORT verfügbar; deploy-compose.yml leitet es über nginx unter http://admin.localhost weiter und setzt ADMIN_PANEL_URL für den API-Dienst.

LibreChat Redirect-URL

Wenn das Admin-Panel unter einer separaten URL von LibreChat gehostet wird, setzen Sie ADMIN_PANEL_URL in der LibreChat API-Umgebung. Verwenden Sie die externe Basis-URL des Admin-Panels, einschließlich eines eventuellen Pfad-Präfixes, und lassen Sie den abschließenden Schrägstrich weg:

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

Für Helm-Deployments setzen Sie librechat.adminPanelUrl in Ihrer values-Datei. Das Chart rendert dies als ADMIN_PANEL_URL für den Admin-OAuth-Flow von LibreChat:

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

Für OpenID SSO registrieren Sie ${DOMAIN_SERVER}/api/admin/oauth/openid/callback bei Ihrem Identitätsanbieter.

Cache-Steuerung

Diese spiegeln die Cache-Umgebungsvariablen von LibreChat wider. ADMIN_PANEL_*-Varianten haben Vorrang und greifen auf die gemeinsam genutzten LibreChat-Äquivalente zurück, wenn sie nicht gesetzt sind.

Authentifizierung

Das Admin-Panel verwendet den Authentifizierungs-Stack von LibreChat wieder und verfügt über keine eigene Benutzerdatenbank. Es werden zwei Anmeldepfade unterstützt:

• Lokale Konten: Benutzername/Passwort für jeden LibreChat-Benutzer, dessen Konto die Admin-Zugriffsprüfung besteht.
• Single sign-on: OpenID Connect, SAML und die Social-OAuth-Anbieter, die bereits auf Ihrer LibreChat-Instanz konfiguriert sind. Setzen Sie ADMIN_SSO_ONLY=true, um das Passwort-Formular vollständig auszublenden.

Der Administratorzugriff wird von LibreChat für jede Anfrage serverseitig überprüft. Das Konto muss entweder:

1. Haben Sie role: 'ADMIN' in MongoDB, oder
2. Sie müssen über die access:admin Systemberechtigung verfügen (die einem anderen Principal über das Admin-Panel selbst zugewiesen wurde; siehe System Grants).

Sitzungen sind cookie-basiert, mit SESSION_SECRET verschlüsselt und laufen bei Inaktivität gemäß ADMIN_SESSION_IDLE_TIMEOUT_MS ab.

Konfigurationsverwaltung

Das Panel rendert die LibreChat-Konfiguration als dynamisches Formular, das durch das Konfigurationsschema gesteuert wird. Dies hat zwei nützliche Eigenschaften:

• Vorwärtskompatibel: Wenn LibreChat ein neues Konfigurationsfeld einführt, übernimmt das Panel dieses automatisch aus dem Schema. Ein Upgrade oder eine erneute Bereitstellung des Admin-Panels ist nicht erforderlich.
• Layered overrides: Die Basiskonfiguration (aus librechat.yaml) kann durch prinzipalspezifische Overrides überschrieben werden, die auf eine Rolle oder Gruppe beschränkt sind. Wenn sich ein Benutzer anmeldet, werden die Overrides in der Prioritätsreihenfolge aufgelöst und mit der Basis zusammengeführt, um die effektive Konfiguration zu erstellen, die der Benutzer sieht.

Dies ist die Oberfläche hinter dem DB-gestützten Konfigurations-Override-System pro Principal von LibreChat. Typische Anwendungsfälle:

• Geben Sie einer "Research"-Gruppe ein höheres recursionLimit und zusätzliche endpoints
• Lassen Sie eine "FinanceAdmins"-Rolle MCP-Server verwalten, während normale Benutzer diese nur verwenden können
• Beschränken Sie strengere interface-Berechtigungen auf externe Auftragnehmergruppen

Verwandt

• Access Control: das Berechtigungsmodell, auf dem das Admin-Panel basiert
• Interface Configuration: die Feature-Flags, die das Panel bearbeitet
• Authentication: Benutzerauthentifizierung in LibreChat
• v0.8.5 Changelog: Grundlagen der Admin-API
• GitHub: ClickHouse/librechat-admin-panel: Quelle, Issues, Releases