Перейти к основному содержимому

Готовы внести вклад в Open WebUI? Давайте начнем! 🚀

Хотите погрузиться в разработку Open WebUI? Это подробное руководство поможет вам быстро и легко настроить локальную среду разработки. Независимо от того, опытный вы разработчик или только начинаете, вы сможете настроить фронтенд, улучшить бэкенд и внести вклад в будущее Open WebUI! Давайте настроим вашу среду разработки шаг за шагом!

Необходимые требования​

Прежде чем начать, убедитесь, что ваша система отвечает этим минимальным требованиям:

  • Операционная система: Linux (или WSL на Windows), Windows 11 или macOS. (Рекомендуется для лучшей совместимости)
  • Python: Версия 3.11 или выше. (Требуется для работы бэкенд-сервисов)
  • Node.js: Версия 22.10 или выше. (Требуется для разработки фронтенда)
  • IDE (Рекомендуется): Мы рекомендуем использовать IDE, такую как VSCode, для редактирования кода, отладки и доступа к интегрированному терминалу. Вы также можете использовать свою любимую IDE, если такая у вас есть!
  • [Опционально] GitHub Desktop: Для упрощенного управления Git-репозиторием, особенно если вы не слишком знакомы с Git в командной строке, рекомендуется установить GitHub Desktop.

Настройка локальной среды​

Мы настроим как фронтенд (пользовательский интерфейс), так и бэкенд (API и серверную логику) Open WebUI.

1. Клонирование репозитория​

Сначала используйте git clone, чтобы загрузить репозиторий Open WebUI на ваш локальный компьютер. Это создаст локальную копию проекта на вашем устройстве.

  1. Откройте ваш терминал (или Git Bash, если вы используете Windows и Git Bash).
  2. Перейдите к каталогу, куда вы хотите сохранить проект Open WebUI.
  3. Клонируйте репозиторий: Выполните следующую команду:
git clone https://github.com/open-webui/open-webui.git
cd open-webui

Команда git clone загружает файлы проекта с GitHub. Команда cd open-webui затем переводит вас в недавно созданный каталог проекта.

2. Настройка фронтенда (Пользовательский интерфейс)​

Сначала запустим пользовательский интерфейс (то, что вы видите в своем браузере):

  1. Настройте переменные окружения:

    • Скопируйте пример файла окружения в .env:

      cp -RPp .env.example .env

      Эта команда копирует файл .env.example в новый файл с именем .env. Файл .env используется для настройки переменных окружения для фронтенда.

    • Настройте .env: Откройте файл .env в вашем редакторе кода (например, в VSCode). Этот файл содержит конфигурационные переменные для фронтенда, такие как конечные точки API и другие настройки. Для локальной разработки настроек по умолчанию в .env.example обычно достаточно. Однако вы можете настроить их при необходимости.

Важно: Не добавляйте конфиденциальную информацию в .env, если вы делаете вклад обратно в репозиторий.

  1. Установите зависимости фронтенда:

    • Перейдите в каталог фронтенда: Если вы еще не находитесь в корне проекта (open-webui), убедитесь, что вы там.

      # Если вы не в корне проекта, выполните:
      cd open-webui

    • Установите необходимые JavaScript-пакеты:

      npm install

      Эта команда использует npm (Node Package Manager) для чтения файла package.json в корневой директории проекта и загрузки всех необходимых JavaScript-библиотек и инструментов для работы фронтенда. Это может занять несколько минут в зависимости от вашего интернет-соединения.

  2. Запустите сервер разработки фронтенда:

    npm run dev

    Эта команда запускает сервер разработки фронтенда. Если шаги были успешно выполнены, обычно будет указано, что сервер работает, и сообщён локальный URL.

    🎉 Доступ к фронтенду: Откройте ваш веб-браузер и перейдите на http://localhost:5173. Вы должны увидеть сообщение, указывающее, что фронтенд Open WebUI работает и ожидает доступности бэкенда. Не волнуйтесь об этом сообщении сейчас! Давайте настроим бэкенд. Не закрывайте этот терминал – он используется для обслуживания вашего фронтенда!

3. Настройка бэкенда (API и сервер)​

Для более удобной разработки мы настойчиво рекомендуем использовать отдельные окна терминала для процессов вашего фронтенда и бэкенда. Это поможет сохранить организованность и облегчит управление каждой частью приложения отдельно.

