Полное руководство по установке Onyx с помощью Docker

Onyx — это платформа искусственного интеллекта с открытым исходным кодом, предназначенная для связи языковых моделей с документами, приложениями и базами знаний. Она может использоваться как командный чат, корпоративная поисковая система, система RAG и рабочее пространство с агентами и инструментами.

Платформа может предоставляться в качестве управляемой услуги, но также может быть развернута на вашей собственной инфраструктуре. В последнем случае, Docker Compose — один из наиболее доступных методов., поскольку это позволяет запускать интерфейс, API, базы данных, процессы индексирования и остальные компоненты без необходимости вручную устанавливать все их зависимости.

В этом руководстве мы рассмотрим, как установить Onyx с помощью Docker, в чем разница между режимами Lite и Standard, как управлять контейнерами и какие шаги следует предпринять перед публикацией экземпляра в интернете.

Что такое Onyx и к каким сервисам он может подключаться?

Onyx — это корпоративная платформа для чата и поиска, позволяющая пользователям запрашивать информацию из документов и приложений с помощью моделей искусственного интеллекта. Она может взаимодействовать как с коммерческими поставщиками, так и с моделями, размещенными на собственной инфраструктуре.

К его основным функциям относятся:

• Общайтесь с моделями из разных компаний.
• Агенты и инструменты, способные выполнять действия.
• Соединители для синхронизации источников знаний.
• Гибридный поиск с использованием ключевых слов и векторов.
• Ответы RAG основаны на документах.
• Углубленное исследование и поиск в интернете.
• Интеграция с инструментами посредством действий и MCP.
• Загрузка файлов и их организация по проектам.
• Системы администрирования пользователей и аутентификации.

Onyx не обязательно включает в себя ту генеративную модель, которую вы будете использовать. После установки вам потребуется настроить провайдер, например, OpenAI, Anthropic, Gemini, Ollama, LiteLLM или vLLM.

Onyx Lite или Standard: Какую версию установить?

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

Особенность	Оникс Лайт	Оникс Стандарт
Пообщайтесь с моделями	Ага	Ага
Агенты и инструменты	Ага	Ага
Загрузка файла	Ага	Ага
Проекты	Ага	Ага
Соединители с внешними источниками	Нет	Ага
Индексирование и поиск RAG	Нет	Ага
OpenSearch	Нет	Ага
Редис	Нет	Ага
Серверы моделей для индексирования	Нет	Ага
Фоновые процессы	Интегрировано в API	Независимые контейнеры
Рекомендуемое использование	Тестирование, чат и небольшие команды	RAG, связующие звенья и организации

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

Оникс Стандарт Она предназначена для использования коннекторов, синхронизации документации и построения корпоративной системы поиска. Для её работы требуется значительно больше памяти и хранилища, поскольку она включает OpenSearch, Redis, фоновые процессы, объектное хранилище и серверы, используемые во время индексирования.

Требования для установки Onyx с использованием Docker

Onyx может работать на Linux, macOS или Windows с использованием Docker. Для производственного сервера обычно предпочтительнее использовать актуальный дистрибутив Linux.

Официальные требования зависят от выбранного режима:

Режим	минимальный процессор	минимальный объем оперативной памяти	минимальное дисковое пространство	Предпочтительная конфигурация
Оникс Лайт	2 vCPU	2 ГБ	10 ГБ	4 виртуальных процессора, 4 ГБ оперативной памяти и 50 ГБ
Оникс Стандарт	4 vCPU	10 ГБ	32 ГБ плюс место для индексированных данных	8 виртуальных процессоров или больше и 16 ГБ оперативной памяти или больше

В стандартном режиме в документации рекомендуется оценить размер индексируемых документов и добавить значительный запас. Фактическое потребление ресурсов зависит от объема контента, встраиваний, параллельной обработки и конфигурации OpenSearch.

Перед началом работы вам понадобится:

• Учетная запись с правами на управление сервером.
• Docker Engine и плагин Docker Compose.
• Для загрузки изображений и моделей требуется подключение к интернету.
• Используйте Git, если собираетесь выполнять установку вручную.
• Python и uv если вы хотите установить Onyx CLI напрямую.
• Если вы планируете публиковать приложение, вам потребуется домен и доступ к его DNS-настройкам.

Проверьте работу Docker и Compose, используя:

