> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yahont.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Yahont CLI

> Установка и управление развёртыванием Docker Compose с помощью `onyx-cli deploy`

[Yahont CLI](https://docs.yahont.ai/overview/yahont_anywhere/cli.md) включает группу команд `deploy`,
которая устанавливает и обслуживает самостоятельно размещаемое развёртывание Docker Compose:
пошаговый установщик и команды жизненного цикла для обновления, проверки, остановки и удаления развёртывания.

Это рекомендуемый способ настроить и обслуживать самостоятельно размещаемое развёртывание в Linux, macOS и Windows.
[Скрипты установки](https://docs.yahont.ai/deployment/getting_started/quickstart.md) `install.sh` / `install.ps1` — это тонкие обёртки,
которые устанавливают CLI и запускают `onyx-cli deploy install`, поэтому оба пути дают одно и то же развёртывание.
Развёртывания, созданные старыми версиями скриптов,
обнаруживаются и [обслуживаются на месте](#migrating-an-existing-deployment).

По сравнению с ручным управлением [файлами Docker Compose](https://docs.yahont.ai/deployment/local/docker.md) CLI:

* **Автоматически синхронизирует файлы compose**: `deploy upgrade` обновляет файлы compose, оверлеи
  и конфигурацию nginx в соответствии с целевой версией, поэтому вам не нужно самому сравнивать их с репозиторием.
* **Защищает ваши настройки**: файлы, изменённые вручную,
  обнаруживаются по манифесту контрольных сумм и сохраняются в резервной копии, прежде чем их когда-либо перезапишут,
  а настройки в вашем `.env` переживают каждое обновление.
* **Помогает в отладке**: `deploy status` показывает расхождение версий и объясняет, *почему* сервис не работает
  (перезапуски, код выхода, OOM, последняя неудачная проверка здоровья),
  а `deploy logs` сам находит нужные файлы compose и оверлеи.
* **Берёт на себя окружение**: проверяет ОЗУ, диск и порты, устанавливает Docker в Linux
  и генерирует секреты, вместо того чтобы оставлять требования README.
* **Предоставляет удобный и понятный интерфейс**: пошаговые запросы с разумными значениями по умолчанию, `--help` у каждой команды
  и понятные сообщения об ошибках, а также `--no-prompt` и `--json` для автоматизации.

| Команда | Описание |
| - | - |
| `onyx-cli deploy install` | Установить новое развёртывание или перезапустить / обновить существующее |
| `onyx-cli deploy upgrade` | Обновить существующее развёртывание до новой версии |
| `onyx-cli deploy status` | Показать версии, контейнеры и их состояние |
| `onyx-cli deploy stop` | Остановить контейнеры, не удаляя данные |
| `onyx-cli deploy logs` | Показать журналы сервисов |
| `onyx-cli deploy uninstall` | Безвозвратно удалить развёртывание и все его данные |

## Предварительные требования

Установите CLI из PyPI:

```shell theme={null}
uv tool install onyx-cli
```

Или с помощью pip:

```shell theme={null}
pip install onyx-cli
```

Другие способы установки см. в [обзоре CLI](https://docs.yahont.ai/overview/yahont_anywhere/cli.md).
Шаг `onyx-cli configure` не нужен — команды `deploy` работают напрямую с вашим локальным Docker, а не с сервером Yahont.

> [!TIP]
>
> Прежде чем начать, ознакомьтесь с [руководством по ресурсам](https://docs.yahont.ai/deployment/getting_started/resourcing.md).

## Установка

```shell theme={null}
onyx-cli deploy install
```

Интерактивный установщик задаёт два вопроса — режим развёртывания (**Lite** или **Standard**)
и версию для развёртывания, по умолчанию подставляется последний релиз, — пока в фоне выполняются проверки окружения.
Затем он:

* Проверяет системные ресурсы (ОЗУ, диск) и ищет свободный порт хоста
* Устанавливает Docker Engine и плагин compose в Linux после подтверждения;
  запускает Docker Desktop и ждёт его в macOS; обнаруживает Docker и даёт инструкции в Windows
* Создаёт файл `.env` из шаблона со случайно сгенерированными секретами
* Загружает образы Yahont и запускает контейнеры, дожидаясь, пока каждый сервис сообщит, что он работает

Повторный запуск `deploy install` для существующего развёртывания задаёт один вопрос:
**Restart** (перезапустить как есть) или **Upgrade** (обновить до новой версии).

### Флаги

| Флаг | Описание |
| - | - |
| `--lite` | Развернуть Yahont Lite (без OpenSearch, Redis и серверов моделей) |
| `--include-craft` | Включить [Yahont Craft](https://docs.yahont.ai/deployment/local/craft_docker_compose.md) — Craft включается только этим флагом и не предлагается интерактивным запросом |
| `--tag <version>` | Тег образа для развёртывания (по умолчанию: последний релиз Yahont) |
| `--dir <path>` | Каталог развёртывания (по умолчанию: `~/.config/onyx` или существующий `./onyx_data`) |
| `--no-prompt` | Запуск без интерактивных запросов, с применением значений по умолчанию (для CI и автоматизации) |
| `--local` | Использовать существующие файлы конфигурации на диске вместо загрузки |
| `--offline` | Развернуть из образов, уже имеющихся на хосте, без доступа к сети (подразумевает `--local`) |
| `--no-wait` | Вернуться сразу после запуска контейнеров, не дожидаясь их работоспособности |
| `--dry-run` | Показать, что будет сделано, без внесения изменений |
| `--force` | Перезаписать вручную изменённые управляемые файлы (резервная копия сохраняется) и пересоздать работающие сервисы |
| `--verbose` | Показать подробный вывод для отладки |

Например, полностью неинтерактивная установка с закреплённой версией:

```shell theme={null}
onyx-cli deploy install --tag v4.4.6 --no-prompt
```

### Каталог развёртывания

Новые установки находятся в `~/.config/onyx` (с учётом XDG). Развёртывания,
созданные старыми версиями скрипта `install.sh` в `./onyx_data`,
обнаруживаются автоматически и обслуживаются **на месте** — миграция не нужна.
Укажите `--dir` или задайте переменную окружения `ONYX_DEPLOYMENT_DIR`, чтобы выбрать конкретное расположение.

В каталоге лежат файлы compose, `.env` и манифест `install-state.json`, где записаны режим развёртывания,
версия и контрольная сумма каждого управляемого файла. Данные приложения там не хранятся — чаты,
пользователи и документы находятся в именованных томах Docker.

### Офлайн-установка

`--offline` разворачивает целиком из того, что уже есть на хосте, — без поиска релиза,
загрузки конфигурации и загрузки образов. Образы нужно загрузить заранее,
а Docker должен быть уже установлен (без сети установщик не может его установить). Флаг подразумевает `--local`:
файлы конфигурации, уже лежащие на диске, используются как есть, а отсутствующие записываются из копий,
встроенных в CLI. Всё равно рекомендуется подготовить каталог развёртывания из подключённой к сети установки (ниже):
встроенные копии соответствуют версии самого CLI, а не обязательно развёртываемой версии Yahont.

На компьютере с доступом в интернет установите последний релиз с теми же флагами режима (или закрепите конкретную версию
с помощью `--tag`), затем экспортируйте образы, которые определило развёртывание:

```bash theme={null}
onyx-cli deploy install
cd ~/.config/onyx/deployment
docker save -o onyx-images.tar $(docker compose config --images)
```

Скопируйте `onyx-images.tar` и каталог `~/.config/onyx` на офлайн-хост, затем:

```bash theme={null}
docker load -i onyx-images.tar
onyx-cli deploy install --offline
```

Без `--tag` офлайн-установка предлагает новейшую выпущенную версию, образы которой уже есть на хосте,
— только что загруженную.
Перед запуском чего-либо установщик проверяет каждый нужный развёртыванию образ и называет каждый отсутствующий —
загрузите их с помощью `docker load` и запустите снова.

> [!NOTE]
>
> `deploy upgrade --offline` работает так же для перевода изолированного от сети развёртывания на более новую
> подготовленную версию.

## Обновление

```shell theme={null}
onyx-cli deploy upgrade
```

Обновляет существующее развёртывание до последнего релиза или до конкретной версии с помощью `--tag`:

```shell theme={null}
onyx-cli deploy upgrade --tag v4.4.6
```

Обновление рассчитано на сохранение ваших настроек:

* Перезаписывается только строка `IMAGE_TAG` в `.env` (а также `SANDBOX_BACKEND`, когда включён Craft) —
  все остальные настройки, включая ваши правки, сохраняются.
* Управляемые файлы (файлы compose, оверлеи, конфигурация nginx) обновляются в соответствии с целевой версией.
  Файлы, изменённые вами вручную, обнаруживаются по манифесту,
  сохраняются в резервной копии и перезаписываются только после вашего подтверждения (или с `--force`).
* Понижение до более старой версии выдаёт предупреждение и требует подтверждения или `--force`.

Работающие сервисы продолжают обслуживать запросы, пока загружаются новые образы, а затем пересоздаются на новой версии.
`upgrade` принимает те же флаги `--dir`, `--no-prompt`, `--local`, `--offline`, `--no-wait`, `--dry-run` и `--verbose`,
что и `install`.

## Состояние

```shell theme={null}
onyx-cli deploy status
```

Показывает версию, установленную по данным CLI,
по `.env` и по работающим контейнерам (расхождения между ними отмечаются),
а также состояние и работоспособность каждого контейнера,
опубликованный порт и — для неработающего сервиса — причину (перезапуски, код выхода, OOM,
последняя неудачная проверка здоровья).

`status` работает только на чтение и подходит как проверка здоровья:
используйте `--json` для машиночитаемого вывода и проверяйте код завершения.

| Код завершения | Значение |
| - | - |
| `0` | Всё работает и в порядке |
| `1` | Остановлено или работает с ошибками |
| `9` | Установка не найдена |

## Журналы

```shell theme={null}
onyx-cli deploy logs api_server
```

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

| Флаг | Описание |
| - | - |
| `-f`, `--follow` | Продолжать выводить новые строки журнала |
| `--tail <n>` | Сколько строк показывать с конца каждого журнала (по умолчанию `200`, `all` — все) |
| `--since <time>` | Только журналы начиная с этого момента (например, `10m`, `2h` или метка времени) |

## Остановка

```shell theme={null}
onyx-cli deploy stop
```

Останавливает контейнеры, не удаляя их и никакие данные.
Снова запустите развёртывание с помощью `onyx-cli deploy install`.

## Удаление

```shell theme={null}
onyx-cli deploy uninstall
```

Удаляет контейнеры Yahont, тома и каталог развёртывания.

> [!WARNING]
>
> Это безвозвратно удаляет все данные пользователей и документы.
> В интерактивном режиме для подтверждения нужно ввести `DELETE`; в неинтерактивном требуется `--force`.

## Перенос существующего развёртывания

### Из старого развёртывания install.sh

Сегодняшний `install.sh` запускает CLI, но старые версии были самостоятельными и устанавливались в каталог `onyx_data`.
Такие развёртывания обслуживаются на месте — запустите CLI из каталога,
содержащего `onyx_data` (или укажите его в `--dir`), и он возьмёт управление на себя, миграция не требуется.
Флаги режимов старого скрипта соответствуют отдельным командам:

| install.sh | Yahont CLI |
| - | - |
| `./install.sh` | `onyx-cli deploy install` |
| Запустить заново и ввести `update` | `onyx-cli deploy upgrade` |
| `./install.sh --shutdown` | `onyx-cli deploy stop` |
| `./install.sh --delete-data` | `onyx-cli deploy uninstall` |

### Перенос в `~/.config/onyx`

Устаревшую установку `onyx_data` также можно перенести в рекомендуемое расположение `~/.config/onyx`.
Переносится только конфигурация: чаты, пользователи и документы находятся в именованных томах Docker,
привязанных к имени проекта compose (`onyx`), которое остаётся прежним,
поэтому перенесённое развёртывание автоматически подхватывает их. Единственный файл,
который обязательно нужно перенести, — `.env`: в нём секреты,
с которыми были инициализированы тома базы данных и объектного хранилища.

```bash theme={null}
# From the directory containing onyx_data
onyx-cli deploy stop
mkdir -p ~/.config/onyx/deployment
cp onyx_data/deployment/.env ~/.config/onyx/deployment/
onyx-cli deploy install --dir ~/.config/onyx
```

Выберите **Restart**, чтобы запуститься на версии, уже закреплённой в `.env`, или **Upgrade**,
чтобы перейти на более новую. Файлы compose загружаются заново, поэтому повторно примените свои ручные правки в них.
Когда `onyx-cli deploy status` сообщит, что всё в порядке, удалите старый каталог — в нём только конфигурация:

```bash theme={null}
rm -rf onyx_data
```

> [!NOTE]
>
> Удаление старого каталога важно: когда `onyx_data` существует в рабочем каталоге, CLI предпочитает его,
> а не `~/.config/onyx`. После его удаления обычные команды `onyx-cli deploy` находят новое расположение без `--dir`.

### Из ручной установки docker compose

Развёртывание, запущенное вручную из каталога `deployment/docker_compose` репозитория,
можно взять под управление так же, если оно использует имя проекта compose по умолчанию (`onyx`,
закреплено в `docker-compose.yml`):

```bash theme={null}
# From the directory with your docker-compose.yml
docker compose down   # keeps the data volumes — do NOT pass -v
mkdir -p ~/.config/onyx/deployment
cp .env ~/.config/onyx/deployment/
onyx-cli deploy install
```

Установщик обнаруживает скопированный `.env` как существующее развёртывание,
загружает управляемые файлы compose и поднимает стек обратно на существующих томах.

> [!WARNING]
>
> Развёртывания,
> запущенные под другим именем проекта — старым именем `onyx-stack` или любым пользовательским значением `-p`,
> — хранят свои тома под этим префиксом и **не** подхватываются автоматически.
> Продолжайте управлять ими напрямую через `docker compose` или перенесите данные томов вручную,
> прежде чем переключаться.

## Дальнейшие шаги

> [card] [Настройте аутентификацию](https://docs.yahont.ai/deployment/authentication/basic.md)
>
> Настройте аутентификацию для вашего развёртывания Yahont с помощью OAuth, OIDC или SAML.

> [card] [Больше параметров конфигурации Yahont](https://docs.yahont.ai/deployment/configuration/configuration.md)
>
> Узнайте обо всех доступных параметрах конфигурации вашего развёртывания Yahont.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.