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

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

Шаблон не подходит, или клон никогда не доходит до Ready​

Симптом: ВМ не появляется в списке выбора Шаблонная ВМ PVE в диалоге Шаблоны → Зарегистрировать, либо клоны пула застревают в состоянии customizing, а данные гостя показывают Агент не установлен или Агент неизвестен.

Причина: guest-агент QEMU не установлен и не запущен внутри гостя, либо на самой ВМ в Proxmox VE не включена опция QEMU Guest Agent — оба условия обязательны, включения только одного из них недостаточно.

Решение:

  1. Установите guest-агент внутри гостя (qemu-guest-agent в Linux; установщик guest-agent из ISO virtio-win в Windows) и убедитесь, что служба запущена.
  2. Включите QEMU Guest Agent на вкладке Options ВМ в интерфейсе Proxmox VE.
  3. Пока ВМ ещё работает как обычная ВМ (до преобразования в шаблон), откройте её в интерфейсе Proxmox VE и проверьте вкладку Summary — появившийся там IP-адрес подтверждает, что агент отвечает.

Полное руководство см. в разделе Подготовка шаблонов ВМ.

Пул завис на этапе провижининга​

Симптом: пул никогда не достигает своего значения Мин. размер или целевого размера подготовленного пула; его ВМ остаются в состоянии planned или cloning.

Причина: чаще всего одно из: API-токен Proxmox, настроенный для кластера, не имеет прав на клонирование или создание ВМ, у настроенного в пуле хранилища (Хранилище) закончилось место, либо конкретное задание клонирования провалилось.

Решение:

  1. Откройте страницу Задания («Фоновые задания») и отфильтруйте по статусу Ошибка — у зависшего пула почти всегда там висит задание Клонирование ВМ с ошибкой.
  2. Прочитайте текст ошибки задания на предмет сообщения о правах или нехватке места от Proxmox VE.
  3. В Настройки → Подключение Proxmox убедитесь, что API-токен кластера имеет права на клонирование/создание, и нажмите Проверить подключение; отдельно проверьте, что у настроенного в пуле хранилища (Хранилище) есть свободное место.
  4. После устранения первопричины выберите Повторить на провалившемся задании (вернуть в очередь можно только задания в статусе Ошибка), либо подействуйте на саму ВМ через Пересоздать или Удалить — см. Пулы рабочих столов → Обработка сбоев.

Не удаётся подключиться к рабочему столу в браузере​

Симптом: при выборе Открыть в браузере появляется статус вроде «Рабочий стол сейчас недоступен.» или «Соединение неожиданно закрылось. Переподключитесь.».

Причина: gateway недоступен, промежуточный прокси блокирует апгрейд WebSocket, сам guacd не работает, либо RDP заблокирован в межсетевом экране гостевой ОС.

Решение:

  1. Убедитесь, что процесс/контейнер gateway запущен и доступен по публичному wss://-адресу, который отдаёт ваш обратный прокси (GATEWAY_PUBLIC_WS_URL).
  2. Убедитесь, что ваш обратный прокси пропускает апгрейд WebSocket на этом пути — прокси, который перенаправляет только обычный HTTP, молча ломает туннель.
  3. Убедитесь, что guacd запущен и доступен из gateway (GUACD_ADDRESS).
  4. Убедитесь, что межсетевой экран гостевой ОС разрешает входящий RDP (порт 3389) с адреса guacd. Полный путь — браузер → gateway по WSS, gateway → guacd по протоколу Guacamole (порт 4822), guacd → ВМ рабочего стола по RDP (порт 3389) — см. Требования → Сетевые пути.

Не удаётся войти через OIDC​

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

Причина: обычно одно из: redirect URI не зарегистрирован в приложении провайдера идентификации, токен отклоняется из-за рассинхронизации часов между хостом, который его выпустил, и хостом, который его проверяет (проверка срока действия не допускает большого расхождения), либо в токене пользователя есть значение claim'а группы, для которого нет соответствующей OIDC-привязки.

Решение:

  1. Убедитесь, что все три redirect URI зарегистрированы в приложении вашего провайдера идентификации. См. Провайдеры идентификации → Настройка стандартного OIDC.
  2. Убедитесь, что часы на хосте, где работает API, и на вашем провайдере идентификации синхронизированы (NTP) — токен, который из-за рассинхронизации выглядит ещё не действительным или уже истёкшим, не проходит проверку точно так же, как реально истёкший токен.
  3. Если сам вход проходит успешно, но у пользователя нет доступа, проверьте вкладку Пользователи и доступ → OIDC-привязки на наличие привязки, чьё значение claim'а совпадает с тем, что реально присылает ваш провайдер идентификации, — сам по себе claim не даёт никаких прав, пока не сопоставлен с локальной группой. См. Управление доступом → OIDC-привязки групп.

/readyz начинает отказывать после обновления​

Симптом: /readyz API или worker возвращает 503 {"status":"not_ready","dependency":"migrations"} сразу после раскатки новой версии.

Причина: миграции для новой версии ещё не применены — автоматически они никогда не применяются.

Решение: выполните шаг применения миграций для вашего канала установки, затем повторно проверьте /readyz:

Точную форму ответа и значение каждого dependency см. в разделе Наблюдаемость → Семантика readiness.

Где искать логи​

Канал установкиКоманда
Docker Composedocker compose logs -f <service> — имена сервисов: api, worker, gateway, web, guacd, postgres, redis
VM (systemd)journalctl -u <unit> -f — юниты: planeon-api, planeon-worker, planeon-gateway, planeon-web, planeon-guacd
Kubernetes (Helm)kubectl get pods -l app.kubernetes.io/instance=planeon, чтобы найти под, затем kubectl logs <pod-name> -f — точные метки и имена подов задаёт чарт, см. Установка на Kubernetes (Helm)