LibreChat 是一个开源的、自托管的 AI 聊天平台，它统一了所有主要 AI 提供商（OpenAI、Anthropic、Google、AWS Bedrock 等）在一个隐私优先的界面中。它提供了 AI 代理、MCP 支持、代码解释器、工件（Artifacts）、对话搜索和企业级多用户认证等高级功能。

1. 系统要求与准备

1.1 硬件与软件要求

  • 操作系统：Linux、macOS 或 Windows (通过 WSL)。
  • 内存：建议至少 4GB（运行多个 AI 代理或模型时可能需要更多）。
  • 存储：至少 10GB 可用空间（用于应用、数据库和缓存）。
  • 网络：需要访问互联网以调用 AI 提供商的 API。

1.2 软件前提

  • Node.js：版本 24.x（推荐，项目 .nvmrc 指定了 24）。
  • 包管理器：npm 或 bun。
  • Git：用于克隆仓库。
  • 数据库（至少一种）：
    • MongoDB：推荐，用于生产环境。
    • Amazon DocumentDB：5.0+ 版本。
  • 缓存（可选但强烈推荐）：
    • Redis：用于会话管理、缓存和流恢复。

1.3 必需的 API 密钥

您至少需要一个 AI 提供商的 API 密钥。支持的提供商包括：

  • OpenAI (GPT-5.x, o1 等)
  • Anthropic (Claude)
  • Google (Gemini, Vertex AI)
  • AWS Bedrock
  • Azure OpenAI
  • OpenRouter, DeepSeek, Groq, Mistral, Ollama 等

2. 部署方式

LibreChat 提供了多种部署方式，推荐使用 Docker Compose 进行生产部署。

2.1 方式一：使用 Docker Compose（推荐）

这是最简便、最可靠的方式，适合生产环境。

  1. 克隆仓库：

    1
    2
    git clone https://github.com/danny-avila/LibreChat.git
    cd LibreChat

  2. 配置环境变量：

    1
    2
    # 复制示例环境文件
    cp .env.example .env

    编辑 .env 文件，至少需要配置：

    • OPENAI_API_KEY：您的 OpenAI API 密钥（如使用其他提供商，配置相应的密钥）。
    • MONGO_URI：MongoDB 连接字符串（如果使用内置 MongoDB 容器，可保持默认）。
    • REDIS_URI：Redis 连接字符串（如果使用内置 Redis 容器，可保持默认）。

  3. 启动服务：

    1
    docker compose up -d

    此命令会拉取镜像，启动包含应用、MongoDB 和 Redis 的完整服务栈。

  4. 访问应用：
    在浏览器中打开 http://localhost:3080。

2.2 方式二：从源码手动部署（适合开发或定制）

  1. 克隆并安装依赖：

    1
    2
    3
    git clone https://github.com/danny-avila/LibreChat.git
    cd LibreChat
    npm ci  # 或 bun install

  2. 配置环境变量：
    复制 cp .env.example .env 并编辑，配置数据库、API 密钥等。

  3. 构建应用：

    1
    npm run build

  4. 启动应用：

    1
    2
    3
    4
    5
    # 开发模式（支持热加载）
    npm run dev

    # 生产模式（需先构建）
    npm run start

2.3 方式三：使用 Helm (Kubernetes)

项目在 helm/ 目录下提供了 Helm Charts，便于在 Kubernetes 集群中部署。请参考项目文档获取详细说明。

3. 核心配置与后续步骤

3.1 管理员面板（Admin Panel）

首次启动后，您可以通过导航到 Settings -> Admin 访问管理员面板。在这里，您可以：

  • 管理用户：创建、禁用、删除用户。
  • 管理组与角色：设置权限和访问控制。
  • 配置覆盖：在不重新部署的情况下，实时调整应用配置。

3.2 添加 AI 模型

通过管理面板或编辑配置文件（librechat.example.yaml），您可以添加并启用您需要的 AI 模型：

  1. 转到 Admin -> Models。
  2. 点击 Add Model，选择提供商（如 openai）并填写模型 ID（如 gpt-5.6）。
  3. 保存后，用户即可在对话中选择该模型。

3.3 配置代码解释器（可选）

LibreChat 集成了安全的代码解释器。您需要在 docker-compose.yml 或环境变量中配置代码解释器服务的端点（默认使用 ClickHouse/code-interpreter）。

4. 升级与备份

4.1 升级

使用 Docker Compose 升级：

1
2
3
4
# 拉取最新镜像
docker compose pull
# 重新创建并启动容器
docker compose up -d --remove-orphans

重要：在升级前，请务必查阅 CHANGELOG.md 了解可能的不兼容更改。

4.2 备份

  • 数据库：使用 MongoDB 的备份工具（如 mongodump）定期备份数据库。
  • 配置文件：备份 .env 文件和任何自定义的 YAML 配置文件。
  • 用户数据：如果使用了文件上传功能，需备份对应的存储目录（如 S3 或本地磁盘）。

5. 常见问题排查

问题 可能原因 解决方案
Docker 容器启动失败 端口冲突或环境变量错误 检查 docker-compose.yml 中的端口映射（默认 3080）是否被占用。查看容器日志：docker compose logs。
无法连接到 MongoDB 或 Redis 连接字符串（URI）配置错误 确认 .env 文件中的 MONGO_URI 和 REDIS_URI 格式正确，且服务已启动。
AI 模型调用返回错误 API 密钥无效、过期或模型 ID 错误 检查对应提供商的 API 密钥。在管理员面板中确认模型 ID 与提供商支持的模型名称完全一致。
文件上传/代码解释器失败 代码解释器服务未运行或配置错误 检查代码解释器服务（如 code-interpreter-api）是否正常运行，并确认其 URL 在环境变量中配置正确。
登录后页面空白或报错 前端资源未正确构建或缓存问题 尝试清除浏览器缓存。如果从源码部署，重新运行 npm run build。
“Resumable Streams”功能不工作 Redis 未配置或连接失败 确认 Redis 已正确配置并在运行。此功能依赖 Redis 缓存消息状态。

6. 总结

LibreChat 是一个功能丰富、高度可定制的 AI 聊天平台，是商业 ChatGPT 服务的有力替代方案。

核心部署路径：

  1. 选择部署方式：对于大多数用户，使用 Docker Compose 是最高效、最可靠的选择。运行 docker compose up -d 即可获得完整运行环境。
  2. 配置环境：关键步骤是配置 .env 文件中的 数据库连接 和至少一个 AI 提供商的 API 密钥。
  3. 后续配置：通过 管理员面板 可以灵活管理用户、模型和系统设置，无需频繁重启或重新部署。

建议：首先通过 Docker Compose 方式启动一个测试实例，熟悉其功能和界面。在准备投入生产前，请务必为 MongoDB 和 Redis 配置持久化存储和备份策略。所有配置更改和升级前，建议查阅官方文档和更新日志。

项目地址：https://github.com/danny-avila/LibreChat