Docker (远程 Linux)

这些说明旨在帮助从零开始在远程 Ubuntu 服务器上进行 Docker 安装的用户

为了使用本指南，你需要部署一台远程计算机或虚拟机。虽然你可以在本地安装中使用本指南，但请记住，它最初是为云部署编写的。

⚠️ 本指南最初是为 Digital Ocean 设计的，因此您可能需要针对其他平台修改说明，但核心思路保持不变。

第一部分：安装 Docker 及其他依赖项：

在 Linux 系统上安装 Docker 有多种方法。我将引导您按照本指南介绍的最佳且推荐的方式进行安装。

请注意，在 Ubuntu 上使用 Docker 安装的“最佳”方式并不意味着“最快”或“最简单”。它指的是为了长期收益（例如更快的更新、安全补丁等）而进行的最佳安装方式。

1. 更新并安装 Docker 依赖

首先，让我们更新软件包列表并安装所需的 Docker 依赖项。

sudo apt update

然后，使用以下命令安装依赖项或先决条件包。

sudo apt install apt-transport-https ca-certificates curl software-properties-common gnupg lsb-release

安装说明

在本指南的所有 [Y/n] (yes/no) 终端提示中，请输入 “Y”。
在第一个 [Y/n] 提示之后，你将看到几个紫色屏幕中的第一个，要求重启服务。
- 每次发生这种情况时，您可以直接按 ENTER 键选择已选定的默认选项：

如果您的 droplet 控制台在任何时候断开连接，请执行以下操作，然后从中断处继续：
- 按照上述说明再次访问控制台
- 使用 su - <yourusername> 切换到你创建的用户。

2. 将 Docker 存储库添加到 APT 源

虽然从 Ubuntu 软件源安装 Docker Engine 更简单，但添加官方 Docker 软件源可以让你更快地获取更新。因此，这是推荐的方法。

首先，让我们获取连接到 Docker 仓库所需的 GPG 密钥。为此，请使用以下命令。

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

接下来，将该仓库添加到源列表中。虽然您也可以手动添加，但下面的命令会自动为您完成此操作。

echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

上述命令将自动填充您的发行版代号（22.04 为 jammy，20.04 为 focal，18.04 为 bionic）。

最后，再次刷新您的软件包。

sudo apt update

如果您忘记添加 GPG 密钥，上述步骤将会失败并显示错误消息。否则，让我们继续在 Ubuntu 上安装 Docker。

3. 安装 Docker

docker.io 和 docker-ce 之间有什么区别？

docker.io 是某些主流 Linux 发行版（例如 Ubuntu/Debian）提供的 docker 软件包。而 docker-ce 则是来自官方 Docker 仓库的 docker 软件包。通常情况下，docker-ce 的版本更新，且更受推荐。

我们现在将安装 docker-ce（而不是 docker.io 软件包）

sudo apt install docker-ce

紫色屏幕意味着按下 ENTER 键。:)

推荐：你应该确保创建的用户已添加到 docker 组，以便顺畅地使用命令：

sudo usermod -aG docker $USER

现在让我们重启系统以确保一切正常。

sudo reboot

重启后，如果使用的是浏览器 droplet 控制台，您可以点击重新加载并等待重新进入控制台。

提醒： 每次使用 sudo reboot 重启后，您都应该使用 su - <yourusername> 切换回您之前设置的用户。

4. 验证 Docker 是否在 Ubuntu 上运行

在 Ubuntu 上检查 Docker 是否正在运行有多种方法。其中一种方法是使用以下命令：

sudo systemctl status docker

你应该能看到状态显示为 active (running)。

按 CTRL (或 CMD) + C 退出此日志。

5. 安装 Docker Compose

由于我们已经在第 2 步中添加了 Docker 的官方仓库，使用官方 Compose 插件安装 Docker Compose 非常简单：

sudo apt install docker-compose-plugin

验证安装：

docker compose version

注意：Docker Compose v2 使用 docker compose 命令（不带连字符），而不是旧版的 docker-compose。本指南中的所有命令均使用现代语法。

虽然不是技术上的必要条件，但拥有 git 和 npm 将使安装/更新变得非常简单：

sudo apt install git nodejs npm

