1. LibreChat 到底是什么一个聚合多模型的对话底座我第一次接触 LibreChat 是在本地跑模型跑得有点烦的时候。当时手头同时有 OpenAI 的 Key、Anthropic 的订阅偶尔还要切到本地跑的 Ollama 模型结果就是浏览器里永远开着三四个聊天窗口上下文各管各的历史记录散落一地。后来同事甩给我一个 GitHub 地址说这个项目能把它们全收进去那个人就是 LibreChat。LibreChat 本质上是一个开源的、可自托管的 AI 对话前端平台底层用 Next.js 加 Node.js 写的后端用 MongoDB 存数据官方推荐用 Docker Compose 一键拉起。它解决的问题非常具体当你的工作流里同时存在多个模型服务商、多个模型、多个使用者的时候你需要一个统一入口而不是每人各自开一堆网页靠浏览器收藏夹吃饭。它就干这个事。它的定位和 ChatGPT 网页版最大的不同在于你不依赖任何一家厂商的前端。你只需要在后台配好各家模型的 API Key剩下的聊天界面、历史记录、多用户管理、预设提示词、文件上传、代码解释器全部由 LibreChat 自己提供。换句话说LibreChat 是前端 中间层真正干活的模型在它背后可以是云服务商也可以是你自己机器上跑的本地模型。适合谁看三类人最合适个人开发者想用自己的 Key 在统一界面里调用多个模型并且希望聊天记录留在自己手里。小团队需要给几个人开账号共用一套模型配置但各自的历史记录和对话互不干扰。对数据敏感的技术用户不想把对话记录存在第三方厂商的云端自己在 VPS 或者家里 NAS 上部署一套。我建议你把它理解成自建版 ChatGPT但功能上又比原生界面多一些东西。下面我会把核心能力、部署流程、模型接入、进阶配置和实际踩坑全部分享出来尽量做到你照着操作就能跑起来。2. 核心功能拆解它凭什么比官方聊天界面更能打LibreChat 不是简单把 ChatGPT 页面抄了一遍它有几个设计上的关键差异值得先搞明白。2.1 多模型接入一个界面管所有这是最核心的卖点。你可以在同一个对话界面里通过下拉菜单切换不同的模型。官方支持的提供商包括 OpenAI、Azure OpenAI、Google Gemini、Anthropic Claude、Amazon Bedrock以及任何兼容 OpenAI API 格式的第三方服务比如本地部署的 vLLM、Ollama、One API 网关之类的。这意味着什么比如你上午用 GPT-4o 写代码下午想用 Claude 做长文档理解晚上想试试本地跑的开源模型不用换页面不用重新描述上下文。LibreChat 的每个对话是独立的会话切换模型只影响当前会话后续的回复历史上下文都还在。我实测过同一个会话里从 GPT-4o 切到 Claude 3.5 Sonnet之前讨论的内容它能接得上只要这个模型支持足够长的上下文窗口。2.2 多用户体系小团队直接开账号原生 ChatGPT 的 Team 方案是按人头收费的而且管理员能做的控制很有限。LibreChat 自带一套完整的用户注册、登录、角色权限体系。你可以设置为允许任何人注册、只允许邀请注册、或者完全关闭注册自己建账号。用户角色分为管理员和普通用户管理员可以在后台看到所有用户的会话统计、删除违规账号、调整全局访问权限。对于一个小团队或者家庭共享场景这个功能等于白送了一个 AI 网关的用户管理系统省掉了自己写授权逻辑的麻烦。2.3 对话管理比官方更强的历史能力用过 ChatGPT 的人都知道官方会对历史对话做分类整理但你能做的操作其实有限。LibreChat 里的对话管理做得很细每个会话有独立的标题自动生成也可以手动改支持搜索历史记录、固定/取消固定对话、共享对话链接、导出对话内容为 Markdown 或 JSON。尤其导出功能我经常用。有些长对话需要整理成文档归档直接在界面上点导出得到的就是格式干净的 Markdown 文件省去复制粘贴再排版的时间。对于做技术调研、写方案、整理需求的人来说这个功能很实用。2.4 预设提示词和助手角色LibreChat 里可以定义预设Presets相当于把提示词、模型参数、温度、top_p、上下文长度等组合固化成一套配置。你可以给自己的常用场景建预设比如代码审查、文案润色、SQL 优化。更进阶的是创建助手Assistants类似 GPTs 的概念。你可以在配置中给助手设定系统提示词、附加文件、指定模型然后团队成员都能调用它。对于固定业务流程比如客服标准回复、技术文档摘要提前做好助手模板能大大减少重复写提示词的时间。2.5 文件上传与代码解释器LibreChat 支持在对话中上传文件包括图片、PDF、TXT、CSV 等。我常用的场景是把一份 CSV 传上去让它用 pandas 分析数据字段然后直接生成图表代码。它还有一个 RAG检索增强生成能力可以把上传的文档切片后向量化后续对话直接基于这些文档内容回答相当于给模型接了一个临时记忆库。代码解释器是基于 Jupyter 内核的模型会生成 Python 代码在后端执行完再把结果传回来。实测对数据清洗、图表生成、数学计算这类任务很有效。需要注意一点代码解释器的执行环境是容器内的沙箱依赖预装的 Python 包如果你要跑特殊库需要在镜像里额外安装。2.6 插件与内置搜索LibreChat 早期的插件系统现在逐渐整合成了一些内置工具。最有用的一个是联网搜索某些版本通过 RAG 或插件实现它会把用户的提问包装成搜索引擎查询抓取网页摘要作为上下文喂给模型让模型能回答超出训练截止日期的问题。我实际测试过让它搜索最近的编程框架发布动态它能给出带引用的回答虽然调用链比普通对话要慢几秒但信息时效性确实上来了。对于需要做技术选型调研、查最新版本特性的场景这个功能比直接问模型靠谱得多。3. 部署实战Docker Compose 从零搭一套可用实例LibreChat 的部署方式有几种直接用 Docker 单容器、Docker Compose 多服务、源码编译运行。我强烈建议走 Docker Compose因为它的服务依赖关系前端、后端、数据库、可选组件比较多手工跑容易漏。3.1 准备工作与资源评估先说你需要的条件一台 Linux 服务器或者本地机器建议 2 核 4G 以上。如果你的对话频率高、并发大内存建议 8G。我有一次在 1G 内存的小机器上硬跑MongoDB 经常被系统 OOM killer 干掉。Docker 20.10 以上Docker Compose v2 插件。一个域名加反代可选但推荐否则直接用 IP 访问也可以。能连通你要接入的模型服务商 API。端口规划上默认架构是前端client跑 3000 端口后端api跑 3080 端口MongoDB 在容器内部不对外暴露。如果你只有一个域名建议用 Nginx 或 Caddy 把 443 端口统一指到前端 3000然后用路径或者二级域名区分。3.2 docker-compose 配置详解我用的 compose 文件官方稍作精简version: 3.8 services: api: image: ghcr.io/danny-avila/librechat-api:latest container_name: librechat-api ports: - 3080:3080 env_file: - .env restart: always depends_on: - mongodb client: image: ghcr.io/danny-avila/librechat-client:latest container_name: librechat-client ports: - 3000:3000 restart: always depends_on: - api environment: - NEXT_PUBLIC_API_ENDPOINThttp://api:3080 mongodb: image: mongo:7 container_name: librechat-mongodb restart: always volumes: - ./data/mongodb:/data/db healthcheck: test: [CMD, mongosh, --eval, db.adminCommand(ping)] interval: 10s timeout: 5s retries: 5注意几个关键点NEXT_PUBLIC_API_ENDPOINT这个环境变量必须指向后端 API 的容器间地址不能写localhost因为前端容器里的 localhost 不是 API 容器。这里填http://api:3080是让前端在服务器内部请求后端。MongoDB 的持久化目录./data/mongodb必须提前建好或者让 Docker 自动创建。万一容器重建数据不会丢。我加了 MongoDB 的健康检查这样后面在 compose 里可以让 api 服务等待数据库就绪。.env文件是最关键的部分核心配置项# 安全相关务必换成随机字符串 JWT_SECRETyour_jwt_secret_here JWT_REFRESH_SECRETyour_jwt_refresh_secret_here CREDS_KEYyour_creds_key_here # MongoDB 连接注意这里的域名是 compose 服务名 MONGO_URImongodb://mongodb:27017/LibreChat # 开放注册小范围用可以开 ALLOW_REGISTRATIONtrue ALLOW_EMAIL_PASSWORDfalse # OpenAI 配置 OPENAI_API_KEYsk-xxxx OPENAI_MODELSgpt-4o,gpt-4o-mini,o4-mini # 会话相关 SESSION_EXPIRY60JWT 那三个密钥建议用openssl rand -hex 32生成别用弱口令。CREDS_KEY是用来加密用户在界面里填写的自定义 API Key 的如果大家都用服务端统一配置的 Key这个字段也不能为空。3.3 首次启动与日志排查配置好后直接docker compose up -d首次启动要拉几个镜像大概几百 MB取决于你的网络情况。启动完以后用docker compose ps查看三个容器是否都处于 Up 状态。如果前端页面打不开先看一下 client 容器的日志docker logs librechat-client --tail 100最常遇到的问题是NEXT_PUBLIC_API_ENDPOINT没生效前端请求 3080 失败。这时候进入浏览器 F12 看 Network 面板确认请求走到哪个地址。如果是localhost:3080且你在远程服务器上访问那说明环境变量没传给前端构建需要重建客户端镜像。还有个小坑LibreChat 的 client 容器跑的是 Next.js默认监听 3000 端口但它有一个 service worker 缓存机制更新版本后偶尔出现旧页面。强制刷新浏览器缓存一般能解决实在不行就docker compose restart client。4. 接入真实模型OpenAI、Anthropic 和本地模型怎么配LibreChat 没有自带任何模型所以部署完成后第一件事就是接入模型提供商。它会读取.env里的大模型相关配置然后按照你指定的模型列表显示在界面上。4.1 OpenAI 系配置最简单的场景你在.env里填上OPENAI_API_KEY和OPENAI_MODELSOPENAI_API_KEYsk-你的密钥 OPENAI_MODELSgpt-4o,gpt-4o-mini,o1-mini其中模型名必须和 OpenAI API 返回的模型 ID 完全一致不然界面上虽然显示了下拉项实际请求会报 400。你可以通过curl https://api.openai.com/v1/models拉一遍当前可用的模型 ID。如果你用的是 Azure OpenAI需要额外填AZURE_OPENAI_API_KEY... AZURE_OPENAI_ENDPOINThttps://你的资源名.openai.azure.com/ AZURE_OPENAI_API_INSTANCE_NAME你的部署名Azure 的模型名不是标准的 gpt-4o而是你的仪表盘里自定义的部署名deployment name这个特别容易搞混配完之后界面上看不到模型多半就是部署名写错了。4.2 Anthropic Claude 配置Anthropic 的配法和 OpenAI 几乎一样ANTHROPIC_API_KEYsk-ant-xxxxLibreChat 会自动拉取 Anthropic 可用的模型列表。需要注意Anthropic 的 API 对请求频率限制比较严格如果你在团队里共享同一个 Key并发一高很容易收到 429。建议在界面的模型设置里把速率限制关掉或者在 LibreChat 的配置项里调大请求间隔。4.3 本地模型与 OpenAI 兼容接口本地模型这块我强烈推荐用 Ollama 再加一个转换层。Ollama 本身提供的 API 格式不是完全兼容 OpenAI 的但 LibreChat 要求接入端点必须是 OpenAI 格式所以需要中间做一层转换。最简单的办法是部署一个支持 OpenAI 格式的推理服务比如 vLLM它原生兼容 OpenAI 的/v1/chat/completions接口。用 vLLM 启动本地模型后在 LibreChat 里这么配OPENAI_API_KEYdummy-key-not-used OPENAI_BASE_URLhttp://你的vLLM服务IP:8000/v1 OPENAI_MODELSQwen/Qwen2.5-72B-InstructOPENAI_BASE_URL是指向 OpenAI 兼容服务的根地址后面必须带/v1。这里的OPENAI_API_KEY可以随便填因为 vLLM 默认不校验 Key但 LibreChat 校验配置时不允许为空。如果非要用 Ollama那你得在外面套一个类似llm-gateway的一层代理把 OpenAI 格式转成 Ollama 的/api/chat格式或者直接用支持该格式的网关软件。总体思路是LibreChat 不强求模型服务商是谁只要求你提供一个 OpenAI 风格的接口剩下的它全不管。这一点做完之后整个平台立刻变成一个各种模型都能统一调度的入口比单独用各家后台舒服太多。4.4 验证模型连通性接入完成后在界面上随便开一个会话模型下拉框里应该能看到你配置的模型列表。选一个发条消息比如你好用一句话介绍你自己。如果回复正常说明链路通了。有问题的话去 api 容器的日志里看docker logs librechat-api --tail 50常见的错误Incorrect API key provided说明 Key 配错了或者.env改动后没重启 api 服务。The model xx does not exist模型 ID 写错。OpenAI 的模型 ID 大小写敏感GPT-4o和gpt-4o是两个概念。Connection refusedOPENAI_BASE_URL指向的服务没起来或者端口不通。5. 进阶配置多用户权限、预设助手与移动端访问基础跑通之后真正让 LibreChat 好用起来的是下面这几个进阶操作。5.1 用户注册策略与账号管理默认情况下 LibreChat 允许任何人访问你的部署页面并注册账号。如果你部署在公网上这就是一个安全隐患任何人都能蹭你的模型 Key 产生费用。推荐改成邀请制ALLOW_REGISTRATIONfalse关闭注册后你需要用管理员账号在后台创建用户。管理员账号怎么来第一次以任意方式注册的第一个账号会自动成为管理员所以流程是先保持注册打开自己注册一个账号然后关闭注册再用管理员身份给其他人生成邀请链接。后台还提供了按用户查看会话记录、重置密码、封禁账号的功能。对于团队使用来说这点很重要——每个成员的对话内容是隔离的管理员只能看到统计信息看不到具体聊天内容除非你有意开启审计日志。如果有合规要求建议在部署文档里记录好谁有管理员权限。5.2 预设与助手配置的实战用法预设的配置界面很直观新建一个预设填上预设名称、选择模型、写好系统提示词、调整温度参数保存。之后在对话前选择对应预设新会话会用它作为默认配置。我分享一个我自己团队的用法我们每周要做竞品分析原来每个人的提问方式都不一样效果也不稳定。后来我在 LibreChat 里建了一个竞品分析师助手系统提示词里写了分析框架市场定位、功能对比、定价策略、优劣势判断限定用 GPT-4o温度降到 0.3保证输出风格稳定。现在新同学进来只需要选择这个助手丢一份竞品官网链接输出质量基本及格再人工微调就行。预设里还能绑定 RAG 文档、指定自定义工具这个对固定业务场景非常有用。不过要注意一点不同模型对相同的预设文本解释程度不同同一个系统提示词在 Claude 上的表现和在 GPT 上可能差距很大。建议预设按模型来建而不是一套提示词走天下。5.3 反向代理与 HTTPS如果用 IP 直接访问浏览器会一直提示不安全而且一些浏览器的高级 API比如麦克风会受限。建议套一层 Caddy 反代Caddy 的配置特别短自动申请证书your.domain.com { reverse_proxy localhost:3000 }Caddy 会自动处理 HTTPS 证书不需要手动装 Certbot。如果你用 Nginx配置也差不多server { listen 443 ssl; server_name your.domain.com; ssl_certificate /etc/letsencrypt/live/your.domain.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/your.domain.com/privkey.pem; location / { proxy_pass http://127.0.0.1:3000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } }这里有个容易踩的坑前端如果反代到 3000那前端和 API 的通信仍然走http://api:3080容器内或者http://127.0.0.1:3080如果从宿主机访问。你要确保客户端请求的 API 地址和实际可达地址对上否则就会出现页面能开但发消息一直转圈的情况。5.4 移动端适配LibreChat 的前端是响应式设计手机上直接浏览器访问也可以正常用。但如果你想装成 App 的模式Android 可以用 Chrome 的添加到主屏幕iOS 用 Safari 的添加到主屏幕它支持 PWA体验接近原生应用。我实测过从手机上通过 PWA 访问对话、历史记录、文件上传都能用只要服务器带宽不是太差体验基本流畅。6. 生产环境实操备份、更新与踩坑记录把 LibreChat 当一个长期服务跑下面这几点必须提前想好否则早晚出事。6.1 MongoDB 备份策略LibreChat 的所有对话历史、账号信息都存在 MongoDB 里。MongoDB 单容器跑在服务器上最怕磁盘损坏或者误删 volume。我的备份方案是每天凌晨用mongodump导出一份压缩包传到另一台机器或者对象存储。docker exec librechat-mongodb mongodump --archive --gzip ./backup/librechat-$(date %Y%m%d).archive.gz恢复的时候用mongorestore --archive --gzip注意要恢复到同一个数据库名LibreChat。别问我是怎么知道这个坑的——我第一次恢复的时候没带库名参数结果数据全部进了admin库前端的会话记录全丢了。还有一个小建议MongoDB 的 WiredTiger 引擎在容器里如果被强制 kill比如机器断电有概率出现索引损坏。启动容器加--nojournal的场景不适用于生产反而要确保 journal 开启默认就是开着的。如果日志里频繁出现database cannot be locked多半是上次没正常退出删掉 mongod.lock 再重启但不能保证数据完整所以我再次强调备份的重要性。6.2 版本升级与兼容性LibreChat 的迭代非常快基本每周都有新版本。执行升级前我强烈建议看一遍 GitHub Releases 重点看Breaking Changes部分。有些版本会改环境变量名称比如之前把OPENAI_API_KEY相关的变量结构换过如果你直接用docker compose pull docker compose up -d容器可能起不来。我现在的升级流程是备份 MongoDB 数据。拉取新镜像docker compose pull比对docker-compose.yml和.env是否有新增必填项。重启服务docker compose up -d打开页面先确认管理员登录、历史会话、模型列表都正常再让团队成员使用。6.3 高并发与限流LibreChat 本身没有内建很细粒度的限流策略如果你共享一个 Key 给很多人用模型厂商的 API 会先帮你 429。但如果你用本地模型并发一高推理服务可能直接把内存打爆。我的经验是把 LibreChat 后端的请求并发数限制配合模型服务的并发队列一起做。比如 vLLM 启动时可以加--max-num-seqs限制同时处理的序列数LibreChat 这边则可以在代理层比如 Nginx对/api/chat/stream路径做limit_req限制。虽然这会影响并发体验但总比整个服务挂掉强。6.4 我遇到的三个典型故障与排查思路第一个是前端页面打不开。排查步骤先curl localhost:3000看返回如果 curl 正常但浏览器打不开检查防火墙和安全组是否放行 3000 端口如果反代配置了检查 Nginx/Caddy 日志里的具体报错。第二个是发消息一直转圈没有回复。这是最典型的配置问题。打开浏览器 F12 看 Network找到 chat 请求的响应状态。如果 401检查 JWT 密钥如果 502说明 API 容器崩了看 api 日志确认是 Mongo 连不上还是模型请求失败如果 404大概率是NEXT_PUBLIC_API_ENDPOINT配错了。第三个是MongoDB 容器反复重启。大多数情况是权限问题宿主机上data/mongodb目录的属主和容器内 mongod 用户不一致。最简单的处理是删掉 volume 重建但那样历史数据就没了所以创建目录时要提前把权限给对mkdir -p data/mongodb chown -R 1000:1000 data/mongodbMongo 官方镜像默认用 uid 1000 跑进程你非要用 root 跑的话启动参数加--storageEngine还是会有权限报错建议直接听官方安排。6.5 资源占用与长期运行观察LibreChat 三个常驻容器加起来大约占 600MB 到 1GB 内存其中 MongoDB 是大头。如果是 2G 内存的小机器不建议同时跑 LibreChat 再加本地模型推理可以让 LibreChat 只做前端代理模型全部走云 API。长期运行观察指标主要看三点MongoDB 容器日志里有没有connection refused一类的报错api 容器内存涨幅是否稳定如果持续上涨考虑是不是有会话泄漏重启能暂时缓解磁盘占用是否因为日志文件持续膨胀。我一般给 Docker 配置日志轮转避免单个容器日志文件涨到几个 GBlogging: driver: json-file options: max-size: 10m max-file: 3在 compose 文件的每个服务下都加上这一段日志管理会省心很多。7. 下一步还能怎么玩把 LibreChat 变成一个团队 AI 入口如果你已经能稳定运行一套 LibreChat并且熟悉了上边的操作那最后我再分享几个往外扩展的方向都是我在实际使用中验证过比较顺的路子。一是把 LibreChat 嵌入到现有系统里。它提供了 API 接口你可以在自己的应用里调用 LibreChat 的后台接口创建会话、发送消息、读取回复完全跳过官方前端。再者LibreChat 支持自定义模型供应商的能力意味着你可以随时把新的模型服务商加进来而不需要改动前端代码。二是配合知识库做垂直场景。LibreChat 的 RAG 功能可以配置多个向量库把公司内部的文档、FAQ、历史工单都喂进去然后让模型基于这些内容回答。团队内部做内部问答机器人效果比直接问通用模型好得多因为回答会带上你们的业务上下文。三是习惯用预设 多模型的工作流之后把那些你反复使用的提示词模板沉淀成团队资产。很多团队买了一大堆 AI 服务但真正用起来的时候每个成员还是在重复造轮子。LibreChat 给了你一个沉淀和复用提示词的地方可以让团队里积累的最佳实践变成所有人都能调用的预设和助手。我在跑这套东西的这几个月里最大的感受是工具的复杂度其实是可控的难点从来不在装好它而在想清楚你到底要它解决什么问题。LibreChat 适合那种模型越来越多入口越来越杂的阶段它不是一个花哨的产品但它是那个能把多个 AI 服务真正揉进日常工作的地基。如果你正好也走到这一步拿它当起点大概率不会让你失望。