Panel de administración de LibreChat

El LibreChat Admin Panel es una interfaz de gestión independiente basada en navegador para LibreChat. Se conecta a la misma base de datos que LibreChat y proporciona una GUI para las tareas administrativas que potencian el control de acceso granular: administración de usuarios y grupos, gestión de roles, anulaciones de configuración con alcance a roles o grupos, y concesiones de capacidades a nivel de sistema.

Qué hace

El panel de administración es un cliente ligero: todos los datos residen en la base de datos de LibreChat, y cada acción pasa por los endpoints versionados /api/admin/* en el servidor de la API de LibreChat. Ofrece a los administradores un lugar único para:

• Gestionar configuración: vea y edite cada configuración de LibreChat a través de un formulario dinámico basado en esquemas. Los nuevos campos añadidos al esquema de configuración aparecen automáticamente, sin necesidad de una versión del panel de administración.
• Aplicar anulaciones por principal: limite las anulaciones de configuración a roles o grupos específicos, con una cascada basada en prioridades que determina el valor final resuelto que cada usuario ve al iniciar sesión.
• Administrar usuarios: listar, buscar y ver cada cuenta en la instancia.
• Gestionar grupos: crear y eliminar grupos, añadir/eliminar miembros y utilizar grupos como entidades de primer nivel en ACL y anulaciones.
• Gestionar roles: cree roles personalizados más allá de los integrados USER / ADMIN, edite su matriz de permisos de funciones y asigne usuarios a los roles.
• Emisión de concesiones del sistema: delegue capacidades de administración (por ejemplo, manage:users, read:usage, manage:mcpservers) a usuarios, grupos o roles específicos sin convertirlos en administradores completos.
• Autenticación: inicie sesión con una cuenta de administrador local de LibreChat, o mediante SSO de OpenID / SAML / proveedores de OAuth compatibles cuando estos estén habilitados en la instancia de LibreChat.

Para conocer el modelo de permisos subyacente (principales, ACL de recursos, capacidades y cómo se componen las capas), consulte la página Access Control.

Arquitectura

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

El panel de administración se ejecuta como un servicio independiente; no comparte proceso con LibreChat. Las capacidades de administración se verifican en el lado de LibreChat mediante la concesión del sistema access:admin o el rol SystemRoles.ADMIN, por lo que el panel no puede otorgarse a sí mismo privilegios que no debería tener.

La superficie de la API de administración expuesta por LibreChat es:

Primeros pasos

Requisitos previos

• Una instancia de LibreChat en ejecución en la v0.8.5 o posterior (las APIs de administración no están disponibles en versiones anteriores)
• Acceso de red desde el contenedor/host del admin-panel a la API de LibreChat
• Una cuenta de administrador en LibreChat: ya sea el primer usuario registrado (auto-admin), un usuario con role: 'ADMIN' configurado en Mongo, o un principal al que se le haya otorgado la capacidad access:admin

Incluido con LibreChat (recomendado)

Si ejecutas LibreChat con su docker-compose.yml o deploy-compose.yml oficial, el panel de administración se incluye como un servicio y se inicia automáticamente junto con LibreChat; no se requiere una implementación por separado.

Establezca el secreto de sesión del panel en el archivo .env de LibreChat antes de iniciar la pila; los archivos compose lo pasan como el SESSION_SECRET del panel:

# 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

Los archivos compose conectan el resto automáticamente: API_SERVER_URL apunta al servicio api, VITE_API_BASE_URL sigue a DOMAIN_CLIENT para las redirecciones OAuth orientadas al navegador, y ADMIN_PANEL_URL se configura para que LibreChat devuelva a los administradores al panel después del SSO. Para optar por no participar, elimine el servicio admin-panel o protéjalo detrás de una entrada de profiles de Compose.

Standalone (despliegue independiente)

Para alojar el panel de administración por su cuenta (apuntando a una instancia de LibreChat que se ejecuta en otro lugar), utilice la imagen publicada desde 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 independiente:

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

Ejecutar localmente para desarrollo

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 de entorno

En las pilas de Docker incluidas en LibreChat, el panel de administración se ejecuta como un servicio admin-panel. El docker-compose.yml predeterminado lo expone en ADMIN_PANEL_PORT; deploy-compose.yml lo enruta a través de nginx en http://admin.localhost y establece ADMIN_PANEL_URL para el servicio de API.

URL de redirección de LibreChat

Cuando el panel de administración se aloja en una URL separada de LibreChat, configure ADMIN_PANEL_URL en el entorno de la API de LibreChat. Utilice la URL base externa del panel de administración, incluyendo cualquier prefijo de ruta, y omita la barra diagonal final:

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

Para despliegues con Helm, configure librechat.adminPanelUrl en su archivo values. El chart lo renderiza como ADMIN_PANEL_URL para el flujo de OAuth de administración de LibreChat:

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

Para OpenID SSO, registre ${DOMAIN_SERVER}/api/admin/oauth/openid/callback con su proveedor de identidad.

Controles de caché

Estos reflejan las variables de entorno de caché de LibreChat. Las variantes ADMIN_PANEL_* tienen prioridad, recurriendo a los equivalentes compartidos de LibreChat cuando no están configuradas.

Autenticación

El panel de administración reutiliza la pila de autenticación de LibreChat y no tiene su propia base de datos de usuarios. Se admiten dos rutas de inicio de sesión:

• Cuentas locales: nombre de usuario/contraseña para cualquier usuario de LibreChat cuya cuenta supere la verificación de acceso de administrador.
• Single sign-on: OpenID Connect, SAML y los proveedores de OAuth sociales ya configurados en su instancia de LibreChat. Establezca ADMIN_SSO_ONLY=true para ocultar el formulario de contraseña por completo.

El acceso de administrador es verificado en el lado del servidor por LibreChat para cada solicitud. La cuenta debe cumplir con una de las siguientes condiciones:

1. Tener role: 'ADMIN' en MongoDB, o
2. Tener el permiso de sistema access:admin (asignado a otro principal a través del propio panel de administración; consulte System Grants).

Las sesiones están basadas en cookies, cifradas con SESSION_SECRET y expiran por inactividad según ADMIN_SESSION_IDLE_TIMEOUT_MS.

Gestión de configuración

El panel renderiza la configuración de LibreChat como un formulario dinámico basado en el esquema de configuración. Esto tiene dos propiedades útiles:

• Compatible con versiones futuras: cuando LibreChat lanza un nuevo campo de configuración, el panel lo detecta automáticamente a partir del esquema. No se requiere ninguna actualización ni redistribución del panel de administración.
• Anulaciones en capas: la configuración base (desde librechat.yaml) puede ser ensombrecida por anulaciones por principal delimitadas a un rol o grupo. Cuando un usuario inicia sesión, las anulaciones se resuelven en orden de prioridad y se fusionan sobre la base para producir la configuración efectiva que el usuario ve.

Esta es la superficie detrás del sistema de anulación de configuración por principal respaldado por BD de LibreChat. Casos de uso típicos:

• Asignar a un grupo "Research" un recursionLimit más alto y endpoints adicionales
• Permitir que un rol "FinanceAdmins" gestione servidores MCP mientras que los usuarios regulares solo puedan usarlos
• Limitar los permisos de interface más estrictos a los grupos de contratistas externos

Relacionado

• Access Control: el modelo de permisos sobre el cual está construido el panel de administración
• Configuración de la interfaz: los indicadores de funciones que edita el panel
• Authentication: autenticación de usuario en LibreChat
• registro de cambios v0.8.5: fundamentos de la API de administración
• GitHub: ClickHouse/librechat-admin-panel: código fuente, problemas, versiones