开启矩阵代码流。

您可以通过以下命令确认这些软件包已成功安装：

git --version
node -v
npm -v

注意：这可能会安装旧版本的 Node.js 和 npm。如果您直接在宿主机上运行 LibreChat，请使用 Node.js v24.16.0 和 npm v11.16.0。对于本 Docker 指南，宿主机的 Node.js 版本无关紧要，因为 LibreChat 是在容器内运行的。

好了，现在你已经设置好了 Droplet，接下来将设置应用本身

第二部分：设置 LibreChat

1. 克隆仓库

在 droplet 命令行中（以您的用户身份，而非 root 用户）：

# clone down the repository
git clone https://github.com/danny-avila/LibreChat.git

# enter the project directory
cd LibreChat/

2. 创建 LibreChat 配置和环境变量文件

配置 (librechat.yaml) 文件

接下来，我们创建 LibreChat 配置文件，即 librechat.yaml，它允许自定义应用程序的设置以及自定义 endpoint。

无论您是否想要进一步自定义该应用，对于我们正在使用的 deploy-compose.yml 文件来说，这是必需的，因此我们可以创建一个仅包含最低限度配置的值来启动：

nano librechat.yaml

您将进入编辑器界面，您可以粘贴以下内容：

# For more information, see the Configuration Guide:
# https://www.librechat.ai/docs/configuration/librechat_yaml

# Configuration version (required)
version: 1.3.5
# This setting caches the config file for faster loading across app lifecycle
cache: true

使用 CTRL + X 退出编辑器，然后按 Y 保存，最后按 ENTER 确认。

配置验证

如果您的 librechat.yaml 文件包含验证错误，LibreChat 将会报错并退出（退出代码 1）。这种快速失败（fail-fast）机制确保了配置问题能够在部署初期被及时发现。

在部署之前，请使用 YAML Validator 验证您的配置。如果您的 CI/CD 流水线启动了服务器，它会在配置无效时快速失败，从而防止部署配置错误的设置。

环境 (.env) 文件

默认值足以让您开始并运行应用程序，允许您从 Web 应用程序提供凭据。

# Copies the example file as your global env file
cp .env.example .env

然而，强烈建议您将 "secret" 值从默认值修改为其他值，以提高安全性。如果未进行修改，API 启动日志将会向您发出警告。

为了方便起见，您可以运行此命令来生成您自己的值：

https://www.librechat.ai/toolkit/creds_generator

nano .env

# FIND THESE VARIABLES AND REPLACE THEIR DEFAULT VALUES!

# Must be a 16-byte IV (32 characters in hex)

CREDS_IV=e2341419ec3dd3d19b13a1a87fafcbfb

# Must be 32-byte keys (64 characters in hex)

CREDS_KEY=f34be427ebb29de8d88c107a71546019685ed8b241d8f2ed00c3df97ad2566f0
JWT_SECRET=16f8c0ef4a5d391b26034086c628469d3f9f497f08163ab9b40137092f2909ef
JWT_REFRESH_SECRET=eaa5191f2914e30b9387fd84e254e4ba6fc51b4654968a9b0803b456a54b8418

如果您想为您的实例的所有用户提供任何凭据以供使用，您应该在编辑此文件时添加它们：

OPENAI_API_KEY=sk-yourKey

和之前一样，使用 CTRL + X 退出编辑器，然后按 Y 保存，最后按 ENTER 确认。

就是这样！

若要进行全面配置，您应根据需要编辑 .env 文件，并请务必阅读文件中的注释以及下方的资源。

# if editing the .env file
nano .env

这是一个需要注意的环境变量。如果你希望在创建账户后禁用外部注册，可以使用此变量。

ALLOW_REGISTRATION=false

资源：

3. 启动 Docker

# should already be running, but just to be safe
sudo systemctl start docker

# confirm docker is running
docker info

现在我们可以启动 app 容器了。第一次启动时，我们将使用完整命令，之后可以使用简写命令。

sudo docker compose -f ./deploy-compose.yml up -d

如果您愿意，可以安全地关闭终端——Docker 应用程序将继续运行。

