[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"docs-infra\u002Fserver-access-recovery":3,"docs-tabs-infra\u002Fserver-access-recovery":6},{"content":4,"lastmod":5},"# Восстановление доступа к серверу\n\nСервер остаётся привязан к текущему управляющему ключу, поэтому после истечения или отзыва этого ключа другой ключ сервер не видит. Доступ возвращается сменой управляющего ключа в личном кабинете, сервер при этом не пересоздаётся.\n\n## Как выглядит потеря доступа\n\nПотеря доступа проявляется так:\n\n- `GET \u002Fv1\u002Finfra\u002Fservers` возвращает успех и пустой массив `data`, хотя серверы на портале есть.\n- `GET \u002Fv1\u002Finfra\u002Fservers\u002F:id` по известному идентификатору возвращает `404 NOT_FOUND`.\n- `GET \u002Fv1\u002Fme` при этом подтверждает, что новый ключ действует: `accessMode` равен `READWRITE`, скоуп `vibe:infra` присутствует.\n- В личном кабинете сервер виден в разделе «Серверы Black Hole» и продолжает работать.\n\nСписок серверов с ключом, который ими не управляет:\n\n```json\n{\n  \"success\": true,\n  \"data\": []\n}\n```\n\nОбращение к конкретному серверу тем же ключом:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"NOT_FOUND\",\n    \"message\": \"Server not found\"\n  }\n}\n```\n\nНадёжная проверка — сравнить личный кабинет и API: сервер виден в разделе «Серверы Black Hole», но не приходит в `GET \u002Fv1\u002Finfra\u002Fservers`. Кабинет показывает серверы по владельцу, поэтому он и есть источник правды о том, что сервер существует.\n\nСчётчики в `GET \u002Fv1\u002Fme` дают дополнительную подсказку, но не доказательство. Поле `infra.limits.used` считает отдельные виртуальные машины (`STANDALONE`) текущего ключа, а `infra.limits.breakdown` — серверы владельца по всем его ключам на портале. Нулевой `used` при ненулевом `breakdown.total` сам по себе не говорит, что текущий ключ не управляет ничем: `used` не считает галактики и Galaxy-приложения даже тогда, когда управляет ими именно он. Это повод сверить с кабинетом, не более:\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"infra\": {\n      \"limits\": {\n        \"max\": 3,\n        \"used\": 0,\n        \"breakdown\": {\n          \"direct\": 7,\n          \"agents\": 0,\n          \"bots\": 0,\n          \"total\": 7\n        }\n      }\n    }\n  }\n}\n```\n\nУ подсказки есть и другие границы. Сервер, полностью потерявший ключ, в `breakdown` не попадает — там оба счётчика останутся нулевыми, хотя сервер работает и виден в кабинете. И наоборот, `breakdown` считает в том числе виртуальные машины агентов и ботов: они тоже дают `used: 0` при ненулевом `total`, но управляют ими в их разделах личного кабинета, а не через `\u002Fv1` — см. [AI-агенты](\u002Fdocs\u002Fagents). Про галактики подробнее — [Galaxy-приложение](\u002Fdocs\u002Finfra\u002Fgalaxy). Поэтому счётчики подсказывают, куда смотреть, а решает сравнение с кабинетом.\n\n## Почему сервер не виден\n\nУ сервера две разные привязки. Владение закреплено за пользователем и не меняется при действиях с ключами. Поле `apiKeyId` означает другое — какой ключ управляет сервером сейчас.\n\nЭндпоинты `\u002Fv1\u002Finfra\u002F*` авторизуют доступ по управляющему ключу: запрос видит только те серверы, у которых `apiKeyId` совпадает с вызывающим ключом. Личный кабинет опирается на владение, поэтому там сервер остаётся виден. Отсюда и расхождение: в кабинете сервер есть, через API с новым ключом его нет.\n\nДанные сервера при истечении ключа не затрагиваются. Виртуальная машина, развёрнутое приложение, настройки и субдомен продолжают работать — недоступно только управление через API.\n\n## Как вернуть доступ\n\nСмена управляющего ключа выполняется в личном кабинете владельцем сервера:\n\n1. Откройте раздел [Серверы Black Hole](\u002Fblack-hole).\n2. Найдите нужный сервер в списке.\n3. В меню карточки сервера выберите **Сменить управляющий ключ**.\n4. Выберите в списке новый ключ и подтвердите.\n\nЕсли у сервера нет управляющего ключа, на его карточке появляется кнопка **Восстановить доступ**, которая открывает тот же выбор. Когда карточка показывает **Владение потеряно**, сначала нажмите **Вернуть себе** — это вернёт сервер во владение, после чего появится выбор ключа. Бесхозные серверы видит и возвращает себе только администратор портала: остальным `POST \u002Fapi\u002Fservers\u002F:id\u002Fadopt` отвечает `403 ADMIN_ONLY`, и карточка им не показывается.\n\nСмена затрагивает только управляющую привязку. Виртуальная машина, данные, настройки и субдомен остаются нетронутыми, перезапуск не выполняется. После подтверждения новый ключ сразу видит сервер в `GET \u002Fv1\u002Finfra\u002Fservers` — при условии, что срок его действия не закончился. Набор доступных операций зависит от типа ресурса: отдельной виртуальной машине (`STANDALONE`) доступны и жизненный цикл, и развёртывание, а Galaxy-приложению (`GALAXY_APP`) — развёртывание и удаление, потому что своей виртуальной машины у него нет и будить или перезагружать нечего. Владелец сервера получает сообщение от бота-помощника о том, что управляющий ключ сменён.\n\n## Требования к новому ключу\n\nВ списке выбора показываются только подходящие ключи. Ключ подходит, когда выполнены все условия:\n\n| Условие | Значение |\n|---------|----------|\n| Тип | API-ключ (`vibe_api_`). Ключ авторизации (`vibe_app_`) в качестве управляющего не принимается |\n| Назначение | Ключ общего назначения. Выпущенные платформой временные ключи обслуживания и ключи Cowork не принимаются |\n| Владелец | Тот же пользователь, которому принадлежит сервер |\n| Портал | Тот же портал Битрикс24, что и у сервера |\n| Состояние | Отозванный и заблокированный ключи в списке не показываются |\n| Скоуп | `vibe:infra` |\n| Не текущий | Ключ, который уже управляет этим сервером, в списке не показывается |\n\nВыбирайте ключ, срок действия которого не закончился. Ключ с истёкшим сроком остаётся в списке, и перепривязка на него проходит — но запросы с ним отклоняются с кодом `401 KEY_EXPIRED`, и доступ к серверу придётся восстанавливать заново. Срок действия каждого ключа виден в разделе [Ключи API](\u002Fkeys).\n\nЕсли подходящих ключей нет, создайте новый в разделе [Ключи API](\u002Fkeys) со скоупом `vibe:infra` — форма позволяет сделать это, не покидая диалог смены ключа.\n\n## Когда это нужно\n\nСитуации приводят к одному видимому итогу — сервер работает, а новый ключ его не видит. Но состояний за этим три, и порядок действий у них разный.\n\n**Управляющий ключ на месте, но не работает.** Привязка сервера цела, нерабочим стал сам ключ:\n\n1. **Секрет ключа потерян.** Ключ действует, но его значение не сохранили при создании. Значение ключа показывается один раз, восстановить его нельзя.\n2. **Ключ отозван.** Ключ переведён в состояние `REVOKED` — владельцем, например после компрометации, или платформой при отключении самостоятельно размещённого портала: отключение отзывает ключи пользователя, привязку сервера оно не трогает.\n3. **Ключ истёк.** Срок действия закончился, запросы отклоняются с кодом `401 KEY_EXPIRED`.\n\nВо всех трёх случаях порядок обычный — смена управляющего ключа на новый.\n\n**Сервер остался без управляющего ключа.** Поле `apiKeyId` пусто, владелец сохранён. Карточка показывает кнопку **Восстановить доступ**, которая открывает тот же выбор ключа. Удалить ключ с работающими серверами вручную нельзя — это запрещает проверка при удалении.\n\n**Сервер остался и без владельца.** Оба поля пусты. Так бывает после удаления учётной записи владельца: его ключи удаляются вместе с ней, и `userId` с `apiKeyId` обнуляются одновременно. Карточка показывает **Владение потеряно** — сначала нажмите **Вернуть себе**, и только после этого появится выбор ключа. Такие серверы видит только администратор портала.\n\nВозврат владения работает для отдельных виртуальных машин (`STANDALONE`). Galaxy-приложение, оставшееся без владельца, вернуть себе нельзя — платформа помечает его удалённым. Пока владелец у приложения сохранён, управляющий ключ ему меняется обычным порядком.\n\n## Ошибки\n\n| HTTP | Код | Когда возвращается |\n|------|-----|---------------------|\n| 401 | `KEY_EXPIRED` | Срок действия ключа закончился |\n| 401 | `KEY_INACTIVE` | Ключ отозван или заблокирован |\n| 404 | `NOT_FOUND` | Обращение к серверу ключом, который им не управляет |\n| 403 | `WRONG_KEY` | Развёртывание на сервер ключом, который им не управляет |\n| 409 | `KEY_HAS_ACTIVE_SERVERS` | Удаление ключа, на котором есть активные серверы |\n| 409 | `KEY_HAS_LINKED_AGENT` | Удаление ключа, которым управляется агент или бот |\n| 409 | `APP_HAS_ACTIVE_SERVERS` | Удаление приложения, на ключе которого есть активные серверы |\n| 409 | `CONCURRENT_REBIND` | Одновременная смена на разные ключи — сервер уже привязан к другому ключу |\n\nПолный справочник кодов — [Коды ошибок](\u002Fdocs\u002Ferrors).\n\n## Известные особенности\n\n**Удаление ключа с активными серверами не проходит.** Запрос возвращает `409 KEY_HAS_ACTIVE_SERVERS`. Смените у этих серверов управляющий ключ — удалять сами серверы для этого не нужно. Полное число серверов приходит в поле `details.activeServerCount` при удалении из кабинета и в `error.details.activeServerCount` у `DELETE \u002Fv1\u002Fkeys\u002F:id`. Список лежит рядом со счётчиком — соответственно в `details.servers` и `error.details.servers`. В списке не больше 10 серверов, самые новые — при значении счётчика больше десяти опирайтесь на него, а остальные серверы смотрите в кабинете. Если на ключе есть ещё и агент или бот, следующая попытка вернёт `409 KEY_HAS_LINKED_AGENT` — перепривязка серверов эту проверку не снимает.\n\n**Смена ключа выполняется только в личном кабинете.** У операции нет варианта в `\u002Fv1`: перепривязка работающего сервера — решение человека, а не автоматизированного клиента. Ключ `vibe_api_` этот вызов не выполняет.\n\n**Развёртывание чужим ключом возвращает `403 WRONG_KEY`.** Ответ приходит, когда сервер существует, но управляется другим ключом. В поле `hint` приходит разбор ситуации и указание на смену управляющего ключа как способ восстановления.\n\n**Сервер, созданный приложением, после смены ключа приложению больше не доступен.** Если сервер создан ключом авторизации, сменить управление можно только на личный API-ключ владельца — принять привязку другой ключ авторизации не может. После этого `GET \u002Fv1\u002Finfra\u002Fservers\u002F:id` со старым ключом возвращает `404 NOT_FOUND`, а `POST \u002Fv1\u002Finfra\u002Fservers\u002F:id\u002Fdeploy` — `403 WRONG_KEY`. Управлять сервером через `\u002Fv1` можно только новым личным ключом.\n\n**Порядок относится к серверам и Galaxy-приложениям.** В разделе «Black Hole серверы» показываются отдельные виртуальные машины (`STANDALONE`) и Galaxy-приложения (`GALAXY_APP`). Галактика-хост (`GALAXY`) живёт в разделе «Галактики», и смены управляющего ключа там нет — в `GET \u002Fv1\u002Finfra\u002Fservers` она возвращается наравне с остальными, поэтому по пустому ответу нового ключа отличить её нельзя.\n\n**Одновременная смена ключа с двух устройств разрешается по целевому ключу.** Когда оба запроса выбрали один и тот же ключ, второй запрос возвращает `200` — привязка уже такая, какую он запрашивал. Когда запросы выбрали разные ключи, второй возвращает `409 CONCURRENT_REBIND`: обновите страницу и посмотрите текущую привязку.\n\n## Смотрите также\n\n- [Список серверов](\u002Fdocs\u002Finfra\u002Fservers\u002Flist)\n- [Инфраструктура](\u002Fdocs\u002Finfra)\n- [Создание и использование ключа](\u002Fdocs\u002Fkeys-auth)\n- [Коды ошибок](\u002Fdocs\u002Ferrors)\n","2026-07-17",{}]