Подробная Инструкция по Установке LibreChat на Linux (с Docker)

Эта инструкция поможет вам установить и настроить LibreChat на системе Linux с использованием Docker.

Общая информация

• Назначение: LibreChat — это открытая платформа для работы с различными моделями ИИ, предоставляющая единый интерфейс.
• Рекомендуемые ресурсы: Около 11 GB дискового пространства (3 GB для ОС, 8 GB для LibreChat).
• Ссылки для справки:
  • Официальная документация LibreChat (Docker Linux)
  • Пример использования ClickHouse с LibreChat

Подготовка к установке

1. Клонирование репозитория (если еще не сделали):

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

2. Настройка переменных окружения (.env):

Создайте копию файла с примером и откройте её для редактирования:

cp .env.example .env
nano .env

• Ключи API провайдеров: Для удобства управления ключами через веб-интерфейс LibreChat, раскомментируйте и установите значение user_provided для соответствующих API-ключей (например, OPENAI_API_KEY=user_provided).
• Регистрация пользователей: Чтобы разрешить самостоятельную регистрацию новых пользователей, установите:

  ALLOW_REGISTRATION=true

• Секретные ключи (обязательно измените!): Найдите следующие переменные и замените их значения на уникальные, случайные строки. Это критически важно для безопасности!
  • CREDS_IV: 16-байтовая строка (32 символа в hex).
  • CREDS_KEY: 32-байтовая строка (64 символа в hex).
  • JWT_SECRET: 32-байтовая строка (64 символа в hex).
  • JWT_REFRESH_SECRET: 32-байтовая строка (64 символа в hex).

  Пример генерации случайной строки (для каждого ключа отдельно):

  openssl rand -hex 16 # для CREDS_IV
  openssl rand -hex 32 # для CREDS_KEY, JWT_SECRET, JWT_REFRESH_SECRET

• Пример с изменёнными ключами:

  CREDS_IV=ВАША_УНИКАЛЬНАЯ_СТРОКА_16_БАЙТ
  CREDS_KEY=ВАША_УНИКАЛЬНАЯ_СТРОКА_32_БАЙТ
  JWT_SECRET=ВАША_УНИКАЛЬНАЯ_СТРОКА_32_БАЙТ
  JWT_REFRESH_SECRET=ВАША_УНИКАЛЬНАЯ_СТРОКА_32_БАЙТ
  # OPENAI_API_KEY=sk-yourKey  <-- Если используете user_provided, то эта строка должна быть закомментирована
  ALLOW_REGISTRATION=true
  ANYSCALE_API_KEY=user_provided # Пример
  APIPIE_API_KEY=user_provided   # Пример

3. Настройка переопределения Docker Compose (docker-compose.override.yml):

Этот файл позволяет добавлять или изменять параметры основного docker-compose.yml без его прямого редактирования.

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

• В этом файле вы можете, например, настроить монтирование файла librechat.yaml в контейнер API, чтобы использовать его для конфигурации провайдеров:

  services:
    api:
      volumes:
        - ./librechat.yaml:/app/librechat.yaml

4. Настройка конфигурации LibreChat (librechat.yaml):

Этот файл используется для тонкой настройки провайдеров, моделей и отображения иконок в интерфейсе.

cp librechat.example.yaml librechat.yaml
nano librechat.yaml

• Здесь вы можете добавлять, изменять или удалять провайдеров, а также менять цвета иконок (в то время как в .env вы указываете, кто будет предоставлять API-ключи).
• Важно: Убедитесь, что YAML-синтаксис корректен. Проверить можно так:

  yamllint librechat.yaml

Запуск LibreChat

1. Первый запуск сервисов Docker:

Используйте deploy-compose.yml для запуска всех необходимых контейнеров.

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

• up -d: Запускает контейнеры в фоновом режиме.

2. Запуск фронтенда (если требуется напрямую, а не через Docker):

npm run start:deployed

• Примечание: Обычно при использовании deploy-compose.yml фронтенд также запускается в Docker-контейнере. Эта команда может быть нужна для разработки или в специфических случаях, если фронтенд запускается отдельно.

3. Мониторинг логов API:

Чтобы убедиться, что всё работает, следите за логами контейнера API.

docker logs -f LibreChat-API

• Ожидаемый результат: Успешное подключение к MongoDB и отсутствие критических ошибок.

Применение изменений и пересборка (важно после изменений конфигов)

После изменения файлов .env, docker-compose.override.yml или librechat.yaml необходимо перезапустить сервисы Docker.

sudo docker-compose -f ./deploy-compose.yml down       # Останавливает и удаляет текущие контейнеры
sudo docker-compose -f ./deploy-compose.yml up -d --build # Запускает заново и пересобирает (перечитывает) образы

• --build: Это критически важно для применения изменений, так как он заставляет Docker пересобрать образ api, используя обновлённые файлы конфигурации.

Распространенные ошибки и их решения

1. Ошибка getaddrinfo EAI_AGAIN mongodb в логах LibreChat-API:

error: There was an uncaught error: getaddrinfo EAI_AGAIN mongodb

• Причина: Контейнер api не может разрешить имя хоста mongodb. Это часто указывает на проблему с сетевым взаимодействием Docker или нехватку ресурсов при старте.
• Решение: На системах Proxmox или виртуализациях убедитесь, что CPU установлен в режим HOST, а не KVM64 или другое. Это иногда решает проблемы с сетевыми стеками в Docker. Также попробуйте увеличить выделенные ресурсы (RAM, CPU) для VM/контейнера, если они низкие. Иногда помогает повторный запуск Docker Compose.

2. Разлогинивание после обновления страницы (из-за отсутствия HTTPS):

• Причина: Разработчики LibreChat по умолчанию настроили куки для работы только по HTTPS для безопасности. Если вы используете HTTP, браузер может отклонять или игнорировать эти куки, что приводит к разлогиниванию.
• Решение:
  1. Настройте HTTPS: Рекомендуется настроить полноценный HTTPS с использованием Nginx (или Apache) в качестве обратного прокси и Let's Encrypt для сертификатов. Это стандартный и безопасный подход.
  2. Временное решение (для локальной разработки/тестирования, не для продакшена!): В файле .env найдите и установите:

     SECURE_COOKIES=false

     После этого обязательно перезапустите Docker Compose с --build. Однако, помните, что это значительно снижает безопасность.