LibreChat：聚合主流模型与 Agent 能力的开源自托管多用户 AI 对话平台｜部署与使用全指南

项目仓库： https://github.com/danny-avila/LibreChat

开源协议：MIT（Copyright 2026 LibreChat） · 技术栈：Node.js / Express 后端、React 前端、MongoDB、Meilisearch、pgvector、RAG API · 交付形态：Docker Compose 自托管栈、源码本地运行、npm 管理脚本 · 默认应用端口 3080，内置管理后台端口 3000 · 官方文档：docs.librechat.ai · 官方站点：librechat.ai

非官方声明：LibreChat 是开源社区项目，与 OpenAI、Microsoft Azure、Anthropic、Google、AWS、Bedrock、Vertex AI、DeepSeek、Qwen、Ollama 等模型与平台厂商不存在隶属、授权或合作关系；文中出现的模型与服务名称仅用于说明兼容目标。API Key、订阅账号与模型服务条款由对应厂商约束，使用者须自行确认合规边界。

1 项目简介

LibreChat 是一个自托管的 AI 对话平台，在一个注重隐私的统一界面中整合主流 AI 服务商：除基础对话外，还提供 AI 智能体（Agents）、模型上下文协议（MCP）支持、Artifacts 生成式 UI、代码解释器、自定义操作、对话搜索与企业级多用户认证。项目完全开源、持续公开开发，面向希望自主掌控 AI 基础设施的个人、小团队与私有化场景。

1.1 核心信息一览

1.2 适用场景

• 个人或团队需要一个统一对话入口，在同一界面切换多家云端模型与本地 / 自部署模型，集中管理 API Key。
• 多用户私有化部署：邮箱注册 / 登录、OAuth2 社交登录、LDAP、角色与分组权限、内置审核与 Token 消耗管理。
• 需要无代码构建自定义助手与 Agent，接入 MCP 服务器、文件搜索、代码执行、子智能体与 Skills 的工作流场景。
• 需要代码解释器（沙箱执行 Python、Node.js、Go、C/C++、Java、PHP、Rust、Fortran）、网页搜索、Artifacts 预览、图像生成与语音交互的进阶使用场景。
• 开发者基于仓库前后端与 packages/ 工作区二次开发模型端点、Agent 工具与界面能力。

1.3 能力边界（官方口径）

• 官方 README 自述为 “self-hosted AI chat platform that unifies all major AI providers in a single, privacy-focused interface”；平台本身不提供模型、不托管模型权重，能力边界取决于已配置的模型与后端服务。
• 自定义端点（Custom Endpoints）支持任意 OpenAI 兼容 API，无需代理；本地与远程服务商兼容清单以官方 AI Endpoints 文档 为准。
• 部分能力标记为实验性：如附属代码工作区（Attached workspaces）、Agent 插件打包、代码工作区 Bash 执行等；上线生产前应阅读对应文档的风险说明。
• 管理后台、RAG、代码解释器、MCP、语音等功能依赖对应的服务组件与环境变量；未配置时相关入口不可用或降级为基础对话。

2 功能特性

2.1 多模型选择与自定义端点

• 内置 Anthropic（Claude）、AWS Bedrock、OpenAI、Azure OpenAI、Google、Vertex AI、OpenAI Responses API（含 Azure）等提供者配置。
• 通过自定义端点接入任意 OpenAI 兼容 API；兼容 Ollama、AMD Lemonade、groq、Cohere、Mistral AI、Apple MLX、koboldcpp、together.ai、OpenRouter、Helicone、Perplexity、ShuttleAI、DeepSeek、Qwen 等本地与远程服务。

2.2 智能体（Agents）与工具集成

• 无代码自定义助手：可视化构建专业化 AI 助手；Agent 市场：发现并部署社区构建的 Agent；支持与指定用户、分组协作共享。
• 工具能力覆盖 MCP 服务器、工具调用、文件搜索、代码执行；支持 Skills（可复用 SKILL.md 指令包，手动 / 自动 / 常驻三种工作流）、Subagents（独立上下文窗口的隔离子智能体）、Agent 插件（实验性打包 Skills 与 MCP）。
• Agent 管理 API（beta）可创建、发现、更新、删除 Agent，管理 Agent 文件与 Skills，并通过部署绑定的 OIDC 身份认证机器客户端；公开 OpenAPI 与 Swagger UI 覆盖推理、事件、Agent 与 Skill 管理。

