Docker (Linux từ xa)

Để sử dụng hướng dẫn này, bạn cần có một máy tính từ xa hoặc máy ảo (VM) đã được triển khai. Mặc dù bạn có thể sử dụng hướng dẫn này với cài đặt cục bộ, hãy lưu ý rằng nó được viết ban đầu cho việc triển khai trên đám mây.

⚠️ Hướng dẫn này ban đầu được thiết kế cho Digital Ocean, vì vậy bạn có thể phải sửa đổi hướng dẫn cho các nền tảng khác, nhưng ý tưởng chính vẫn không thay đổi.

Phần I: Cài đặt Docker và các phụ thuộc khác:

Có nhiều cách để thiết lập Docker trên các hệ thống Linux. Tôi sẽ hướng dẫn bạn cách tốt nhất và được khuyến nghị dựa trên hướng dẫn này.

Lưu ý rằng cách "Tốt nhất" để cài đặt Docker trên Ubuntu không có nghĩa là cách "nhanh nhất" hay "dễ nhất". Nó có nghĩa là cách tốt nhất để cài đặt nhằm mang lại lợi ích lâu dài (ví dụ: cập nhật nhanh hơn, các bản vá bảo mật, v.v.).

1. Cập nhật và cài đặt các phụ thuộc Docker

Trước tiên, hãy cập nhật danh sách gói của chúng ta và cài đặt các phụ thuộc Docker cần thiết.

sudo apt update

Sau đó, sử dụng lệnh sau để cài đặt các phụ thuộc hoặc các gói điều kiện tiên quyết.

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

Ghi chú cài đặt

• Nhập "Y" cho tất cả các lời nhắc [Y/n] (có/không) trong terminal xuyên suốt toàn bộ hướng dẫn này.
• Sau lời nhắc [Y/n] đầu tiên, bạn sẽ nhận được màn hình đầu tiên trong số vài màn hình màu tím yêu cầu khởi động lại các dịch vụ.
  • Mỗi khi điều này xảy ra, bạn có thể nhấn ENTER một cách an toàn để chọn các tùy chọn mặc định đã được chọn sẵn:

• Nếu tại bất kỳ thời điểm nào bảng điều khiển droplet của bạn bị ngắt kết nối, hãy thực hiện các bước sau rồi tiếp tục từ nơi bạn đã dừng lại:
  • Truy cập lại console như đã chỉ dẫn ở trên
  • Chuyển sang người dùng bạn đã tạo bằng su - <yourusername>

2. Thêm Docker Repository vào APT Sources

Mặc dù việc cài đặt Docker Engine từ các kho lưu trữ của Ubuntu dễ dàng hơn, nhưng việc thêm kho lưu trữ chính thức của docker sẽ giúp bạn nhận được các bản cập nhật nhanh hơn. Đây chính là lý do tại sao đây là phương pháp được khuyến nghị.

Trước tiên, hãy lấy khóa GPG cần thiết để kết nối với kho lưu trữ Docker. Để làm điều đó, hãy sử dụng lệnh sau.

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

Tiếp theo, hãy thêm kho lưu trữ vào danh sách nguồn. Mặc dù bạn cũng có thể thêm thủ công, lệnh dưới đây sẽ thực hiện việc đó tự động cho bạn.

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

Lệnh trên sẽ tự động điền tên mã phát hành của bạn (jammy cho 22.04, focal cho 20.04, và bionic cho 18.04).

Cuối cùng, hãy làm mới lại các gói của bạn một lần nữa.

sudo apt update

Nếu bạn quên thêm khóa GPG, bước trên sẽ thất bại kèm theo thông báo lỗi. Nếu không, hãy tiếp tục với việc cài đặt Docker trên Ubuntu.

3. Cài đặt Docker

Sự khác biệt giữa docker.io và docker-ce là gì?

docker.io là gói docker được cung cấp bởi một số bản phân phối Linux phổ biến (ví dụ: Ubuntu/Debian). Mặt khác, docker-ce là gói docker từ kho lưu trữ Docker chính thức. Thông thường, docker-ce cập nhật hơn và được ưu tiên sử dụng hơn.

