Bảng điều khiển quản trị LibreChat

LibreChat Admin Panel là một giao diện quản lý độc lập trên trình duyệt dành cho LibreChat. Nó kết nối với cùng một cơ sở dữ liệu như LibreChat và cung cấp GUI cho các tác vụ quản trị hỗ trợ granular access control: quản trị người dùng và nhóm, quản lý vai trò, ghi đè cấu hình theo phạm vi vai trò hoặc nhóm, và cấp quyền khả năng ở cấp hệ thống.

Nó làm được gì

Bảng điều khiển quản trị là một thin client: tất cả dữ liệu nằm trong cơ sở dữ liệu của LibreChat và mọi hành động đều đi qua các endpoint /api/admin/* được đánh phiên bản trên máy chủ API LibreChat. Nó cung cấp cho quản trị viên một nơi duy nhất để:

• Quản lý cấu hình: xem và chỉnh sửa mọi cài đặt LibreChat thông qua biểu mẫu động, dựa trên lược đồ. Các trường mới được thêm vào lược đồ cấu hình sẽ tự động xuất hiện mà không cần phát hành bản cập nhật bảng điều khiển quản trị.
• Áp dụng ghi đè theo từng chủ thể (per-principal overrides): giới hạn phạm vi ghi đè cấu hình cho các vai trò hoặc nhóm cụ thể, với cơ chế phân cấp dựa trên độ ưu tiên để xác định giá trị cuối cùng mà mỗi người dùng thấy khi đăng nhập.
• Quản trị người dùng: liệt kê, tìm kiếm và xem mọi tài khoản trên instance.
• Quản lý nhóm: tạo và xóa nhóm, thêm/xóa thành viên, và sử dụng nhóm như các thực thể chính (principals) trong ACL và các ghi đè (overrides).
• Quản lý vai trò: tạo các vai trò tùy chỉnh ngoài các vai trò mặc định USER / ADMIN, chỉnh sửa ma trận quyền tính năng của chúng và gán người dùng vào các vai trò.
• Cấp quyền hệ thống: ủy quyền các khả năng quản trị (ví dụ: manage:users, read:usage, manage:mcpservers) cho những người dùng, nhóm hoặc vai trò cụ thể mà không cần cấp quyền quản trị viên toàn quyền cho họ.
• Authenticate: đăng nhập bằng tài khoản quản trị viên LibreChat cục bộ, hoặc thông qua OpenID SSO / SAML / các nhà cung cấp OAuth được hỗ trợ khi các tính năng này được bật trên instance LibreChat.

Để biết về mô hình quyền cơ bản (các chủ thể, ACL tài nguyên, khả năng và cách các lớp kết hợp với nhau), hãy xem trang Access Control.

Kiến trúc

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

Bảng điều khiển quản trị chạy như một dịch vụ riêng biệt; nó không chia sẻ tiến trình với LibreChat. Các khả năng quản trị được xác minh ở phía LibreChat thông qua quyền hệ thống access:admin hoặc vai trò SystemRoles.ADMIN, vì vậy bảng điều khiển không thể tự cấp cho mình các đặc quyền mà nó không được phép có.

Bề mặt API quản trị được LibreChat cung cấp là:

Bắt đầu

Điều kiện tiên quyết

• Một instance LibreChat đang chạy trên v0.8.5 hoặc mới hơn (các API quản trị không khả dụng trong các phiên bản cũ hơn)
• Truy cập mạng từ container/host admin-panel đến LibreChat API
• Một tài khoản quản trị viên trên LibreChat: có thể là người dùng đăng ký đầu tiên (tự động trở thành quản trị viên), người dùng có role: 'ADMIN' được thiết lập trong Mongo, hoặc một thực thể (principal) đã được cấp quyền access:admin.

Được tích hợp sẵn với LibreChat (khuyên dùng)

Nếu bạn chạy LibreChat với docker-compose.yml hoặc deploy-compose.yml chính thức, bảng điều khiển quản trị (admin panel) sẽ được cung cấp dưới dạng một dịch vụ và tự động khởi chạy cùng với LibreChat -- không cần triển khai riêng biệt.

Thiết lập session secret của bảng điều khiển trong tệp .env của LibreChat trước khi khởi chạy stack; các tệp compose sẽ chuyển nó dưới dạng SESSION_SECRET của bảng điều khiển:

# 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

Các tệp compose tự động kết nối phần còn lại: API_SERVER_URL trỏ đến dịch vụ api, VITE_API_BASE_URL tuân theo DOMAIN_CLIENT cho các chuyển hướng OAuth phía trình duyệt, và ADMIN_PANEL_URL được thiết lập để LibreChat đưa quản trị viên quay lại bảng điều khiển sau khi SSO. Để từ chối, hãy xóa dịch vụ admin-panel hoặc chặn nó phía sau một mục profiles của Compose.

Standalone (triển khai riêng biệt)

Để lưu trữ bảng điều khiển quản trị (admin panel) riêng biệt -- trỏ đến một instance LibreChat đang chạy ở nơi khác -- hãy sử dụng image đã được xuất bản từ 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 độc lập:

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

Chạy cục bộ để phát triển

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

Các biến môi trường

Trong các ngăn xếp Docker đi kèm của LibreChat, bảng quản trị chạy dưới dạng dịch vụ admin-panel. Tệp docker-compose.yml mặc định hiển thị nó trên ADMIN_PANEL_PORT; deploy-compose.yml định tuyến nó thông qua nginx tại http://admin.localhost và thiết lập ADMIN_PANEL_URL cho dịch vụ API.

URL chuyển hướng LibreChat

Khi bảng quản trị được lưu trữ trên một URL riêng biệt với LibreChat, hãy thiết lập ADMIN_PANEL_URL trong môi trường API của LibreChat. Sử dụng URL cơ sở của bảng quản trị bên ngoài, bao gồm cả tiền tố đường dẫn (nếu có) và bỏ dấu gạch chéo ở cuối:

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

Đối với các triển khai Helm, hãy đặt librechat.adminPanelUrl trong tệp values của bạn. Chart sẽ hiển thị nó dưới dạng ADMIN_PANEL_URL cho luồng OAuth quản trị của LibreChat:

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

Đối với OpenID SSO, hãy đăng ký ${DOMAIN_SERVER}/api/admin/oauth/openid/callback với nhà cung cấp danh tính của bạn.

Kiểm soát bộ nhớ đệm (Cache Controls)

Các biến này phản ánh các biến môi trường bộ nhớ đệm của LibreChat. Các biến ADMIN_PANEL_* sẽ được ưu tiên, và sẽ sử dụng các biến tương đương của LibreChat làm dự phòng khi không được thiết lập.

Xác thực

Bảng điều khiển quản trị sử dụng lại ngăn xếp xác thực của LibreChat và không có cơ sở dữ liệu người dùng riêng. Hai đường dẫn đăng nhập được hỗ trợ:

• Tài khoản cục bộ: tên người dùng/mật khẩu đối với bất kỳ người dùng LibreChat nào có tài khoản vượt qua bước kiểm tra quyền truy cập quản trị viên.
• Đăng nhập một lần (Single sign-on): OpenID Connect, SAML và các nhà cung cấp OAuth xã hội đã được cấu hình trên instance LibreChat của bạn. Thiết lập ADMIN_SSO_ONLY=true để ẩn hoàn toàn biểu mẫu mật khẩu.

Quyền truy cập quản trị viên được LibreChat xác minh ở phía máy chủ cho mọi yêu cầu. Tài khoản phải đáp ứng một trong các điều kiện sau:

1. Có role: 'ADMIN' trong MongoDB, hoặc
2. Sở hữu quyền hệ thống access:admin (được gán cho một chủ thể khác thông qua chính bảng điều khiển quản trị; xem System Grants).

Các phiên làm việc dựa trên cookie, được mã hóa bằng SESSION_SECRET và sẽ hết hạn khi không hoạt động theo ADMIN_SESSION_IDLE_TIMEOUT_MS.

Quản lý cấu hình

Bảng điều khiển hiển thị cấu hình LibreChat dưới dạng một biểu mẫu động được điều khiển bởi lược đồ cấu hình. Điều này có hai đặc tính hữu ích:

• Tương thích ngược: khi LibreChat phát hành một trường cấu hình mới, bảng điều khiển sẽ tự động nhận diện nó từ schema. Không cần nâng cấp bảng quản trị hay triển khai lại.
• Ghi đè theo lớp (Layered overrides): cấu hình cơ sở (từ librechat.yaml) có thể bị che khuất bởi các ghi đè theo từng chủ thể (per-principal) được giới hạn trong một vai trò hoặc nhóm. Khi người dùng đăng nhập, các ghi đè sẽ được giải quyết theo thứ tự ưu tiên và được hợp nhất lên trên cấu hình cơ sở để tạo ra cấu hình hiệu dụng mà người dùng đó nhìn thấy.

Đây là bề mặt đằng sau hệ thống ghi đè cấu hình theo từng chủ thể dựa trên DB của LibreChat. Các trường hợp sử dụng điển hình:

• Cấp cho nhóm "Research" giá trị recursionLimit cao hơn và các endpoint bổ sung
• Cho phép vai trò "FinanceAdmins" quản lý các máy chủ MCP trong khi người dùng thông thường chỉ có thể sử dụng chúng
• Giới hạn quyền interface chặt chẽ hơn cho các nhóm nhà thầu bên ngoài

Liên quan

• Access Control: mô hình phân quyền mà bảng điều khiển quản trị được xây dựng dựa trên đó
• Cấu hình giao diện: các cờ tính năng mà bảng điều khiển chỉnh sửa
• Authentication: xác thực người dùng trên LibreChat
• v0.8.5 changelog: nền tảng API quản trị
• GitHub: ClickHouse/librechat-admin-panel: mã nguồn, vấn đề, bản phát hành