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

Обновление Студии

Статус механизма обновления в 0.3.66

В текущем релизе есть nicesoft-ai-studio-updater и вкладка «Параметры → Обновление». Это уже доверенный consumer подписанных обновлений, но пока только до стадии проверки и подготовки.

Updater проверяет:

  • channel descriptor и manifest.json;
  • Ed25519-подпись final-релиза;
  • совместимость версии и архитектуры;
  • фиксированный registry registry.ncsgp.ru/nicesoft-ai-studio;
  • наличие immutable sha256 digest у всех runtime images;
  • запрет сборки на сервере клиента;
  • свободное место;
  • Docker Engine;
  • доступность backup-manager;
  • обязательную резервную копию и verify, когда это требует manifest.

Действие «Скачать и подготовить» скачивает и проверяет runtime bundle и выполняет pull готовых образов по digest. Состояние длительной подготовки сохраняется на диске.

Не называть это автоматической установкой

В 0.3.66 отсутствуют install/switch/rollback endpoints. Updater не выполняет start/stop/remove контейнеров. Автоматическое атомарное переключение и rollback — следующий слой продукта.

updater — единственная основная служба 0.3.66, которой передаётся Docker socket; её разрешённые операции в этом выпуске ограничены чтением состояния и pull образов.

Контур выпуска 0.3.65+

Разработчик формирует draft:

./nicesoft.sh update-release

После публикации образов финализирует release:

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

Final-релиз должен быть подписан и использовать только repository@sha256:.... Runtime bundle не содержит Dockerfile, .env экземпляра, секреты, backup archives или model weights.

Что вы сделаете

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

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

1. Главное правило обновления

Обновление ИИ Студии — это переход с одного зафиксированного выпуска на другой.

Неправильно:

docker compose pull latest

Правильно:

текущая версия
    ↓
резервная копия
    ↓
проверенный новый выпуск
    ↓
контрольные суммы
    ↓
предварительные проверки
    ↓
обновление
    ↓
проверки после запуска
    ↓
приёмка или откат

2. Почему нельзя использовать latest

Плавающий тег не фиксирует конкретное состояние продукта.

Сегодня и завтра под одним именем могут оказаться разные образы.

Это ломает:

  • воспроизводимость;
  • расследование ошибок;
  • откат;
  • контроль состава;
  • паспорт версии.

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

3. Что является выпуском ИИ Студии

Выпуск — это не только версия основного веб-приложения.

Он включает согласованный набор:

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

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

4. Принцип обновления базовой платформы

Один из ключевых архитектурных принципов ИИ Студии:

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

Используются:

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

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

5. Как обновляется базовая платформа при разработке нового релиза

Это процесс команды продукта, а не действие администратора заказчика на рабочем сервере.

новый официальный выпуск базовой платформы
        ↓
сравнение изменений
        ↓
анализ несовместимостей
        ↓
проверка конфигурации и схем данных
        ↓
пересборка локализованного слоя
        ↓
применение собственных слоёв НайсСофт
        ↓
автоматические тесты
        ↓
приёмочные испытания
        ↓
новый выпуск ИИ Студии

На рабочем сервере клиента не следует делать прямой git merge базовой платформы.

6. Что нужно получить перед обновлением

Для нового выпуска должны быть доступны как минимум:

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

7. Паспорт версии

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

Минимум:

текущая версия Студии
дата установки
контрольная сумма релизного архива
версии контейнерных образов
активная модель
версия каталога моделей
состояние Яндекс Облака
состояние Yandex AI

Для выпущенных версий NiceSoft полезно хранить отдельный паспорт релиза.

8. Окно изменений

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

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

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

Не начинайте рискованное обновление в случайный момент рабочего дня.

9. Сначала состояние, потом обновление

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

Выполните штатную проверку, например:

./nicesoft.sh health

и:

docker compose ps

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

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

10. Обязательная резервная копия

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

См. Резервное копирование.

Не продолжайте, если:

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

11. Свободное место

Обновление может временно требовать место одновременно для:

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

Проверьте:

df -h

Не начинайте обновление на почти заполненном разделе.

12. Память и ресурсы

Проверьте:

  • RAM;
  • свободную VRAM, если меняется модельный контур;
  • свободный диск;
  • состояние контейнерной среды;
  • доступность реестра образов, если требуется сеть.

13. Контрольная сумма нового релиза

До распаковки или установки сверяйте опубликованную SHA-256 с фактической.

Пример:

sha256sum nicesoft-ai-studio-<версия>.tar.gz

Если сумма не совпала, не продолжайте установку.

14. Не подменяйте архив выпуска случайным каталогом

Рабочий сервер должен обновляться из известного комплекта.

Не следует собирать выпуск из:

  • файлов из разных веток;
  • старого compose.yml и новых образов;
  • новой конфигурации со старым model-manager;
  • случайно скачанных файлов из нескольких версий.

15. Сохраните локальные данные отдельно от кода релиза

Корректная архитектура развёртывания должна разделять:

релизные файлы
        ≠
пользовательские данные
        ≠
секреты
        ≠
модельные веса
        ≠
резервные копии