2.3 代码解释器

• 基于开源的 ClickHouse/code-interpreter 提供隔离沙箱执行，支持 Python、Node.js（JS/TS）、Go、C/C++、Java、PHP、Rust、Fortran。
• 支持文件上传、处理与下载；执行环境完全隔离，详见官方 Code Interpreter 文档。

2.4 网页搜索与上下文检索

• 结合搜索提供者、内容爬虫与结果重排序检索互联网信息并增强模型上下文；支持自定义 Jina 重排序 API URL；检索组件由 Meilisearch 承担会话索引。

2.5 Artifacts 与图像生成

• 代码 Artifacts 可在对话中直接生成 React、HTML 与 Mermaid 内容，支持全屏预览，Mermaid 图表可导出为 SVG 或 PNG。
• 图像能力：GPT-Image-1 文生图 / 图生图；本地 Stable Diffusion、Flux；或任意图像类 MCP 服务器。

2.6 预设、上下文与会话管理

• 创建、保存、分享自定义预设；对话中途切换端点与预设；编辑、重新提交、分支继续消息；消息与对话 Fork 实现高级上下文控制；可按需压缩长对话并保留近期上下文；支持手动上下文压缩。
• 多模态：上传并分析图像（Claude 3、GPT-4.5、GPT-4o、o1、Llama-Vision、Gemini 等）；与文件对话；消息可复制为富文本。

2.7 语音、多语言与界面

• 语音转文字（STT）与文字转语音（TTS），支持 OpenAI、Azure OpenAI、ElevenLabs，可自动发送与播放音频。
• 界面覆盖英语、简繁中文、阿拉伯语、德语、西语、法语、意语、波兰语、葡语、俄语、日语、瑞典语、韩语、越南语、土耳其语、荷兰语、希伯来语等数十种语言；支持浅色、深色、系统与高对比主题；内置 DeepSeek-R1 等思维链模型的动态推理 UI。

2.8 多用户认证、管理后台与可观测性

• 多用户安全认证：OAuth2、LDAP、邮箱登录；内置审核与 Token 消耗工具。
• 浏览器端管理后台管理用户、分组、角色与配置覆盖，可在线调整设置与角色 / 分组权限而无需重新部署。
• 可观测性：通过 OpenTelemetry 导出追踪与日志，接入 Langfuse 查看 Agent 与模型洞察；Trace Viewer 查看有序模型对话、工具轮次与成本。
• 可恢复流（Resumable Streams）：连接中断自动重连续传；多标签页、多设备同步；从单机到 Redis 水平扩展均支持。

3 官方品牌标识与界面说明

本目录未采集到可上线的官方界面截图，封面仅使用官方 512×512 羽毛 Logo（图1）。产品界面受 ChatGPT 启发并在其上增强设计：左侧为会话与助手侧栏，中部为对话区与 Markdown / 代码 / 公式 / Mermaid 渲染面板，右侧为端点、模型、预设与工具设置；完整界面演示与截图以官方文档 docs.librechat.ai 与 在线演示 / 官网 为准。

4 官方跳转链接汇总

5 前置要求与环境配置

5.1 软件前提

• Docker 部署（推荐）：Docker 与 Docker Compose；栈内自带 MongoDB、Meilisearch、pgvector 与 RAG API 服务，宿主机无需单独安装数据库。
• 源码本地运行：Node.js 运行环境、MongoDB Community Server（或 MongoDB Atlas 连接串）；具体 Node 版本以官方 Local Installation 文档 与 Dockerfile 基础镜像为准（仓库 Dockerfile 基于 node:24.22.1-alpine 构建）。
• 模型凭据：至少准备一个提供者的 API Key（如 OPENAI_API_KEY 或 ANTHROPIC_API_KEY）；user_provided 表示允许用户在界面中自行填写 Key。
• 反向代理（公网部署）：需要 HTTPS 域名时准备 Nginx / Caddy 等反向代理；Passkeys 等能力在生产环境要求 HTTPS（localhost 除外）。

