LibreChat部署指南：用Docker Compose搭建多模型AI聚合工作台

我大概是2023年底才开始正视一个问题浏览器标签栏已经被AI工具占满了一半。ChatGPT一个页面、Claude一个页面、Gemini一个页面还有偶尔用到的本地模型页面要对比不同模型的输出就得手动复制来粘贴去三个月前的某条对话更是想找都找不到。后来我把这些入口统一到了一个自建服务里也就是LibreChat它把所有主流模型收进同一个聊天界面对话记录和文件也都存放在自己的服务器上。这篇文章我把完整的部署过程、模型接入方案和实际踩过的坑都整理出来希望能给想搭个人AI工作台或者给团队做统一AI入口的读者一点参考。1. 为什么我不再用浏览器里的三四个AI标签页LibreChat解决的是什么1.1 多模型分地而居的真实痛点先说说我当时的别扭之处。日常写代码、写文案、做翻译不同模型确实各有擅长所以我同时用着不止一个AI服务。但多开带来的问题很明显对话上下文割裂A模型这边聊到一半想去B模型那边试个方案只能把前面几轮对话重新粘贴过去查找历史记录更痛苦一个问题分散在两三个平台里搜索和归档根本无从谈起。如果只是自己一个人用多开几个页面还能忍。但2024年我开始带着一个小团队共用AI工具问题就放大了不同成员各自注册账号额度分散权限难管理成员离职后账号和数据也没法统一回收。说白了这个阶段缺的不是另一个AI聊天产品而是一个能收拢所有模型、统一账号、统一记录的入口。1.2 LibreChat不是又一个AI它是一个聚合客户端LibreChat是一个开源的、可以部署在自己服务器上的AI聊天平台。它自己并不训练模型更像一个聚合入口把OpenAI、Anthropic、Google、本地Ollama等不同模型提供商的API接到同一个界面里前端长得很像ChatGPT左侧是会话列表中间是对话窗口右下角随时切换模型。我习惯用一个类比解释它LibreChat好比一个集成了多家支付渠道的收款App界面本身不生产货品但你能在一个App里选微信、支付宝或者银行卡完成付款。对AI来说货品就是各家模型的API而LibreChat负责把打款姿势统一成一样的。也正因如此它天然解决了我前面说的几个痛点多模型共用一个入口、一套会话管理、一套账号系统所有数据都落到我自己的MongoDB里。这里要补充一句LibreChat本来就是开源社区里迭代很积极的项目从最初定位ChatGPT的开源增强客户端慢慢成长成了支持多模型协议的工具我目前看到的版本里已经加入了预设提示词、知识库检索、联网搜索、多模态上传等能力已经不只是个套壳前端了。1.3 哪些人最适合自建LibreChat按我这段时间的使用经验适合自建LibreChat的人大概有三类。第一类是重度AI用户自己手里有多个模型的API Key又不想被某个平台的网页版锁住第二类是小团队或者兴趣小组希望给成员开统一账号但不想给每个人单独购置订阅第三类是数据敏感场景比如处理内部代码库、客户材料希望对话记录留在自己服务器上而不是散落在外部平台。反过来如果你完全没接触过命令行和Docker也不打算维护一个长期运行的服务器那LibreChat暂时不适合你。它虽然部署门槛已经降得很低但终归是一个自托管服务需要有人偶尔关注一下版本升级和备份这部分运维成本是躲不掉的。2. 部署前需要搞懂的LibreChat运行骨架和准备工作2.1 一句话拆解LibreChat的启动链路我建议部署前先对LibreChat的组成有点概念否则出了问题连日志都看不懂。从Docker Compose的角度看LibreChat一般会拉起这么几个服务核心的LibreChat应用容器负责前端页面和大多数后端接口一个MongoDB容器用来存用户、会话、消息记录一个Meilisearch容器处理聊天记录的全文搜索如果需要RAG知识库功能还可能有一个向量数据库容器。把这几个容器想象成一个小组。LibreChat应用是前台接待所有请求都走它MongoDB是档案室重要资料都存在这里Meilisearch是检索员专门负责帮你翻旧账向量数据库则像一个临时记忆板主要在做知识库检索时派上用场。理解了谁负责什么后面排查问题的时候思路会清楚很多。比如页面显示正常但搜索不到历史消息那大概率是Meilisearch的问题而不是MongoDB的问题。2.2 服务器与Docker环境要求LibreChat本身不算吃资源但加上MongoDB和Meilisearch最低配置建议至少2GB内存长期使用我更推荐4GB以上。个人用的话2核4G的Linux服务器就非常舒服了同时开几个会话资源占用也不会太紧张。磁盘方面镜像加数据卷预留20GB比较稳妥对话记录多了之后增长也很快。Docker环境是必须的。现在的Linux发行版基本都能直接装Docker Engine安装完后记得确认docker compose命令可用。如果你用的是旧版docker-compose命令中间带横杠也能跑但建议还是升级到新版Compose V2因为LibreChat的配置和日志操作都默认用新版命令。Windows和macOS上跑Docker Desktop也没问题但如果你打算长时间挂机我建议还是放到一台24小时运行的Linux服务器上笔记本跑服务器总有断电合盖的时候。2.3 模型API和密钥第一优先级在真正部署之前先把模型提供商的API Key准备好。最少有一个就能跑起来LibreChat的界面会自动根据你配置的Key显示可用的模型源。我个人是开通了OpenAI、Anthropic和Google三家再加一个本地的Ollama这样公开模型和本地模型都能覆盖到。模型源需要准备的信息说明OpenAIOPENAI_API_KEY在OpenAI平台创建按量计费AnthropicANTHROPIC_API_KEY在Anthropic平台创建涉及Claude系列GoogleGOOGLE_API_KEY在Google AI Studio创建有免费额度Ollama无需要服务器或本机安装Ollama本地运行开源模型不产生API费用需要提醒的是API Key相当于真金白银的凭证不要把它提交到Git仓库里也不要在聊天截图里暴露。如果服务器被多人访问建议通过环境变量或密钥管理工具来配置至少别把.env文件传到公开代码库。2.4 版本迭代很快配置以模板为准LibreChat的开发节奏相当快我部署的版本到现在可能又更新了好几轮各个配置文件里的字段名也可能发生变化。所以这篇文章里的操作步骤和.env变量你把它当作通用思路来理解就好真正落地的时候一定要以你克隆下来的仓库里docker/.env.example文件为准里面每条配置都有注释说明。另外一个经验如果打算长期使用别用latest标签拉镜像建议在GitHub Release里找一个稳定版本固定下来。否则哪天重新部署拉到了带破坏性变更的新版本可能升完级数据迁移出错那才是麻烦事。我自己的习惯是每三到四周手动升一次级升级前先备份升级后看日志这套流程走到后面会越来越顺。3. 从零到一Docker Compose部署LibreChat的完整记录3.1 拉取代码并初始化环境变量部署的第一步是把LibreChat仓库拉下来。在服务器上找一个工作目录执行git clone https://github.com/danny-avila/LibreChat.git cd LibreChat cp docker/.env.example .env这里有个细节复制出来的是.env但位置在项目根目录下而不是docker目录里。就算之前没接触过这套项目的朋友只要记住Compose读取的是根目录的.env就不会找错文件了。拉取代码后先不用急着改配置把.env打开从头到尾看一遍注释花十分钟弄清每条是干什么的。这个动作能帮你后面省很多事。3.2 修改.env的核心字段打开.env之后重点改下面这些字段。我不会在这一步展开模型细节先把最基本的用户系统和启动项配置好。修改注册与登录相关的配置要先想清楚这个服务是给谁用的。个人使用可以保留开放注册方便以后在多台设备上登录但要设置足够复杂的登录邮箱和密码小团队使用建议关闭开放注册通过其他方式管理用户。ALLOW_REGISTRATIONtrue ALLOW_EMAIL_LOGINtrue ALLOW_SOCIAL_LOGINfalse ALLOW_PASSWORD_RESETtrue然后是数据库和搜索引擎的地址。这里基本不需要改动除非你打算把MongoDB和Meilisearch拆到独立的服务器上MONGODB_URImongodb://mongodb:27017/LibreChat MEILI_HOSThttp://meilisearch:7700 MEILI_MASTER_KEY请换成一段足够长的随机字符串MEILI_MASTER_KEY这里要着重说一下新版Meilisearch强制要求有主密钥留空可能导致搜索服务启动异常。生成一个随机字符串的方式很多openssl rand -hex 32随手就能生成一段足够安全的密钥。这一段如果忘了改后面启动搜索服务会一直报错。3.3 启动服务与日志检查修改完基础配置后开始第一次启动docker compose up -d docker compose ps第一次启动会拉取多个镜像包括LibreChat主应用、MongoDB、Meilisearch网络状况好的话几分钟也就完成了。启动完成后看下容器状态docker compose ps如果输出里各个服务都是Up状态说明基础启动成功。这时候浏览器访问http://服务器IP:3080应该就能看到注册登录页面了。如果遇到容器反复重启别急着瞎猜看日志是最直接的手段docker compose logs -f api这段日志会输出应用启动过程中的具体错误比如连不上数据库、密钥配置不对、端口被占用等。我在后面专门的排障部分会展开讲几个高频问题。3.4 设置管理员账号LibreChat部署好之后默认注册的用户并不会自动变成管理员。第一次注册完成、可以登录之后手动把这个用户提升为管理员这样才能进入管理面板查看用量、管理成员。方法是在MongoDB里直接修改用户role字段。先在页面上正常注册一个账号记住邮箱然后执行docker compose exec mongodb mongosh mongodb://mongodb:27017/LibreChat --eval db.users.updateOne({ email: 你注册的邮箱 }, { $set: { role: admin } })执行后如果想确认改动生效可以再查一下docker compose exec mongodb mongosh mongodb://mongodb:27017/LibreChat --eval db.users.findOne({ email: 你注册的邮箱 }, { role: 1 })我看到有些新版本可能把角色字段设计成数组或者不同的字符串写法比如USER、ADMIN。如果上面命令执行后没有把用户变成管理员先findOne看一下这条用户记录里role字段当前长什么样再照着改。这个排查思路比死记命令更靠谱。3.5 用域名和HTTPS把服务暴露出去如果只在局域网里自己用到上一步就够用了。但如果要给团队用或者想在任何地方都能访问建议配一个域名并启用HTTPS。这里的核心思路不复杂让你的域名指向这台服务器然后在一个支持自动申请HTTPS证书的Web服务里把请求转发到本机的3080端口。以Caddy为例Caddyfile里只需要简单几行域名申请和证书续期都是自动的。你不需要关心证书的具体细节Caddy会处理。如果你公司或团队里已经有Nginx等入口服务的经验也可以直接把3080端口反向转发到域名上效果一样。配置完成后记得在服务器防火墙和安全组里放行对应端口。很多新手部署完发现外部访问不了排查半天最后发现是云厂商安全组没放行端口这种低级错误我踩过不止一次。4. 一次性接入四类模型源OpenAI、Anthropic、Google与本地Ollama4.1 先搞清ENDPOINTS和模型白名单的关系LibreChat有个ENDPOINTS变量作用是控制启用哪些模型提供商的接口比如ENDPOINTSopenai,anthropic,google,ollama但真正决定聊天界面里出现哪些模型的是你为每个提供商配置的API Key和模型白名单。两个机制配合起来理解ENDPOINTS相当于打开某扇门模型列表则决定门后陈列哪些商品。就算你把ENDPOINTS里加了openai如果OPENAI_API_KEY是空的前端的OpenAI入口照样不会展示任何模型。这套设计的合理性在于厂商的模型目录一直在膨胀如果全量拉取前端会变得很拥挤且难以管理。用白名单的方式你可以只保留自己真正用得上的模型。4.2 OpenAI和Anthropic的接入配置OpenAI和Anthropic是最常见的两个模型源。在.env里配置方式类似格式都是Key加模型列表OPENAI_API_KEYsk-xxxx OPENAI_MODELSgpt-4o,gpt-4o-mini ANTHROPIC_API_KEYsk-ant-xxxx ANTHROPIC_MODELSclaude-3-5-sonnet-20241022,claude-3-opus-latest,claude-3-5-haiku-20241022这里有个容易搞混的点模型列表里填的必须是提供商官方认可的具体模型ID而不是你随口起的别名。Claude这种后缀带日期的模型ID尤其容易记错建议以对应平台当前的模型文档为准。填错的话界面上虽然能看到模型名但发消息时会提示模型不存在。更稳妥的做法是改完模型列表后一定重启一下api容器docker compose up -d --force-recreate api很多前端没刷新的问题到这一步就解决了。4.3 Google Gemini的接入配置Google的配置逻辑和前面两家一致GOOGLE_API_KEY你的key GOOGLE_MODELSgemini-1.5-pro,gemini-1.5-flashGoogle这套接口我实际用下来免费额度对个人开发者非常友好用来做日常任务分流挺合适。质量上Gemini在长文档理解上给我感觉不错和Claude、GPT各有优势。在LibreChat里接入Google之后我就很少单独去打开Google那个网页了直接在这个界面就能切换。4.4 本地Ollama把开源模型也塞进同一个界面如果说前面三个模型源解决的是云端集中管理的问题那Ollama解决的就是本地离线兜底的问题。接入Ollama后你可以把llama3.1、qwen2.5这类开源模型也拉到同一个LibreChat界面里用对话不经过任何云端API断网也能用敏感的测试文本丢给它完全放心。我推荐的接入方式是把Ollama作为Docker Compose里的一个额外服务。在项目根目录创建docker-compose.override.yml内容如下services: ollama: image: ollama/ollama:latest container_name: ollama ports: - 11434:11434 volumes: - ollama_data:/root/.ollama restart: always volumes: ollama_data:然后在.env里把OLLAMA相关变量指到Docker网络内的服务名OLLAMA_BASE_URLhttp://ollama:11434 OLLAMA_MODELSqwen2.5:7b,llama3.1:8b用这种方式Linux服务器上不需要单独安装Ollama容器之间通过ollama这个服务名就能通信省去了host.docker.internal在Linux上解析不到的麻烦。启动后先在Ollama容器里拉取想要的模型docker compose exec ollama ollama pull qwen2.5:7bOLLAMA_MODELS里填的模型名一定是已经拉取成功的否则前端列表里虽然能看到真正聊天时会报404。本地模型跑7B到14B级别的响应速度还算行再大的模型就要看显卡和个人耐心了。4.5 四类模型源配置速查我把自己的配置经验汇总成一个表格方便对照检查模型源关键环境变量需要额外的设施主要优点OpenAIOPENAI_API_KEY、OPENAI_MODELS无模型丰富生态成熟AnthropicANTHROPIC_API_KEY、ANTHROPIC_MODELS无Claude长文能力强Artifacts界面顺手GoogleGOOGLE_API_KEY、GOOGLE_MODELS无免费额度香长文档理解不错OllamaOLLAMA_BASE_URL、OLLAMA_MODELS需要单独的Ollama容器或本机服务数据完全本地离线可用免费我建议至少接一家云端模型加一家本地模型云端用于日常高强度打工人本地用于敏感数据和离线场景。两边互补才算把LibreChat用回本了。5. 部署完该怎么用几个能重塑工作流的进阶功能5.1 会话树和上下文管理当你把多个模型收到同一个界面后会话管理就变成了新问题。LibreChat的会话设计比网页版原生服务细得多每个会话可以独立重命名、归档、删除还能从某条消息的位置分叉出一条新对话。这个分叉功能相当实用。我经常在同一个对话里让模型写方案写到一半觉得方向偏了但前面的内容又舍不得丢这时候从某条关键消息分叉出去保留原始分支在新的分支里继续探索。用起来很像给代码拉了条Git分支。如果你曾经因为重新开一局就得放弃旧对话而烦恼你会喜欢这个设计。另外LibreChat支持把对话导出成JSON也可以导入回系统。这个功能在做方案沉淀、知识整理时很好用相当于给你的对话记录做了可迁移的存档。5.2 预设Prompt把自己的常用角色固定下来用得越久越发现预设Prompt是提升效率的关键。LibreChat左侧栏有Prompts功能可以把经常用的系统级提示词存成模板下次直接调用。比如我存了一个代码评审助手的模板提示词里写了请从可维护性、性能、安全性三个维度给出评审意见再用Claude模型打开预设基本就是进入工作状态的快捷键。预设Prompt还能跨会话保持一致性。给团队成员统一配置几条规范类提示词比如日报生成、周报整理、客户邮件润色大家用起来质量下限就有了保障。这一步对团队使用场景的价值甚至比接入多少模型还大。5.3 联网搜索与文件上传当模型需要实时信息时只靠训练数据是不够的。LibreChat支持通过配置搜索API实现联网搜索。在.env里配置对应的搜索服务API Key聊天输入框附近会多出搜索开关打开后模型就能在回答前先检索一下最新信息。这个功能的实际体验让我比较惊喜至少查天气、查新发布的技术文档这类场景不再依赖手动切换浏览器了。文件上传方面多模态模型可以直接接收图片、PDF、文本等附件我经常直接把一张报错截图丢给Claude/GPT-4o让它看省去很多文字描述的时间。5.4 用Meilisearch把聊天记录变成搜索档案LibreChat自带的搜索能力依托Meilisearch在顶部搜索框可以搜索所有历史对话的消息内容。这个能力有和没有完全是两种体验尤其在连续用了两三周之后搜索能直接定位到之前写过的某段代码在哪个对话里出现过比手动翻列表高效太多。有一点需要做好心理准备Meilisearch对中文分词的支持相对一般搜中文长句时偶尔不如英文精确。我自己的缓解办法是搜索时多提取几个关键词而不是整句扔进去。如果你有大量中文内部文档要检索可以考虑在外部再挂一个更成熟的中文搜索方案但普通使用场景下自带的搜索已经够用。6. 实测排障部署LibreChat我踩过的五个坑6.1 坑一api容器无限重启罪魁是MongoDB初始化失败部署后第一件让我头疼的事就是api容器一直在重启。docker compose ps里能看到api的状态是Restarting日志里反复出现连不上MongoDB或者初始化失败的报错。排查思路是分层的。先确认MongoDB容器本身是否起来了然后检查网络互通最后看.env里的MONGODB_URI。我那次的问题就出在把MONGODB_URI改成了localhost:27017以为是在宿主机上访问。实际上api容器访问MongoDB应该走Docker网络里的服务名mongodb而不是localhost。后来改回模板默认的mongodb://mongodb:27017/LibreChat就正常了。如果你在自己机器上遇到过数据库目录权限导致MongoDB起不来的情况可以用docker compose logs mongodb看具体报错然后把对应的数据卷清理掉重新初始化。启动前多看一眼日志比反复重启容器高效得多。6.2 坑二新增模型列表刷新不出来辛辛苦苦配好新的API Key和模型列表回到界面发现模型选择器里空空如也这是另一个高频现象。我遇到时的第一反应是配置没生效但其实问题往往出在浏览器缓存上。LibreChat前端会把可用的模型配置缓存到浏览器里改了.env后没有强制刷新页面展示的永远是旧配置。正确的操作路径是改完.env后先用docker compose up -d --force-recreate api重启应用容器然后在浏览器里强制刷新页面Mac上是CmdShiftRWindows上是CtrlShiftR。这样大概率能看到新模型出现在列表里。如果强制刷新后还是没有再回头检查.env里对应的Key是否真的填了填了ENDPOINTS是否包含该模型源模型白名单里的模型ID拼写是否和官方文档一致。按这个顺序排查基本不会漏掉问题。6.3 坑三界面里的Token统计和官方账单对不上有段时间我发现LibreChat界面里某个会话显示的Token用量和OpenAI后台账单差异挺大一开始以为是Bug后来看了一圈相关讨论才明白Token统计的源头来自各模型接口返回的usage字段而不同提供商对这个字段的统计口径本身就不同有些会精确输出Token数有些提供的是采样结果或包含额外上下文信息。LibreChat只是把这个值展示出来不负责对齐官方计费。所以如果你像我一样有对账的需求最靠谱的方式还是以模型提供商后台的用量报表为准。界面里的Token统计更适合做相对趋势判断比如哪个会话消耗大、每天大概跑多少量级看趋势是没问题的但别拿它当财务账本。6.4 坑四文件上传后预览空白附件页打不开上传文件后附件区域空白的现象在自托管场景下通常和文件存储配置有关。LibreChat的文件上传支持不同驱动方式如果默认配置的本地存储路径对应的容器目录不可写或者宿主机挂载目录权限不对就会出现上传成功但实际读写不了的情况。我的排查顺序是这样先看浏览器开发者工具里请求是否报错然后看api容器日志里有没有文件操作失败的记录。日志里通常能直接看到是权限问题还是路径不存在。如果是本地文件存储检查挂载目录在宿主机上的属主和权限确保uid能读写。如果是自己额外加了Nginx这类入口还需要注意上传大小限制大文件被网关拦下来时前端提示不一定明显。6.5 坑五升级版本把数据迁没了这是我最心疼的一次事故。当时看到LibreChat出了新版本手一滑就用docker compose pull docker compose up -d把服务升了结果MongoDB数据结构迁移出了问题登录会话失效部分旧消息查不到。还好之前有断断续续导出JSON存档的习惯不然真的欲哭无泪。从那以后我养成了两个习惯。第一升级前一定备份MongoDB数据卷执行docker compose exec -T mongodb mongodump --urimongodb://mongodb:27017/LibreChat --out/tmp/dump docker compose cp mongodb:/tmp/dump ./backup_$(date %F)第二不追latest标签固定到具体的release版本上升级前先看Release Notes确认没有破坏性变更再动手。这套流程跑顺之后升级LibreChat变成了一件完全不慌的事。6.6 排障后的两点体会把上面这些坑踩过来之后我对LibreChat的运维理解也清晰了很多这类自托管工具真正让人犹豫的从来不是安装而是后续维护的确定性。LibreChat做得比较好的是配置集中、日志清晰、社区活跃遇到问题搜一搜基本都能找到方向实际的维护负担没有很多人想得那么大。最后分享一个我现在每周自动跑的小动作用cron定时执行一次上面那份MongoDB备份命令备份文件保留最近两周。数据库备份这件事平时感觉永远用不上可真出问题时能救命。希望你部署LibreChat顺利少踩我踩过的坑把这套聚合AI工作台真正用起来。