Тогда замена релизного набора не удаляет рабочие данные.

16. Никогда не используйте down -v как часть обычного обновления

Команда:

docker compose down -v

может удалить постоянные тома.

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

17. Предварительная проверка конфигурации

До запуска нового стека проверьте синтаксис Compose:

docker compose config

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

18. Проверьте обязательные переменные

Сверьте примечания к релизу.

Новая версия может добавить:

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

Не копируйте новый .env.example поверх рабочего .env.

Сначала сравните различия.

19. Секреты не должны регенерироваться при обычном обновлении

Если обновление случайно создаст новые:

  • пароли баз;
  • ключи сеанса;
  • внутренние токены;
  • ключи шлюзов;

часть системы может потерять доступ к уже существующим данным или завершить все пользовательские сеансы.

Генерация нового секрета должна быть отдельной осознанной операцией ротации.

20. Миграции базы данных

Миграция — один из главных рисков отката.

Перед применением выясните:

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

21. Почему нельзя «просто вернуть старый контейнер» после миграции

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

Тогда настоящий откат выглядит так:

остановить новую версию
        ↓
восстановить данные из предобновительной копии
        ↓
вернуть старый релиз
        ↓
запустить
        ↓
проверить

Это нужно знать до обновления.

22. Обновление контейнерных образов

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

Не обновляйте вручную до «самой новой» версии отдельные компоненты:

  • MongoDB;
  • PostgreSQL/pgvector;
  • Redis;
  • NGINX;
  • SearXNG;
  • модельную среду;
  • RAG API.

Совместимость проверяется как набор.

23. Не скачивайте модель повторно без необходимости

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

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

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

24. Если модельный каталог изменился

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

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

Новая рекомендация не означает, что рабочую модель нужно немедленно менять без тестирования.

25. Первый запуск после обновления

Сначала следите за состоянием сервисов.

docker compose ps

При необходимости:

docker compose logs --tail=200 <сервис>

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

Дайте системе пройти предусмотренную инициализацию.

26. Штатная проверка после обновления

Выполните команду текущего выпуска, например:

./nicesoft.sh health

Не ограничивайтесь зелёными контейнерами.

Нужны пользовательские тесты.

27. Минимальный приёмочный тест после обновления

Вход

  • ADMIN входит;
  • обычный USER входит;
  • USER не получает административную панель.

Чат

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

Модель

  • отображается правильная активная модель;
  • нет неожиданного переключения провайдера;
  • локальная модель действительно локальная.

Файлы

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

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

  • поиск возвращает источники;
  • извлечение страницы работает;
  • локальные/служебные адреса остаются заблокированы.

Помощники

  • существующий помощник открывается;
  • права Viewer/Editor/Owner сохранились.

Проекты

  • старые проекты отображаются;
  • разговоры не потеряли привязку.

28. Обязательные отрицательные тесты безопасности

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

Тест 1. Выполнение произвольного кода

Должно оставаться запрещённым текущей продуктовой политикой.

Тест 2. Создание произвольного внешнего сервиса пользователем

Обычный USER не должен получать такую возможность.

Тест 3. Изменение ресурса Яндекс Облака

Утверждённый системный контур Яндекс Облака остаётся только на чтение.

Тест 4. USER → административная панель

Доступ должен быть отклонён, если отдельное системное полномочие не выдано.

Тест 5. Изоляция пользователей

Пользователь А не должен видеть частные данные пользователя Б.

Эти тесты критичнее красивого экрана с номером новой версии.

29. Проверка Яндекс Облака после обновления

Выполните диагностику текущего релиза.

Например:

./nicesoft.sh yc-doctor

Проверьте:

  • чтение авторизованного ключа;
  • получение IAM-токена;
  • рабочий Folder;
  • Cloud;
  • доступ к разрешённым сервисам;
  • отсутствие изменяющих операций.

30. Проверка Yandex AI

Если он используется:

  1. проверьте AI Studio Folder;
  2. проверьте роль ai.languageModels.user;
  3. выполните проверку доступа;
  4. создайте новый тестовый чат;
  5. убедитесь, что ответ помечается фактической облачной моделью;
  6. убедитесь, что локальная модель не переключается туда скрыто.

31. Проверка FinOps

Если используется Billing:

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

32. Проверка административной панели

Проверьте:

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

Особенно важно убедиться, что объединение нескольких ролей не изменилось неожиданно.

33. Проверка общего доступа

Если организация использует общие ссылки и общие помощники:

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

34. Проверка плановых заданий

Если они используются:

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

35. Проверка памяти

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

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

36. Критерий успешного обновления

Обновление нельзя считать завершённым только потому, что:

все контейнеры Up

Завершение означает:

система здорова
+
данные на месте
+
права на месте
+
основные функции работают
+
запреты безопасности сохранились
+
резервная копия существует

37. Когда останавливать обновление

Не продолжайте раскатку, если обнаружено:

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

38. Критерии отката определяются заранее

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

Например:

не проходит вход
или
не проходит контрольный RAG-тест
или
нарушено разграничение USER/ADMIN
или
миграция завершилась ошибкой

