Состояние системы¶

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

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

1. Что значит «Студия здорова»¶

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

Минимум:

вход
+
новый чат
+
ответ модели
+
история
+
файлы
+
RAG
+
поиск, если включён
+
сервисы, если включены

2. Уровни проверки¶

Уровень 1. Контейнер жив¶

docker compose ps

Уровень 2. Проверка готовности успешна¶

Контейнер отвечает на свой healthcheck.

Уровень 3. Компоненты связаны¶

Например, основной сервер видит MongoDB и Redis.

Уровень 4. Реальный пользовательский сценарий работает¶

Например, модель действительно генерирует ответ.

Только уровень 4 подтверждает полезную работоспособность.

3. Штатная проверка¶

В текущем продуктовом семействе используется команда вида:

./nicesoft.sh health

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

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

4. Основные компоненты¶

В 0.3.66 compose содержит 19 основных служб и 2 optional GPU runtime. В системную проверку дополнительно к прежнему набору входят backup-manager и updater.

Основные службы:

proxy, api, admin-panel, mongodb, meilisearch, vectordb, rag-api, redis,
node-exporter, prometheus, certificates, backup-manager, updater,
system-monitor, web-search, web-scraper, model-manager,
yc-billing-mcp, yandex-gateway

Optional GPU:

model-runtime
model-runtime-test

Docker socket

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

В зависимости от профиля установки встречаются:

Компонент	Назначение
proxy	TLS и маршрутизация
api	чаты и серверная логика
admin-panel	администрирование
mongodb	пользователи, чаты и состояние
meilisearch	поиск по истории
vectordb	векторное хранилище
rag-api	поиск по документам
redis	кэш и состояние потоков
node-exporter	системные метрики хоста
prometheus	история и сбор внутренних метрик
certificates	сертификаты, домен и Let's Encrypt
backup-manager	`.nsbackup`, verify и restore
updater	доверенная проверка и staging обновлений
system-monitor	агрегированное состояние системы
web-search	интернет-поиск
web-scraper	безопасное получение страниц
model-manager	модели и мастер первого запуска
yandex-gateway	Яндекс Облако и Yandex AI
yc-billing-mcp	FinOps
`model-runtime`	основная локальная модель
`model-runtime-test`	Bootstrap/диагностика

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

5. Быстрый порядок диагностики¶

Если пользователь говорит «ничего не работает»:

откройте главную страницу;
проверьте вход;
выполните health;
выполните docker compose ps;
найдите unhealthy/restarting;
откройте журнал именно этого сервиса;
выполните один контрольный сценарий.

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

6. Главная страница не открывается¶

Проверяйте:

proxy;
порт;
сертификат;
DNS;
межсетевой экран;
состояние api;
свободный диск.

Команды:

docker compose ps

docker compose logs --tail=200 proxy

7. Страница открывается, вход не работает¶

Проверяйте:

api;
MongoDB;
выбранный способ входа;
состояние пользователя;
cookie/session настройки;
корпоративный вход, если он включён.

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

8. Вход работает, чат не отвечает¶

Проверяйте:

активный модельный маршрут;
model-manager;
локальную среду модели или Yandex AI;
доступность Redis;
ошибки api.

Создайте новый разговор для теста.

9. Чат работает, файлы нет¶

Проверяйте:

файловое хранилище;
права каталога;
лимит размера;
rag-api;
vectordb;
парсер.

Сначала загрузите маленький TXT, затем переходите к PDF/DOCX.

10. Файлы работают, поиск по ним нет¶

Проверяйте:

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

11. Интернет-поиск не работает¶

Проверяйте отдельно:

право пользователя
→ подтверждение
→ SearXNG
→ web-scraper
→ DNS/Интернет

Не перезапускайте модель только из-за ошибки загрузки страницы.

12. Яндекс Облако не работает¶

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

./nicesoft.sh yc-doctor

Если общая система здорова, локализуйте проблему в:

ключе;
IAM;
рабочем каталоге;
роли конкретного сервиса;
Billing;
AI Studio.

13. Проверка диска¶

df -h

Особенно важны разделы, где хранятся:

контейнерные данные;
модели;
MongoDB;
PostgreSQL;
файлы пользователей;
резервные копии;
журналы.

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

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

free -h

При недостатке RAM проверьте:

OOM killer;
рестарты контейнеров;
большие документы;
слишком много параллельных процессов;
кэш.

15. Проверка GPU¶

nvidia-smi

Смотрите:

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

Если nvidia-smi не работает на хосте, модельный контейнер не является первым местом диагностики.

16. Перезапускающийся контейнер¶

Сначала сохраните журнал:

docker compose logs --tail=300 <service>

Потом посмотрите состояние:

docker inspect <container>

И только после понимания причины перезапускайте.

17. После перезапуска¶

Проверьте не только Up.

Выполните:

вход;
чат;
файл;
один RAG-запрос;
один внешний сервис, если используется;
фактическую активную модель.

18. Матрица симптомов¶

Симптом	С чего начать
502/504	proxy → api
Вход не работает	api → MongoDB → auth
Чат висит	model-manager → модель → Redis
История не ищется	Meilisearch
Файл не индексируется	rag-api → vectordb
Поиск в Интернете пуст	web-search → сеть
Ссылка найдена, страница не читается	web-scraper
YC 403	yc-doctor → IAM
Yandex AI 403	AI Studio Folder → роль
FinOps пуст	область Billing → кэш

19. Базовый контрольный сценарий¶

После исправления выполните один стандартный набор:

1. Вход USER
2. Новый чат
3. Короткий ответ
4. Загрузка rag-test.txt
5. Поиск уникального маркера
6. Интернет-поиск, если включён
7. Новый чат после проверки

Так вы не получите ситуацию «контейнер починили, а пользовательский путь всё ещё сломан».

20. Когда состояние считать аварийным¶

Авария, если:

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

Что дальше¶

При найденной ошибке переходите к журналам и диагностике.