Перейти к содержанию

Команды администратора

Эта страница — краткий справочник по штатным командам НайсСофт — ИИ Студии 0.3.66.

Команды ниже выполняются на сервере из каталога установленной Студии. Они нужны владельцу сервера и не заменяют административный интерфейс в браузере.

Не копируйте команды из старой версии документации

Набор команд меняется вместе с продуктом. Этот справочник относится к 0.3.66. Перед выполнением действия на другой версии сначала проверьте ./nicesoft.sh без параметров и журнал изменений установленного выпуска.

Быстрый выбор команды

Задача Команда
Инициализировать параметры экземпляра и TLS ./nicesoft.sh init
Выполнить полный первый запуск ./nicesoft.sh install
Проверить сервер и конфигурацию ./nicesoft.sh check
Проверить статическую конфигурацию проекта ./nicesoft.sh validate
Показать состояние контейнеров ./nicesoft.sh status
Выполнить расширенную проверку работающей Студии ./nicesoft.sh health
Смотреть журналы ./nicesoft.sh logs [служба]
Перезапустить стек или службу ./nicesoft.sh restart [служба]
Запустить стек ./nicesoft.sh up
Остановить стек ./nicesoft.sh down
Создать резервную копию ./nicesoft.sh backup
Восстановить резервную копию ./nicesoft.sh restore <файл.nsbackup>
Сформировать локальный draft обновления ./nicesoft.sh update-release
Финализировать подписанный выпуск после публикации образов ./nicesoft.sh update-release-finalize
Проверить Яндекс Облако ./nicesoft.sh yc-check
Выполнить подробную диагностику Яндекс Облака ./nicesoft.sh yc-doctor
Проверить локальный интернет-поиск ./nicesoft.sh web-search-check
Проверить артефакты локальных моделей ./nicesoft.sh model-artifact-test
Проверить метаданные артефактов через сеть ./nicesoft.sh model-artifact-test --online-metadata
Показать внешнюю модель ./nicesoft.sh model-status
Повторно определить внешнюю модель ./nicesoft.sh model-check
Настроить внешний совместимый сервис модели ./nicesoft.sh model-setup
Проверить русскую локализацию ./nicesoft.sh localization-check
Скачать закреплённые образы и собрать слои НайсСофт ./nicesoft.sh build
То же действие, альтернативное имя ./nicesoft.sh pull
Пересоздать контейнеры из закреплённых образов ./nicesoft.sh rebuild
То же действие, альтернативное имя ./nicesoft.sh recreate

1. Общие правила

1.1. Работайте из каталога Студии

Пример:

cd /opt/nicesoft-ai-studio

Фактический путь зависит от способа установки образа.

Проверьте, что в каталоге присутствуют как минимум:

nicesoft.sh
compose.yml
VERSION
.env
config/
scripts/
data/

1.2. Не запускайте неизвестные команды от имени root

Перед копированием команды из переписки, старой инструкции или тикета поддержки:

  1. убедитесь, что команда относится к вашей версии;
  2. прочитайте её полностью;
  3. проверьте, не удаляет ли она тома Docker;
  4. проверьте, не выводит ли она секреты;
  5. только после этого выполняйте.

1.3. Не используйте docker compose down -v для обычной эксплуатации

Ключ -v удаляет постоянные тома.

Это может уничтожить рабочие данные баз и других компонентов.

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

./nicesoft.sh down

1.4. Не редактируйте состояние внутренних баз вручную

Не рекомендуется напрямую изменять:

  • MongoDB;
  • PostgreSQL/pgvector;
  • Redis;
  • базу состояния управления моделями;
  • базу интеграции с Яндекс Облаком;
  • внутренние таблицы прав;
  • состояние сертификатов.

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

2. Первый запуск

./nicesoft.sh init

Назначение:

  • создать или дополнить .env;
  • определить параметры экземпляра;
  • подготовить TLS;
  • на новой установке запросить IP-адрес или доменное имя;
  • не перегенерировать уже существующие секреты без необходимости.

Команда полезна при первичной подготовке экземпляра.

После неё обычно выполняется:

./nicesoft.sh install

Образ ВМ

Для готового образа Яндекс Облака значительная часть подготовки уже выполнена. Основной пользовательский сценарий описан в разделе «Установка в Яндекс Облаке».

./nicesoft.sh install

Полный первый запуск текущего выпуска.