Иначе команда может долго пытаться «чинить на месте» уже неприемлемое состояние.

39. Откат без миграции

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

  1. остановить новый релиз;
  2. вернуть старый набор файлов/образов;
  3. запустить;
  4. пройти проверки.

Но всё равно следуйте инструкции конкретной версии.

40. Откат после необратимой миграции

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

Порядок обычно:

остановить новую систему
        ↓
сохранить её аварийное состояние отдельно
        ↓
восстановить предобновительную копию
        ↓
вернуть старый релиз
        ↓
запустить
        ↓
пройти приёмочные тесты

Не уничтожайте состояние неудачной новой версии до завершения расследования.

41. Не смешивайте откат и исправление

Есть два разных пути:

Откат

Вернуться в известное рабочее состояние.

Исправление новой версии

Остаться на новой версии и применить отдельное проверенное исправление.

Решение должно приниматься осознанно.

42. Обновление на нескольких узлах

Если Студия развёрнута не на одном сервере, используйте поэтапную стратегию.

Возможный порядок:

  1. испытательная среда;
  2. один контрольный узел;
  3. проверка;
  4. остальные узлы;
  5. финальная проверка.

Не обновляйте сразу весь парк, если можно сократить область возможного отказа.

43. Испытательная среда

Хороший процесс сначала повторяет обновление вне рабочей среды.

Испытательный стенд должен быть достаточно похож по:

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

Иначе тест на пустой системе мало что докажет.

44. Копия рабочих данных для испытаний

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

Лучше использовать:

  • обезличенную копию;
  • синтетический тестовый набор;
  • специально созданные контрольные файлы.

Не переносите производственные секреты на менее защищённый тестовый сервер без необходимости.

45. Обновление локализации и интерфейсных слоёв

После нового релиза проверьте:

  • русские подписи;
  • фирменное название;
  • вкладки НайсСофт;
  • Центр управления моделями;
  • «Параметры»;
  • интеграцию с Яндекс Облаком;
  • административную панель.

Не должно внезапно появляться внутреннее или чужое брендинг-оформление в основных пользовательских маршрутах.

46. Проверка собственных слоёв после обновления базовой платформы

Команда разработки должна отдельно проверить:

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

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

47. Не переносите старый патч вслепую

Даже если патч применился без конфликта, это не означает корректное поведение.

Нужно проверить смысл изменения на новой версии.

Автоматическое применение текста — не функциональная приёмка.

48. Журнал изменений

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

Администратору нужны ответы:

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

49. Документация обновляется вместе с продуктом

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

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

50. Хранение предыдущего выпуска

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

Сохраните:

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

Срок хранения определяется политикой организации.

51. Очистка старых контейнерных образов

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

Старые образы могут потребоваться для отката.

Очистка проводится после:

  • завершения периода наблюдения;
  • подтверждения новой версии;
  • проверки резервной копии;
  • окончания окна быстрого отката.

52. Наблюдение после обновления

После формальной приёмки некоторое время наблюдайте:

  • ошибки API;
  • перезапуски контейнеров;
  • использование RAM;
  • VRAM;
  • диск;
  • задержку ответа модели;
  • RAG;
  • интернет-поиск;
  • ошибки Яндекс Облака;
  • необычные 401/403/429.

53. Что фиксировать в отчёте об обновлении

Минимум:

старая версия
новая версия
дата и время
ответственный
SHA-256 нового релиза
резервная копия перед обновлением
результат миграций
результат health
результат пользовательских тестов
результат отрицательных тестов безопасности
выявленные проблемы
решение: принято / откат

54. Пример краткой процедуры

1. Прочитать журнал изменений.
2. Проверить требования.
3. Выполнить health старой версии.
4. Создать резервную копию.
5. Проверить SHA-256 резерва.
6. Скопировать резерв с сервера.
7. Скачать новый релиз.
8. Проверить SHA-256 нового релиза.
9. Сравнить настройки.
10. Проверить docker compose config.
11. Выполнить миграции по инструкции релиза.
12. Запустить новый выпуск.
13. Выполнить health.
14. Проверить ADMIN и USER.
15. Проверить чат.
16. Проверить модель.
17. Проверить файл/RAG.
18. Проверить интернет-поиск.
19. Проверить Яндекс Облако.
20. Проверить отрицательные тесты безопасности.
21. Зафиксировать результат.
22. Создать резерв уже новой версии.

55. Частые ошибки

Обновлять один контейнер «потому что вышла новая версия»

Можно получить несовместимый набор.

Использовать latest

Теряется воспроизводимость.

Не делать резерв перед миграцией

Откат может стать невозможным.

Перегенерировать секреты

Можно потерять доступ к данным или сеансам.

Выполнить down -v

Можно удалить постоянные тома.

Проверить только главную страницу

Это не проверка рабочих функций.

Не выполнять отрицательные тесты

Система может выглядеть исправной, но потерять защитные ограничения.

Делать прямой merge базовой платформы в рабочую среду

Так теряется контролируемый релизный процесс НайсСофт.

56. Проверка результата

Обновление считается правильно организованным, если:

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

Что дальше

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