Panneau d'administration LibreChat

Le Panneau d'administration LibreChat est une interface de gestion autonome basée sur navigateur pour LibreChat. Il se connecte à la même base de données que LibreChat lui-même et fournit une interface graphique pour les tâches administratives qui alimentent le contrôle d'accès granulaire : administration des utilisateurs et des groupes, gestion des rôles, remplacements de configuration étendus aux rôles ou aux groupes, et octroi de capacités au niveau du système.

Ce qu'il fait

Le panneau d'administration est un client léger : toutes les données résident dans la base de données de LibreChat, et chaque action passe par les endpoints versionnés /api/admin/* sur le serveur API de LibreChat. Il offre aux administrateurs un emplacement unique pour :

• Gérer la configuration : affichez et modifiez chaque paramètre de LibreChat via un formulaire dynamique basé sur un schéma. Les nouveaux champs ajoutés au schéma de configuration apparaissent automatiquement, sans nécessiter de nouvelle version du panneau d'administration.
• Appliquer des remplacements par principal : limitez les remplacements de configuration à des rôles ou des groupes spécifiques, avec une cascade basée sur la priorité qui détermine la valeur finale résolue que chaque utilisateur voit lors de la connexion.
• Administrer les utilisateurs : lister, rechercher et consulter chaque compte sur l'instance.
• Gérer les groupes : créer et supprimer des groupes, ajouter/supprimer des membres, et utiliser les groupes en tant que principaux de premier ordre dans les ACL et les remplacements (overrides).
• Gérer les rôles : créez des rôles personnalisés au-delà des rôles intégrés USER / ADMIN, modifiez leur matrice de permissions de fonctionnalités et attribuez des utilisateurs aux rôles.
• Attribution de systèmes de droits : déléguez des capacités d'administration (par ex. manage:users, read:usage, manage:mcpservers) à des utilisateurs, groupes ou rôles spécifiques sans leur accorder le statut d'administrateur complet.
• Authentification : connectez-vous avec un compte administrateur local LibreChat, ou via OpenID SSO / SAML / les fournisseurs OAuth pris en charge lorsque ceux-ci sont activés sur l'instance LibreChat.

Pour le modèle de permission sous-jacent (principaux, ACL de ressources, capacités et comment les couches se composent), consultez la page Access Control.

Architecture

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

Le panneau d'administration s'exécute en tant que service distinct ; il ne partage pas de processus avec LibreChat. Les capacités d'administration sont vérifiées du côté de LibreChat via l'autorisation système access:admin ou le rôle SystemRoles.ADMIN, de sorte que le panneau ne peut pas s'octroyer lui-même des privilèges qu'il ne devrait pas avoir.

La surface de l'API d'administration exposée par LibreChat est :

Démarrage

Prérequis

• Une instance LibreChat en cours d'exécution sur la v0.8.5 ou une version ultérieure (les API d'administration ne sont pas disponibles dans les versions antérieures)
• Accès réseau depuis le conteneur/hôte admin-panel vers l'API LibreChat
• Un compte administrateur sur LibreChat : soit le premier utilisateur enregistré (auto-admin), un utilisateur avec role: 'ADMIN' défini dans Mongo, ou un principal auquel la capacité access:admin a été accordée.

Inclus avec LibreChat (recommandé)

Si vous exécutez LibreChat avec son docker-compose.yml ou deploy-compose.yml officiel, le panneau d'administration est fourni en tant que service et démarre automatiquement avec LibreChat -- aucun déploiement séparé n'est nécessaire.

Définissez le secret de session du panneau dans le fichier .env de LibreChat avant de démarrer la stack ; les fichiers compose le transmettent en tant que SESSION_SECRET du panneau :

# 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

Les fichiers compose connectent automatiquement le reste : API_SERVER_URL pointe vers le service api, VITE_API_BASE_URL suit DOMAIN_CLIENT pour les redirections OAuth côté navigateur, et ADMIN_PANEL_URL est défini afin que LibreChat renvoie les administrateurs vers le panneau après une connexion SSO. Pour désactiver cette option, supprimez le service admin-panel ou protégez-le derrière une entrée profiles de Compose.

Standalone (déploiement séparé)

