inecs
f8d3cbdd59
Add the FastAPI app, PostgreSQL migrations, Docker/Helm packaging, API contracts, docs, client examples, and the unit/integration/compatibility test suite for local client and tooling labs without a real vCenter.
76 lines
4.4 KiB
Markdown
76 lines
4.4 KiB
Markdown
**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`), чтобы восстановить более богатую фикстуру.
|