**Language / Язык:** [English](../troubleshooting.md) | [Русский](troubleshooting.md)

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

## Ready остаётся недоступным

1. Проверьте Postgres: `make logs` / health в Compose.
2. Выполните `make db-migrate`.
3. Снова вызовите `/health/ready`.

Task workers могут повторять попытки, пока миграции не догонят после позднего migrate.

## Неожиданный HTTP 501

У каждого зарегистрированного маршрута должен быть реальный обработчик или
DB-backed стаб — 501 не должен появляться для известного пути. Если вы его видите:

- Убедитесь, что вызываете точный зарегистрированный path/verb (проверьте
  `app/vsphere/rest/coverage.py` или `/docs`).
- 501 от опционального legacy-стаба (`ENABLE_PVE_STUB=true`) ожидается для
  необъявленных методов в стиле PVE, когда `CONTRACT_FALLBACK=error`; это
  не относится к native vSphere-поверхности.
- Сообщите о регрессии — на native vSphere-плоскости ожидается полное
  покрытие реестра.

## 401 / 403

- Сессия истекла (скользящий TTL 2 часа) или заголовок/cookie
  `vmware-api-session-id` не отправлен.
- Некорректный Basic auth на `/api/session` (отсутствует заголовок, неверный
  base64 от `user:password`).
- Отказ по правам — попробуйте сравнить `administrator@vsphere.local` и
  `readonly@vsphere.local` (см. [Авторизация](domains/authz.md)).

## Задача никогда не завершается

- Изучите `/api/cis/tasks/{task}`.
- Проверьте логи worker/симулятора (`make logs`).
- Убедитесь, что `TASK_WORKER_CONCURRENCY` > 0 и аренды в базе данных можно
  забрать (claim).
- Очень высокий `SIMULATION_TIME_SCALE` даёт необычные замедления (больше =
  быстрее симуляция); чаще виноваты неверно заданные worker-аренды.

## Сбои TLS / gateway

- Используйте порт хоста **443** (gateway) для TLS-клиентов — pyvmomi,
  govmomi, провайдер Terraform `hashicorp/vsphere`, Pulumi.
- Устанавливайте `verify_ssl=False` / `allow_unverified_ssl=true` **только**
  для локального self-signed development-сертификата.
- Внутри Compose обращайтесь напрямую к `simulator:8080` (обычный HTTP, без
  gateway).
- Seeded-имена ВМ для `small` — `web-01`, `web-02`, `db-01`, `app-01`,
  `jumpbox`, а не Proxmox-style `pve01`/VMID.

## Drift Terraform / Pulumi / Ansible после reseed

Reseed заменяет инвентарь в PostgreSQL (MOID-ы и имена ВМ могут измениться);
состояние внешних инструментов автоматически не обновляется. Выполните
refresh, import или пересоберите стеки после `make seed`.

## Hot-swap «ничего не сделал»

- Просмотр каталога ≠ apply. Используйте **Apply as runtime** или
  `POST /ui/api/contract/apply?major=N`.
- Применение мажора меняет **каталог Web UI / представление evidence**, а не
  живую таблицу маршрутов — runtime всегда обслуживает полную
  зарегистрированную поверхность. См. [Версии API](api-versions.md).
- Apply локален для процесса; перезапуск Compose возвращает к значению по
  умолчанию (мажор 9).

## Demo unload удивил

`POST /ui/api/demo/unload` очищает состояние, созданное через API, и
загружает `small`. Повторите `make seed` (или снова загрузите
`demo-cluster`), чтобы восстановить более богатую фикстуру.