docker --version
docker compose version

В Linux также необходимо убедиться, что пользователь может запускать Docker или использовать другие программы. sudo при необходимости.

Как установить Onyx с помощью рекомендуемого установщика

В настоящее время рекомендуется использовать встроенный в комплект пошаговый установщик. Onyx CLIЭта процедура проверяет ресурсы компьютера, позволяет выбрать между версиями Lite и Standard, загружает образы, запускает контейнеры и ожидает, пока все службы станут доступны.

Если оно у вас уже установлено uv, бежать:

uv tool install onyx-cli
onyx-cli deploy install

Ассистент задаст вам вопрос:

• Какой режим установки вы хотите использовать: Lite или Standard?
• Какую версию Onyx вы хотите развернуть?
• Какую конфигурацию следует использовать для данной среды?

При новой установке файлы развертывания хранятся в следующем месте:

~/.config/onyx

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

Как установить Onyx с помощью официального скрипта

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

curl -fsSL https://onyx.app/install_onyx.sh | bash

Этот скрипт представляет собой оболочку для установщика Onyx CLI. Следовательно, он обеспечивает тот же тип пошагового развертывания и больше не должен рассматриваться как автономная система.

Перед непосредственным запуском любого скрипта, загруженного из интернета, вы можете сохранить его и просмотреть его содержимое:

curl -fsSLo install_onyx.sh https://onyx.app/install_onyx.sh
less install_onyx.sh
bash install_onyx.sh

Программа установки проверяет окружение, при необходимости устанавливает Docker на совместимые системы Linux и ожидает, пока контейнеры не будут работать корректно.

После завершения процесса отобразится адрес, по которому вы сможете получить к нему доступ. В локальной установке без домена это обычно:

http://localhost:3000

Если Onyx работает на другом сервере в сети, он заменяет собой предыдущий. localhost по соответствующему IP-адресу. Не открывайте порт публично без настройки аутентификации и HTTPS.

Как установить Onyx вручную с помощью Docker Compose

Ручная установка полезна, если вы хотите напрямую просматривать файлы Compose или интегрировать Onyx в собственный конвейер развертывания. Однако она требует от вас самостоятельного управления обновлениями и изменениями конфигурации.

Сначала клонируйте официальный репозиторий:

git clone --depth 1 https://github.com/onyx-dot-app/onyx.git
cd onyx/deployment/docker_compose

Для начала стандартного развертывания с использованием опубликованных образов:

docker compose up -d

Если вы хотите скомпилировать изображения из исходного кода:

docker compose up -d --build --force-recreate

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

После запуска контейнеров Onyx необходимо завершить процесс подготовки. Проверить его статус можно с помощью:

docker compose ps

Для отслеживания записей:

docker compose logs -f

Когда все службы будут готовы, откройте:

http://localhost:3000

Как вручную развернуть Onyx Lite

Onyx Lite активируется с помощью дополнительного файла Compose, который отключает ненужные службы:

docker compose \
  -f docker-compose.yml \
  -f docker-compose.onyx-lite.yml \
  up -d

В этом режиме запускаются только необходимые службы:

• api_serverкоторая также занимается фоновой работой.
• web_server, соответствующий интерфейсу.
• relational_dbна основе PostgreSQL.
• nginxкоторый действует как обратный прокси.

В версию Lite не входят коннекторы, OpenSearch или поиск RAG по синхронизированным источникам. Вы можете загружать файлы и использовать проекты, но она не заменяет стандартную версию, если вам необходимо индексировать документацию из внешних приложений.

Какие услуги использует компания Onyx Standard?

Точная архитектура может меняться между версиями, поэтому не рекомендуется копировать старый файл Compose или вручную исправлять образы PostgreSQL, Redis или других компонентов.

В общих чертах, Onyx Standard включает в себя:

• API-сервер с основной логикой.
• Веб-интерфейс.
• PostgreSQL как реляционная база данных.
• Фоновые процессы для коннекторов и индексирования.
• Redis используется для кэширования и управления сессиями.
• OpenSearch для векторного и ключевого поиска.
• Модельные серверы, используемые при индексировании и извлечении данных.
• Объектное хранилище с использованием MinIO или совместимого бэкэнда.
• Nginx в качестве обратного прокси.