Внутри последовательно выполняются:

  1. подготовка переменных окружения;
  2. предварительные проверки сервера;
  3. проверка конфигурации;
  4. получение закреплённых контейнерных образов и сборка собственных слоёв;
  5. миграция старого частного профиля, если она нужна;
  6. запуск контейнеров;
  7. применение управляемой конфигурации;
  8. принудительное сохранение продуктовой политики;
  9. перезапуск основной службы;
  10. итоговая проверка состояния.

После успешного запуска основной адрес имеет вид:

https://<адрес-сервера>:8143/

При первом запуске по IP браузер ожидаемо покажет предупреждение локального сертификата. Подробнее: «HTTPS, домен и сертификаты».

3. Адрес экземпляра

./nicesoft.sh instance-setup

Используйте, если нужно штатно задать:

  • IP-адрес экземпляра;
  • доменное имя;
  • локальный адрес привязки Docker;
  • производные адреса служб.

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

./nicesoft.sh instance-status
./nicesoft.sh health

./nicesoft.sh instance-status

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

Полезно при проверке:

  • основного URL;
  • адреса административного интерфейса;
  • внутренних производных URL;
  • результата после смены IP или DNS.

./nicesoft.sh instance-sync

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

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

Предпочтительный путь — instance-setup, потому что он уменьшает риск неполной конфигурации.

4. Проверка до запуска

./nicesoft.sh check

Команда объединяет:

предварительную проверку сервера
+
проверку конфигурации проекта

Её полезно выполнять:

  • перед первым запуском;
  • перед обновлением;
  • после изменения .env;
  • после изменения конфигурации;
  • после переноса экземпляра;
  • перед обращением в поддержку.

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

./nicesoft.sh validate

Выполняет статические проверки проекта без необходимости считать работающий стек исправным.

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

  • структуры конфигурации;
  • управляемых файлов;
  • продуктовых ограничений;
  • внутренних связей проекта.

validate и health отвечают на разные вопросы:

validate → правильно ли подготовлена конфигурация
health   → правильно ли работает запущенный экземпляр

5. Состояние работающей системы

./nicesoft.sh status

Показывает состояние контейнеров.

Это быстрый ответ на вопрос:

Какие службы сейчас запущены?

Пример назначения результата:

Up / healthy     → контейнер работает
Up / unhealthy   → контейнер запущен, но проверка состояния не проходит
Restarting       → цикл перезапуска
Exited           → контейнер остановлен

Одного status недостаточно для приёмки системы.

./nicesoft.sh health

Это основная расширенная проверка работающей Студии.

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

В текущем выпуске проверяются, в частности:

  • готовность основной диалоговой службы;
  • основной интерфейс;
  • административная панель;
  • локальный интернет-поиск;
  • безопасное получение веб-страниц;
  • шлюз Яндекс Облака;
  • финансовая служба;
  • Центр управления моделями;
  • Redis;
  • продуктовые политики;
  • отсутствие тестовых операций в рабочем контуре;
  • некоторые ограничения интерфейса и доступа.

После:

  • обновления;
  • восстановления;
  • изменения сертификата;
  • изменения модели;
  • изменения Яндекс Облака;

всегда выполняйте:

./nicesoft.sh health

Но даже успешный health не заменяет отрицательные проверки прав, описанные в руководстве администратора.

6. Журналы

./nicesoft.sh logs

Показывает последние 200 строк журналов и продолжает вывод новых сообщений.

Остановить просмотр:

Ctrl+C

Журнал конкретной службы

Формат:

./nicesoft.sh logs <служба>

Примеры:

./nicesoft.sh logs api
./nicesoft.sh logs proxy
./nicesoft.sh logs model-manager
./nicesoft.sh logs model-runtime
./nicesoft.sh logs model-runtime-test
./nicesoft.sh logs yandex-gateway
./nicesoft.sh logs web-search
./nicesoft.sh logs web-scraper

Точное имя службы сверяйте через:

./nicesoft.sh status

Не отправляйте журнал целиком без проверки

Перед передачей в поддержку удалите или замаскируйте:

  • пароли;
  • токены;
  • закрытые ключи;
  • пользовательские запросы, если они содержат конфиденциальную информацию;
  • содержимое документов;
  • внутренние адреса, если политика организации запрещает их раскрытие;
  • идентификаторы, которые ваша организация считает чувствительными.

