如果你手里同时握着 OpenAI、Claude、Gemini 的 API key又不想每天在几个网页之间来回切换LibreChat 基本就是为这个需求长出来的。它是目前社区里迭代很活跃的开源 AI 聊天前端之一把多模型聚合、会话管理、文件上传、代码解释、多用户登录这些能力全部打包进一个自托管服务里。装好之后你打开的就不再是某个厂商的对话框而是一个“自己说了算的 AI 应用门户”。这篇文章面向想自己搭一套 AI 工具的人无论个人自用还是团队内部共用一个入口都适用。我会从最基础的部署说起讲到多模型配置、本地模型接入、多人登录、数据备份和安全加固最后把实际使用中踩过的坑一并列出来。看懂之后你可以根据手里的服务器或者电脑配置快速复现一套可长期使用的 ChatGPT 替代品。1. LibreChat 是什么一套自己说了算的多模型聊天门户1.1 核心功能图谱LibreChat 不是一个简单的聊天 UI它更像是一层“聚合层”。官方项目最初借鉴了 ChatGPT 的交互方式但发展到现在已经远远超出了“仿 ChatGPT”的范畴。我把它常用的能力拆开来看至少有这几块多模型聚合。一个界面里可以切换 OpenAI、Azure OpenAI、Anthropic Claude、Google Gemini、本地 Ollama 模型以及任何兼容 OpenAI API 格式的服务。切换模型不用换页面会话上下文还能共享。会话管理与历史搜索。所有对话记录存数据库支持按关键词搜索历史会话这一点对长期使用非常关键。多模态与文件上传。支持上传图片、PDF、Word、Excel 等文件模型能读取的内容会直接进入上下文配合视觉模型可以做 OCR、图片理解配合支持工具的模型可以解析文档。多用户与权限管理。自带注册登录流程支持 Google/GitHub 免密登录管理员后台可以看用户列表、管理会话数据。插件系统。代码解释器、网页浏览、图片生成等能力是可插拔的不是所有模型都能用同一套插件但整体生态已经比较完整。国际化与 PWA。界面支持简体中文可以安装到手机桌面用起来和原生 App 的体验差别不大。所以准确地说LibreChat 解决的问题是“AI 入口碎片化”。如果你同时在用 ChatGPT、Claude 和 Gemini你就会明白“统一入口 统一历史记录 统一账号体系”这件事比多开几个网页要舒服得多。1.2 为什么不用官方网页而选自托管有人会问直接用官方网页不好吗这取决于你的使用场景。拿 LibreChat 和官方 ChatGPT、以及另一类常见的开源前端做对比差别还是很明显的。对比维度LibreChat官方 ChatGPT常见轻量前端模型聚合支持多种厂商模型仅 OpenAI 系部分支持但深度不一数据控制权完全自托管数据在平台侧完全自托管多用户体系完整账号、OAuth、角色权限平台账号体系通常较弱甚至只有单一密码历史记录搜索内置全文搜索自带但受平台限制有历史但搜索能力参差插件与扩展沙箱执行、可扩展内置但不可控很少运维门槛有 Docker 基础即可零门槛低门槛我做这个选择的核心原因是数据权。对话记录里经常带着代码片段、内部文档、未公开的想法放在自托管服务里数据落在自己的存储上权限自己控制备份自己掌握至少心里有数。另一个原因是成本多个模型按需使用哪个好用切哪个不会被单一厂商的订阅费绑住。1.3 一句话讲清它的工作方式LibreChat 的前端是 React后端是 Express数据库默认用 MongoDB历史搜索依赖 Meilisearch再加上一个可选的 RAG 服务用于文档问答。请求的流转路径大致是浏览器里的对话请求先到 LibreChat 后端后端根据当前会话选择的模型端点把请求转给对应的模型 API模型返回的内容以流式方式推回页面。会话记录、文件信息等数据落到 MongoDB历史搜索从 Meilisearch 读取索引。这个结构的好处是“前端只管展示后端统一做接口切换”以后哪怕新增一个模型厂商通常只需要加一个 endpoint 配置不用改动页面逻辑。这也正是我后面要重点讲的扩展思路。2. 部署前的准备与整体方案设计2.1 需要准备什么在开始之前先把你手里的底牌盘一遍。部署 LibreChat 不需要多高配置的服务器但有几个硬性条件一台能跑 Docker 的机器Linux 服务器、本地电脑、虚拟机都行。Docker 20 和 Docker Compose v2。老版本 Compose 命令有差异建议直接装新版。内存建议 4GB 以上。MongoDB 和 Meilisearch 都比较吃内存如果你还要跑本地模型内存越多越好。至少一个可用的大模型 API Key。OpenAI、Anthropic、Google 三家里有一个就能跑通全流程。可选一个域名。如果只是自己局域网用IP 就够了如果需要多人从外网访问建议绑定域名并上 HTTPS。我自己第一次部署时用的是一台 4GB 内存的轻量服务器先是只接 OpenAI 和 Claude后来又加了 Ollama 跑本地小模型整体运行没有问题。如果你只有 2GB 内存建议不要开搜索功能后面会讲怎么关。2.2 整体架构Docker Compose 一把梭LibreChat 官方仓库自带 docker-compose.yml这是最推荐的部署方式因为里面有完整的服务编排。拉下来并启动后你会发现系统里有几个容器在跑每个都有明确分工librechat主服务跑前端静态资源、后端 API、WebSocket。mongodb存账号、会话、消息、文件元数据。meilisearch提供历史会话的全文搜索。rag_api可选的 RAG 服务用于把文档切块、向量化、做问答检索。我第一次看到这串容器心里是有点慌的但实际上默认配置已经调好基本不需要改任何内部参数。你要做的就是复制环境变量模板填自己的 Key然后启动。这种“开箱即用”的设计降低了门槛也意味着你后期可以根据需求裁剪组件比如不想要搜索就撤掉 Meilisearch。2.3 账号系统与扩展模块的取舍部署前要想清楚一个问题这套服务是自己一个人用还是团队共用一个人用密码登录就够了甚至可以把注册关闭只有一个账号简单省事。团队共用我建议提前计划好 OAuth 登录Google/GitHub这样成员不需要重新设密码权限也更好管理。LibreChat 还区分普通用户和管理员管理员可以进后台面板看使用情况、停用异常账号这些都是团队场景里很实用的功能。至于 RAG、代码解释器这类扩展先不要在一开始就全部打开。我的建议是“最小可用优先”先把基础的聊天跑通再加花活。否则排错的时候分不清是模型 Key 问题还是 RAG 服务问题会非常头疼。3. 手把手部署从拉代码到看到聊天框3.1 拉取代码与环境变量部署的第一步是拿到官方代码。这里以命令行为例操作过程很简单git clone https://github.com/danny-avila/LibreChat.git cd LibreChat cp .env.example .env复制完 .env 之后用编辑器打开它。这个文件里全是可配置项但你不需要每个都看懂。首次部署只需要关注一小部分剩下的保持默认即可。我的经验是不要在 .env 里乱改看不懂的项很多问题都是“过度配置”改出来的。3.2 关键环境变量解读下面这些是第一次部署必须理解的变量我按重要性从高到低说。OPENAI_API_KEY / ANTHROPIC_API_KEY / GOOGLE_API_KEY模型服务商的密钥。至少填一个否则登录后模型列表会是空的。ALLOW_REGISTRATION是否允许注册。默认 true方便你注册第一个账号。正式使用如果只自己用可以改成 false。ALLOW_EMAIL_LOGIN是否允许邮箱密码登录。如果只打算用 OAuth可以关掉但建议保留因为 OAuth 配置出错时邮箱登录是救命稻草。MONGODB_URIMongoDB 连接串。用 Docker Compose 时一般保持默认因为服务之间在同一网络里直接用容器名互相访问。MEILI_MASTER_KEYMeilisearch 的密钥。默认模板里有一串建议改成你自己的强随机字符串。改的时候注意 .env 和 docker-compose.yml 中要保持一致。DOMAIN_CLIENT / DOMAIN_SERVER对外访问地址。局域网 IP 或域名。这个变量影响 OAuth 回调地址如果只在本机访问可以不急着改。LOG_LEVEL日志级别。排错时改成 debug平时可以调回 info。提示.env 文件不要提交到 Git也不要截图发给别人。里面装着你的 API Key泄露出去等于把钱包交给别人保管。3.3 配置主流模型供应商配置模型 Key 大概是整个部署中最让人有成就感的一步。打开 .env找到对应的变量填进去就行。下面是一些常见的配置写法。# OpenAI OPENAI_API_KEYsk-你的密钥 # Anthropic Claude ANTHROPIC_API_KEYsk-ant-你的密钥 # Google Gemini GOOGLE_API_KEYAIza你的密钥 # Azure OpenAI如果你走 Azure 通道需要额外信息 AZURE_OPENAI_API_KEY你的Azure密钥 AZURE_OPENAI_API_INSTANCE_NAME你的资源名 AZURE_OPENAI_API_DEPLOYMENT_NAME你的部署名 AZURE_OPENAI_API_VERSION2024-02-15-preview如果你是个人开发者OpenAI 和 Anthropic 是最容易上手的组合。Google Gemini 的 Key 在 AI Studio 申请也支持免费额度适合用来做备用通道。Azure 的变量比较多但只要理解“实例名 部署名 版本号”这三件套就能配置好它本质上是把请求打到一个固定端点。3.4 启动与第一次登录配置完 .env 之后回到项目目录执行docker compose up -d第一次启动会自动拉取需要的容器镜像耗时取决于网络状况耐心等待即可。启动完成后查看容器状态docker compose ps docker compose logs -f librechat看到类似“Server listening on port 3080”的日志说明主服务起来了。浏览器输入http://你的服务器IP:3080就能看到登录页面。第一次进入先注册一个账号。注册成功后右上角的模型选择器里应该会出现你刚才填了 Key 的那些模型。随便挑一个发条消息看到流式回复的那一刻整套服务就算跑通了。4. 进阶配置接入本地模型、多人认证与文件存储4.1 接入本地模型Ollama把本地模型接进来是 LibreChat 一个很关键的能力。好处有两个一是数据完全不出内网适合处理敏感内容二是不需要为每一个新模型都付 API 费用本地小模型可以承担大量简单任务。操作分三步。第一步在宿主机上安装 Ollama一个非常易用的本地模型运行工具然后拉一个模型比如ollama pull qwen2.5:7b第二步在 LibreChat 的 .env 里加一行OLLAMA_BASE_URLhttp://host.docker.internal:11434这里用 host.docker.internal 是因为 LibreChat 跑在容器里需要通过这个特殊域名访问宿主机上的 Ollama。Windows 和 macOS 的 Docker 默认支持这个域名Linux 上稍微麻烦一点需要在启动容器时加 extra_hosts 配置官方文档有说明。第三步重启 LibreChatdocker compose restart librechat重启后模型列表里通常会出现 Ollama 下的模型。如果没出现也先别急着排查去 config 目录找 librechat.yaml在里面手动定义一个 Ollama 端点指向同样的地址模型列表就会按你定义的规则展示。本地模型的延迟和速度取决于机器配置7B 左右的模型在普通 CPU 上也能跑但想要顺畅体验还是建议有一块能用的 NVIDIA 显卡。4.2 开启 Google / GitHub 免密登录如果团队内部已经有 Google 或 GitHub 账号体系建议直接开启 OAuth省掉密码管理成本。以 Google 为例流程大概是去 Google Cloud Console 创建 OAuth Client ID。把回调地址填成http(s)://你的域名/api/auth/google/callback。在 .env 里配置 GOOGLE_CLIENT_ID 和 GOOGLE_CLIENT_SECRET并把 ALLOW_SOCIAL_LOGIN 设为 true。重启服务。这里最容易踩坑的是回调地址不一致。Google 要求严格匹配少一个斜杠、漏了端口都会报 redirect_uri 错误。我遇到过很多次最后都是把浏览器地址栏里的实际网址完整复制到配置里才解决。GitHub 的配置思路完全一样对应的回调路径是/api/auth/github/callback。开了 OAuth 之后邮箱密码登录建议保留万一 OAuth 服务临时不可用至少还有一条备用通道。4.3 文件存储与数据库备份LibreChat 里用户上传的文件默认存在容器卷中直接跟着 Docker volume 走。这种方式简单但不够灵活。如果你的部署环境里有 S3 兼容的对象存储可以配置 S3 相关变量让上传文件直接落到对象存储里。好处是文件与容器解耦后续迁移服务、重建容器都不怕丢文件。但无论存在哪里有两样东西必须定期备份一个是 .env 文件另一个是 MongoDB 数据库。数据库备份可以用最简单的命令docker exec -it mongodb mongodump --archive/tmp/mongo.gz --gzip docker cp mongodb:/tmp/mongo.gz ./然后把这个 gz 文件拷贝到另一台机器或对象存储里。别等到磁盘坏了才想起来备份到时候连哭的地方都没有。我的习惯是写一个脚本每天凌晨备份一次保留最近七天的备份文件。5. 常见问题排查与稳定性调优5.1 高频报错速查表实际部署过程中总会遇到各种奇奇怪怪的问题。下面是我见过的高频问题按出现频率排序现象可能原因处理方法页面打不开端口映射错误 / 防火墙拦截检查docker compose ps确认 3080 端口已映射查看云安全组是否放行登录后模型列表为空没配置任何模型 Key或 Key 格式不对检查 .env填完 Key 后重启服务发消息报 401 / 403API Key 无效或过期到对应平台检查 Key 状态更换后重启历史搜索无结果Meilisearch 未启动或密钥不一致查看 meilisearch 日志确认 MEILI_MASTER_KEY 与 Compose 配置一致注册被拒绝ALLOW_REGISTRATIONfalse临时改成 true重启注册完再改回来消息返回正常但页面卡顿服务器内存不足查看内存占用考虑限制 MongoDB 缓存或升级配置更新后数据没了升级前未备份从备份恢复到 MongoDB后面养成备份习惯5.2 内存占用与性能优化LibreChat 默认全家桶运行时内存占用通常在 2GB 到 3GB 之间其中 MongoDB 和 Meilisearch 是两个大头。如果你的服务器内存紧张有两个收敛措施。第一关掉搜索功能。在 .env 里设置 SEARCHfalseLibreChat 就不会依赖 Meilisearch历史记录依然在 MongoDB 中保存只是不能用全文搜索。牺牲一点检索便利换回 1GB 左右的内存非常划算。第二限制 MongoDB 的可用内存。修改 docker-compose.yml 里的 mongodb 服务给它加一个 Deployment 级别的内存限制比如deploy: resources: limits: memory: 1g我自己在实际使用中发现普通聊天场景下 MongoDB 1GB 内存完全够用。如果是从旧版本升级上来的记得查看新版本的 release notes有些版本会改变默认模型列表或环境变量名称升级后需要同步调整 .env。5.3 安全加固建议自托管服务暴露在网络上安全必须自己做。这里分享几条我总结的加固思路不算复杂但很有用。第一修改所有默认密钥。MEILI_MASTER_KEY 一定要改MongoDB 的用户名密码也不要沿用默认值。默认配置只适合内网测试放到公网就是开门揖盗。第二设置正确的 DOMAIN_CLIENT 和 DOMAIN_SERVER。这两个变量影响 Cookie 的作用域和 OAuth 回调。配置不对轻则登录跳转失败重则存在会话安全问题。第三建议用 Caddy 或 Nginx 这类工具接一层 HTTPS。Caddy 的体验最好绑定域名后证书自动申请域名直接指向本机 3080 端口就能用。这一步不是为了追求仪式感而是登录密码、API Key 这些敏感信息如果走明文 HTTP 传输等于直接裸奔。第四只开放服务需要的端口。3080 端口对外SSH 端口建议改掉或限制来源 IP。LibreChat 的管理后台默认不暴露额外端口不需要额外开放。6. 还能怎么玩定制、插件与二次开发6.1 自定义模型列表LibreChat 支持通过 config/librechat.yaml 来定制模型列表、隐藏不想展示的模型、聚合自定义端点。比如你有一个跑在局域网里的推理服务只要它兼容 OpenAI API 格式就可以这样写version: 1.0.2 endpoints: - name: Internal LLM apiKey: ${INTERNAL_API_KEY} baseURL: http://192.168.1.100:8000/v1 models: default: [intern-model-name]写完重启服务这个自定义端点就会出现在模型列表里。这个机制很适合企业内部接入非主流模型。之前团队里有个同事用 vLLM 部署了一个开源模型我通过这种方式接进同一套聊天界面大家无需知道后端细节直接在模型选择器里切换即可。6.2 插件与代码解释器LibreChat 的插件体系里代码解释器算是比较有代表性的一个。它的实现思路是用户在对话中请求执行代码时后端把代码交给一个沙箱容器在隔离环境里运行拿到输出结果后再返回给模型和用户。这样做既保证了模型可以“动手算”又不会把宿主机环境搞乱。启用代码解释器需要确保宿主机 Docker 可用因为沙箱本身是一个动态创建的容器。具体配置项在不同版本里有调整建议直接看官方文档里关于插件沙箱的说明。如果你只是需要“让模型写代码我复制出去自己跑”那这个插件不装也行反而能让系统更轻量。6.3 把 LibreChat 嵌入其他系统LibreChat 的后端是完整的 REST API前端只是它的一个客户端。这意味着你完全可以写一个自定义页面调用它的 API 完成对话功能把这套对话能力嵌入到自己的业务系统里。我见过有人把它集成到内部知识库后台也有人用 iframe 嵌到团队工作台里。需要注意的一点是iframe 嵌入时要用同一个域名体系或者处理好登录态否则会出现会话失效的问题。如果只是给少量内部人员使用最简单的做法是直接让用户访问 LibreChat 原版页面不折腾嵌入反而更顺畅。最后再分享一个小技巧如果我只让你记住一件事那就是第一次部署完成后别急着使用先把 LOG_LEVELdebug 打开把每个配置好的模型都发一条消息试一遍然后看一眼日志里有没有异常。这件事看起来不起眼但能帮你在未来省下大量排查时间。等确认没问题了再把日志级别调回 info。之后记得给 MongoDB 写个每天凌晨的备份脚本拷到另一台机器或对象存储里。这两件事做完你的 LibreChat 才算真正落地了。