# Перенос приложения на свой сервер

Как перенести приложение из кабинета Вайбкод на собственный сервер: что поменять в коде, как сменить адрес, что изменится после переезда и как вернуться обратно.

## Когда переносить

Перенос нужен, когда код приложения должен работать на вашем сервере, а не на сервере Вайбкод. Меняется только адрес, по которому открывается приложение. За платформой остаётся всё остальное:

- карточка приложения в разделе «Приложения», ключ авторизации и доступ к приложению,
- встройки в Битрикс24 и карточки каталогов — они начинают вести на новый адрес,
- API Вайбкод: приложение вызывает `/v1/*` так же, как раньше.

Карточки каталогов переехавшего приложения получают пометку «Вне платформы» и «Безопасность сервера не проверена»: внешний сервер платформа не проверяет.

Перенос может быть выключен для вашего портала — тогда вкладки «Внешний сервер» в кабинете нет, а запрос на перенос получает отказ `EXTERNAL_URL_DISABLED`. Возврат на Вайбкод от этой настройки не зависит.

## Перед переездом: исходники

Код нужно забрать с сервера Вайбкод до переезда. Первый шаг вкладки «Внешний сервер» показывает один из двух вариантов:

- **Сохранённая версия есть** — кнопка «Открыть исходники» ведёт в раздел «Исходники приложений», там скачайте последнюю версию. Как устроено хранилище — [Хранилище исходного кода](/docs/source-storage).
- **Сохранённой версии нет** — скопируйте промпт для ИИ-агента. Он начинается с выгрузки кода с сервера Вайбкод, дальше описывает правки из следующего раздела.

## Что поменять в коде

На сервере Вайбкод вход пользователя выполняет Gateway: он подставляет в запрос заголовок `X-Vibe-Authorization` с токеном сессии. Вне платформы Gateway нет, поэтому вход приложение делает само:

1. Встройка открывает приложение по вашему адресу с одноразовым параметром `code`.
2. Ваш сервер обменивает код на токен сессии: `POST /v1/oauth/token` с телом `{ app_key, code, redirect_uri }`. В `app_key` — ключ авторизации приложения, в `redirect_uri` — ровно тот адрес, который вы укажете при переезде.
3. Токен `vibe_session_*` хранится только на сервере и в браузер не передаётся.
4. Данные пользователя приложение читает через `GET /v1/me` с заголовком `Authorization: Bearer` и этим токеном.
5. Страница приложения должна разрешать встраивание во фрейм Битрикс24: заголовки `X-Frame-Options` и CSP `frame-ancestors` настраиваете вы.