7. Запуск, остановка и перезапуск

./nicesoft.sh up

Запускает стек в фоновом режиме.

После:

./nicesoft.sh health

./nicesoft.sh down

Корректно останавливает стек.

Не добавляйте -v без специально спланированного удаления постоянных данных.

./nicesoft.sh restart

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

Перезапуск отдельной службы

Пример:

./nicesoft.sh restart model-manager

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

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

8. Локальные модели

Обычное управление моделью

Для установки, выбора и удаления квалифицированной локальной модели предпочитайте Центр управления моделями в интерфейсе.

Он выполняет дополнительные проверки:

  • GPU;
  • видеопамяти;
  • вычислительной совместимости;
  • диска;
  • метаданных модели;
  • состояния установки;
  • блокировки параллельного развёртывания.

Не рекомендуется вручную скачивать произвольный каталог Hugging Face в data/models и считать такую модель поддерживаемой.

./nicesoft.sh model-artifact-test

Проверяет контракты всех устанавливаемых локальных артефактов без скачивания реальных весов.

Это полезно:

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

Команда не является реальным GPU-тестом качества модели.

./nicesoft.sh model-artifact-test --online-metadata

Дополнительно проверяет через сеть метаданные официальных репозиториев моделей.

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

Для изолированного контура этот вариант, естественно, требует временного сетевого доступа либо заранее подготовленной процедуры поставки.

9. Внешняя совместимая модель

Этот блок относится не к квалифицированным локальным моделям Студии, а к отдельному внешнему сервису с OpenAI-совместимым программным интерфейсом.

./nicesoft.sh model-setup

Настраивает такое подключение.

Используйте только для доверенного корпоративного сервиса.

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

./nicesoft.sh model-status

Показывает безопасную сводку подключения:

  • адрес;
  • базовый путь;
  • модель;

без вывода ключа доступа.

./nicesoft.sh model-check

Повторно определяет доступную модель и базовый URL внешнего совместимого сервиса.

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

10. Интернет-поиск

./nicesoft.sh web-search-check

Проверяет связку:

основная служба
    ↓
локальный поисковик
    ↓
служба безопасного получения страниц

Используйте, если:

  • поиск не запускается;
  • источники находятся, но страницы не читаются;
  • ответы не получают содержимое веб-страницы;
  • после изменения прокси или DNS появились ошибки.

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

11. Яндекс Облако

./nicesoft.sh yc-check

Быстрая проверка шлюза и опубликованных системных сервисов Яндекс Облака.

Альтернативное имя текущего выпуска:

./nicesoft.sh yandex-mcp-check

В пользовательской документации используется термин «сервисы Яндекс Облака», поэтому внутреннее историческое имя команды не означает, что пользователю нужно понимать внутренний протокол интеграции.

./nicesoft.sh yc-doctor

Основная пошаговая диагностика подключения.

Показывает, в частности:

  • присутствует ли авторизованный ключ;
  • может ли шлюз получить IAM-токен;
  • выбран ли рабочий Folder;
  • выбран ли Cloud;
  • принимает ли Яндекс учётные данные;
  • передаётся ли область доступа;
  • на каком этапе возникла ошибка.

Команда специально предназначена для диагностики без вывода закрытого ключа или IAM-токена.

Если вывод содержит:

IAM auth available: YES

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

Финансы

Для глубокой проверки финансового контура в поставке присутствует отдельный сценарий:

./scripts/yc-billing-doctor.sh <идентификатор-платёжного-аккаунта>

Используйте только идентификатор платёжного аккаунта, доступ к которому разрешён служебной учётной записи.

12. Русская локализация

./nicesoft.sh localization-check

Проверяет полноту русских наложений интерфейса.

Эта команда полезна преимущественно при подготовке выпуска или после обновления базовой платформы.

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

13. Миграция старого профиля

./nicesoft.sh migrate-private

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

Для новой чистой установки обычно отдельно запускать её не требуется: штатная install уже включает нужный этап.

Не запускайте миграцию многократно «для профилактики» без понимания её назначения.

14. Сборка и пересоздание контейнеров

./nicesoft.sh build

./nicesoft.sh pull

В текущем выпуске это два имени одного эксплуатационного действия:

  • получить закреплённые сторонние образы;
  • собрать локализованные и собственные слои НайсСофт.

Это не выпуск новой версии продукта.