Pour héberger le panneau d'administration séparément -- pointé vers une instance LibreChat s'exécutant ailleurs -- utilisez l'image publiée depuis 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 autonome :

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

Exécuter localement pour le développement

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

Variables d'environnement

Dans les piles Docker fournies avec LibreChat, le panneau d'administration s'exécute en tant que service admin-panel. Le fichier docker-compose.yml par défaut l'expose sur ADMIN_PANEL_PORT ; deploy-compose.yml le dirige via nginx sur http://admin.localhost et définit ADMIN_PANEL_URL pour le service API.

URL de redirection LibreChat

Lorsque le panneau d'administration est hébergé sur une URL distincte de LibreChat, définissez ADMIN_PANEL_URL dans l'environnement de l'API LibreChat. Utilisez l'URL de base externe du panneau d'administration, incluant tout préfixe de chemin, et omettez la barre oblique finale :

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

Pour les déploiements Helm, définissez librechat.adminPanelUrl dans votre fichier values. Le chart le rend sous la forme ADMIN_PANEL_URL pour le flux OAuth d'administration de LibreChat :

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

Pour OpenID SSO, enregistrez ${DOMAIN_SERVER}/api/admin/oauth/openid/callback auprès de votre fournisseur d'identité.

Contrôles du cache

Ceux-ci reflètent les variables d'environnement de cache de LibreChat. Les variantes ADMIN_PANEL_* sont prioritaires et reviennent aux équivalents partagés de LibreChat lorsqu'elles ne sont pas définies.

Authentification

Le panneau d'administration réutilise la pile d'authentification de LibreChat et ne possède pas sa propre base de données d'utilisateurs. Deux chemins de connexion sont pris en charge :

• Comptes locaux : nom d'utilisateur/mot de passe pour tout utilisateur LibreChat dont le compte réussit la vérification d'accès administrateur.
• Single sign-on : OpenID Connect, SAML, et les fournisseurs OAuth sociaux déjà configurés sur votre instance LibreChat. Définissez ADMIN_SSO_ONLY=true pour masquer entièrement le formulaire de mot de passe.

L'accès administrateur est vérifié côté serveur par LibreChat pour chaque requête. Le compte doit soit :

1. Avoir role: 'ADMIN' dans MongoDB, ou
2. Détenir l'autorisation système access:admin (attribuée à un autre mandataire via le panneau d'administration lui-même ; voir System Grants).

Les sessions sont basées sur des cookies, chiffrées avec SESSION_SECRET, et expirent en cas d'inactivité selon ADMIN_SESSION_IDLE_TIMEOUT_MS.

Gestion de la configuration

Le panneau affiche la configuration de LibreChat sous forme de formulaire dynamique piloté par le schéma de configuration. Cela présente deux propriétés utiles :

• Compatible avec les versions futures : lorsqu'une nouvelle configuration est ajoutée à LibreChat, le panneau la détecte automatiquement à partir du schéma. Aucune mise à jour ou redéploiement du panneau d'administration n'est nécessaire.
• Remplacements en couches : la configuration de base (issue de librechat.yaml) peut être masquée par des remplacements par mandant (principal) limités à un rôle ou à un groupe. Lorsqu'un utilisateur se connecte, les remplacements sont résolus par ordre de priorité et fusionnés sur la base pour produire la configuration effective que l'utilisateur voit.

Ceci est l'interface derrière le système de remplacement de configuration par principal basé sur une base de données de LibreChat. Cas d'utilisation typiques :

• Donner à un groupe "Research" une valeur recursionLimit plus élevée et des endpoints supplémentaires
• Permettre à un rôle "FinanceAdmins" de gérer les serveurs MCP tandis que les utilisateurs réguliers peuvent seulement les utiliser
• Restreindre les permissions d' interface aux groupes de contractants externes

Connexe

• Access Control : le modèle de permission sur lequel le panneau d'administration est construit
• Configuration de l'interface : les indicateurs de fonctionnalités que le panneau modifie
• Authentication : authentification des utilisateurs sur LibreChat
• changelog v0.8.5 : fondations de l'API admin
• GitHub: ClickHouse/librechat-admin-panel : source, problèmes, versions