LibreChat 管理面板

LibreChat Admin Panel 是一个基于浏览器的独立 LibreChat 管理界面。它连接到与 LibreChat 相同的数据库，并为支持 granular access control 的管理任务提供了图形用户界面（GUI）：包括用户和组管理、角色管理、针对角色或组的配置覆盖，以及系统级权限授予。

功能概述

管理面板是一个瘦客户端：所有数据都存储在 LibreChat 的数据库中，并且每个操作都通过 LibreChat API 服务器上带有版本号的 /api/admin/* endpoint 进行。它为管理员提供了一个统一的平台，用于：

• 管理配置：通过动态的、基于模式（schema-driven）的表单查看并编辑每一项 LibreChat 设置。添加到配置模式中的新字段会自动显示，无需发布管理面板即可生效。
• 应用基于主体的覆盖（Apply per-principal overrides）：将配置覆盖范围限定于特定角色或组，并通过基于优先级的级联机制来确定每个用户在登录时最终解析出的值。
• 管理用户：列出、搜索并查看实例上的每个账户。
• 管理组：创建和删除组，添加/移除成员，并将组作为 ACL 和覆盖配置中的一等主体使用。
• 管理角色：创建除内置 USER / ADMIN 之外的自定义角色，编辑其功能权限矩阵，并将用户分配给这些角色。
• 颁发系统授权：将管理权限（例如 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 共享进程。管理功能通过 LibreChat 端的 access:admin 系统授权或 SystemRoles.ADMIN 角色进行验证，因此该面板无法授予自身其本不应拥有的权限。

LibreChat 暴露的管理员 API 接口为：

入门指南

先决条件

• 一个正在运行的 LibreChat 实例，版本需为 v0.8.5 或更高版本（早期版本不提供管理 API）
• 从 admin-panel 容器/主机到 LibreChat API 的网络访问
• LibreChat 上的管理员账户：即第一个注册的用户（自动管理员）、在 Mongo 中设置了 role: 'ADMIN' 的用户，或已被授予 access:admin 权限的主体。

与 LibreChat 捆绑（推荐）

如果您使用官方的 docker-compose.yml 或 deploy-compose.yml 运行 LibreChat，管理面板将作为一项服务随 LibreChat 一起自动启动，无需单独部署。

在启动堆栈之前，请在 LibreChat 的 .env 文件中设置面板的 session secret；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 遵循 DOMAIN_CLIENT 以用于面向浏览器的 OAuth 重定向，而设置 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。Chart 会将其渲染为 LibreChat 管理员 OAuth 流程所需的 ADMIN_PANEL_URL：

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

对于 OpenID SSO，请将 ${DOMAIN_SERVER}/api/admin/oauth/openid/callback 注册到您的身份提供商中。

缓存控制

这些镜像了 LibreChat 的缓存环境变量。ADMIN_PANEL_* 变体具有优先权，当未设置时，将回退到共享的 LibreChat 等效项。

身份验证

管理面板复用了 LibreChat 的身份验证堆栈，且没有自己的用户数据库。支持两种登录路径：

• Local accounts: 用户名/密码，适用于任何通过管理员访问检查的 LibreChat 用户账户。
• 单点登录 (Single sign-on)：OpenID Connect、SAML 以及已在您的 LibreChat 实例上配置的社交 OAuth 提供商。设置 ADMIN_SSO_ONLY=true 可完全隐藏密码登录表单。

LibreChat 会在每次请求时在服务器端验证管理员权限。该账户必须满足以下任一条件：

1. 在 MongoDB 中拥有 role: 'ADMIN'，或者
2. 拥有 access:admin 系统授权（通过管理面板本身分配给另一个主体；请参阅 System Grants）。

会话基于 cookie，使用 SESSION_SECRET 进行加密，并根据 ADMIN_SESSION_IDLE_TIMEOUT_MS 设置空闲过期时间。

配置管理

该面板将 LibreChat 配置渲染为由配置模式驱动的动态表单。这具有两个有用的特性：

• 前向兼容：当 LibreChat 发布新的配置字段时，面板会自动从 schema 中获取该字段。无需升级或重新部署管理面板。
• 分层覆盖 (Layered overrides)：基础配置（来自 librechat.yaml）可以被针对特定主体（principal）的覆盖所屏蔽，这些覆盖的作用域限定为角色或组。当用户登录时，系统会按优先级顺序解析覆盖项，并将其合并到基础配置之上，从而生成该用户所看到的最终有效配置。

这是 LibreChat 基于数据库的每个主体配置覆盖系统背后的实现逻辑。典型用例包括：

• 为“Research”组提供更高的 recursionLimit 和额外的 endpoint
• 允许 "FinanceAdmins" 角色管理 MCP 服务器，而普通用户仅能使用它们
• 将更严格的 interface 权限范围限定为外部承包商组

相关内容

• Access Control：管理面板所基于的权限模型
• 界面配置：面板编辑的功能标志
• Authentication: LibreChat 上的用户身份验证
• v0.8.5 更新日志：admin API 基础架构
• GitHub: ClickHouse/librechat-admin-panel: 源码，问题，发布版本