Команда не должна сама менять:

  • VERSION;
  • README.md;
  • CHANGELOG.md.

./nicesoft.sh rebuild

./nicesoft.sh recreate

Пересоздаёт контейнеры текущего выпуска из закреплённых образов.

Это также не означает переход на новую версию.

После выполнения:

./nicesoft.sh health

15. Резервное копирование и восстановление

./nicesoft.sh backup

Создаёт зашифрованную резервную копию .nsbackup через внутренний backup-manager.

Основной состав:

  • MongoDB;
  • PostgreSQL/pgvector;
  • пользовательские файлы и изображения;
  • YC state и авторизованный ключ;
  • TLS/Let's Encrypt;
  • состояние моделей;
  • навыки и расширения;
  • deployment/configuration bundle для аварийного восстановления.

Веса моделей, Redis, Meilisearch, история Prometheus и журналы штатно не дублируются.

./nicesoft.sh restore <файл.nsbackup>

Аварийный локальный путь восстановления. В 0.3.66 эта команда существует. Она использует ту же службу и проверки, что и веб-панель.

Пример:

./nicesoft.sh restore /secure/backups/nicesoft-ai-studio-20260915.nsbackup

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

Подробнее: «Резервное копирование и восстановление».

16. Обновление

./nicesoft.sh update-release

Формирует локальный development draft формата обновлений v1. Команда предназначена прежде всего для сборочного/релизного контура и ничего не публикует автоматически.

Результат создаётся в release-output/updates/v1/ и содержит manifest, changelog, runtime bundle и план публикации.

Draft не является клиентским устанавливаемым выпуском.

./nicesoft.sh update-release-finalize

После публикации образов получает immutable registry digest, пересобирает runtime bundle, создаёт final manifest и подписывает manifest/channel внешним Ed25519-ключом.

Типичный вызов:

NICESOFT_RELEASE_CHANNEL=stable \\
NICESOFT_RELEASE_SIGNING_KEY=/secure/nicesoft-release-ed25519.pem \\
./nicesoft.sh update-release-finalize

Без корректного signing key финализация запрещена.

Что делает клиентский updater 0.3.66

Вкладка «Параметры → Обновление» умеет обнаружить, проверить и подготовить final-релиз, включая pull images по digest. Но она не выполняет install/switch/rollback и не должна описываться как «обновить всё одной кнопкой».

Не используйте docker pull ...:latest как замену release-процессу.

Подробнее: «Обновление».

17. Что не следует делать вручную

Без отдельной процедуры поддержки не рекомендуется:

  • менять файлы внутри работающего контейнера;
  • заменять базовую платформу произвольным новым образом;
  • устанавливать модель путём ручного копирования файлов в хранилище;
  • редактировать внутренние БД;
  • выдавать себе права прямой записью в MongoDB;
  • править состояние мастера моделей вручную;
  • копировать IAM-токен в браузер;
  • открывать наружу MongoDB, PostgreSQL, Redis, Prometheus или внутренние службы;
  • заменять TLS-файлы в обход службы сертификатов;
  • удалять тома Docker ради «чистой перезагрузки»;
  • менять версию контейнера отдельно от версии Студии.

18. Минимальный набор после любого серьёзного изменения

После изменения конфигурации, модели, сети, сертификата или версии выполните:

./nicesoft.sh status
./nicesoft.sh health

При изменениях Яндекс Облака дополнительно:

./nicesoft.sh yc-doctor

При изменениях интернет-поиска:

./nicesoft.sh web-search-check

После обновления продукта дополнительно выполните отрицательные проверки:

  • USER не получил ADMIN;
  • выполнение произвольного кода осталось запрещено;
  • пользователь не может создать произвольное внешнее подключение;
  • системные сервисы Яндекс Облака остаются только для чтения;
  • пользователь А не видит частные данные пользователя Б;
  • локальная модель не переключается в Yandex AI без явного действия администратора.

19. Как собрать данные для поддержки

Сначала зафиксируйте:

cat VERSION
./nicesoft.sh status
./nicesoft.sh health

Для соответствующей подсистемы добавьте:

./nicesoft.sh yc-doctor
./nicesoft.sh web-search-check

или журнал конкретной службы:

./nicesoft.sh logs <служба>

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

Раздел с единой процедурой сбора комплекта поддержки пока отложен и помечен как «в разработке».