注意：此处使用的是针对该部署环境优化的特殊 compose 文件。如果您需要在此处进行更多配置，应检查 deploy-compose.yml 和 Dockerfile.multi 文件以了解它们的设置方式。由于内存不足，我们无法在此环境中构建镜像。相反，我们拉取了 librechat 的最新 dev-api 镜像，该镜像会在每次推送到 main 分支后自动构建。

如果您正在设置一个用于 LibreChat 的域名，此 compose 文件将使用位于 client/nginx.conf 的 nginx 文件。相关说明请见下文第五部分。

4. 应用程序运行后，您可以通过 `http://yourserverip` 进行访问

返回 droplet 页面获取您的服务器 IP，复制并将其粘贴到您的浏览器中！

第三部分：更新 LibreChat

只要上述内容都已成功安装，且你没有修改过 git 历史记录，这一步操作会非常轻松。

注意：如果您正在使用包含自己提交的已编辑分支（例如，对 client/nginx.conf 进行了修改），则应检查 config/deployed-update.js，并根据需要手动运行其中的一些命令。有关此内容的更多信息，请参阅第五部分。

运行以下命令进行自动更新

npm run update:deployed

停止 Docker 容器

npm run stop:deployed

这仅仅是运行 docker compose -f ./deploy-compose.yml down

启动 Docker 容器

npm run start:deployed

这仅仅是运行 docker compose -f ./deploy-compose.yml up -d

检查正在运行的 Docker 容器

docker ps

如果您遇到问题，可以不使用脚本进行手动更新。

docker compose -f ./deploy-compose.yml 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 -f ./deploy-compose.yml pull

docker compose -f ./deploy-compose.yml up

第四部分：编辑 NGINX 文件（适用于自定义域名和高级配置）

如果您出于任何原因需要编辑 NGINX 文件（例如将您的服务器指向自定义域名），请使用以下内容：

npm run stop:deployed

nano client/nginx.conf

我不会在此指导你进行自定义域名设置或对 NGINX 进行任何其他更改，你可以查看 Cloudflare 指南、Traefik 指南或 NGINX 指南来开始配置自定义域名。

不过，我将向您展示在此配置下，需要在 LibreChat 端进行哪些编辑以适配自定义域名。

由于默认情况下 NGINX 被用作代理转发（proxy pass），我仅编辑了以下内容：

# before
server_name localhost;

# after
server_name custom.domain.com;

注意：此功能之所以有效，是因为 deploy-compose.yml 文件默认使用 NGINX，这与主要的 docker-compose.yml 文件不同。一如既往，您可以根据需要配置 compose 文件。

现在将这些更改提交到一个单独的分支：

# create a new branch
# example: git checkout -b edit
git checkout -b <branchname>

# stage all file changes
git add .

要将更改提交到 git 分支，您需要在 git 上标识您的身份。这些可以是虚假值，但如果您希望它们与 GitHub 同步（如果您将此分支推送到 LibreChat 的 fork 仓库），请使用您的 GitHub 邮箱。

# these values will work if you don't care what they are
git config --global user.email "[email protected]"
git config --global user.name "Your Name"

# Now you can commit the change
git commit -m "edited nginx.conf"

在已编辑的分支上进行更新，现在的操作方式会有所不同

npm run rebase:deployed

一切就绪！

警告如果您在未完全掌握的情况下对分支进行重大修改，将会遇到合并冲突，因此除非您清楚自己在做什么，否则不建议这样做。

请注意，由于 compose 文件拉取的是由 GitHub 自动构建的 Docker 镜像，因此在此环境中对代码所做的任何更改都不会生效。

第五部分：使用最新稳定版本而非最新主分支

默认情况下，此设置将拉取 LibreChat 主分支的最新更新。如果您更倾向于使用“稳定”版本（由 latest tags 定义），则需要编辑 deploy-compose.yml 并按照第五部分所述提交您的更改。请注意，如果这样做，您将无法第一时间体验到最新功能。

让我们编辑 deploy-compose.yml：

nano deploy-compose.yml

将 librechat-dev-api 修改为 librechat-api：

image: registry.librechat.ai/danny-avila/librechat-api:latest

按照第五部分所述进行暂存和提交，你就大功告成了！

Docker (远程 Linux)

本页内容