5.2 硬件与系统建议

5.3 端口与服务构成

docker-compose.yml 默认包含以下服务；除应用与管理后台外，其他端口仅在容器网络内部通信：

deploy-compose.yml 为分离部署版本：api 单独运行在 3080，client 使用 nginx:1.27.0-alpine 暴露 80/443，再经 Nginx 反代到 API 与管理后台。

5.4 关键持久化目录与卷

6 方式一：Docker Compose 一键部署（推荐）

6.1 获取源码并准备环境变量

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

# 复制环境变量模板
cp .env.example .env

6.2 编辑 .env 基础项

# 应用监听与访问地址（默认 3080）
HOST=0.0.0.0
PORT=3080
DOMAIN_CLIENT=http://localhost:3080
DOMAIN_SERVER=http://localhost:3080

# 数据库（Docker 栈内使用容器名；本地直连 MongoDB 时改成本地连接串）
MONGO_URI=mongodb://mongodb:27017/LibreChat

生产环境必须为以下项填写持久化唯一值；留空时应用会生成临时密钥并保存到 .env.temp，仅适合本地试用：

# 会话加密密钥（管理后台会话密钥，openssl rand -hex 32 生成，至少 32 字符）
ADMIN_PANEL_SESSION_SECRET=

# JWT 与会话 / 刷新令牌签名密钥
JWT_SECRET=
JWT_REFRESH_SECRET=

# 凭据加解密 Key 与 IV
CREDS_KEY=
CREDS_IV=

# 搜索引擎主密钥（启用 SEARCH 时必填，不要复用公开默认值）
MEILI_MASTER_KEY=

6.3 配置模型提供者

# OpenAI / Anthropic / Google 等：直接填 Key；user_provided 表示允许用户在界面填写
OPENAI_API_KEY=user_provided
ANTHROPIC_API_KEY=user_provided
GOOGLE_KEY=user_provided

各提供者专属变量（Azure、AWS Bedrock、Google Gemini、OpenAI Assistants、Azure AI Search 等）按 .env.example 对应小节填写；本地 / 兼容端点可在 librechat.yaml 中按官方 AI Endpoints 文档 配置。

6.4 启动服务栈

# 后台启动全部服务
docker compose up -d

# 查看服务状态
docker compose ps

# 跟踪主应用日志
docker compose logs -f api

启动完成后浏览器访问 http://localhost:3080；按界面引导注册账号，首批创建的账号具备管理员角色（以官方管理后台文档为准）。管理后台默认通过 http://localhost:3000 访问（或在 deploy-compose 中经 Nginx 路径访问），需先配置 ADMIN_PANEL_SESSION_SECRET。

6.5 代理与反向代理

• 容器内访问外部模型服务需走代理时，配置 PROXY、HTTP_PROXY、HTTPS_PROXY、NO_PROXY 等变量；Compose 默认把 mongodb、meilisearch、rag_api、vectordb、host.docker.internal 加入 no_proxy。
• 公网域名部署时，在 .env 把 DOMAIN_CLIENT / DOMAIN_SERVER 改为对外 HTTPS 地址，并在反向代理层配置 WebSocket / SSE 流式响应所需的长连接与超时。

7 方式二：源码本地运行（开发 / 自定义构建）

7.1 环境准备

• 安装 Node.js 与包管理器（仓库 package.json 标注 npm@11.13.0，具体支持版本以官方本地安装文档为准）。
• 运行 MongoDB Community Server 或使用 MongoDB Atlas；按 .env.example 填写 MONGO_URI。
• 复制 .env.example 为 .env，填写模型 Key 与生产密钥项。

7.2 常用 npm 脚本（取自仓库 package.json）

# 后端开发模式（nodemon 热更新）
npm run backend:dev

# 前端开发模式
npm run frontend:dev

# 生产模式后端启动
npm run backend

# 前端 / 各工作区构建
npm run build
npm run frontend

# 单工作区构建
npm run build:data-provider
npm run build:api
npm run build:data-schemas
npm run build:client
npm run build:chat

