Для AI-агентов: markdown этой страницы — /docs-content/infra/move-to-own-server.md индекс документации — /llms.txt

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

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

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

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

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

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

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

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

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

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

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

На сервере Вайбкод вход пользователя выполняет 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 приложение.

Ключ авторизации приложения положите в окружение своего сервера. Сырой ключ платформа не хранит: если ключа у вас нет, нажмите «Перевыпустить ключ» в карточке приложения — новый ключ показывается один раз. Прежний ключ перестаёт работать сразу, а приложение нужно заново авторизовать на портале Битрикс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).

Предупреждения о доступе кабинет показывает сразу после переезда. Это не отказы: приложение при этом уже перенесено. Как задать доступ заново — Политика доступа.

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

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

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

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

Ограничения

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

Коды отказов

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

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

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