Справочник CLI

Помимо install и uninstall (см. Установка Vision), бинарный файл vision оборачивает остальную повседневную работу: запуск и остановку сервиса, проверку его состояния, резервное копирование и восстановление данных, просмотр конфигурации. Каждая команда — тонкая и честная обёртка: большинство выводят нижележащую команду systemctl или journalctl, которую они выполняют (в stderr, чтобы stdout при передаче по конвейеру оставался чистым), а эти исходные команды по-прежнему полностью поддерживаются, если вы предпочитаете использовать их напрямую.

Выполните vision help, чтобы увидеть полный список, или vision help <command> — подробности об одной команде.

Сервис

Команда	Что делает
`vision start [--force]`	Проверяет конфигурацию, затем `systemctl start vision`.
`vision stop`	`systemctl stop vision`.
`vision restart [--force]`	Проверяет конфигурацию, затем `systemctl restart vision`.
`vision enable [--now]`	`systemctl enable [--now] vision` — запуск при загрузке системы.
`vision disable [--now]`	`systemctl disable [--now] vision`.
`vision logs [-f] [-n N] [--since W] [--until W] [-o FMT]`	`journalctl -u vision --no-pager` с вашими флагами. `-f` следит за выводом.

vision logs никогда не требует root: чтение журнала доступно участникам группы systemd-journal (или adm). Если записей нет, добавьте своего пользователя в эту группу или запустите команду через sudo.

Диагностика

Команда	Что показывает
`vision status [--json] [--verbose]`	Состояние unit, те же проверки, что выполняет `/readyz`, пути и размеры конфигурации и данных, а также два предупреждения о расхождении: бинарный файл, заменённый без перезапуска, и принадлежащие root вспомогательные файлы WAL, в которые сервис не может писать. Строка License показывает публичный ID файла лицензии или not activated (текущее состояние и срок действия — в Settings → License).
`vision doctor [--json] [--config PATH] [--db PATH]`	Автономная проверка для машины, на которой сервис не запускается: проверка конфигурации, проверки схемы/окружения/связки ключей, структура unit systemd, проверка целостности базы данных и версии схемы, владельцы файлов, свободное место на диске, действующий набор включённых worker, параметры безопасности reconcile-sweep, файл лицензии (существует, владелец `vision`, режим `0600`, разрешён unit) и отвечают ли серверы лицензий (только предупреждение — см. Лицензирование). Для каждой находки указано, как её исправить.
`vision version`	Выводит версию бинарного файла и время сборки.

И status, и doctor работают без root — проверки, требующие root, показываются как пропущенные, а не как сбойные. status никогда не завершается с кодом 0, пока сервис остановлен, поэтому его безопасно использовать в скриптах мониторинга:

Код завершения	Значение
`0`	ok
`4`	не установлен
`5`	unit не активен
`6`	активен, но не готов

На свежей установке status сообщает Not ready: no Alta server yet с адресом Settings → Connections — добавьте сервер, и статус станет «готов».

Данные

Команда	Что делает
`vision backup [--output PATH\|-] [--no-secrets] [--no-maps] [--force] [--recover-wal] [--db PATH] [--config PATH]`	Согласованная горячая резервная копия — без простоя. См. Резервное копирование и восстановление.
`vision restore <archive> [--dry-run] [--stop-service] [--yes] [--force-key-mismatch]`	Проверяемое, защищённое восстановление. `--yes` принимает запрос, специфичный для хоста, в скриптах. См. Резервное копирование и восстановление.
`vision reset-password <email> [--url BASE] [--config PATH] [--db PATH]`	Создаёт одноразовую ссылку для сброса пароля для администратора, потерявшего доступ. См. Восстановление забытого пароля.

Конфигурация

Команда	Что делает
`vision config validate [--config PATH] [--env-file PATH]`	Проверяет установленную конфигурацию точно так же, как при загрузке, — то же слияние `config.yaml` и файла окружения systemd.
`vision config print [--format text\|json]`	Выводит действующую, объединённую конфигурацию со скрытыми секретами — её безопасно вставлять в обращение в поддержку.
`vision config print --reference`	Выводит полную аннотированную эталонную конфигурацию (каждый ключ, его значение по умолчанию и описание) — установленная конфигурация не нужна.

