IT相关 · 2026年8月18日

Docker 部署 LibreChat：Nginx 反代、Hermes Gateway 接入与账户初始化排查记录

本文记录一次使用 Docker 部署 LibreChat，并接入现有 Hermes Gateway 的排查与配置过程，供后续维护、升级和故障恢复时参考。

一、部署目标与初始规划

本次部署使用 Docker 运行 LibreChat，服务器位于英国，已有宝塔面板和 Nginx。访问域名规划为：

  • 主站：chat.example.com
  • Admin Panel：chatadmin.example.com

LibreChat 主服务使用宿主机 3080 端口；由于宿主机 3000 端口已被 Open WebUI 占用，Admin Panel 使用宿主机 3001 端口。容器内部端口保持默认，不做修改。Nginx 负责 SSL 证书和域名反向代理。

初期不启用 RAG，因此不部署 PostgreSQL/pgvector 和 RAG API；OAuth、社交登录也暂不启用。MongoDB 和 Meilisearch 作为基础依赖保留并使用持久化存储。

二、Nginx 反向代理排查

1. 上游协议错误

最关键的问题是 Nginx 反代上游最初使用了 HTTPS：

proxy_pass https://127.0.0.1:3080;

LibreChat 容器默认提供普通 HTTP，不是 HTTPS，因此应修改为：

proxy_pass http://127.0.0.1:3080;
proxy_pass http://127.0.0.1:3001;

SSL 只在用户到 Nginx 这一段终止，Nginx 到本机 Docker 映射端口使用 HTTP。

2. WebSocket、SSE 和长连接

LibreChat 的聊天流式响应和部分交互需要正确处理长连接。反代配置中保留或补充以下内容：

proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
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;
proxy_buffering off;
proxy_cache off;
proxy_read_timeout 600s;
proxy_send_timeout 600s;
proxy_connect_timeout 60s;
client_max_body_size 100m;

关闭代理缓冲可以避免流式内容积累后才一次性返回；提高超时可以降低长时间模型生成时被 Nginx 中断的概率；上传大小限制则为后续文件功能预留空间。

三、端口映射与服务状态

最终采用以下映射关系：

127.0.0.1:3080 → LibreChat 容器 3080
127.0.0.1:3001 → Admin Panel 容器内部 3000

MongoDB、Meilisearch 等数据库和内部服务不直接暴露到公网，由 Nginx 统一承担公网入口，减少数据库端口暴露风险。

排查过程中确认，Nginx 配置检查通过，LibreChat、Admin Panel、MongoDB 和 Meilisearch 容器均可正常运行，主站和管理面板通过 HTTPS 返回 HTTP 200。

四、接入现有 Hermes Gateway

LibreChat 支持通过配置文件连接 OpenAI 兼容接口。现有 Hermes Gateway 运行在宿主机 8642 端口，因此不能在 LibreChat 容器中使用 127.0.0.1 访问宿主机，因为容器内的 127.0.0.1 指向容器自身。

Linux Docker Compose 中可通过以下方式让容器解析宿主机：

extra_hosts:
  - "host.docker.internal:host-gateway"

LibreChat 的 OpenAI 兼容端点使用：

Base URL: http://host.docker.internal:8642/v1
API Key: Hermes Gateway 的 API_SERVER_KEY

API Key 应从 Hermes Gateway 的实际配置中读取，不能误填模型供应商的原始密钥。模型 ID 也应以网关的 /v1/models 返回结果为准。

排查时还发现一个容易混淆的情况：曾有一个启动失败、不断重启的 Hermes Docker 容器，而宿主机上已经存在正常监听 8642 端口的 Hermes Gateway。该 Docker 容器已移除，LibreChat 应继续连接现有的宿主机 Hermes Gateway，避免重复部署和端口冲突。

五、认证与公开注册

LibreChat 的注册配置需要区分普通邮箱注册、社交注册和邮箱登录：

ALLOW_REGISTRATION=false
ALLOW_SOCIAL_REGISTRATION=false
ALLOW_EMAIL_LOGIN=true

关闭公开注册不会阻止通过官方用户创建脚本初始化账户；如果需要临时创建首个账户，可以在 Compose 目录执行：

docker compose exec api npm run create-user

本次部署期间曾临时放开普通注册以完成账户初始化，社交注册和 OAuth 始终保持关闭。完成首个管理员账户创建后，生产环境应重新设置 ALLOW_REGISTRATION=false，避免陌生访客继续自行创建账户。

六、验证清单

  • docker compose config --quiet 通过
  • nginx -t 通过
  • LibreChat 主服务健康
  • Admin Panel 健康
  • MongoDB 健康
  • Meilisearch 健康
  • 本机 3080 和 3001 端口可访问
  • 两个 HTTPS 域名可访问
  • Hermes Gateway 作为 OpenAI 兼容端点使用宿主机 8642 端口

七、后续维护建议

正式运行后建议固定 LibreChat 镜像版本，不要长期使用 latest；升级前备份 MongoDB、配置文件和上传目录，并先在测试环境验证。还应设置 Docker 日志轮转，定期检查磁盘空间和容器健康状态。

涉及 MCP、Plugins、Agents 或代码执行能力时，应只启用可信组件，不要把 Docker Socket、SSH 私钥或云平台凭证挂载到 LibreChat 容器中。

总结

本次问题的核心是：Nginx 到 LibreChat 的上游应使用 HTTP 而不是 HTTPS；流式聊天需要关闭代理缓冲并延长超时；Docker 容器访问宿主机 Hermes Gateway 应使用 host.docker.internal；公开注册完成初始化后应重新关闭。以上配置可以作为后续升级和故障排查的基准记录。

标签：