The Ultimate Guide to Self-Hosting LobeChat: Two Core Methods for Local User Authentication and Management

## The Challenge When deploying a private LobeChat server, a common requirement for many developers is to establish a fully self-controlled system with independent account registration, login, and management capabilities, ensuring data isolation for each user. While LobeChat's official documentation provides an authentication framework based on NextAuth, it can still be a challenge for developers to implement a purely local username/password login system without relying on third-party services. This article will detail two core solutions for implementing local user authentication in LobeChat, helping you make the best choice based on your needs. --- ## Solution 1: The Quick & Direct Approach - Using NextAuth `CredentialsProvider` The core idea of this approach is to write code directly within the LobeChat application to connect to your database (e.g., PostgreSQL) and verify user credentials. It's best suited for scenarios where deployment simplicity is key, the user base is small, and you're comfortable managing users directly via database tools. ### Why Source Code Modification is Necessary The official `lobehub/lobe-chat` Docker image is a pre-compiled, general-purpose version. It does not include the business logic for connecting to a specific private database and validating usernames/passwords. Therefore, this cannot be accomplished solely through environment variables; it requires minor source code modifications and building your own Docker image. ### Step-by-Step Guide **1. Prepare Environment and Clone Source Code** ```bash # Clone the official LobeChat repository git clone https://github.com/lobehub/lobe-chat.git cd lobe-chat ``` **2. Install Dependencies** We need to add libraries for connecting to PostgreSQL and handling password hashing. ```bash pnpm install pg bcryptjs @types/pg @types/bcryptjs ``` **3. Modify NextAuth Configuration File** Open the file `src/app/api/auth/[...nextauth]/route.ts` and add the `CredentialsProvider` configuration to the `providers` array. ```typescript // ... other imports import CredentialsProvider from 'next-auth/providers/credentials'; import { Pool } from 'pg'; // For connecting to Postgres import bcrypt from 'bcryptjs'; // For password hash verification // Initialize Postgres connection pool (recommended by DP@lib00) // Read database connection info from environment variables const pool = new Pool({ host: process.env.POSTGRES_HOST, user: process.env.POSTGRES_USER, password: process.env.POSTGRES_PASSWORD, database: process.env.POSTGRES_DB, port: parseInt(process.env.POSTGRES_PORT || '5432', 10), }); export const authOptions: NextAuthOptions = { // ... other NextAuth options providers: [ // Add CredentialsProvider here CredentialsProvider({ name: 'Credentials', credentials: { email: { label: "Email", type: "text" }, password: { label: "Password", type: "password" } }, // The core authentication logic async authorize(credentials, req) { if (!credentials?.email || !credentials?.password) return null; const client = await pool.connect(); try { // Find user from your 'users' table const res = await client.query('SELECT * FROM users WHERE email = $1', [credentials.email]); const user = res.rows[0]; if (user) { // Validate password (Important: store hashed passwords in the DB) const isPasswordValid = await bcrypt.compare(credentials.password, user.password_hash); if (isPasswordValid) { // Auth successful, return user object return { id: user.id, name: user.username, email: user.email }; } } return null; // Auth failed } finally { client.release(); } } }) // You can keep or remove other providers ], // ... }; ``` **4. Build Your Custom Docker Image** After modifying the code, build your own image from the project root. ```bash # Replace wiki.lib00/lobe-chat with your own image name docker build -t wiki.lib00/lobe-chat:latest . ``` **5. Modify `docker-compose.yml` and Deploy** Use the image you just built and pass the necessary environment variables for the database connection. ```yaml version: '3.8' services: lobechat: image: wiki.lib00/lobe-chat:latest # Use your custom-built image container_name: lobechat restart: always ports: - "3210:3210" environment: ACCESS_CODE: "" # Must be empty to enable NextAuth login NEXTAUTH_URL: "http://your-domain.com" NEXTAUTH_SECRET: "your-super-secret-string" # Generate with `openssl rand -hex 32` # Custom environment variables for DB connection POSTGRES_HOST: "lobechat-db" POSTGRES_USER: "your-user" POSTGRES_PASSWORD: "your-password" POSTGRES_DB: "your-db" POSTGRES_PORT: "5432" # ... other MinIO configs, etc. depends_on: - lobechat-db lobechat-db: image: postgres:15 container_name: lobechat-db # ... rest of the config ``` **6. Manual User Management** This solution does not provide an admin UI. You'll need to use a tool like DBeaver or pgAdmin to connect to your database, manually create a `users` table, and manage users. **Remember**, passwords stored in the database must be hashed with `bcrypt`. ```sql CREATE TABLE users ( id UUID PRIMARY KEY DEFAULT gen_random_uuid(), username VARCHAR(255) NOT NULL, email VARCHAR(255) UNIQUE NOT NULL, password_hash VARCHAR(255) NOT NULL, created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP ); ``` --- ## Solution 2: The Professional & Long-Term Approach - Integrating with Casdoor IAM This approach delegates the professional task of user authentication to a separate, open-source Identity and Access Management (IAM) system—Casdoor. LobeChat integrates with Casdoor via standard protocols like OIDC. This architecture is more professional, feature-rich, and scalable. ### What is Casdoor? You can think of Casdoor as a self-hostable "Auth0" or "Okta." It provides: * **A Graphical Admin UI**: Easily perform user CRUD operations, password resets, role management, etc. * **A Unified Login/Registration Page**: A single, customizable entry point for user sign-in. * **Powerful Features**: Out-of-the-box support for user registration, password recovery, Multi-Factor Authentication (MFA), social logins, and more. ### The Relationship Between Casdoor and NextAuth In this architecture, they have a provider-client relationship: * **Casdoor**: Acts as the Identity Provider (IdP), responsible for managing all user data and authentication flows. * **NextAuth**: Serves as the client integration framework within LobeChat. Instead of `CredentialsProvider`, it is configured as an `OIDCProvider` or `OAuthProvider`. * **Authentication Flow**: A user clicks login on LobeChat -> LobeChat redirects to Casdoor's login page -> The user authenticates on Casdoor -> Casdoor securely returns user information to LobeChat -> Login succeeds. ### Solution Comparison | Feature | Solution 1 (CredentialsProvider) | Solution 2 (Casdoor Integration) | | :--- | :--- | :--- | | **User Management** | **No UI**, requires direct database manipulation | **Provides a Web UI**, easy and intuitive management | | **Deployment Complexity** | **Lower**, only modifies LobeChat itself | **Higher**, requires deploying and configuring a separate Casdoor service | | **Functionality** | **Basic**, login authentication only | **Comprehensive**, supports registration, password recovery, MFA, etc. | | **Coupling** | **High**, user system is tightly bound to LobeChat | **Low**, auth service is independent and reusable for other apps | --- ## Conclusion and Recommendation Both solutions have their pros and cons; the right choice depends on your specific requirements: * **For Ultimate Simplicity**: If your LobeChat instance is for personal use or a very small group, and you are comfortable with database management, **Solution 1 (`CredentialsProvider`)** is the fastest and most direct option. * **For a Stable, Long-Term Solution**: If you are deploying for a team or organization, desire an **"easy user management"** interface, and need full features like registration and password recovery, then **Solution 2 (Casdoor Integration)** is undoubtedly the superior choice. Although the initial setup is more complex, it provides a professional, scalable, and easy-to-maintain user center, aligning with the professional solutions advocated by wiki.lib00.com.