Panel Admin LibreChat

LibreChat Admin Panel adalah antarmuka manajemen berbasis peramban yang berdiri sendiri untuk LibreChat. Panel ini terhubung ke basis data yang sama dengan LibreChat itu sendiri dan menyediakan GUI untuk tugas-tugas administratif yang mendukung granular access control: administrasi pengguna dan grup, manajemen peran, penggantian konfigurasi yang dicakup untuk peran atau grup, serta pemberian kapabilitas tingkat sistem.

Apa Fungsinya

Panel admin adalah klien tipis: semua data tersimpan di basis data LibreChat, dan setiap tindakan melalui endpoint /api/admin/* yang memiliki versi di server API LibreChat. Panel ini memberikan administrator satu tempat untuk:

• Kelola konfigurasi: lihat dan edit setiap pengaturan LibreChat melalui formulir dinamis berbasis skema. Bidang baru yang ditambahkan ke skema konfigurasi akan muncul secara otomatis, tanpa memerlukan rilis panel admin.
• Terapkan penggantian per-principal: cakup penggantian konfigurasi ke peran atau grup tertentu, dengan kaskade berbasis prioritas yang menentukan nilai akhir yang diselesaikan yang dilihat setiap pengguna saat login.
• Mengelola pengguna: mencantumkan, mencari, dan melihat setiap akun pada instance.
• Kelola grup: membuat dan menghapus grup, menambah/menghapus anggota, serta menggunakan grup sebagai prinsipal kelas satu dalam ACL dan penggantian (overrides).
• Kelola peran: buat peran kustom di luar USER / ADMIN bawaan, edit matriks fitur-izin mereka, dan tetapkan pengguna ke peran tersebut.
• Issue system grants: mendelegasikan kemampuan admin (contoh: manage:users, read:usage, manage:mcpservers) kepada pengguna, grup, atau peran tertentu tanpa menjadikan mereka admin penuh.
• Authenticate: masuk dengan akun admin LibreChat lokal, atau melalui OpenID SSO / SAML / penyedia OAuth yang didukung saat fitur tersebut diaktifkan pada instance LibreChat.

Untuk model izin yang mendasarinya (prinsipal, ACL sumber daya, kapabilitas, dan bagaimana lapisan-lapisan tersebut disusun), lihat halaman Access Control.

Arsitektur

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

Panel admin berjalan sebagai layanan terpisah; layanan ini tidak berbagi proses dengan LibreChat. Kemampuan admin diverifikasi di sisi LibreChat melalui pemberian akses access:admin atau peran SystemRoles.ADMIN, sehingga panel tidak dapat memberikan hak istimewa kepada dirinya sendiri yang seharusnya tidak dimilikinya.

Permukaan API admin yang diekspos oleh LibreChat adalah:

Memulai

Prasyarat

• Instans LibreChat yang sedang berjalan pada v0.8.5 atau lebih baru (API admin tidak tersedia pada versi sebelumnya)
• Akses jaringan dari container/host admin-panel ke API LibreChat
• Akun admin di LibreChat: bisa berupa pengguna yang pertama kali mendaftar (auto-admin), pengguna dengan role: 'ADMIN' yang diatur di Mongo, atau prinsipal yang telah diberikan kapabilitas access:admin

Dibundel dengan LibreChat (direkomendasikan)

Jika Anda menjalankan LibreChat dengan docker-compose.yml atau deploy-compose.yml resminya, panel admin akan disertakan sebagai layanan dan dimulai secara otomatis bersama LibreChat -- tidak diperlukan penerapan terpisah.

Atur session secret panel di dalam .env LibreChat sebelum memulai stack; file compose akan meneruskannya sebagai SESSION_SECRET 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

File compose menghubungkan sisanya secara otomatis: API_SERVER_URL mengarah ke layanan api, VITE_API_BASE_URL mengikuti DOMAIN_CLIENT untuk pengalihan OAuth yang menghadap ke browser, dan ADMIN_PANEL_URL diatur agar LibreChat mengembalikan admin ke panel setelah SSO. Untuk tidak ikut serta, hapus layanan admin-panel atau batasi di balik entri profiles Compose.

Standalone (penyebaran terpisah)

Untuk menghosting panel admin secara mandiri -- yang diarahkan ke instans LibreChat yang berjalan di tempat lain -- gunakan image yang dipublikasikan dari 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 mandiri:

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

Jalankan Secara Lokal untuk Pengembangan

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

Environment Variables

Dalam tumpukan Docker bawaan LibreChat, panel admin berjalan sebagai layanan admin-panel. docker-compose.yml standar mengeksposnya pada ADMIN_PANEL_PORT; deploy-compose.yml merutekannya melalui nginx di http://admin.localhost dan mengatur ADMIN_PANEL_URL untuk layanan API.

URL Pengalihan LibreChat

Ketika panel admin di-host pada URL yang terpisah dari LibreChat, atur ADMIN_PANEL_URL di lingkungan API LibreChat. Gunakan URL dasar panel admin eksternal, termasuk awalan jalur (path prefix) apa pun, dan hilangkan garis miring (trailing slash) di akhir:

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

Untuk penyebaran Helm, atur librechat.adminPanelUrl di dalam file values Anda. Chart tersebut akan merendernya sebagai ADMIN_PANEL_URL untuk alur OAuth admin LibreChat:

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

Untuk OpenID SSO, daftarkan ${DOMAIN_SERVER}/api/admin/oauth/openid/callback dengan penyedia identitas Anda.

Kontrol Cache

Ini mencerminkan env var cache LibreChat. Varian ADMIN_PANEL_* lebih diutamakan, dan akan kembali ke padanan LibreChat bersama jika tidak diatur.

Autentikasi

Panel admin menggunakan kembali tumpukan autentikasi LibreChat dan tidak memiliki basis data pengguna sendiri. Dua jalur masuk didukung:

• Akun lokal: nama pengguna/kata sandi terhadap pengguna LibreChat mana pun yang akunnya lolos pemeriksaan akses admin.
• Single sign-on: OpenID Connect, SAML, dan penyedia OAuth sosial yang sudah dikonfigurasi pada instans LibreChat Anda. Atur ADMIN_SSO_ONLY=true untuk menyembunyikan formulir kata sandi sepenuhnya.

Akses admin diverifikasi di sisi server oleh LibreChat untuk setiap permintaan. Akun tersebut harus:

1. Memiliki role: 'ADMIN' di MongoDB, atau
2. Memiliki hak akses sistem access:admin (diberikan kepada principal lain melalui panel admin itu sendiri; lihat System Grants).

Sesi berbasis cookie, dienkripsi dengan SESSION_SECRET, dan akan kedaluwarsa saat tidak aktif sesuai dengan ADMIN_SESSION_IDLE_TIMEOUT_MS.

Manajemen Konfigurasi

Panel ini merender konfigurasi LibreChat sebagai formulir dinamis yang didorong oleh skema konfigurasi. Hal ini memiliki dua properti yang berguna:

• Forward-compatible: ketika LibreChat merilis field konfigurasi baru, panel akan mengambilnya secara otomatis dari skema. Tidak diperlukan peningkatan atau redeploy panel admin.
• Layered overrides: konfigurasi dasar (dari librechat.yaml) dapat dibayangi oleh override per-principal yang dicakup ke peran atau grup. Saat pengguna masuk, override diselesaikan berdasarkan urutan prioritas dan digabungkan di atas konfigurasi dasar untuk menghasilkan konfigurasi efektif yang dilihat oleh pengguna tersebut.

Ini adalah antarmuka di balik sistem penggantian konfigurasi per-prinsipal berbasis DB milik LibreChat. Kasus penggunaan umum:

• Berikan grup "Research" recursionLimit yang lebih tinggi dan endpoint tambahan
• Izinkan peran "FinanceAdmins" untuk mengelola server MCP sementara pengguna biasa hanya dapat menggunakannya
• Batasi izin interface yang lebih ketat untuk grup kontraktor eksternal

Terkait

• Access Control: model perizinan yang menjadi dasar pembangunan panel admin
• Konfigurasi Antarmuka: fitur flag yang disunting oleh panel
• Authentication: autentikasi pengguna pada LibreChat
• changelog v0.8.5: fondasi API admin
• GitHub: ClickHouse/librechat-admin-panel: sumber, masalah, rilis