Docs / Диагностика

Диагностика

С чего начать, когда что-то не работает: проверки состояния, расшифровка кодов ответа, типовые проблемы портала, секретов и WebSocket.

Первые проверки

curl -s localhost:9090/api/health    # процесс жив
curl -s localhost:9090/api/ready     # данные свежие
curl -s localhost:9091/api/portal/health

docker compose ps
docker compose logs -f --tail=200 docker-stat
docker logs docker-api --tail=100

401, 403 и 502

401 Unauthorized

Истёк или отсутствует токен. UI обновляет access по refresh автоматически; если не получается — войдите заново. Прямые запросы к API требуют Authorization: Bearer.

502 contour_unauthorized

Портал авторизован, но контур не принял сохранённый токен. Откройте /#/dashboard, дважды кликните по ноде сервера и введите ключ заново (Connect сохраняет и проверяет его). Это не истечение сессии портала.

403

• {"code":"section_disabled","section":"secrets"} — раздел выключен в /#/settings → Sections.
• {"error":"container actions disabled"} — PRIVILEGES не содержит нужную возможность.
• {"error":"exec is disabled by the Docker proxy…"} — запрет на уровне docker-api; проверьте env у обоих контейнеров.

Секреты не попадают в контейнер

Сначала посмотрите, что ответил API:

curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  localhost:9090/api/secrets/1/push | jq

Авто-push требует одновременно push и exec; иначе в логе будет secret auto-push disabled. После пересоздания контейнера файл исчезает — push выполнится на событие start.

Портал не подключается к контуру

• Адрес. Из контейнера портала localhost — это сам портал. Укажите имя сервиса (http://docker-stat:8080) или http://host.docker.internal:9090 для контура на хосте.
• Ключ. POST /api/portal/servers/{id}/check возвращает 200 даже при неверном ключе — смотрите тело ответа.
• Сеть. Портал и контур должны быть в общей сети или доступны по IP; проверьте docker compose ps и curl из контейнера.
• Подпись. В разделе Deployment задайте адрес и алиас ноды, иначе на графе будет bridge-IP.

WebSocket и граф

• За обратным прокси нужны Upgrade и Connection, а для nginx — отключённая буферизация на WS-локациях.
• При другом origin добавьте его в ALLOWED_ORIGINS; без значения разрешён только same-origin.
• Оверлей «нет связи» с backoff — штатное поведение при рестарте контура; после реконнекта приходит полный снимок.

AI недоступен

• В режиме портала AI настраивается на портале: /#/settings → Portal → AI analysis. На контуре блок скрыт.
• Проверьте GET /api/portal/ai/status: enabled и model. Ключ в браузер не отдаётся, только api_key_set.
• Ошибки провайдера видны в логах портала ([portal ai]); таймауты и 429 приходят от провайдера.
• Standalone: ключ и URL задаются на контуре, GET /api/ai/status показывает ready.

Restore не применился

• Нужен BACKUP_RESTORE_ENABLED=true, иначе API ответит 403.
• Restore ставится в очередь и применяется на следующем старте: перезапустите контейнер.
• Архив с другой версией схемы или повреждённым манифестом отклоняется на этапе проверки.
• Bootstrap-секреты не входят в архив — восстановите их отдельно.

Логи пустые или обрезаны

• Проверьте logs_capture_enabled и лимит объёма snapshot_logs в настройках.
• Redaction вырезает секреты и токены — это ожидаемо.
• Исторические логи есть только у сохранённых срезов; live-логи приходят по WebSocket.

Прочее