Jak zainstalować LibreChat z Dockerem: kompletny przewodnik

LibreChat pozwala skonfigurować interfejs AI podobny do ChatGPT na własnym komputerze lub serwerze. Z jednego miejsca możesz pracować z dostawcami komercyjnymi, punktami końcowymi zgodnymi z OpenAI, modelami działającymi za pośrednictwem Ollama oraz serwerami MCP.

Jednym z najłatwiejszych sposobów instalacji jest użycie Dockera. Ten system Utwórz osobne kontenery dla LibreChat i jego usług pomocniczychunikając konieczności ręcznej konfiguracji MongoDB, Meilisearch i innych zależności.

Proces instalacji różni się jednak nieznacznie w zależności od tego, czy uruchamiasz LibreChat na swoim komputerze, czy na zdalnym serwerze Ubuntu. Ważne jest również zrozumienie przeznaczenia poszczególnych plików. .env, librechat.yaml y docker-compose.override.ymlNastępnie zobaczymy Jak zainstalować LibreChat za pomocą Dockera i przygotować konfigurację, którą można aktualizować bez utraty zmian.

Wymagania dotyczące instalacji LibreChat z Dockerem

Do instalacji lokalnej potrzebne będą dwa narzędzia:

• Git, służy do pobierania repozytorium i otrzymywania jego aktualizacji.
• Doker, odpowiedzialny za prowadzenie LibreChat i usług, od których jest on zależny.

W systemach Windows i macOS najprostszą opcją jest instalacja Docker Desktop. W systemie Linux można używać Docker Engine wraz z oficjalną wtyczką Docker Compose.

Dostępność obu narzędzi można sprawdzić za pomocą następujących poleceń:

git --version
docker --version
docker compose version

Ostatnie polecenie powinno pokazać wersję Compose. Jest ona obecnie używana. docker compose, bez myślnika, ponieważ Compose v2 działa jako wtyczka Dockera.

W przypadku instalacji lokalnej nie jest konieczna instalacja Node.js ani NPM. Narzędzia te mogą być wymagane podczas korzystania z niektórych skryptów zawartych w przewodniku zdalnego wdrażania LibreChat.

Zainstaluj Dockera na serwerze Ubuntu

Jeśli hostujesz LibreChat na serwerze VPS lub Ubuntu, najlepiej zainstalować Dockera z jego oficjalnego repozytorium. W ten sposób otrzymasz Docker Engine, interfejs wiersza poleceń i wtyczkę Compose, obsługiwane przez sam projekt.

Przed rozpoczęciem należy zaktualizować indeks pakietu:

sudo apt update
sudo apt upgrade

Następnie zainstaluj Gita i postępuj zgodnie z oficjalną procedurą Dockera, aby dodać repozytorium i pakiety. Po zakończeniu instalacji sprawdź, czy usługa działa.

sudo systemctl status docker

Możesz także uruchomić:

sudo docker run hello-world

Jeśli chcesz używać Dockera bez pisania sudo W każdym zamówieniu dodaj swojego użytkownika do odpowiedniej grupy:

sudo usermod -aG docker $USER

Następnie musisz się wylogować i zalogować ponownie lub zrestartować serwer. Pamiętaj, że członkowie grupy docker Mają bardzo wysoki poziom dostępu do systemu. Nie dodawaj użytkowników, którym nie ufasz.

Zainstaluj LibreChat na komputerze

Aby pobrać LibreChat, otwórz terminal i sklonuj jego oficjalne repozytorium:

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

Następnym krokiem jest utworzenie pliku zmiennych środowiskowych, korzystając z przykładu zawartego w projekcie:

cp .env.example .env

W programie Windows PowerShell, jeśli powyższe polecenie nie jest dostępne, użyj:

Copy-Item .env.example .env

Domyślna konfiguracja pozwala na początkowe uruchomienie, jednak przed użyciem LibreChat na serwerze dostępnym z Internetu należy przejrzeć plik.

Aby uruchomić kontenery, uruchom:

docker compose up -d

Docker pobierze niezbędne obrazy i utworzy usługi. Początkowa konfiguracja może potrwać kilka minut.

Po zakończeniu otwórz go w przeglądarce:

http://localhost:3080

LibreChat nie zawiera domyślnego hasła. Pierwsze zarejestrowane przez Ciebie konto stanie się kontem administratora.Dlatego zaleca się jego utworzenie zanim pozwoli się innym osobom na dostęp do instancji.

Zrozumienie plików konfiguracyjnych LibreChat

LibreChat korzysta z kilku plików o różnych funkcjach:

• .env Przechowuje klucze API, sekrety, opcje uwierzytelniania i zmienne serwerowe.
• librechat.yaml Zdefiniuj niestandardowe punkty końcowe, modele, serwery MCP i inne zaawansowane ustawienia.
• docker-compose.yml Zawiera główną definicję usług Docker.
• docker-compose.override.yml Umożliwia dodawanie własnych portów, woluminów i zmian bez konieczności modyfikowania pliku głównego.

Tworzenie nie jest obowiązkowe librechat.yaml Aby uruchomić LibreChat. Potrzebujesz go tylko wtedy, gdy chcesz korzystać z niestandardowych punktów końcowych lub niektórych zaawansowanych funkcji.

Można go wygenerować na podstawie dołączonego przykładu:

cp librechat.example.yaml librechat.yaml

Kluczy prywatnych nie należy zapisywać bezpośrednio w pliku YAML. Zaleca się ich przechowywanie w .env i odwoływać się do nich za pomocą zmiennych.

Zamontuj plik librechat.yaml w kontenerze

Gdy LibreChat jest uruchamiany za pomocą Dockera, zapisz librechat.yaml Katalog projektu nie zawsze jest wystarczający. Kontener API musi mieć dostęp do pliku.

Najpierw skopiuj dołączony przykładowy plik nadpisujący:

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

Następnie sprawdź, co zawiera ten tom:

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

Docker Compose automatycznie łączy ten plik z docker-compose.ymlW ten sposób możesz zachować swoje zmiany podczas aktualizacji repozytorium.

Aby zastosować zmiany, utwórz ponownie usługi:

docker compose down
docker compose up -d

Jeśli skonfigurowany punkt końcowy nie pojawia się w LibreChat, sprawdź logi API:

docker compose logs api

Błędy wynikają zazwyczaj z nieprawidłowego wcięcia w pliku YAML, brakującej zmiennej w pliku .env lub wolumin, który nie został poprawnie zmontowany.

Zainstaluj LibreChat na serwerze zdalnym

LibreChat oferuje specjalny plik dla serwerów Linux o ograniczonych zasobach:

deploy-compose.yml

To wdrożenie wykorzystuje wstępnie skompilowane obrazy, co eliminuje konieczność lokalnego budowania aplikacji przez serwer. Zawiera również kontener NGINX, który odbiera połączenia internetowe.

Po pobraniu repozytorium i przygotowaniu pliku .envWersję wdrożeniową można rozpocząć za pomocą:

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

Następnie możesz uzyskać do niego dostęp z:

http://IP_DEL_SERVIDOR

Adres ten różni się od adresu instalacji lokalnej, ponieważ plik wdrożenia publikuje NGINX na zwykłych portach internetowych.

Przed udostępnieniem instancji należy wygenerować unikalne klucze tajne dla wszystkich zmiennych, które ich wymagają. Na przykład klucz tajny sesji panelu administracyjnego można wygenerować za pomocą:

openssl rand -hex 32

Skopiuj wynik do odpowiedniej zmiennej .env bez udostępniania lub publikowania w repozytorium.

Po utworzeniu konta administratora możesz również wyłączyć rejestrację nowych użytkowników:

ALLOW_REGISTRATION=false

Uruchom ponownie usługi, aby zastosować zmiany w zmiennych środowiskowych.

Skonfiguruj domenę i zabezpiecz LibreChat za pomocą protokołu HTTPS

Sama edycja nazwy serwera w NGINX nie wystarczy, aby zabezpieczyć instalację. Najpierw należy utworzyć rekord DNS, który będzie kierował domenę na adres IP serwera.

Następnie będziesz potrzebować certyfikatu TLS, na przykład Let's Encrypt, i skonfiguruj NGINX do jego używania. Jeśli uruchomisz NGINX dołączony do deploy-compose.ymlBędziesz musiał również zamontować pliki certyfikatu wewnątrz kontenera.