7.3 用户管理脚本

npm run create-user        # 创建用户
npm run invite-user        # 邀请用户
npm run list-users         # 列出用户
npm run reset-password     # 重置密码
npm run ban-user           # 封禁用户
npm run delete-user        # 删除用户

7.4 部署版 Compose 脚本

# 启动 deploy-compose 分离栈
npm run start:deployed

# 停止 deploy-compose 栈
npm run stop:deployed

7.5 Redis 模式（多节点 / 多标签同步）

# 单机 Redis
npm run backend:redis:single

# Redis 集群
npm run backend:redis:cluster

# 脚本管理
bash scripts/redis-mode.sh single
bash scripts/redis-mode.sh cluster
bash scripts/redis-mode.sh stop

8 配置项说明

8.1 服务与会话基础项

8.2 认证与注册策略

8.3 社交登录与 LDAP、邮件

8.4 模型提供者端点

8.5 搜索、语音、代码解释器与 RAG

8.6 审核、共享链接与观测性

9 常用运维命令

9.1 Docker Compose 日常操作

# 查看服务状态
docker compose ps

# 后台启动 / 重启 / 停止
docker compose up -d
docker compose restart api
docker compose down

# 查看日志（api / admin-panel / rag_api / meilisearch 等）
docker compose logs -f api
docker compose logs --tail=200 admin-panel

# 拉取最新镜像并滚动更新
docker compose pull
docker compose up -d

升级前务必先阅读官方 Changelog 的破坏性更改说明；备份 data-node、meili_data_v1.35.1、uploads、images、logs、skill 与 librechat-data 卷后再执行更新。

9.2 备份与恢复

• 数据库备份：进入 mongodb 容器执行 mongodump，把 data-node 目录与命名卷纳入定期备份计划。
• 文件备份：打包 ./uploads、./images、./skill 目录；librechat-data 命名卷通过 docker run --rm -v 挂载方式导出。
• 环境变量与自定义配置：备份 .env 与 librechat.yaml；更换服务器时连同持久化目录一起迁移。

9.3 源码方式管理命令

npm run list-users          # 查看用户
npm run create-user         # 新增用户
npm run reset-password      # 重置指定用户密码
npm run ban-user            # 封禁用户
npm run delete-user         # 删除用户
npm run flush-cache         # 刷新缓存
npm run user-stats          # 用户统计（脚本见 package.json）

9.4 索引与缓存维护

# 重置 Meilisearch 同步（以仓库脚本为准）
npm run reset-meili-sync

# 刷新服务缓存
npm run flush-cache

10 常见故障排查

10.1 页面打不开或 3080 端口无响应

• 执行 docker compose ps 确认 api 与依赖服务状态；docker compose logs api 查看启动报错。
• 确认宿主机 3080 端口未被占用，防火墙 / 安全组已放行；反向代理转发地址与 DOMAIN_CLIENT / DOMAIN_SERVER 一致。
• 数据库未就绪时 API 会反复重连；检查 MONGO_URI 与 mongodb 容器日志。

10.2 登录后提示密钥相关错误或凭据无法解密

• 生产环境未填写 JWT_SECRET、JWT_REFRESH_SECRET、CREDS_KEY、CREDS_IV 时，重启后临时密钥轮换会导致旧会话与已存凭据不可用；首次部署即填写持久唯一值。
• 修改密钥后需要重建容器使配置生效；确认 .env 已挂载进 api 容器（Compose 中 ./.env 挂载到 /app/.env）。

10.3 管理后台无法启动

• 未配置 ADMIN_PANEL_SESSION_SECRET 时后台拒绝启动；用 openssl rand -hex 32 生成后写入 .env 并 docker compose up -d admin-panel。
• 核对 API_SERVER_URL 与 VITE_API_BASE_URL 在容器网络内可达；后台宿主端口 3000 未被占用。

10.4 模型请求失败或模型列表为空

• 核对提供者 Key、Base URL 与模型名；user_provided 模式下需在登录后于界面填写 Key。
• 本地 / 自定义端点按 librechat.yaml 文档配置；检查容器到端点的网络与代理变量（HTTP_PROXY / HTTPS_PROXY / NO_PROXY）。
• 被审核策略、角色权限或 librechat.yaml 端点配置隐藏的模型，不会出现在选择列表中。