Почему отдельные терминалы?

  • Изоляция процессов: Серверы разработки фронтенда и бэкенда — это разные программы. Запуская их в отдельных терминалах, вы гарантируете, что они не будут конфликтовать друг с другом, и сможете независимо перезапускать или останавливать их.
  • Более понятные логи и вывод: Каждый терминал будет отображать логи и вывод, относящиеся непосредственно к фронтенду или бекенду. Это значительно облегчает отладку и мониторинг, так как вам не придется разбирать переплетенные логи.
  • Снижение загроможденности терминала: Смешивание команд фронтенда и бекенда в одном терминале может создавать путаницу. Отдельные терминалы помогают упорядочить вашу историю команд и активные процессы.
  • Повышение эффективности рабочего процесса: Вы можете работать над задачами фронтенда (например, запуск npm run dev) в одном терминале и одновременно управлять задачами бекенда (например, запуск сервера или просмотр логов) в другом терминале, не переключаясь постоянно между контекстами в одном терминале.

Использование интегрированного терминала в VSCode (рекомендуется):

Функция интегрированного терминала в VSCode значительно упрощает управление несколькими терминалами. Вот как использовать ее для разделения фронтенда и бекенда:

  1. Терминал для фронтенда (возможно, он у вас уже есть): Если вы следовали шагам настройки фронтенда, у вас, вероятно, уже открыт терминал в VSCode в корневой директории проекта (директория open-webui). Именно здесь вы будете запускать команды для фронтенда (npm run dev и т.д.). Убедитесь, что вы находитесь в директории open-webui перед следующим шагом, если вы еще этого не сделали.

  2. Терминал для бекенда (откройте новый):

    • В VSCode перейдите в Терминал > Новый терминал (или используйте сочетание клавиш Ctrl+Shift+ на Windows/Linux или Cmd+Shift+ на macOS). Это откроет новую панель терминала.
    • Перейдите в директорию backend: В этом новом терминале используйте команду cd backend, чтобы перейти в папку backend вашего проекта. Это гарантирует, что все команды, связанные с бекендом, будут выполняться в правильном контексте.

    Теперь у вас есть два отдельных экземпляра терминала в VSCode: один для фронтенда (вероятно, в директории open-webui) и один специально для бекенда (внутри директории backend). Вы можете легко переключаться между этими терминалами в VSCode, чтобы независимо управлять процессами фронтенда и бекенда. Такой подход настоятельно рекомендуется для более чистого и эффективного рабочего процесса.

Шаги настройки бекенда (в вашем терминале для бекенда):

  1. Перейдите в директорию бекенда: (Вы уже должны находиться в директории backend в вашем новом терминале с предыдущего шага). Если нет, выполните:

    cd backend

  2. Создайте и активируйте среду Conda (рекомендуется):

    • Мы настоятельно рекомендуем использовать Conda для управления зависимостями Python и изоляции вашей рабочей среды. Это предотвращает конфликты с другими проектами Python на вашей системе и обеспечивает использование корректной версии Python и библиотек.

      conda create --name open-webui python=3.11
      conda activate open-webui
      • conda create --name open-webui python=3.11: Эта команда создает новую среду Conda с именем open-webui, использующую Python версии 3.11. Если вы выбрали другую версию Python 3.11.x, это также допустимо.
      • conda activate open-webui: Эта команда активирует только что созданную среду Conda. После активации приглашение терминала обычно изменится, чтобы показать, что вы находитесь в среде open-webui (например, в начале строки может появиться (open-webui)).

    Убедитесь, что вы активировали среду в вашем терминале для бекенда перед продолжением.

    (Использование Conda необязательно, но настоятельно рекомендуется для управления зависимостями Python и предотвращения конфликтов.) Если вы решили не использовать Conda, убедитесь, что вы используете Python 3.11 или выше, и перейдите к следующему шагу, однако обратите внимание на возможные конфликты зависимостей.

  3. Установите зависимости для бекенда:

    • В вашем терминале для бекенда (в Conda-среде, если вы ее используете) выполните:
    pip install -r requirements.txt -U

    Эта команда использует pip (установщик пакетов Python), чтобы прочитать файл requirements.txt в директории backend. requirements.txt содержит список всех библиотек Python, необходимых для работы бекенда. pip install загружает и устанавливает эти библиотеки в вашу активную среду Python (вашу Conda-среду, если вы ее используете, или вашу глобальную среду Python в противном случае). Флаг -U гарантирует, что вы получите последние совместимые версии библиотек.

  4. Запустите сервер разработки бекенда:

    • В вашем терминале для бекенда выполните:
    sh dev.sh

    Эта команда выполняет скрипт dev.sh. Этот скрипт, вероятно, содержит команду для запуска сервера разработки бекенда. (Вы можете открыть и изучить файл dev.sh в вашем редакторе кода, чтобы узнать, какая команда выполняется, если вам интересно.) Сервер бекенда обычно запускается и выводит информацию в терминал.