Всегда используйте файлы, входящие в состав устанавливаемой вами версии Onyx. Изменение версий базы данных по отдельности может привести к несовместимости или сбоям миграции.

Как завершить первоначальную настройку

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

После входа в систему:

1. Создайте надежный пароль для учетной записи администратора.
2. Войдите в панель администрирования.
3. Настройте поставщика языковой модели.
4. Добавьте соответствующие учетные данные.
5. Выберите модель по умолчанию.
6. Проведите тестовый разговор.
7. Если вы используете стандартную версию, создайте коннектор и проверьте индексацию.

Onyx может работать как с коммерческими сервисами, так и со своими собственными серверами, такими как Ollama, vLLM или LiteLLM. Собственный хостинг Onyx не означает автоматически, что модель также будет локальной: если вы настроите OpenAI, Anthropic или Gemini, необходимые запросы будут отправлены этому провайдеру.

Как управлять Onyx с помощью командной строки

Одним из преимуществ текущего установщика является наличие специальных команд для управления всем жизненным циклом развертывания:

onyx-cli deploy status
onyx-cli deploy logs
onyx-cli deploy stop
onyx-cli deploy upgrade

Его основные функции:

• statusПроверьте состояние служб.
• logs: отображает журналы развертывания.
• stop: останавливает контейнеры, не удаляя их.
• upgrade: обновляет управляемую установку.
• uninstall: исключает необходимость развертывания.

Не беги uninstall Для устранения временной ошибки. Перед удалением проверьте, какие данные и тома будут сохранены, и выполните отдельное резервное копирование.

Как обновить установленную вручную программу

Если вы управляете файлами Docker Compose напрямую, перед обновлением ознакомьтесь с примечаниями к выпуску новой версии. Затем загрузите изменения из репозитория и соответствующие образы.

В каталоге развертывания стандартный процесс включает в себя:

git pull
docker compose pull
docker compose up -d

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

Для установки, выполненной с помощью Onyx CLI, предпочтительно использовать:

onyx-cli deploy upgrade

Сохранение данных и резервное копирование

Docker Compose использует тома для сохранения базы данных, индексов, файлов и других данных после пересоздания контейнеров. Однако, Постоянный том — это не то же самое, что резервная копия..

Перед обновлением или изменением развертывания:

• Создайте копию сохраненных настроек в ~/.config/onyx.
• Создайте резервную копию PostgreSQL, используя инструмент, совместимый с установленной версией.
• Это позволяет сохранять данные из файлов или объектного хранилища на стороне сервера.
• Сохраните переменные среды и секреты, необходимые для восстановления работы сервиса.
• Периодически проверяйте, можно ли восстановить резервные копии.
• Храните как минимум одну копию вне основного сервера.

Некоторые подключенные источники могут быть переиндексированы, но база данных содержит пользователей, настройки, переписки и другие данные, которые не следует считать восстанавливаемыми без резервной копии.

Как настроить домен и HTTPS

Если Onyx будет доступен из интернета, настройте домен, DNS-запись которого указывает на публичный IP-адрес сервера. Затем установите переменную:

WEB_DOMAIN=onyx.ejemplo.com

В репозитории содержится скрипт для получения сертификата Let's Encrypt в развертываниях Docker:

./init-letsencrypt.sh

Перед запуском проверьте файлы среды и убедитесь, что домен корректно разрешается в сервер. Также должны быть доступны порты 80 и 443.

Не следует напрямую публиковать рабочий экземпляр, используя адрес, подобный этому. http://IP:3000Без протокола HTTPS учетные данные и данные могут быть раскрыты во время передачи.

Как защитить Onyx перед публикацией

Аутентификация по электронной почте и паролю включена по умолчанию. Первая зарегистрированная учетная запись получает права администратора.

Для установки, используемой командой:

• Немедленно зарегистрируйте учетную запись администратора.
• Используйте уникальный и надежный пароль.
• Ограничьте доступ с помощью брандмауэра.
• Перед разрешением внешних подключений включите протокол HTTPS.
• При необходимости настройте OAuth, OIDC или SAML.
• Ограничьте количество разрешенных доменов электронной почты.
• Отключайте журнал открытых файлов, когда он больше не нужен.
• Защитите ключи поставщиков моделей и разъемов.
• Обновите Onyx, Docker и операционную систему.
• Проверьте права доступа для агентов, действий и инструментов MCP.