Формат обмена, ответ и второй способ получить сессию — [Self-hosted приложение](/docs/infra/app-runtime#self-hosted-приложение-не-black-hole).

Ключ авторизации приложения положите в окружение своего сервера. Сырой ключ платформа не хранит: если ключа у вас нет, нажмите «Перевыпустить ключ» в карточке приложения — новый ключ показывается один раз. Прежний ключ перестаёт работать сразу, а приложение нужно заново авторизовать на портале Битрикс24.

## Как переехать

Переносит владелец приложения или администратор портала.

1. Откройте раздел «Приложения» и карточку приложения.
2. В строке «Сервер» нажмите «Заменить».
3. Откройте вкладку «Внешний сервер». Рядом — вкладки «Мой сервер Вайбкод» и «Новый сервер Вайбкод», они меняют сервер в пределах платформы.
4. Пройдите шаги вкладки: «1. Код», «2. Что поменять в коде», «3. Адрес», «4. Что изменится».
5. В поле адреса укажите адрес приложения на вашем сервере. Адрес начинается с `https://` и не содержит логина и пароля, а его домен находится в DNS и указывает на публичный адрес, не во внутреннюю сеть. Адрес на сервере Вайбкод не подходит.
6. Нажмите «Перенести».

Кнопка «Указать свой адрес» в мастере публикации в каталог меняет только адрес приложения и сервер Вайбкод не отвязывает. Отвязку сервера делает только вкладка «Внешний сервер».

## Что изменится

- Меню, встройки и карточки каталогов ведут на новый адрес и получают пометку «Вне платформы».
- Сервер Вайбкод отвязывается от приложения, но не удаляется и не останавливается. Он тарифицируется, пока работает. Удалите его в разделе «Серверы Black Hole», когда код перенесён и работает на новом адресе.
- Строка «Сервер» в карточке показывает «Внешний сервер» и адрес, рядом — кнопка «Вернуть на Вайбкод».
- Доступ, настроенный на сервере, переносится на карточку приложения:
  - «весь портал» и «только владелец» сохраняются как были,
  - список людей переносится тем, кого удалось сопоставить с аккаунтами Вайбкод. Кого не удалось, в том числе людей из другого портала, в доступе не будет — кабинет называет их число (предупреждение `ACCESS_USERS_NOT_MOVED`), выдайте им доступ заново,
  - доступ по отделу не переносится (`ACCESS_DEPARTMENTS_NOT_MOVED`) — задайте его заново,
  - если прежний сервер приложения был удалён, после переезда доступ остаётся только у владельца (`ACCESS_CARD_AXIS_RESET`).

Предупреждения о доступе кабинет показывает сразу после переезда. Это не отказы: приложение при этом уже перенесено. Как задать доступ заново — [Политика доступа](/docs/infra/access/access-policy).

## Как вернуться на Вайбкод

1. Откройте раздел «Приложения» и карточку приложения.
2. Нажмите «Вернуть на Вайбкод».
3. Выберите сервер на вкладке «Мой сервер Вайбкод» или создайте его на вкладке «Новый сервер Вайбкод».
4. Нажмите «Вернуть на Вайбкод» в окне.

Адрес приложения снова ведёт на сервер Вайбкод, свой адрес перестаёт использоваться. На новый сервер код нужно выложить: возврат меняет привязку, но не переносит код и данные. Возврат работает и тогда, когда перенос на свой сервер для портала выключен.

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

## Ограничения

- Встройки переехавшего приложения не меняются: изменить набор встроек можно после возврата на Вайбкод.
- Создать новый сервер из карточки переехавшего приложения нельзя — такой запрос получает отказ `APPLICATION_HOSTED_EXTERNALLY`. Путь к серверу Вайбкод — «Вернуть на Вайбкод».
- Каталог приложений в мессенджере показывает карточку прежнего сервера Вайбкод, и она ведёт на его адрес, а не на новый.

## Коды отказов

| HTTP | Код | Что значит и что делать |
|------|-----|-------------------------|
| 403 | `EXTERNAL_URL_DISABLED` | Перенос на свой сервер выключен для портала. Возврат на Вайбкод доступен. |
| 403 | `FORBIDDEN` | Переносит только владелец приложения или администратор портала. |
| 409 | `APPLICATION_NO_AUTH_KEY` | У приложения нет ключа авторизации — выпустите его и повторите. |
| 400 | `APP_URL_UNSAFE` | Адрес не начинается с `https://`, содержит логин или пароль, его домен не находится в DNS или указывает во внутреннюю сеть. Укажите публичный адрес. |
| 400 | `APP_URL_NOT_EXTERNAL` | Адрес ведёт на сервер Вайбкод: поддомен Black Hole или подтверждённый домен отвязываемого сервера. Укажите адрес своего сервера. |
| 409 | `APP_URL_CONFLICT` | Адрес приложения изменился в это же время. Обновите страницу и повторите. |
| 409 | `APPLICATION_OP_IN_PROGRESS` | С приложением или его сервером идёт другая операция. Повторите через минуту. |

Предупреждения `ACCESS_USERS_NOT_MOVED`, `ACCESS_DEPARTMENTS_NOT_MOVED` и `ACCESS_CARD_AXIS_RESET` — не отказы, они описаны в разделе «Что изменится». Остальные коды — [Коды ошибок](/docs/errors).

## Смотрите также

- [Авторизация в приложении на Black Hole](./app-runtime.md)
- [Хранилище исходного кода](/docs/source-storage)
- [Политика доступа](/docs/infra/access/access-policy)
- [Коды ошибок](/docs/errors)