En client/nginx.confPodstawowa dyrektywa zmienia się z:

server_name localhost;

a:

server_name chat.ejemplo.com;

Dodatkowo należy poprawnie skonfigurować zmienne domeny LibreChat w .env i postępuj zgodnie z procedurą certyfikacji odpowiadającą Twojej architekturze.

Nie publikuj instancji z kontami użytkowników przez HTTP. W przypadku dostępu do LibreChat z internetu, używaj protokołu HTTPS, silnych haseł, zapory sieciowej i kopii zapasowych woluminów trwałych.

Zmień port LibreChat 3080

Jeżeli inna aplikacja używa portu 3080, Docker wyświetli błąd podobny do bind: address already in use.

Nie ma potrzeby modyfikowania pliku głównego. Dodaj tę konfigurację do docker-compose.override.yml:

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

Utwórz ponownie kontenery:

docker compose down
docker compose up -d

Od tego momentu będziesz mógł otworzyć LibreChat używając:

http://localhost:3081

Ten przykład odpowiada lokalnemu utworzeniu. Jeśli używasz deploy-compose.ymlNależy pamiętać, że połączenia przechodzą przez kontener NGINX.

Co zrobić, jeśli pojemniki są zamknięte

Aby sprawdzić stan usług, uruchom:

docker compose ps

Następnie sprawdź logi kontenera API:

docker compose logs api

Możesz również śledzić wiadomości na bieżąco:

docker compose logs -f api

Najczęstszymi przyczynami są:

• Plik .env Nie znajduje się on w katalogu głównym projektu.
• librechat.yaml Zawiera błąd składniowy lub błąd wcięć.
• Brak wymaganej zmiennej.
• Docker nie został uruchomiony.
• Wymagany port jest używany przez inny program.
• Podczas uruchamiania serwera zabrakło pamięci.

Aby sprawdzić, czy zmienna dotarła do kontenera, możesz użyć:

docker compose exec api env | grep -i NOMBRE_DE_LA_VARIABLE

Nie wyświetlaj pełnego wyniku tego polecenia na publicznych zrzutach ekranu, ponieważ środowisko może zawierać dane uwierzytelniające.

Jak zaktualizować LibreChat zainstalowany za pomocą Dockera

W przypadku instalacji lokalnych dokumentacja LibreChat zaleca zatrzymanie usług, pobranie zmian z repozytorium i uzyskanie zaktualizowanych obrazów:

docker compose down
git pull
docker compose pull
docker compose up -d

Jeśli korzystasz ze zdalnego wdrażania i masz dostępne skrypty projektu, możesz uruchomić:

npm run update:deployed

Można to również zrobić ręcznie:

docker compose -f ./deploy-compose.yml down
git pull
docker compose -f ./deploy-compose.yml pull
docker compose -f ./deploy-compose.yml up -d

Jeśli bezpośrednio modyfikowałeś pliki kontrolowane przez Git, aktualizacja może powodować konflikty. Dlatego zaleca się zapisanie zmian w .env, librechat.yaml i zastępuj pliki, kiedy tylko jest to możliwe.

Domyślna konfiguracja zdalna może być zgodna z obrazem skompilowanym z gałęzi głównej. Jeśli stabilność jest dla Ciebie priorytetem, sprawdź tagi opublikowane przez LibreChat i wyraźnie skonfiguruj wersję stabilną, pamiętając, że natychmiast przestaniesz otrzymywać nowo dodane funkcje.

Instalacja LibreChat z Dockerem pozwala na połączenie modeli lokalnych i zewnętrznych dostawców w jednym interfejsie bez zaśmiecania systemu zależnościami. Kluczem jest wybór odpowiedniego pliku Compose, prawidłowe oddzielenie kluczy tajnych od konfiguracji, zabezpieczenie dostępu zdalnego oraz przechowywanie dostosowań poza głównymi plikami projektu.

Po uruchomieniu instancji następnym krokiem może być dodanie Ollama, OpenRouter, komercyjnego dostawcy lub Połącz serwery MCP z LibreChat.