Распространённые ошибки
HTTP-ошибки
401 Unauthorized
| Симптом | API-запросы возвращают 401, либо интерфейс неожиданно перенаправляет на страницу входа |
| Причина | Ваш сеанс OAuth2 истёк или токен недействителен |
| Решение | Выйдите из системы и войдите снова. Если проблема сохраняется после повторного входа, очистите cookie браузера и localStorage для домена OpSee и войдите ещё раз. См. Проблемы со входом для подробностей. |
403 Forbidden
| Симптом | Страница загружается, но данные не появляются, либо действие возвращает ошибку 403 |
| Причина | У вашей учётной записи Keycloak нет требуемой роли для этого ресурса |
| Решение | Свяжитесь с администратором Keycloak, чтобы проверить назначенные вам роли. Проверьте текущие роли в Профиль → Роли и разрешения. Часто требуются роли: menu:production, equipment:view, menu:admin. |
404 Not Found
| Симптом | Страница или конечная точка API возвращает 404 |
| Причина | URL не существует (опечатка, устаревшая закладка) либо модуль не развёрнут в этой инстанции |
| Решение | Перейдите на страницу из главного меню. Если самого пункта меню нет, возможно, функция не включена в вашей установке, обратитесь к администратору. |
500 Internal Server Error
| Симптом | Действие завершается общим сообщением об ошибке сервера |
| Причина | Необработанное исключение в backend API |
| Решение | Проверьте журналы backend-контейнера (docker logs opsee-fastapi). Если ошибка воспроизводима, запишите точное действие, вызывающее её, и сообщите администратору с временной меткой, чтобы он мог сопоставить запись в журнале. |
502 Bad Gateway / 503 Service Unavailable
| Симптом | Всё приложение показывает страницу ошибки 502 или 503 |
| Причина | Backend-сервис или одна из его зависимостей (база данных, Keycloak) не работает или ещё не запущена |
| Решение | Выполните docker ps на сервере, чтобы проверить, какие контейнеры запущены. Перезапустите остановленные контейнеры командой docker compose up -d. Если проблема в базе данных, проверьте исчерпание места на диске или ошибки лимита подключений. |
Сетевые ошибки
«Не удаётся подключиться» / Сетевая ошибка
| Симптом | Вызовы API завершаются сетевой ошибкой в консоли браузера; HTTP-код состояния не возвращается |
| Причина | Backend-контейнер OpSee не работает, либо обратный прокси NGINX не может его достичь |
| Решение | Убедитесь, что контейнеры Docker запущены: docker ps. Если backend-контейнер остановлен, изучите его журналы командой docker logs opsee-fastapi. Перезапустите с помощью docker compose up -d. |
Ошибки валидации форм
Обязательное поле / неверный формат
| Симптом | Форма отказывается отправляться и подсвечивает поля красным |
| Причина | Обязательное поле пусто, значение не соответствует ожидаемому формату (например, в поле даты содержится текст), либо ввод превышает максимальную длину |
| Решение | Заполните все подсвеченные поля. Обращайте внимание на подсказки формата под каждым полем. |
Дублирующая запись
| Симптом | Форма отправляется, но возвращает ошибку вроде «уже существует» или «дубликат ключа» |
| Причина | Запись с тем же уникальным идентификатором (имя, код и т. п.) уже существует в базе данных |
| Решение | Используйте другое значение для уникального поля или отредактируйте существующую запись вместо создания новой. |