📄 Изучите документацию к API: После запуска сервера бекэнда вы можете открыть автоматически сгенерированную документацию к API в вашем веб-браузере по адресу http://localhost:8080/docs. Эта документация чрезвычайно полезна для понимания конечных точек API бекэнда, способов взаимодействия с ним, а также данных, которые он ожидает и возвращает. Держите эту документацию под рукой в процессе разработки!

🎉 Поздравляем! Если вы следовали всем инструкциям, то у вас должны быть локально запущены оба сервера разработки (фронтенд и бекэнд). Вернитесь на вкладку браузера, где вы открывали фронтенд (обычно http://localhost:5173). Обновите страницу. Теперь вы должны увидеть полностью работающий Open WebUI в вашем браузере, подключённый к вашему локальному серверу бекэнда!

Устранение распространенных проблем​

Вот решения некоторых общих проблем, с которыми вы можете столкнуться во время настройки или разработки:

💥 "FATAL ERROR: Reached Heap Limit" (Фронтенд)​

Эта ошибка, часто возникающая при разработке фронтенда, указывает на то, что Node.js исчерпал доступную память во время процесса сборки, особенно при работе с крупными фронтенд-приложениями.

Решение: Увеличьте размер кучи памяти Node.js. Это позволит Node.js воспользоваться большим объемом памяти. У вас есть несколько вариантов:

  1. С использованием переменной окружения NODE_OPTIONS (рекомендуется для разработки):

    • Это временный способ увеличить лимит памяти для текущей сессии терминала. Перед выполнением команды npm run dev или npm run build в вашем терминале фронтенда, установите переменную окружения NODE_OPTIONS:

      export NODE_OPTIONS="--max-old-space-size=4096" # Для Linux/macOS (bash, zsh)
      # set NODE_OPTIONS=--max-old-space-size=4096 # Для Windows (Command Prompt)
      # $env:NODE_OPTIONS="--max-old-space-size=4096" # Для Windows (PowerShell)
      npm run dev

      Выберите команду, подходящую для вашей операционной системы и терминала. 4096 представляет 4 ГБ памяти. При необходимости вы можете увеличить это значение (например, 8192 для 8 ГБ). Этот параметр будет действовать только для команд, выполняемых в текущей сессии терминала.

  2. Изменение Dockerfile (для контейнеризированных сред):

    • Если вы работаете с Docker, вы можете постоянно устанавливать переменную окружения NODE_OPTIONS внутри вашего Dockerfile. Это полезно для стабильного распределения памяти в контейнеризированных средах, как показано в исходном примере:

      ENV NODE_OPTIONS=--max-old-space-size=4096

    • Выделите достаточно ОЗУ: Независимо от выбранного метода, убедитесь, что на вашей системе или в контейнере Docker доступно достаточно ОЗУ для использования Node.js. Рекомендуется не менее 4 ГБ ОЗУ, а для больших проектов или сложных сборок может потребоваться больше. Закройте ненужные приложения, чтобы освободить ОЗУ.

⚠️ Конфликты портов (Фронтенд и Бекэнд)​

Если вы видите ошибки, связанные с портами, такие как "Address already in use" или "Port already bound," это означает, что другое приложение на вашем устройстве уже использует порт 5173 (по умолчанию для фронтенда) или 8080 (по умолчанию для бекэнда). Только одно приложение может использовать конкретный порт одновременно.

Решение:

  1. Определите конфликтующий процесс: Вам нужно выяснить, какое приложение использует порт, который вам нужен.

    • Linux/macOS: Откройте новый терминал и используйте команды lsof или netstat:
      • lsof -i :5173 (или :8080 для порта бекэнда)
      • netstat -tulnp | grep 5173 (или 8080) Эти команды покажут идентификатор процесса (PID) и имя процесса, использующего указанный порт.
    • Windows: Откройте Command Prompt или PowerShell от имени администратора и используйте netstat или Get-NetTCPConnection:
      • netstat -ano | findstr :5173 (или :8080) (Command Prompt)
      • Get-Process -Id (Get-NetTCPConnection -LocalPort 5173).OwningProcess (PowerShell) Эти команды также покажут PID процесса, использующего данный порт.

  2. Завершите конфликтующий процесс: После того, как вы определили идентификатор процесса (PID), вы можете остановить приложение, использующее этот порт. Будьте осторожны при завершении процессов, особенно если вы не уверены, для чего они предназначены.

    • Linux/macOS: Используйте команду kill: kill <PID> (замените <PID> на фактический идентификатор процесса). Если процесс не завершается с помощью kill, вы можете использовать kill -9 <PID> (принудительное завершение), но используйте это с осторожностью.
    • Windows: Используйте команду taskkill в Command Prompt или PowerShell от имени администратора: taskkill /PID <PID> /F (замените <PID> на идентификатор процесса). Флаг /F принудительно завершает процесс.

  3. Или измените порты (продвинутый вариант):

    • Если вы не можете завершить конфликтующий процесс (например, это системный сервис, который вам нужен), вы можете настроить Open WebUI для использования других портов для фронтенда и/или бекэнда. Это обычно включает изменение конфигурационных файлов.
      • Порт фронтенда: Проверьте документацию или конфигурационные файлы фронтенда (обычно vite.config.js или аналогичные) для изменения порта сервера разработки. Возможно, вам также потребуется отредактировать файл .env, если фронтенд использует переменные окружения для настройки порта.
      • Порт сервера: Изучите скрипт dev.sh или файлы конфигурации сервера, чтобы узнать, как установлен порт сервера. Возможно, вам потребуется изменить команду запуска или файл конфигурации, чтобы изменить порт сервера. Если вы измените порт сервера, вероятно, вам потребуется обновить файл .env на стороне фронтенда, чтобы указать новый URL сервера.

🔄 Горячая перезагрузка не работает​

Горячая перезагрузка (или замена горячего модуля - HMR) — это замечательная функция разработки, которая автоматически обновляет ваш браузер при внесении изменений в код. Если она не работает, это может значительно замедлить ваш рабочий процесс.

Шаги по устранению неполадок:

  1. Убедитесь, что серверы разработки запущены: Дважды проверьте, что команды npm run dev (фронтенд) и sh dev.sh (бэкенд) запущены в их соответствующих терминалах и не вызывают ошибок. Проверьте сообщения в выводе терминала, подтверждающие, что они работают в режиме "watch" или "development". Если есть ошибки, сначала устраните их.
  2. Проверка сообщений о watch режиме/HMR: При запуске серверов разработки они обычно выводят сообщения в терминале, указывающие на включение горячей перезагрузки или watch режима. Ищите такие фразы, как "HMR включен", "прослушивание изменений файлов" и подобное. Если вы не видите таких сообщений, возможно, есть проблема с конфигурацией.
  3. Кэш браузера: Иногда кэш вашего браузера может препятствовать отображению последних изменений, даже если горячая перезагрузка работает. Попробуйте выполнить жесткую перезагрузку в вашем браузере:
    • Windows/Linux: Ctrl+Shift+R
    • macOS: Cmd+Shift+R
    • Кроме того, вы можете попробовать очистить кэш браузера или открыть фронтенд в приватном/инкогнито-режиме.
  4. Проблемы с зависимостями (фронтенд): Устаревшие или поврежденные зависимости фронтенда могут иногда мешать работе горячей перезагрузки. Попробуйте обновить зависимости фронтенда:

    • В терминале фронтенда выполните:

      rm -rf node_modules && npm install

      Эта команда удаляет каталог node_modules (где хранятся зависимости) и устанавливает их заново. Это может устранить проблемы, вызванные поврежденными или устаревшими пакетами.

  5. Необходим перезапуск бэкенда (при изменении бэкенда): Горячая перезагрузка обычно лучше работает для изменений кода фронтенда (UI, стили, компоненты). При значительных изменениях кода бэкенда (особенно изменений в логике сервера, конечных точках API или зависимостях) может понадобиться вручную перезапустить сервер бэкенда (остановив sh dev.sh в терминале бэкенда и запустив его снова). Горячая перезагрузка для изменений бэкенда часто менее надежна или не настроена автоматически во многих средах разработки бэкенда.
  6. Проблемы с IDE/редактором: В редких случаях проблемы с вашей IDE или редактором кода могут препятствовать правильному обнаружению изменений файлов серверами разработки. Попробуйте перезапустить вашу IDE или убедиться, что файлы сохраняются правильно.
  7. Проблемы конфигурации (сложные): Если ни один из приведенных выше шагов не помог, возможно, проблема связана с более сложной конфигурацией серверов разработки фронтенда или бэкенда. Ознакомьтесь с документацией проекта, файлами конфигурации (например, vite.config.js для фронтенда, файлами конфигурации сервера бэкенда) или обратитесь за помощью к сообществу Open WebUI или мейнтейнерам.

Вклад в Open WebUI​

Мы рады вашему вкладу в Open WebUI! Ваше участие важно для улучшения этого проекта. Вот краткое руководство для эффективного рабочего процесса по внесению изменений:

  1. Понять структуру проекта: Найдите время, чтобы ознакомиться со структурой каталогов проекта, особенно папками frontend и backend. Изучите код, файлы конфигурации и документацию, чтобы понять, как все организовано.

  2. Начните с небольших изменений: Если вы новичок в проекте, рассмотрите возможность начать с небольших вкладов, таких как:

    • Улучшение документации: Исправление опечаток, уточнение объяснений, добавление деталей в документацию.
    • Исправление ошибок: Решение сообщенных багов или проблем.
    • Небольшие улучшения UI: Улучшение стилей, исправление мелких проблем с макетом. Эти небольшие вклады — отличный способ познакомиться с базой кода и процессом внесения изменений.

  3. Сначала обсудите крупные изменения: Если вы планируете реализовать значительную новую функцию или внести существенные изменения, настоятельно рекомендуется сначала обсудить свои идеи с мейнтейнерами проекта или сообществом. Вы можете сделать это:

    • Создав issue в репозитории GitHub, чтобы предложить свою функцию или изменения.
    • Присоединившись к каналам сообщества Open WebUI (если доступны, проверьте README или сайт проекта для ссылок) и обсудив свои идеи там. Это поможет убедиться, что ваш вклад соответствует целям проекта и предотвратит трату усилий на функции, которые могут не быть интегрированы.

  4. Создавайте отдельную ветку для своей работы: Никогда не коммитите прямо в ветку dev. Всегда создавайте новую ветку для каждой функции или исправления ошибки, над которой вы работаете. Это позволяет изолировать ваши изменения и облегчает управление и отправку pull request.

    • Чтобы создать новую ветку (например, названную my-feature-branch) на основе ветки dev: 
      git checkout dev
      git pull origin dev # Убедитесь, что ваша локальная ветка dev актуальна
      git checkout -b my-feature-branch

  5. Часто фиксируйте изменения и пишите понятные сообщения о фиксациях: Делайте небольшие логические фиксации во время разработки функций или исправления ошибок. Пишите четкие и лаконичные сообщения о фиксациях, которые объясняют, какие изменения вы сделали и почему. Хорошие сообщения о фиксациях облегчают понимание истории изменений и являются важной частью совместной работы.

    • Пример хорошего сообщения о фиксации: Fix: Исправлена опечатка в документации настройки backend
    • Пример хорошего сообщения о фиксации: Feat: Реализована страница пользовательского профиля с отображением основной информации

  6. Регулярно синхронизируйтесь с веткой dev: Работая над своей веткой, периодически синхронизируйтесь с последними изменениями из ветки dev, чтобы минимизировать конфликты слияния позже:

    git checkout dev
    git pull origin dev
    git checkout my-feature-branch
    git merge dev

    Разрешьте любые конфликты слияния, возникшие на этапе git merge.

  7. Запускайте тесты (если они есть) перед отправкой: Хотя это руководство не описывает конкретные процедуры тестирования для Open WebUI, хорошей практикой является запуск любых доступных тестов перед отправкой вашего кода. Проверьте документацию проекта или файлы package.json (для frontend) и файлы backend на наличие команд, связанных с тестированием (например, npm run test, pytest, и т.д.). Запуск тестов помогает убедиться, что ваши изменения не внесли регрессии или не сломали существующий функционал.

  8. Отправьте запрос на слияние (PR): Как только вы завершите работу, протестируете ее (если это применимо) и будете готовы внести свои изменения, отправьте запрос на слияние (PR) в ветку dev репозитория Open WebUI на GitHub.

    • Перейдите в репозиторий Open WebUI на GitHub.
    • Перейдите на свою ветку.
    • Нажмите кнопку "Contribute" или "Pull Request" (обычно зеленую).
    • Заполните форму PR:
      • Название: Дайте вашему PR четкое и понятное название, которое описывает ваши изменения (например, "Fix: Исправлена проблема с проверкой формы входа").
      • Описание: Представьте более подробное описание ваших изменений, проблемы, которую вы решаете (если применимо), и любой соответствующий контекст. Укажите связанные задачи, если они есть.
    • Отправьте PR.

    Поддерживающие проект разработчики рассмотрят ваш запрос на слияние, предоставят обратную связь и, возможно, объединят ваши изменения. Будьте готовы к обратной связи и к необходимости внести правки, если потребуется.

Спасибо за то, что прочитали это подробное руководство и за ваш интерес к вкладу в Open WebUI! Мы рады видеть ваши результаты и помочь вам стать частью сообщества Open WebUI! 🎉 Удачной разработки!