Bây giờ chúng ta sẽ cài đặt docker-ce (và không phải gói docker.io)

sudo apt install docker-ce

Màn hình màu tím nghĩa là hãy nhấn ENTER. :)

Khuyên dùng: bạn nên đảm bảo người dùng đã tạo được thêm vào nhóm docker để sử dụng các lệnh một cách liền mạch:

sudo usermod -aG docker $USER

Bây giờ hãy khởi động lại hệ thống để đảm bảo mọi thứ đều ổn.

sudo reboot

Sau khi khởi động lại, nếu đang sử dụng bảng điều khiển droplet trên trình duyệt, bạn có thể nhấn tải lại và đợi để truy cập lại vào bảng điều khiển.

Nhắc nhở: Bất cứ khi nào bạn khởi động lại bằng sudo reboot, bạn nên chuyển sang người dùng mà bạn đã thiết lập trước đó bằng lệnh su - <yourusername>.

4. Xác minh rằng Docker đang chạy trên Ubuntu

Có nhiều cách để kiểm tra xem Docker có đang chạy trên Ubuntu hay không. Một cách là sử dụng lệnh sau:

sudo systemctl status docker

Bạn sẽ thấy kết quả hiển thị active (running) cho trạng thái.

Thoát khỏi nhật ký này bằng cách nhấn CTRL (hoặc CMD) + C.

5. Cài đặt Docker Compose

Vì chúng ta đã thêm kho lưu trữ chính thức của Docker ở bước 2, việc cài đặt Docker Compose rất đơn giản bằng cách sử dụng plugin Compose chính thức:

sudo apt install docker-compose-plugin

Xác minh cài đặt:

docker compose version

Lưu ý: Docker Compose v2 sử dụng lệnh docker compose (không có dấu gạch nối) thay vì docker-compose cũ. Tất cả các lệnh trong hướng dẫn này đều sử dụng cú pháp hiện đại.

6. Là một phần của hướng dẫn này, tôi khuyên bạn nên cài đặt git và npm:

Mặc dù không bắt buộc về mặt kỹ thuật, nhưng việc có git và npm sẽ giúp cho quá trình cài đặt/cập nhật trở nên rất đơn giản:

sudo apt install git nodejs npm

Hãy bắt đầu các dòng mã ma trận.

Bạn có thể xác nhận các gói này đã được cài đặt thành công bằng lệnh sau:

git --version
node -v
npm -v

Lưu ý: việc này có thể cài đặt các phiên bản Node.js và npm cũ. Nếu bạn chạy LibreChat trực tiếp trên máy chủ, hãy sử dụng Node.js v24.16.0 với npm v11.16.0. Đối với hướng dẫn dựa trên Docker này, phiên bản Node.js trên máy chủ không quan trọng vì LibreChat chạy bên trong các container.

Được rồi, bây giờ bạn đã thiết lập xong Droplet, bạn sẽ tiến hành thiết lập chính ứng dụng này

Phần II: Thiết lập LibreChat

1. Clone repo

Từ dòng lệnh droplet (với tư cách là người dùng của bạn, không phải root):

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

# enter the project directory
cd LibreChat/

2. Tạo các tệp cấu hình và môi trường cho LibreChat

Tệp cấu hình (librechat.yaml)

Tiếp theo, chúng ta tạo tệp cấu hình LibreChat, hay còn gọi là librechat.yaml, cho phép tùy chỉnh các cài đặt của ứng dụng cũng như các endpoint tùy chỉnh.

Cho dù bạn có muốn tùy chỉnh ứng dụng thêm hay không, tệp này vẫn là bắt buộc đối với tệp deploy-compose.yml mà chúng ta đang sử dụng, vì vậy chúng ta có thể tạo một tệp với giá trị tối thiểu cần thiết để bắt đầu:

nano librechat.yaml

