LibreChat AI 聊天自托管部署3条命令从0到生产完整避坑指南【免费下载链接】LibreChatEnhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active项目地址: https://gitcode.com/GitHub_Trending/li/LibreChat把 LibreChat 这个支持 OpenAI、Anthropic、Agents/MCP 的多模型 AI 对话平台装到你自己的机器上只要 3 条命令——5 分钟看到登录页所有会话数据都留在你的磁盘上。先回答三个选型问题再把最小可用环境跑起来最后是一份出事时照着查的排障手册。先决策三个选型问题按场景选部署方式场景推荐方式关键优势主要代价个人/单机Docker Compose一条命令拉起 6 个容器无内置高可用小团队生产Compose 反向代理成熟稳定易挂域名和 SSOcompose 文件需手工维护多节点企业Helm Kubernetes滚动更新、可弹性扩缩需要 K8s 集群经验如果你只是一个人一台机器跑起来直接选第一行后两行现在选都属过度设计。环境要求清单Docker 路线Docker 20.10、docker compose v2至少 4GB 可用内存api、mongodb、meilisearch、pgvector、rag_api 等 6 个容器Helm 路线额外需要 Kubernetes 集群1.25和 Helm 3。如果docker compose version报找不到命令先装好 compose v2 插件再往下走装好后这条输出带版本号就说明环境就绪。留多少扩展余量两个开关决定初始配置现在定好能省一次返工要不要消息搜索.env里SEARCHtrue时必须配MEILI_MASTER_KEY要不要 RAG 向量检索compose 默认已带 vectordb 和 rag_api不用额外动作。模型端点都写在 librechat.example.yaml跑起来之后再补也来得及。Docker Compose 部署把 AI 聊天系统跑起来最小配置清单克隆代码并复制模板配置之后只填必填项。git clone https://gitcode.com/GitHub_Trending/li/LibreChat cd LibreChat cp .env.example .env完整字段见 .env.example实际只动这几处字段填法PORT默认 3080被占用就改JWT_SECRET / JWT_REFRESH_SECRET随机串两者都要填MEILI_MASTER_KEYSEARCHtrue 时必填ADMIN_PANEL_SESSION_SECRET用管理面板时必填用这条命令生成随机串openssl rand -hex 32输出一行 64 位十六进制串粘进.env即可JWT_SECRET留空的话 api 容器会直接启动失败这是最常见的第一个坑。启动并验证后台拉起全部服务并拉取镜像首次拉镜像会比较久docker compose up -d跑完后docker compose ps里 6 个容器都显示 Up/running 说明成功有容器卡在 Restarting直接跳到最后的手册。再用健康端点验证curl http://localhost:3080/health这条路由固定返回OK定义在 api/server/index.js。看到OK就成功了如果是 connection refused说明.env的PORT和你访问的端口不一致。然后打开http://localhost:3080注册第一个账号它就是后续的管理员。生产加固自托管部署的安全配置⚠️ 三个 key 建议立刻存到密码管理器或备份介质里——丢了它们所有登录会话和搜索索引都会失效。Docker 路线.env纳入备份别只留在机器上K8s 路线写进 SecretChart 通过 helm/librechat/values.yaml 里的existingSecretName引用api 前面挂反向代理nginx 等并开 TLS.env里设REVERSE_PROXYadmin-panel默认 3000 端口只对内网开放不要直接暴露公网。接入 K8s 集群先把三个 key 建成 Secretkubectl create secret generic librechat-credentials-env \ --from-literalJWT_SECRETxxx \ --from-literalMEILI_MASTER_KEYxxx \ --from-literalJWT_REFRESH_SECRETxxx \ -n librechat --dry-runclient -o yaml | kubectl apply -f -输出 Secret 清单即成功--dry-runclient只是先本地渲染再应用不会污染集群。再安装 Chart指向仓库里的 helm/librechat/ 目录helm install librechat ./helm/librechat -n librechat --create-namespace输出走完DEPLOYED状态即完成安装。kubectl get pods -n librechatPod 全部1/1 Running说明成功如果某个 Pod 在 CrashLoopBackOff八成是 Secret 的 key 名和 Chart 引用的对不上逐个对照 helm/librechat/values.yaml 里existingSecretApiKey的注释。运维排障手册坏了看哪里健康检查看哪里每天跑一次或挂进你的监控curl http://host:3080/healthOK即正常。典型陷阱是健康检查绿着、发消息却 503——MongoDB 会话池耗尽时写操作会失败api/server/index.js 第 423 行附近的注释写明了这个行为此时查 mongodb 容器的内存和连接数而不是 api。日志看哪里compose 把宿主机的./logs挂进容器日志配置在 api/utils/logger.jswinston。docker compose logs -f api tail -f logs/*.log第一条看容器实时 stdout第二条看落盘文件api 日志出现 listening 字样说明服务起来了。判断规则MEILI超时或 401meilisearch 没就绪或MEILI_MASTER_KEY前后不一致MongoNetworkErrormongodb 容器没起来或MONGO_URI指错compose 内应为mongodb:27017请求批量 401刚换过JWT_SECRET会话被作废重新登录即可。数据安全导出的姿势把 MongoDB 数据按当天日期导出会话、用户、配置都在 Mongo 里docker exec chat-mongodb mongodump --out ./backup/$(date %Y%m%d)备份目录下生成.bson文件即成功。恢复是反向操作把备份文件通过管道送进容器docker exec -i chat-mongodb mongorestore 备份文件输出无报错即完成文件路径给错会直接报 file not found。发新版了怎么办项目自带更新脚本一次处理拉代码、更依赖、重启-d表示 Docker 部署node config/update.js -d它会依次询问是否用 Docker、是否默认 compose答 y 即可逻辑见 config/update.js。先做完上面的数据导出再执行更新后若服务异常把 docker-compose.yml 里的镜像 tag 换回旧版再docker compose up -d数据不受影响。下一步做什么确认密钥已生产化.env里如果还是临时值重新生成JWT_SECRET和MEILI_MASTER_KEY重启后用curl /health确认服务恢复把备份跑成自动给mongodump加一条每日 cron第二天人工抽查一次.bson文件完整性接第二个模型从 librechat.example.yaml 里挑一个 OpenAI 兼容端点先用单会话验证流式输出正常再放开给全团队。【免费下载链接】LibreChatEnhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active项目地址: https://gitcode.com/GitHub_Trending/li/LibreChat创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 LibreChat AI 聊天自托管部署：3条命令从0到生产，完整避坑指南
LibreChat AI 聊天自托管部署3条命令从0到生产完整避坑指南【免费下载链接】LibreChatEnhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active项目地址: https://gitcode.com/GitHub_Trending/li/LibreChat把 LibreChat 这个支持 OpenAI、Anthropic、Agents/MCP 的多模型 AI 对话平台装到你自己的机器上只要 3 条命令——5 分钟看到登录页所有会话数据都留在你的磁盘上。先回答三个选型问题再把最小可用环境跑起来最后是一份出事时照着查的排障手册。先决策三个选型问题按场景选部署方式场景推荐方式关键优势主要代价个人/单机Docker Compose一条命令拉起 6 个容器无内置高可用小团队生产Compose 反向代理成熟稳定易挂域名和 SSOcompose 文件需手工维护多节点企业Helm Kubernetes滚动更新、可弹性扩缩需要 K8s 集群经验如果你只是一个人一台机器跑起来直接选第一行后两行现在选都属过度设计。环境要求清单Docker 路线Docker 20.10、docker compose v2至少 4GB 可用内存api、mongodb、meilisearch、pgvector、rag_api 等 6 个容器Helm 路线额外需要 Kubernetes 集群1.25和 Helm 3。如果docker compose version报找不到命令先装好 compose v2 插件再往下走装好后这条输出带版本号就说明环境就绪。留多少扩展余量两个开关决定初始配置现在定好能省一次返工要不要消息搜索.env里SEARCHtrue时必须配MEILI_MASTER_KEY要不要 RAG 向量检索compose 默认已带 vectordb 和 rag_api不用额外动作。模型端点都写在 librechat.example.yaml跑起来之后再补也来得及。Docker Compose 部署把 AI 聊天系统跑起来最小配置清单克隆代码并复制模板配置之后只填必填项。git clone https://gitcode.com/GitHub_Trending/li/LibreChat cd LibreChat cp .env.example .env完整字段见 .env.example实际只动这几处字段填法PORT默认 3080被占用就改JWT_SECRET / JWT_REFRESH_SECRET随机串两者都要填MEILI_MASTER_KEYSEARCHtrue 时必填ADMIN_PANEL_SESSION_SECRET用管理面板时必填用这条命令生成随机串openssl rand -hex 32输出一行 64 位十六进制串粘进.env即可JWT_SECRET留空的话 api 容器会直接启动失败这是最常见的第一个坑。启动并验证后台拉起全部服务并拉取镜像首次拉镜像会比较久docker compose up -d跑完后docker compose ps里 6 个容器都显示 Up/running 说明成功有容器卡在 Restarting直接跳到最后的手册。再用健康端点验证curl http://localhost:3080/health这条路由固定返回OK定义在 api/server/index.js。看到OK就成功了如果是 connection refused说明.env的PORT和你访问的端口不一致。然后打开http://localhost:3080注册第一个账号它就是后续的管理员。生产加固自托管部署的安全配置⚠️ 三个 key 建议立刻存到密码管理器或备份介质里——丢了它们所有登录会话和搜索索引都会失效。Docker 路线.env纳入备份别只留在机器上K8s 路线写进 SecretChart 通过 helm/librechat/values.yaml 里的existingSecretName引用api 前面挂反向代理nginx 等并开 TLS.env里设REVERSE_PROXYadmin-panel默认 3000 端口只对内网开放不要直接暴露公网。接入 K8s 集群先把三个 key 建成 Secretkubectl create secret generic librechat-credentials-env \ --from-literalJWT_SECRETxxx \ --from-literalMEILI_MASTER_KEYxxx \ --from-literalJWT_REFRESH_SECRETxxx \ -n librechat --dry-runclient -o yaml | kubectl apply -f -输出 Secret 清单即成功--dry-runclient只是先本地渲染再应用不会污染集群。再安装 Chart指向仓库里的 helm/librechat/ 目录helm install librechat ./helm/librechat -n librechat --create-namespace输出走完DEPLOYED状态即完成安装。kubectl get pods -n librechatPod 全部1/1 Running说明成功如果某个 Pod 在 CrashLoopBackOff八成是 Secret 的 key 名和 Chart 引用的对不上逐个对照 helm/librechat/values.yaml 里existingSecretApiKey的注释。运维排障手册坏了看哪里健康检查看哪里每天跑一次或挂进你的监控curl http://host:3080/healthOK即正常。典型陷阱是健康检查绿着、发消息却 503——MongoDB 会话池耗尽时写操作会失败api/server/index.js 第 423 行附近的注释写明了这个行为此时查 mongodb 容器的内存和连接数而不是 api。日志看哪里compose 把宿主机的./logs挂进容器日志配置在 api/utils/logger.jswinston。docker compose logs -f api tail -f logs/*.log第一条看容器实时 stdout第二条看落盘文件api 日志出现 listening 字样说明服务起来了。判断规则MEILI超时或 401meilisearch 没就绪或MEILI_MASTER_KEY前后不一致MongoNetworkErrormongodb 容器没起来或MONGO_URI指错compose 内应为mongodb:27017请求批量 401刚换过JWT_SECRET会话被作废重新登录即可。数据安全导出的姿势把 MongoDB 数据按当天日期导出会话、用户、配置都在 Mongo 里docker exec chat-mongodb mongodump --out ./backup/$(date %Y%m%d)备份目录下生成.bson文件即成功。恢复是反向操作把备份文件通过管道送进容器docker exec -i chat-mongodb mongorestore 备份文件输出无报错即完成文件路径给错会直接报 file not found。发新版了怎么办项目自带更新脚本一次处理拉代码、更依赖、重启-d表示 Docker 部署node config/update.js -d它会依次询问是否用 Docker、是否默认 compose答 y 即可逻辑见 config/update.js。先做完上面的数据导出再执行更新后若服务异常把 docker-compose.yml 里的镜像 tag 换回旧版再docker compose up -d数据不受影响。下一步做什么确认密钥已生产化.env里如果还是临时值重新生成JWT_SECRET和MEILI_MASTER_KEY重启后用curl /health确认服务恢复把备份跑成自动给mongodump加一条每日 cron第二天人工抽查一次.bson文件完整性接第二个模型从 librechat.example.yaml 里挑一个 OpenAI 兼容端点先用单会话验证流式输出正常再放开给全团队。【免费下载链接】LibreChatEnhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active项目地址: https://gitcode.com/GitHub_Trending/li/LibreChat创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考