Docker

如何使用 Docker 在本地安装 LibreChat、验证您的设置并配置自定义 endpoint

对于大多数场景，Docker Compose 是推荐的安装方式，因为它简单、易用且可靠。

先决条件

对于大多数用户，推荐使用 Docker Desktop。对于远程服务器安装，请参阅 Ubuntu Docker 部署指南。

Apple Silicon (M系列) Mac

搭载 Apple Silicon (M1, M2, M3, M4) 处理器的 Mac 电脑不支持 AVX 指令集，而 LibreChat 的 Docker Compose 设置中所使用的默认 MongoDB 镜像需要该指令集。如果您使用的是 M 系列芯片的 Mac，MongoDB 将会在启动时崩溃。

修复： 创建一个 docker-compose.override.yml 以使用较旧且兼容的 MongoDB 镜像：

services:
  mongodb:
    image: mongo:4.4.18

请参阅 Docker Override guide 以获取更多详细信息。

安装

克隆仓库

git clone https://github.com/danny-avila/LibreChat.git
cd LibreChat

创建您的环境文件

cp .env.example .env

默认的 .env 文件可直接用于基本设置。如需深入配置，请参阅 .env 参考。

Windows

在 Windows 上，如果无法使用 cp，请使用 copy .env.example .env。

启动 LibreChat

docker compose up -d

首次启动会拉取 Docker 镜像，可能需要几分钟时间。后续启动速度会快得多。

验证并登录

打开您的浏览器并访问 http://localhost:3080。您应该会看到 LibreChat 登录页面。

第一个账户 = 管理员

您注册的第一个账户将成为管理员账户。系统没有默认凭据——您需要在注册过程中自行创建用户名和密码。

点击 Register 创建您的账户并开始使用 LibreChat。

挂载 librechat.yaml

若要配合 Docker 使用自定义的 librechat.yaml 配置文件，你需要将其挂载为数据卷，以便容器能够访问它。

复制示例覆盖文件并进行编辑：

cp docker-compose.override.yml.example docker-compose.override.yml

确保 docker-compose.override.yml 中的 librechat.yaml 卷挂载已取消注释：

services:
  api:
    volumes:
      - type: bind
        source: ./librechat.yaml
        target: /app/librechat.yaml

重启以使更改生效：

docker compose down && docker compose up -d

有关包括从零开始创建文件在内的完整设置说明，请参阅 librechat.yaml guide。有关更多覆盖选项，请参阅 Docker override guide。

更新 LibreChat

以下命令将获取最新的 LibreChat 项目更改，包括对 docker compose 文件所做的任何必要更改，以及最新的预构建镜像。

权限

根据您的环境权限，您可能需要在命令前加上 sudo。

docker compose down

# Linux/Mac
docker images -a | grep "librechat" | awk '{print $3}' | xargs docker rmi
 
# Windows (PowerShell)
docker images -a --filter "reference=registry.librechat.ai/danny-avila/librechat*" --format "{{.ID}}" | ForEach-Object { docker rmi $_ }
docker images -a --filter "reference=ghcr.io/danny-avila/librechat*" --format "{{.ID}}" | ForEach-Object { docker rmi $_ }

git pull

docker compose pull

docker compose up

故障排除

端口已被占用

如果您看到类似 bind: address already in use 且涉及端口 3080 的错误，说明另一个应用程序正在占用该端口。

请停止冲突的应用程序，或在 docker-compose.override.yml 中更改端口：

services:
  api:
    ports:
      - "3081:3080"

然后访问 http://localhost:3081 即可。

容器启动时崩溃

如果容器在启动后立即退出，请检查日志：

docker compose logs api

常见原因：

librechat.yaml 语法无效 -- 请使用 YAML Validator 进行验证
缺少 .env 文件 —— 请确保项目根目录下存在 .env 文件
Docker 未运行 -- 请确保 Docker Desktop 已打开并正在运行

缺少环境变量

如果功能未按预期运行，请检查 .env 文件中是否已设置所需的环境变量。

docker compose exec api env | grep -i "your_variable"

请参阅 .env reference 以获取所有可用变量及其默认值。

后续步骤

自定义 endpoint

添加 OpenRouter、Ollama 以及其他 AI 提供商

→

配置概览

了解 LibreChat 的配置文件是如何协同工作的

→

身份验证设置

配置 OAuth、LDAP 和其他登录方式

→