笙亿网络策划

从 Docker Compose 起步——LibreChat 最小可用部署要改哪几项环境变量

约 7 分钟读完 1 阅
文章导读
把 LibreChat 跑起来，改动量通常比看着 compose 文件时想象的要小：在 docker-compose.yml 同目录准备一个 .env，把会话加密用的 CREDS_KEY 与 CREDS_IV、JWT 相关的两个密钥、以及至少一个模型端点的凭证填好，再把 librechat.yaml 挂进容器并声明 CONFIG_PATH，就够发出一条消息了。其余变量大多是功能开关，先留空或保持注
📋 目录
  1. 一 先确认编排文件里哪些服务是必须启动的
  2. 二 生成会话加密所需的密钥并填入环境变量
  3. 三 挂载配置文件并在启动日志里确认读取成功
  4. 四 访问首页注册首个账号并发出第一条消息
A A

把 LibreChat 跑起来，改动量通常比看着 compose 文件时想象的要小：在 docker-compose.yml 同目录准备一个 .env，把会话加密用的 CREDS_KEY 与 CREDS_IV、JWT 相关的两个密钥、以及至少一个模型端点的凭证填好，再把 librechat.yaml 挂进容器并声明 CONFIG_PATH，就够发出一条消息了。其余变量大多是功能开关，先留空或保持注释状态，等最小流程跑通再逐个打开，出问题时排查面也小。

最小可用的判断标准是：mongodb 与 api 两个服务能正常起来，日志里没有密钥长度或配置解析类的报错，浏览器能打开首页并用一条消息拿到模型回复。meilisearch、rag_api 这类可选服务不启动，也不影响一次普通对话。密钥和配置文件这两处不要留空启动后再补救，先填好能省掉一轮排错。模型端点没连通之前，首页能打开并不等于部署可用。

先确认编排文件里哪些服务是必须启动的

先打开 docker-compose.yml，把服务按用途分三类，改动范围就清楚了。数据库类是 mongodb；应用类是 api，也就是 LibreChat 主服务；可选类通常包括 meilisearch（消息全文搜索）、rag_api 以及配套的向量库（文件对话与检索）。api 通过 MONGO_URI 指向 mongodb，所以这两个是最小集合；可选服务只有在启用对应功能时才需要。

判断依据可以直接看依赖关系：api 的 depends_on 里一般会写 mongodb；meilisearch 和 rag_api 与主对话流程解耦，不启动只是搜索、上传文件这些入口不可用。想缩到最小，可以先只拉起两个服务，不改文件也能做到：

docker compose up -d mongodb api
docker compose ps

用命令指定服务名适合临时验证；如果希望长期只跑最小集合，把可选服务那段注释掉更省事，但要留意以后执行不带服务名的 docker compose up 时，注释外的服务会被一起启动。启动顺序上，mongodb 先就绪再起 api 更容易一次成功，出现连接类报错时，先确认 mongodb 的健康检查是否通过，再回来看 api。

生成会话加密所需的密钥并填入环境变量

.env 里最先要落实的是 CREDS_KEY 和 CREDS_IV，它们用于加密写入数据库的用户凭证，长度不对或缺失时服务通常起不来。建议在本机用 openssl 生成，不要手敲，也不要直接复制文档里的示例值：

从 Docker Compose 起步——LibreChat 最小可用部署要改哪几项环境变量
openssl rand -hex 32   # 64 位十六进制，填给 CREDS_KEY
openssl rand -hex 16   # 32 位十六进制，填给 CREDS_IV

写进 .env 的形式大致如下，等号右侧换成上一步生成的结果：

CREDS_KEY=上一步生成的64位十六进制
CREDS_IV=上一步生成的32位十六进制
JWT_SECRET=另一段随机字符串
JWT_REFRESH_SECRET=再一段随机字符串

缺失或长度不符时，api 容器一般在启动日志里直接打印包含 CREDS_KEY 或 CREDS_IV 字样的报错并退出，表现是容器反复重启、docker compose ps 里 api 始终不是 running 状态。这时执行 docker compose logs api 看最后几十行即可定位。需要注意的是，CREDS_KEY 一旦用于正式数据，换新值会导致已加密的凭证无法解开，所以第一次启动前就定好并留档，别等注册了账号再改。

挂载配置文件并在启动日志里确认读取成功

模型端点、界面选项这类内容写在 librechat.yaml 里，容器需要挂载这个文件并被告知它的位置。compose 中给 api 服务加上挂载和环境变量：

services:
  api:
    volumes:
      - ./librechat.yaml:/app/librechat.yaml
    environment:
      - CONFIG_PATH=/app/librechat.yaml

宿主机文件名建议就写成 librechat.yaml，与容器内目标路径对应清楚，避免目录层级或大小写写错。改完重启 api，重点看日志开头部分：应用启动时通常会打印一行与自定义配置文件路径相关的信息，并给出解析结果。YAML 语法错误、字段名写错时，这一段会打印失败原因，应用可能退回默认配置继续启动——此时页面照样能打开，但自定义的端点和界面设置不会生效。

从 Docker Compose 起步——LibreChat 最小可用部署要改哪几项环境变量

想确认文件真的被读到，可以在 librechat.yaml 里改一个肉眼可见的项，比如界面标题或某个模型的显示名，重启后刷新页面看是否变化，同时对照日志里有没有该文件的读取记录。两个信号一致，才说明挂载和 CONFIG_PATH 都正确。把文件挂成目录、或容器内路径与 CONFIG_PATH 不一致，都可能让应用悄悄使用默认配置。

访问首页注册首个账号并发出第一条消息

用浏览器打开宿主机端口，默认通常是 http://localhost:3080，具体以 compose 里 api 的 ports 映射为准。首页登录框下方一般有注册入口，也可能是 /register 路径，用它创建第一个账号。是否开放注册、是否需要邮箱验证，取决于 .env 里 ALLOW_REGISTRATION、ALLOW_EMAIL_LOGIN 一类的开关；首个注册的账号往往被赋予管理员角色，可以先确认这一点再继续。

注册之后先别急着聊天，确认模型端点已经配好：最省事的方式是在 .env 里填入某个模型服务的 API Key 和可选的 BASE_URL，或者在 librechat.yaml 的 custom endpoints 段里定义自己的端点，并在界面上选中对应模型。端点名称、模型名要与服务方提供的一致，拼写差异常直接表现为请求失败。

发出第一条消息后如果没有回复，按顺序看三处：api 容器日志里有没有 401、404、连接超时或 DNS 解析失败的记录；librechat.yaml 中端点配置的 baseURL 能否从容器内部访问，宿主机上的服务不能写 localhost，要用容器可达的地址；浏览器开发者工具 Network 里那条会话请求返回的状态码。日志指向上游连接错误，问题在模型端点；日志里连请求记录都没有，问题多半在会话或密钥配置。一次能拿到正常回复的对话，比首页能打开更能说明这套最小部署可用。