10.5 搜索功能不可用

• SEARCH=true 时必须同时配置唯一的 MEILI_MASTER_KEY；meilisearch 容器状态正常且 MEILI_HOST 指向 http://meilisearch:7700。
• 多节点部署时按文档使用 MEILI_NO_SYNC 控制仅单实例执行索引同步。

10.6 语音、代码解释器、RAG 功能报错

• STT / TTS：核对 STT_API_KEY、TTS_API_KEY 与所选提供者接口；网络代理与超时按官方文档调整。
• 代码解释器：确认代码解释器服务已部署并配置 LIBRECHAT_CODE_BASEURL；自托管 JWT 认证相关变量按 Code Interpreter 文档 配对配置。
• RAG 文件解析失败：检查 rag_api 与 vectordb 容器状态、RAG_API_URL、嵌入模型凭据与文件大小 / 超时配置。

10.7 注册与登录异常

• 关闭注册时把 ALLOW_REGISTRATION=false；需要管理员开通时使用 npm run create-user / invite-user。
• 邮件重置依赖完整 SMTP 配置；未配置时保持 ALLOW_PASSWORD_RESET=false。
• OAuth 登录失败核对回调 URL 是否与平台后台白名单一致；LDAP 登录核对 LDAP_URL、绑定 DN、用户搜索基与 CA 证书路径。

10.8 升级后兼容性问题

• 升级前阅读 Changelog 破坏性更改条目；跨大版本升级按官方迁移说明执行索引、权限与数据库迁移脚本。
• 历史部署存在 v0.8.7 及更早索引差异时，按文档重建或同步 Meilisearch 索引；问题复现时在 Issues 附上版本号、.env 非敏感配置与 api 容器日志。

11 风险与合规说明

以下条款整理自官方 README、MIT 许可证、.env.example 与官方文档口径；如与官方原文不一致，以仓库 LICENSE、README 与 docs.librechat.ai 最新说明为准。

11.1 开源协议

LibreChat 开源代码采用 MIT 许可证，允许自由使用、修改、合并、发布与商业再许可，须在副本中保留版权声明与许可声明。MongoDB、Meilisearch、pgvector、Nginx、各模型 SDK、代码解释器组件等第三方依赖各自遵循其对应许可证；RAG API 与官方站点为独立仓库，许可以各自仓库为准。

11.2 模型与 API 条款

• 平台不提供模型与 API Key；OpenAI、Azure、Anthropic、Google、AWS Bedrock、Vertex AI、DeepSeek、Qwen、Ollama 等服务归对应厂商或后端项目所有，受其服务条款、隐私政策与计费规则约束。
• 本地模型权重的版权与使用许可由模型发布方规定；商用前须核对模型许可证。

11.3 多用户数据与隐私

• 部署在公网时应关闭不必要的注册、启用 HTTPS、配置角色分组权限与会话安全策略；共享链接默认需登录访问，公网开放前评估内容泄露风险。
• 用户对话、上传文件与凭据保存在 MongoDB、上传目录与向量库中；运维方应落实访问控制、定期备份与过期清理。代码、文档与上下文按所选模型发送到对应服务，敏感数据优先走自部署模型与离线端点。

11.4 Agent、工具与沙箱风险

• Agent、MCP 服务器、代码解释器、文件搜索与附属工作区具备读取文件、执行命令与发起网络请求的能力；第三方 Agent、MCP 服务器与插件应审核来源、权限与凭据范围后再启用。
• 附属代码工作区、Agent 插件打包等功能官方标记为实验性；生产环境使用前阅读对应文档的限制说明，先在非关键账号与目录内测试。
• 项目按现状（AS-IS）提供，不保证模型输出正确、不保证所有提供者与平台持续兼容；使用者自行承担模型选择、数据泄露、服务中断与业务损失风险。如认为仓库内特定文件侵犯合法权益，请通过 GitHub Issues 提交说明，不要在公开 Issue 中贴出 API Key、密码、会话 Cookie 或内部地址。