В текущих версиях некоторые параметры безопасности можно настроить через панель администрирования. В корпоративных средах для некоторых расширенных функций, таких как RBAC, синхронизация разрешений или дополнительное шифрование секретных данных, может потребоваться версия Enterprise.

Как отслеживать потребление памяти

В стандартном режиме OpenSearch сохраняет индексы, используемые для поиска. Если уровень использования диска достигает критического порога — по умолчанию 95% — OpenSearch может пометить индексы как доступные только для чтения и прекратить запись.

Периодически проверяйте наличие свободного места:

df -h
docker system df

Вы также можете проверить размер томов и удалить неиспользуемые образы Docker:

docker image prune

Эта команда удаляет оставшиеся образы, но всегда следует проверять, что именно будет удалено. Не используйте агрессивные команды очистки Docker на производственном сервере, не проверив предварительно затронутые контейнеры, образы и тома.

Можно ли установить Onyx через Plesk?

Plesk позволяет создавать и управлять отдельными контейнерами, но Onyx — это стек, состоящий из различных сервисов, сетей, зависимостей и томов. Пересборка его по контейнерам через интерфейс Plesk чревата ошибками и затрудняет обновления.

Если ваш сервер использует Plesk, предпочтительнее следующее:

1. Для доступа к серверу используйте SSH.
2. Убедитесь, что Docker и Docker Compose доступны.
3. Установите Onyx с помощью Onyx CLI или официальных файлов Compose.
4. Используйте Plesk только для управления доменом, DNS или прокси, если вы знаете, как правильно интегрировать обе системы.

Перед использованием этой комбинации убедитесь, что поставщик сервера разрешает управление Docker и что порты, сети и ресурсы не конфликтуют с другими службами, управляемыми Plesk.

Распространенные ошибки при установке Onyx с помощью Docker.

Контейнеры пока недоступны.

Проверьте статус и записи:

onyx-cli deploy status
onyx-cli deploy logs

Для ручной установки используйте:

docker compose ps
docker compose logs --tail=200

Наиболее распространенными причинами являются недостаток памяти, нехватка места, проблемы с правами доступа Docker или незавершенный запуск зависимой службы.

Порт 3000 уже занят

Проверьте, какой процесс использует порт, или измените сопоставление в конфигурации Compose. Не меняйте порт контейнера, не проверив прокси и зависящие от него переменные.

В Onyx Lite не отображаются разъемы.

Это не ошибка. В облегченной версии отключены коннекторы, OpenSearch и поиск RAG для снижения потребления ресурсов. Используйте стандартную версию, если хотите синхронизировать внешние источники.

OpenSearch прекращает принимать запросы на запись.

Проверьте доступное пространство. Если дисковое пространство достигло критического порога, сначала освободите или расширьте объем памяти. Затем, прежде чем снимать блокировку только для чтения, ознакомьтесь с документацией OpenSearch.

Интерфейс открывается, но чат не отвечает.

Убедитесь, что вы настроили действительного поставщика услуг и модель в панели администратора. Также проверьте свой баланс, ключ API и подключение к поставщику услуг.

Сервер испытывает нехватку памяти.

Убедитесь, что вы выбрали правильный режим. Для небольшого сервера используйте режим Lite. Для режима Standard требуется не менее 10 ГБ оперативной памяти, и по мере увеличения количества индексируемых документов может потребоваться значительно больше.

Обновление приводит к несовместимости сервисов.

Ознакомьтесь с примечаниями к выпуску, миграциями и файлами среды. Если вы использовали пошаговую установку, управляйте обновлением с помощью интерфейса командной строки Onyx, а не смешивайте его с командами, выполняемыми вручную.

Установка Onyx с помощью Docker позволяет развернуть среду искусственного интеллекта, подключенную к документам и приложениям организации. Для тестирования чата и агентов Onyx Lite предлагает простую архитектуру с низким энергопотреблением. Для индексирования внешних источников и использования поиска RAG необходимо выбрать стандартное развертывание и выделить достаточные ресурсы.

Самый простой способ поддерживать установку — использовать интерфейс командной строки Onyx, который управляет установкой, журналами, состоянием и обновлениями. В производственной среде также следует настроить аутентификацию, HTTPS, резервное копирование и мониторинг хранилища.