Bạn sẽ vào màn hình trình chỉnh sửa và bạn có thể dán nội dung sau:

# 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

Thoát khỏi trình chỉnh sửa bằng CTRL + X, sau đó nhấn Y để lưu và ENTER để xác nhận.

Tệp môi trường (.env)

Các giá trị mặc định là đủ để bạn bắt đầu và chạy ứng dụng, cho phép bạn cung cấp thông tin xác thực của mình từ ứng dụng web.

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

Tuy nhiên, bạn rất nên điều chỉnh các giá trị "secret" từ giá trị mặc định để tăng cường bảo mật. Nhật ký khởi động API sẽ cảnh báo bạn nếu bạn không thực hiện việc này.

Để thuận tiện, bạn có thể chạy lệnh này để tạo các giá trị của riêng mình:

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

Nếu bạn muốn cung cấp bất kỳ thông tin xác thực nào cho tất cả người dùng trong instance của mình để sử dụng, bạn nên thêm chúng trong khi vẫn đang chỉnh sửa tệp này:

OPENAI_API_KEY=sk-yourKey

Như trước đây, hãy thoát khỏi trình chỉnh sửa bằng CTRL + X, sau đó nhấn Y để lưu và ENTER để xác nhận.

Vậy là xong!

Tuy nhiên, để cấu hình kỹ lưỡng, bạn nên chỉnh sửa tệp .env của mình khi cần thiết, đồng thời hãy đọc các bình luận trong tệp và các tài nguyên bên dưới.

# if editing the .env file
nano .env

Đây là một biến môi trường cần lưu ý. Biến này vô hiệu hóa việc đăng ký tài khoản từ bên ngoài, trong trường hợp bạn muốn thiết lập nó sau khi đã tạo tài khoản của mình.

ALLOW_REGISTRATION=false

Tài nguyên:

• Tokens/Apis/v.v.
• Hệ thống Người dùng/Xác thực

3. Khởi động Docker

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

# confirm docker is running
docker info

Bây giờ chúng ta có thể khởi động container ứng dụng. Lần đầu tiên, chúng ta sẽ sử dụng lệnh đầy đủ và sau đó chúng ta có thể sử dụng lệnh viết tắt.

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

Bạn có thể đóng terminal một cách an toàn nếu muốn -- ứng dụng Docker sẽ tiếp tục chạy.

Lưu ý: nội dung này sử dụng một tệp compose đặc biệt được tối ưu hóa cho môi trường triển khai này. Nếu bạn muốn có thêm cấu hình tại đây, bạn nên kiểm tra các tệp deploy-compose.yml và Dockerfile.multi để xem cách chúng được thiết lập. Chúng tôi không xây dựng image trong môi trường này vì không đủ RAM để thực hiện việc đó một cách chính xác. Thay vào đó, chúng tôi kéo image dev-api mới nhất của LibreChat, vốn được tự động xây dựng sau mỗi lần push vào nhánh main.

Nếu bạn đang thiết lập một tên miền để sử dụng với LibreChat, tệp compose này đang sử dụng tệp nginx nằm tại client/nginx.conf. Hướng dẫn về việc này có ở phần V bên dưới.

4. Sau khi ứng dụng đang chạy, bạn có thể truy cập tại http://yourserverip

Quay lại trang droplet để lấy địa chỉ IP máy chủ của bạn, sao chép nó và dán vào trình duyệt!

Đăng ký, đăng nhập và tận hưởng LibreChat của riêng bạn được lưu trữ từ xa :)

Phần III: Cập nhật LibreChat

Tôi đã làm cho bước này trở nên khá dễ dàng, với điều kiện là mọi thứ ở trên đã được cài đặt thành công và bạn chưa chỉnh sửa lịch sử git.

Lưu ý: Nếu bạn đang làm việc trên một nhánh đã chỉnh sửa, với các commit của riêng bạn, ví dụ như các thay đổi đối với client/nginx.conf, bạn nên kiểm tra config/deployed-update.js để chạy thủ công một số lệnh nếu thấy phù hợp. Xem phần V để biết thêm chi tiết về vấn đề này.

