Painel de Administração do LibreChat

O LibreChat Admin Panel é uma interface de gerenciamento independente baseada em navegador para o LibreChat. Ele se conecta ao mesmo banco de dados que o próprio LibreChat e fornece uma GUI para as tarefas administrativas que impulsionam o granular access control: administração de usuários e grupos, gerenciamento de funções, substituições de configuração com escopo para funções ou grupos e concessões de recursos em nível de sistema.

O que ele faz

O painel de administração é um cliente leve: todos os dados residem no banco de dados do LibreChat, e cada ação passa pelos endpoints versionados /api/admin/* no servidor da API do LibreChat. Ele oferece aos administradores um local único para:

• Gerenciar configuração: visualize e edite todas as configurações do LibreChat por meio de um formulário dinâmico baseado em esquema. Novos campos adicionados ao esquema de configuração aparecem automaticamente, sem a necessidade de lançamento de painel administrativo.
• Aplicar substituições por principal: limite as substituições de configuração a funções ou grupos específicos, com uma cascata baseada em prioridade que determina o valor final resolvido que cada usuário vê ao fazer login.
• Administrar usuários: listar, pesquisar e visualizar todas as contas na instância.
• Gerenciar grupos: crie e exclua grupos, adicione/remova membros e use grupos como principais de primeira classe em ACLs e substituições (overrides).
• Gerenciar funções: crie funções personalizadas além das nativas USER / ADMIN, edite sua matriz de permissões de recursos e atribua usuários a funções.
• Concessões do sistema de permissões: delegue capacidades administrativas (por exemplo, manage:users, read:usage, manage:mcpservers) a usuários, grupos ou funções específicos sem torná-los administradores completos.
• Autenticar: faça login com uma conta de administrador local do LibreChat, ou via SSO OpenID / SAML / provedores OAuth suportados quando estes estiverem habilitados na instância do LibreChat.

Para o modelo de permissão subjacente (principais, ACLs de recursos, capacidades e como as camadas se compõem), consulte a página Access Control.

Arquitetura

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

O painel de administração é executado como um serviço separado; ele não compartilha um processo com o LibreChat. As capacidades de administração são verificadas no lado do LibreChat por meio da permissão do sistema access:admin ou da função SystemRoles.ADMIN, portanto, o painel não pode conceder a si mesmo privilégios que não deveria ter.

A superfície da API de administrador exposta pelo LibreChat é:

Primeiros Passos

Pré-requisitos

• Uma instância do LibreChat em execução na v0.8.5 ou posterior (as APIs de administrador não estão disponíveis em versões anteriores)
• Acesso de rede do container/host do admin-panel para a API do LibreChat
• Uma conta de administrador no LibreChat: ou o primeiro usuário registrado (auto-admin), um usuário com role: 'ADMIN' definido no Mongo, ou um principal ao qual foi concedida a capacidade access:admin

Empacotado com o LibreChat (recomendado)

Se você executar o LibreChat com o docker-compose.yml ou deploy-compose.yml oficial, o painel administrativo é fornecido como um serviço e inicia automaticamente junto com o LibreChat -- nenhuma implantação separada é necessária.

Defina o segredo de sessão do painel no .env do LibreChat antes de iniciar a stack; os arquivos compose o transmitem como o SESSION_SECRET do painel:

# 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

Os arquivos compose conectam o restante automaticamente: API_SERVER_URL aponta para o serviço api, VITE_API_BASE_URL segue DOMAIN_CLIENT para redirecionamentos de OAuth voltados ao navegador, e ADMIN_PANEL_URL é definido para que o LibreChat retorne os administradores ao painel após o SSO. Para optar por não utilizar, remova o serviço admin-panel ou proteja-o atrás de uma entrada de profiles do Compose.

Standalone (implantação separada)

Para hospedar o painel de administração separadamente -- apontando para uma instância do LibreChat rodando em outro lugar -- use a imagem publicada no 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 autônomo:

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

Executar Localmente para Desenvolvimento

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

Variáveis de Ambiente

Nas pilhas Docker integradas do LibreChat, o painel administrativo é executado como um serviço admin-panel. O docker-compose.yml padrão o expõe na porta ADMIN_PANEL_PORT; o deploy-compose.yml o roteia através do nginx em http://admin.localhost e define a ADMIN_PANEL_URL para o serviço de API.

URL de redirecionamento do LibreChat

Quando o painel administrativo estiver hospedado em uma URL separada do LibreChat, defina ADMIN_PANEL_URL no ambiente da API do LibreChat. Use a URL base externa do painel administrativo, incluindo qualquer prefixo de caminho, e omita a barra final:

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

Para implantações via Helm, defina librechat.adminPanelUrl no seu arquivo values. O chart o renderiza como ADMIN_PANEL_URL para o fluxo de OAuth do painel administrativo do LibreChat:

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

Para OpenID SSO, registre ${DOMAIN_SERVER}/api/admin/oauth/openid/callback com seu provedor de identidade.

Controles de Cache

Estes espelham as variáveis de ambiente de cache do LibreChat. As variantes ADMIN_PANEL_* têm precedência, recorrendo aos equivalentes compartilhados do LibreChat quando não definidas.

Autenticação

O painel de administração reutiliza a pilha de autenticação do LibreChat e não possui seu próprio banco de dados de usuários. Dois caminhos de login são suportados:

• Contas locais: nome de usuário/senha para qualquer usuário do LibreChat cuja conta passe na verificação de acesso de administrador.
• Single sign-on: OpenID Connect, SAML e os provedores OAuth sociais já configurados na sua instância do LibreChat. Defina ADMIN_SSO_ONLY=true para ocultar o formulário de senha completamente.

O acesso de administrador é verificado no lado do servidor pelo LibreChat para cada solicitação. A conta deve:

1. Tenha role: 'ADMIN' no MongoDB, ou
2. Possuir a permissão de sistema access:admin (atribuída a outro principal através do próprio painel de administração; veja System Grants).

As sessões são baseadas em cookies, criptografadas com SESSION_SECRET e expiram por inatividade conforme ADMIN_SESSION_IDLE_TIMEOUT_MS.

Gerenciamento de Configuração

O painel renderiza a configuração do LibreChat como um formulário dinâmico orientado pelo esquema de configuração. Isso possui duas propriedades úteis:

• Compatível com versões futuras: quando o LibreChat lança um novo campo de configuração, o painel o detecta automaticamente a partir do esquema. Nenhuma atualização ou reimplantação do painel de administração é necessária.
• Substituições em camadas: a configuração base (do librechat.yaml) pode ser ocultada por substituições por principal, com escopo definido para uma função ou grupo. Quando um usuário faz login, as substituições são resolvidas em ordem de prioridade e mescladas sobre a base para produzir a configuração efetiva que o usuário vê.

Esta é a superfície por trás do sistema de substituição de configuração por principal baseado em banco de dados do LibreChat. Casos de uso típicos:

• Dê a um grupo "Research" um recursionLimit maior e endpoints adicionais
• Permita que uma função "FinanceAdmins" gerencie servidores MCP, enquanto usuários comuns apenas possam utilizá-los
• Limitar permissões de interface mais rigorosas a grupos de contratados externos

Relacionado

• Access Control: o modelo de permissão no qual o painel de administração é baseado
• Configuração da Interface: as sinalizações de recursos que o painel edita
• Autenticação: autenticação de usuário no LibreChat
• changelog v0.8.5: fundamentos da API de administrador
• GitHub: ClickHouse/librechat-admin-panel: código-fonte, issues, releases