Ни одна из подкоманд config не требует root.

Настройка

Команда	Что делает
`vision install [--no-restart]`	Устанавливает или обновляет сервис, не заменяя конфигурацию и секреты. Изменённый бинарный файл перезапускает активный сервис, если не задан `--no-restart`.
`vision uninstall`	Удаляет сервис, но сохраняет конфигурацию и данные.
`vision uninstall --purge [--yes] [--no-backup]`	Дополнительно удаляет конфигурацию, данные, системного пользователя и бинарный файл. Создаёт финальную резервную копию и требует подтверждения `purge <hostname>`; `--yes` — для скриптов. Избегайте `--no-backup`, если данные не являются одноразовыми.

Коды завершения

Код	Значение
`0`	успех
`1`	попытка выполнена, но завершилась неудачей
`2`	ошибка использования
`3`	не выполнено предусловие — не Linux, нет `systemctl` или нужен root
`4`	не установлен (не найдены unit, конфигурация или база данных)
`5` / `6`	только `status` — см. таблицу выше

Политика root

Изменяющие команды (start, stop, restart, enable, disable, install, uninstall, restore) сами проверяют наличие root и отказываются с кодом 3, а не позволяют systemctl перейти к запросу polkit — который завис бы навсегда без терминала (cron, CI, конвейер).
Команды только для чтения (status, logs, config, doctor) никогда не требуют root; вместо этого отдельные строки или проверки помечаются как недоступные.

Изменение уровня логирования

Уровень логирования фиксируется при загрузке — намеренно нет переключателя во время работы. Задайте его в файле окружения и перезапустите:

echo 'VISION_LOG_LEVEL=debug' | sudo tee -a /etc/vision/vision.env
sudo vision restart

Не забудьте потом убрать его — debug очень многословен.

Размер журнала

Журналы сервиса — структурированный JSON в stdout, который попадает в journald; ротация журналов — задача journald, а не Vision. Если vision logs показывает, что журнал съедает место на диске, ограничьте его в /etc/systemd/journald.conf:

[Journal]
SystemMaxUse=1G

затем выполните sudo systemctl restart systemd-journald.

Обновление

Запустите установщик заново с новым бинарным файлом — он идемпотентен (конфигурация и секреты никогда не перезаписываются) и перезапускает сервис, как только бинарный файл действительно изменился:

curl -fsSL https://vision.cesbo.com/install.sh | sh

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

sudo /path/to/new/vision install --no-restart
sudo vision restart

vision install также перезапускает сервис, всё ещё работающий со старой копией бинарного файла — однострочная команда сначала помещает новый бинарный файл на место. vision status предупреждает, если запущенный процесс старше бинарного файла на диске.

Обратный прокси / TLS

В бинарном файле намеренно нет TLS-слушателя — в продакшене TLS завершается на обратном прокси перед ним. Минимальный сайт nginx:

server {
    listen 443 ssl;
    server_name vms.example.com;
    ssl_certificate     /etc/letsencrypt/live/vms.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/vms.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:3303;
        proxy_set_header Host              $host;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # SSE (alerts/status feeds) and long-lived requests:
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        proxy_buffering off;
        proxy_read_timeout 3600s;
    }
}

или Caddy, который обрабатывает сертификаты автоматически:

vms.example.com {
    reverse_proxy 127.0.0.1:3303 {
        flush_interval -1
    }
}

Затем в /etc/vision/config.yaml добавьте публичный origin в http.allowed_origins, задайте http.secure_cookies: true и выполните sudo vision restart. Если вы также задаёте http.internal_addr для отдельного слушателя метрик/проверки состояния, не направляйте собственную проверку состояния прокси на /readyz публичного слушателя — см. примечание, которое выводит vision status.