> For the complete documentation index, see [llms.txt](https://docs.iexexchanger.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.iexexchanger.com/server-i-dannye/upravlenie-cherez-iexctl.md).

# Управление через iexctl

`iexctl` — основная команда для проверки и обслуживания уже установленного iEXExchanger. С её помощью можно проверить состояние системы, перезапустить прикладные службы, проконтролировать резервные копии, изменить параметры Backend и Frontend, оценить запас ресурсов и подготовить диагностический архив для технической поддержки.

Команды выполняются на сервере через SSH с правами `root`. Если вы подключились под другим пользователем, добавляйте `sudo`, как показано ниже.

{% hint style="info" %}
`iexctl` предназначен для обслуживания работающего iEXExchanger. Первичная установка и обновление системы выполняются отдельными средствами.
{% endhint %}

### Формат вывода

По умолчанию команда показывает результат обычным текстом. Для автоматической обработки можно запросить JSON или YAML:

```bash
sudo iexctl doctor --format json
sudo iexctl services status --format yaml
```

Форматы `json` и `yaml` поддерживаются всеми описанными ниже командами, кроме просмотра журналов. Если команда завершилась с ненулевым кодом, проверка не пройдена или действие не выполнено полностью.

### Время ожидания

Стандартное время ожидания составляет два часа. Для длительной проверки его можно увеличить, но не более чем до 24 часов:

```bash
sudo iexctl backup verify --full --timeout 12h
```

## Проверка состояния iEXExchanger

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

### Полная диагностика

```bash
sudo iexctl doctor
```

Команда последовательно проверяет:

* целостность установленной системы и служебных файлов;
* готовность прикладных и системных служб;
* конфигурацию Nginx;
* PHP, Node.js и планировщик задач;
* подключение к PostgreSQL и Redis;
* свободное место и количество доступных файлов на дисках;
* состояние управляемых резервных копий, если они включены.

В результате каждая проверка получает отметку `OK`, `WARN` или `ERROR`. `WARN` указывает на риск, который требует внимания, но не всегда блокирует работу. `ERROR` означает, что общая проверка не пройдена.

{% hint style="warning" %}
Не ограничивайтесь последней строкой вывода. Перед дальнейшими действиями прочитайте все сообщения `WARN` и `ERROR`: в них указана конкретная причина проблемы.
{% endhint %}

## Управление службами

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

### Просмотр состояния

```bash
sudo iexctl services status
```

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

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

```bash
sudo iexctl services verify
```

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

### Перезапуск служб

```bash
sudo iexctl services restart frontend
sudo iexctl services restart backend
sudo iexctl services restart all
```

* `frontend` перезапускает только Frontend.
* `backend` перезапускает PHP-FPM и фоновые процессы Backend, затем выполняет проверочный запуск планировщика.
* `all` перезапускает Frontend и Backend, затем выполняет проверочный запуск планировщика.

После перезапуска `iexctl` самостоятельно проверяет готовность затронутых служб. Эти команды не перезапускают PostgreSQL, Redis или Nginx.

### Просмотр журналов

Для повседневной диагностики обычно достаточно журналов Frontend или Backend:

```bash
sudo iexctl services logs frontend --lines 200
sudo iexctl services logs backend --since '30 minutes ago'
```

Также доступны журналы:

* `horizon`;
* `reverb`;
* `pulse`;
* `scheduler`;
* `backup`;
* `update-agent`;
* `all`.

Параметр `--lines` принимает от 1 до 10 000 строк. Параметр `--since` задаёт начало периода в формате `journalctl`. Просмотр журналов поддерживает только текстовый вывод.

{% hint style="warning" %}
Пустой вывод не подтверждает отсутствие записей. Если строки не показаны, возьмите имя нужной службы из `sudo iexctl services status` и прочитайте журнал напрямую:

```bash
sudo journalctl --unit=UNIT_NAME --no-pager --lines=200
```

{% endhint %}

## Резервные копии

Команды `iexctl backup` работают только на сервере, где включено управляемое резервное копирование. Они позволяют проверить расписание и свежесть копий, запустить внеплановое копирование, проверить хранилище и убедиться, что последний снимок можно безопасно извлечь.

{% stepper %}
{% step %}

### Проверка состояния

```bash
sudo iexctl backup status
```

Команда показывает:

* состояние службы резервного копирования;
* состояние расписания;
* последний резервный снимок;
* время следующего запуска;
* результат последней проверки восстановления.

Снимок старше 36 часов считается устаревшим. Проверка восстановления старше 31 дня больше не считается свежим подтверждением восстановления.

Если хранилище копий находится на той же файловой системе, что и приложение, команда покажет предупреждение: такая копия не защищает от отказа накопителя.
{% endstep %}

{% step %}

### Ручной запуск

```bash
sudo iexctl backup run
```

Команда запускает тот же защищённый процесс, который используется расписанием. Успешным считается только запуск, после которого создан новый управляемый снимок и итоговая проверка пройдена.

Если расписание было выключено, команда приводит его в рабочее состояние.
{% endstep %}

{% step %}

### Просмотр снимков

```bash
sudo iexctl backup snapshots
sudo iexctl backup snapshots --limit 50
```

Без параметра `--limit` выводятся последние 20 снимков. Допустимое значение — от 1 до 1 000.
{% endstep %}

{% step %}

### Проверка целостности

Обычная проверка контролирует структуру хранилища и доступные данные:

```bash
sudo iexctl backup verify
```

Полная проверка читает все данные в хранилище:

```bash
sudo iexctl backup verify --full --timeout 12h
```

{% hint style="warning" %}
Полная проверка может выполняться долго и создавать заметную нагрузку на диск. Запускайте её в период низкой нагрузки и задавайте достаточное время ожидания.
{% endhint %}
{% endstep %}

{% step %}

### Проверка восстановления

```bash
sudo iexctl backup restore-test
```

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

{% hint style="info" %}
`restore-test` подтверждает, что содержимое снимка можно извлечь и проверить. Команда не восстанавливает данные в рабочую систему.
{% endhint %}
{% endstep %}
{% endstepper %}

***

## Параметры Backend и Frontend

Группа `iexctl env` предназначена для безопасной работы с параметрами Backend и Frontend.

Backend использует файл:

```
/etc/iexexchanger/backend.env
```

Frontend использует файл:

```
/etc/iexexchanger/frontend.env
```

Изменения записываются атомарно. Перед записью создаётся закрытая резервная копия текущего файла.

В командах ниже заменяйте `KEY_NAME`, `VALUE` и `RECEIPT_ID` своими значениями.

### Просмотр параметров

Показать имена параметров Backend:

```bash
sudo iexctl env list backend
```

Показать имена параметров Frontend:

```bash
sudo iexctl env list frontend
```

Показать несекретные значения:

```bash
sudo iexctl env list backend --show-values
sudo iexctl env list frontend --show-values
```

Получить один параметр:

```bash
sudo iexctl env get backend KEY_NAME
sudo iexctl env get frontend KEY_NAME
```

Значения паролей, токенов, ключей и других секретных параметров всегда скрываются, включая вывод с `--show-values`.

### Изменение параметра

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

* `--value`;
* `--stdin`;
* `--value-file`.

Параметр `--restart` сразу перезапускает соответствующую группу служб и проверяет её готовность.

#### Несекретное значение

```bash
sudo iexctl env set frontend KEY_NAME --value 'VALUE' --restart
```

`--value` подходит только для несекретного однострочного значения.

#### Секретное значение

```bash
sudo iexctl env set backend KEY_NAME --stdin --restart
```

Введите значение и завершите ввод сочетанием `Ctrl+D`. Значение не попадёт в историю командной оболочки.

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

```bash
sudo iexctl env set backend KEY_NAME --value-file /root/iex-value --restart
```

Секретное значение нельзя передавать через `--value`.

{% hint style="warning" %}
Без `--restart` новое значение будет сохранено в файле, но работающие процессы продолжат использовать прежнюю конфигурацию до следующего перезапуска.
{% endhint %}

### Удаление параметра

Удалить параметр Backend:

```bash
sudo iexctl env unset backend KEY_NAME --restart
```

Удалить параметр Frontend:

```bash
sudo iexctl env unset frontend KEY_NAME --restart
```

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

### История изменений

```bash
sudo iexctl env history backend
sudo iexctl env history frontend
```

Ограничить количество записей:

```bash
sudo iexctl env history backend --limit 20
```

История показывает идентификатор операции, время, действие, имя параметра и состояние записи, но не раскрывает значения.

### Восстановление из истории

Восстановление выполняется в два этапа.

#### Подготовка плана

Сначала откройте историю и выберите нужный идентификатор:

```bash
sudo iexctl env history backend
```

Затем сформируйте план:

```bash
sudo iexctl env restore-plan backend RECEIPT_ID
```

Для Frontend используйте:

```bash
sudo iexctl env restore-plan frontend RECEIPT_ID
```

Команда сравнивает сохранённое состояние с текущим файлом и выводит готовую команду подтверждения. Используйте только свежий план.

#### Применение плана

Скопируйте команду, которую вывел `restore-plan`, и выполните её без изменения идентификатора и контрольной суммы.

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

```bash
--restart
```

{% hint style="danger" %}
Восстановление заменяет весь выбранный файл параметров сохранённым состоянием, а не только один ключ. Если файл изменился после подготовки плана, `iexctl` остановит операцию и потребует сформировать новый план.
{% endhint %}

## Контроль ресурсов сервера

Команды `iexctl resources` сохраняют замеры дисков, размера баз данных, доступной памяти и нагрузки, а затем рассчитывают тенденцию заполнения.

Обычные замеры собираются автоматически. Ручной запуск нужен для внеплановой проверки.

### Сохранение замера

```bash
sudo iexctl resources sample
```

Команда собирает текущее состояние и добавляет его в локальную историю.

### Просмотр истории

```bash
sudo iexctl resources history
```

Показать больше записей:

```bash
sudo iexctl resources history --limit 72
```

Без параметра `--limit` выводятся последние 24 замера. Допустимое значение — от 1 до 2 160.

### Прогноз заполнения

```bash
sudo iexctl resources forecast
```

Для расчёта требуется не менее трёх замеров за период не короче шести часов.

Возможные состояния:

* `insufficient_history` — данных для прогноза пока недостаточно;
* `stable` — ближайший риск заполнения не обнаружен;
* `warning` — безопасный порог может быть достигнут не позднее чем через 30 дней;
* `critical` — безопасный порог может быть достигнут не позднее чем через 7 дней.

После состояния команда показывает причину и рекомендуемое действие.

## Архив для технической поддержки

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

### Создание архива

```bash
sudo iexctl support bundle
```

После завершения команда показывает:

* путь к архиву;
* контрольную сумму SHA-256;
* путь к файлу контрольной суммы;
* размер архива;
* количество диагностических файлов.

Архив не содержит файлы параметров, секреты, учётные данные, дампы и строки баз данных или необработанные журналы служб.

{% hint style="warning" %}
Диагностический архив всё равно содержит технические сведения о сервере. Передавайте архив и файл контрольной суммы только через защищённый канал и только уполномоченному специалисту.
{% endhint %}

## Проверка после обслуживания

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

### Проверка служб

```bash
sudo iexctl services verify
```

### Полная диагностика

```bash
sudo iexctl doctor
```

### Проверка резервных копий

```bash
sudo iexctl backup status
```

Команду `backup status` выполняйте только на сервере с включённым управляемым резервным копированием.

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.iexexchanger.com/server-i-dannye/upravlenie-cherez-iexctl.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.