Chạy lệnh sau để cập nhật tự động

npm run update:deployed

Dừng container Docker

npm run stop:deployed

Lệnh này chỉ đơn giản là chạy docker compose -f ./deploy-compose.yml down

Khởi chạy container Docker

npm run start:deployed

Lệnh này chỉ đơn giản là chạy docker compose -f ./deploy-compose.yml up -d

Kiểm tra các container Docker đang hoạt động

docker ps

Bạn có thể cập nhật thủ công mà không cần dùng tập lệnh nếu gặp sự cố.

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

Phần IV: Chỉnh sửa tệp NGINX (cho tên miền tùy chỉnh và các cấu hình nâng cao)

Trong trường hợp bạn muốn chỉnh sửa tệp NGINX vì bất kỳ lý do gì, chẳng hạn như trỏ máy chủ của bạn đến một tên miền tùy chỉnh, hãy sử dụng nội dung sau:

npm run stop:deployed

nano client/nginx.conf

Tôi sẽ không hướng dẫn bạn thiết lập tên miền tùy chỉnh hoặc bất kỳ thay đổi nào khác đối với NGINX, bạn có thể xem hướng dẫn Cloudflare, hướng dẫn Traefik hoặc hướng dẫn NGINX để bắt đầu với các tên miền tùy chỉnh.

Tuy nhiên, tôi sẽ chỉ cho bạn những gì cần chỉnh sửa trên phía LibreChat cho một tên miền tùy chỉnh với thiết lập này.

Vì NGINX đang được sử dụng làm proxy pass theo mặc định, tôi chỉ chỉnh sửa những phần sau:

# before
server_name localhost;

# after
server_name custom.domain.com;

Lưu ý: điều này hoạt động vì tệp deploy-compose.yml đang sử dụng NGINX theo mặc định, không giống như tệp docker-compose.yml chính. Như thường lệ, bạn có thể cấu hình các tệp compose tùy theo nhu cầu của mình.

Bây giờ hãy commit các thay đổi này vào một branch riêng biệt:

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

# stage all file changes
git add .

Để commit các thay đổi vào một nhánh git, bạn sẽ cần xác thực danh tính trên git. Đây có thể là các giá trị giả, nhưng nếu bạn muốn chúng đồng bộ với GitHub trong trường hợp bạn push nhánh này lên một repo đã fork của LibreChat, hãy sử dụng email GitHub của bạn.

# 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"

Việc cập nhật trên một nhánh đã chỉnh sửa giờ đây sẽ hoạt động theo cách hơi khác một chút

npm run rebase:deployed

Bạn đã sẵn sàng!

Cảnh báo Bạn sẽ gặp xung đột khi hợp nhất (merge conflicts) nếu bắt đầu chỉnh sửa nhánh này một cách đáng kể và điều này không được khuyến khích trừ khi bạn biết rõ mình đang làm gì

Lưu ý rằng mọi thay đổi đối với mã trong môi trường này sẽ không được phản ánh vì tệp compose đang kéo các docker images được xây dựng tự động bởi GitHub

Phần V: Sử dụng Bản phát hành ổn định mới nhất thay vì Nhánh chính mới nhất

Theo mặc định, thiết lập này sẽ tải các bản cập nhật mới nhất cho nhánh chính của LibreChat. Nếu bạn muốn sử dụng bản phát hành "ổn định" mới nhất, được xác định bởi các latest tags, bạn sẽ cần chỉnh sửa deploy-compose.yml và commit các thay đổi của mình chính xác như ở Phần V phía trên. Hãy lưu ý rằng bạn sẽ không nhận được các tính năng mới nhất ngay khi chúng ra mắt nếu chọn cách này.

Hãy chỉnh sửa deploy-compose.yml:

nano deploy-compose.yml

Thay đổi librechat-dev-api thành librechat-api:

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

Thực hiện stage và commit như trong Phần V, và bạn đã hoàn tất!