Перейти к основному содержимому

Устранение неполадок

Этот документ был подготовлен при помощи ИИ

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

Начните с состояния сервисов: проверка состояния есть у каждого. Первым делом смотрите тот сервис, который её не прошёл:

docker compose ps
docker compose logs -f backend

Сервисы backend и api-gateway отвечают на /actuator/health, frontend — на /health, а keycloak — на порту 9000 по пути /health.

Вход перенаправляет на localhost​

Адрес, куда уходит браузер, приложение берёт из окружения, а не из запроса. APPLICATION_URL, API_GATEWAY_URL, OAUTH2_ISSUER_URL, OAUTH2_AUTHORIZATION_URL и OAUTH2_ACCOUNT_URL должны быть публичными адресами вашей установки. Если в каком-то из них по-прежнему указан localhost, пользователи за пределами хоста попадут на недоступную им страницу.

Keycloak сообщает о недопустимом URI перенаправления​

Клиент architeezy принимает ровно один URI перенаправления, зафиксированный при первом импорте realm: API_GATEWAY_URL/login/oauth2/code/keycloak. Изменить API_GATEWAY_URL позже недостаточно: настройки клиента останутся прежними. Откройте Clients → architeezy в консоли администратора Keycloak и исправьте Valid redirect URIs и Valid post logout redirect URIs вручную.

API-шлюз не может достучаться до Keycloak​

OAUTH2_TOKEN_URL, OAUTH2_JWK_SET_URL и OAUTH2_USER_INFO_URL вызывает само приложение, а не браузер, и они должны разрешаться изнутри сети контейнеров — http://keycloak:8080/... во встроенной конфигурации. Публичный HTTPS-адрес тоже подойдёт, если контейнер до него дотягивается.

Если OAUTH2_JWK_SET_URL указан неверно, бэкенд не может проверять токены, и каждый вызов API возвращает 401, хотя вход завершился успешно.

Ошибки CORS в консоли браузера​

API-шлюз разрешает origin APPLICATION_URL, ABOUT_URL и APPLICATIONS_URL. Любой другой origin добавьте в ALLOWED_ORIGINS либо опишите шаблоном в ALLOWED_ORIGIN_PATTERNS и перезапустите API-шлюз. Это относится ко второму имени хоста того же экземпляра, к встроенной странице и к вашему приложению, которое ходит в API.

Бэкенд не может подключиться к базе данных​

Бэкенд берёт SPRING_DATASOURCE_USERNAME и SPRING_DATASOURCE_PASSWORD из DATABASE_USERNAME и DATABASE_PASSWORD — той же пары, которой инициализируется контейнер db. PostgreSQL читает её только при первом запуске с пустым томом: измените DATABASE_PASSWORD позже — база данных останется со старым паролем, а бэкенд будет предъявлять новый.

Либо смените пароль внутри базы данных командой ALTER USER, либо начните заново с пустым томом — это удалит данные, поэтому сначала снимите дамп.

Сессии пользователей неожиданно завершаются​

Сессии хранятся в Redis и пропадут, если контейнер redis пересоздали без его тома или если REDIS_PASSWORD разошёлся с тем, что предъявляет API-шлюз.

Если же сессии истекают раньше срока, сравните SESSION_TIMEOUT с SSO Session Idle в realm Keycloak. В поставке оба равны 30 дням, и побеждает меньшее из двух значений.

Ссылки приходят с http:// при работе по HTTPS​

Приложение, API-шлюз и Keycloak строят свои URL из проброшенных заголовков. Обратный прокси перед ними должен задавать Host, X-Forwarded-For, X-Forwarded-Proto и X-Forwarded-Port. Конфигурация на странице о готовых образах задаёт все четыре.

Диаграммы перестают обновляться до перезагрузки страницы​

Живые обновления идут по WebSocket на /subscriptions. Прокси, который не передаёт Connection: upgrade и Upgrade: $http_upgrade, рвёт это соединение. Пример конфигурации задаёт оба заголовка и большое значение proxy_read_timeout, без которого соединение быстро разрывается.

Не удаётся загрузить большой файл​

Файл проходит через три ограничения подряд:

  • обратный прокси перед приложением;
  • контейнер frontend, который принимает до 100 МБ;
  • бэкенд, который принимает до 256 МБ на файл.

Пример конфигурации прокси разрешает 50 МБ; нужно больше — увеличьте там client_max_body_size.

Порт уже занят​

Каждый публикуемый порт задаётся переменной в файле .env — FRONTEND_PORT, KEYCLOAK_PORT, DATABASE_PORT, REDIS_PORT и KEYCLOAK_DATABASE_PORT. Измените значение и снова выполните docker compose up -d. Все они привязаны к 127.0.0.1, поэтому конфликт всегда возникает с чем-то другим на том же хосте.

ИИ-ассистент не отвечает​

Бэкенд обращается к совместимому с OpenAI сервису по адресу OPENAI_URL, который по умолчанию указывает на host.docker.internal:11434 — это сервер модели на хост-машине. Если там ничего не слушает, отказывает только ассистент, остальное приложение работает как обычно. Пропишите в OPENAI_URL, OPENAI_API_KEY и OPENAI_MODEL тот сервис, которым пользуетесь.