> For the complete documentation index, see [llms.txt](https://docs.edgegap.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.edgegap.com/ru/learn/orkestraciya/deployments.md). # Развертывания Узнайте о развертываниях и их жизненном цикле — концепции и лучшие практики для более глубокого понимания. ## 🗺️ Оркестрация Запускайте новые серверы за считанные секунды, чтобы удовлетворять потребности в мощности, используя наш облачно-нативный подход к периферийным вычислениям. Мы относимся к серверам как к [скоту, а не домашним питомцам](https://cloudscaling.com/blog/cloud-computing/the-history-of-pets-vs-cattle/) — полностью заменяя неисправные экземпляры вместо того, чтобы вручную возиться с каждым из них. {% hint style="info" %} Ваш выбор оркестрации **повлияет на ваши расходы на DevOps, стоимость серверов и масштабируемость**. {% endhint %} {% hint style="success" %} [Свяжитесь в Discord](https://discord.gg/MmJf8fWjnt) чтобы узнать о вариантах гибридной оркестрации и оптимизации стоимости хостинга. {% endhint %} Чтобы полностью понять все плюсы и минусы, давайте сравним различные методы оркестрации. Некоторые игры используют несколько методов оркестрации в зависимости от дизайна игрового цикла. ### Привязка к матчу Короткоживущие (ограниченные по времени) серверы масштабируются вниз по завершении матча, обеспечивая **лучшее соотношение цены и производительности**. Сессии обычно автоматизируются через [Подбор матчей](/ru/unity/podbor-matchei.md) сервис, который разворачивает серверы точно в срок по строгим правилам и при необходимости позволяет заполнять уже идущие серверы, чтобы [повысить заполненность матчей](https://edgegap.com/blog/how-session-fill-rate-affects-your-multiplayer-hosting-costs). 👍 **Преимущества** * Лучшая экономическая эффективность — масштабирование в реальном времени для удовлетворения спроса игроков поминутно. * Минимальные расходы на DevOps благодаря хостингу без привязки к региону; Edgegap автоматизирует 99% задач. * Минимальный пинг благодаря более чем 615 площадкам в публичной облачной инфраструктуре Edgegap. * Самое быстрое масштабирование вверх (burst-способность) в случае неожиданного всплеска трафика. * Высочайший стандарт безопасности и предотвращения читерства игроков (серверная авторитетность). * Минимальное влияние неожиданного сбоя сервера на игроков, затрагивающее только один матч. 👎 **Недостатки** * Внедрение новой ментальной модели оркестрации изначально требует некоторых усилий на адаптацию. * Серверы, работающие более 24 часов, будут автоматически завершены. 🧩 **Лучше всего подходит для** * Игры, чувствительные к задержке — **когда оптимизация неткода не может компенсировать высокий пинг:** * Шутеры от первого лица, файтинги, VR и XR (виртуальная и расширенная реальность), … * Игры с **верхним пределом длительности матча по замыслу**, * Королевская битва, PvPvE[^1], кооперативные шутеры, MOBA, спортивные игры, ARPG и данжен-кроулеры, … {% hint style="info" %} Edgegap автоматически масштабирует все 615+ серверных локаций вверх/вниз в зависимости от активности игроков в каждом регионе. Готовьтесь к успеху — без проблем [масштабируйтесь до 14 миллионов одновременных пользователей за 60 минут](https://edgegap.com/resources/performance-benchmark). {% endhint %} ### Региональный резерв Игра MMO с постоянным миром и социальным взаимодействием **срок жизни сервера часто превышает отдельные игровые сессии игроков**. Сессии обычно назначаются через [Server Browser](/ru/learn/server-browser.md) на основе предпочтений игроков (автоматически по региону или через пользовательский поиск) с горизонтальным предварительным масштабированием развертывания на основе региональной мощности. 👍 **Преимущества** * Знакомый и легко понятный старомодный подход для закалённых ветеранов. * Высочайший стандарт безопасности и предотвращения читерства игроков (серверная авторитетность). * Легко предсказуемая стоимость на основе ежемесячного обязательства. 👎 **Недостатки** * Более высокие расходы на хостинг — каждый регион требует один или несколько простаивающих резервных серверов (burst capacity). * Более высокие расходы на DevOps — масштабирование, операции и обслуживание дублируются для каждого региона. * Регионы с меньшей базой игроков испытывают высокий пинг из-за подключения к удалённым серверам. 🧩 **Лучше всего подходит для** * Постоянные миры с пользовательским контентом, хранящимся на сервере даже когда игроки офлайн. * MMO, песочницы с постройкой базы или размещением объектов, extraction-shooters, ... * игры, терпимые к задержке — **когда не требуется серверная авторитетная физика в реальном времени**: * мобильные игры, кооперативные игры, TCG/CCG, пошаговые стратегии, … * Асинхронный многопользовательский режим, **где сбои сервера минимально влияют на игровой опыт:** * гонка с призраками, грабёж базы противника, игры на строительство/фермерство с таймерами, … * приложения с тяжёлым процессом инициализации — когда подготовка серверов занимает минуты. ### Peer-to-Peer Перенаправьте усилия разработки с ~~выделенных серверов~~ на **ретрансляционный неткод для неконкурентных игр**. Связанные темы: listen-серверы, авторитет игрока-хоста, NAT punch-through. 👍 **Преимущества** * Минимальная стоимость хостинга, требуется только Relay-серверы для решения NAT punch-through. * Минимальные расходы на DevOps — обслуживание требуется только для клиентских сборок и каналов распространения. * Минимальное влияние неожиданного сбоя сервера на игроков, затрагивающее только один матч. * Легко реализовать и быстро прототипировать, без необходимости разработки бэкенда. 👎 **Недостатки** * Повышенные усилия по разработке P2P-неткода, требующие навыков параллельного программирования. * Худшие времена пинга и наибольшая чувствительность к неблагоприятным сетевым условиям (например, мобильному интернету). * Наименьшая безопасность, уязвимость к атакам man-in-the-middle и перехвату сессии. * Риск потери сессий, когда хост уходит, если вы не реализуете собственную миграцию хоста. 🧩 **Лучше всего подходит для** * Кооп- и казуальные игры — **когда читерство не лишает удовольствия и не ломает игру**, * Игры для детей, игры-исследования, приключения, … {% hint style="success" %} См. наши [Распределённые ретрансляторы](https://docs.edgegap.com/docs/distributed-relay-manager) для сервиса, обеспечивающего P2P с лучшей в классе задержкой и безопасностью. {% endhint %} ## 📍 Размещение серверов Независимо от того, какой метод оркестрации вы выберете, выбор правильного расположения сервера для группы игроков имеет решающее значение для обеспечения наилучшего возможного пинга и оптимального игрового опыта. Узнайте о различных стратегиях размещения серверов и о том, как они влияют на ваших игроков. {% hint style="info" %} Ваша стратегия размещения серверов **повлияет на игровой опыт ваших игроков, их удержание и отзывы о вашей игре**. {% endhint %} {% hint style="success" %} **Edgegap размещает в** [**наилучшей возможной локации**](#server-score) **с доступной мощностью**, для быстрых матчей с низкой задержкой. {% endhint %}
{% hint style="info" %} См. [#deployment-balance-points](#deployment-balance-points "mention") на **анализ размещения серверов в реальном времени**, в масштабе. {% endhint %} ### Оценка сервера Стратегия оценки сервера использует запатентованную методологию Edgegap, которая **оптимизирует размещение серверов для каждого матча индивидуально**. Выполняет ненавязчивую телеметрию, чтобы приблизительно оценить сетевую близость каждого игрока к нашим локациям серверов и выбрать сервер, который обеспечивает наилучшие: * **отзывчивость** - обеспечивает самый низкий пинг для всех игроков в среднем, * **справедливость** - обеспечивает сбалансированный и справедливый пинг для всех игроков. {% hint style="success" %} Наш [Матчмейкер](/ru/learn/podbor-matchei.md) использует **стратегию Server Score по умолчанию, чтобы обеспечить наилучший возможный опыт**. Чтобы использовать эту стратегию с [API развертывания](https://docs.edgegap.com/api/#tag/Deployments), укажите публичные IP-адреса игроков или геокоординаты в вашем запросе на развертывание. {% endhint %} **Нереагирующее размещение** - сервер находится далеко, высокий пинг для всех игроков:
**Несправедливое размещение** - неравномерный пинг, один игрок находится в невыгодном положении:
**Пример хорошего размещения** - отзывчивый и справедливый пинг для всех игроков:
{% hint style="info" %} Эта стратегия **особенно эффективна для размещения группы игроков, находящихся далеко друг от друга** (Северная Америка против Европы или западное побережье против восточного), что часто бывает в готовых лобби. {% endhint %} ### Геолокация В качестве альтернативы, **укажите целевые координаты широты и долготы или публичный IP-адрес ping beacon в предпочтительном регионе**. Этот подход требует дополнительной клиентской реализации геоопределения, полностью полагаясь на решение разработчика. ### Региональная блокировка Некоторые дизайны или аудитории не предназначены для выхода в соседние регионы по причинам соответствия требованиям, техническим или операционным причинам. Рассмотрите [Server Browser](/ru/learn/server-browser.md) с [региональными политиками масштабирования](/ru/learn/server-browser.md#automated-scaling). ## 🟢 Качество соединения Некоторые игры (и некоторые игроки) более чувствительны к задержке или лагам, чем другие. Хотя отчёты игроков — отличный индикатор инцидентов или ошибок регрессии в масштабе, **игроки могут не иметь глубокого понимания сетевых концепций** и быстро перекладывают вину на студии, неткод или серверы. Первопричина некоторых проблем может быть скрыта от игроков, поэтому сотрудничество студии и хостинг-провайдера может быть крайне важным. **Приоритет Edgegap всегда — предоставить наилучший возможный сервис.** Если вы получаете множество жалоб от игроков, испытываете массовые сбои или повторяющиеся проблемы, пожалуйста, немедленно свяжитесь с нами через тикет поддержки в нашей платформе. #### Низкая задержка Задержка игрока — это совокупность задержек при передаче данных между: * **физическими устройствами —** физическим сигналом, проходящим через [топологию интернет-сети](https://en.wikipedia.org/wiki/Internet#Routing), * **от хоста к хосту** — возникающее из-за протокола, транспорта и мер безопасности, * **от процесса к процессу** — возникающее из-за распаковки/упаковки и обработки данных в клиенте/сервере. Edgegap снижает физическую задержку, размещая серверы ближе к вашим игрокам для более быстрых ответов и меньшего числа сетевых переходов. Благодаря локациям у 17 облачных и bare metal-провайдеров вы получаете **лучший в классе пинг для игроков в любой точке мира**. Покрытие серверов и интернета по всему миру (не только у Edgegap) ограничено из-за таких факторов, как: * **доступность инфраструктуры** - качество интернет-соединения в данном регионе может быть недостаточным, * **природные факторы** - очень сложные серверные стойки требуют в основном стабильной среды. #### Высокая доступность Доступность серверов в различных локациях по всему миру будет меняться со временем, меняясь несколько раз в течение дня. Edgegap автоматически **масштабирует вверх/вниз** локации **по требованию**, учитывая: * **всплеск трафика** - развертывания, выполненные в течение 15-минутного периода, * **требования к vCPU** - больше vCPU на развертывание увеличивает общий спрос на конкретную локацию, * **предложения провайдера** - в некоторых удалённых локациях доступно меньше вариантов провайдеров, * **доступность машин** - в некоторых локациях могут быть доступны только машины на 4 vCPU или 8 vCPU, * **запросы студии** для тестирования, контроля качества, раннего доступа, закрытых бета-версий или турниров. Запросы на развертывание всех приложений объединяются для оценки спроса на локацию. По умолчанию все организации имеют одинаковый приоритет распределения, с **возможностью добавлять частные пулы серверов для корпоративных клиентов, которым требуется определённое оборудование или локации**. {% hint style="success" %} Пожалуйста, **свяжитесь с нами, чтобы спланировать релиз**или если у вас есть какие-либо запросы относительно доступности локаций. {% endhint %} #### Решение проблем игроков Проблемы игроков могут быть связаны с ошибками сервера или инцидентами у провайдера, но также могут возникать из-за третьих сторон, таких как местные провайдеры интернета, игровые сервисы, ошибки в низкоуровневых библиотеках, провайдеры инфраструктуры или другие источники. При устранении проблем по отчётам игроков или инцидентов учитывайте факторы: * **качество подбора игроков** - игроки должны быть близко друг к другу (в одном регионе), чтобы [#server-placement](#server-placement "mention") получить лучшие результаты: * см. [Подбор матчей](/ru/learn/podbor-matchei.md) и [Ping Beacons](/ru/learn/orkestraciya/ping-beacons.md) наши рекомендации, * см. [Подробный обзор](/ru/learn/podbor-matchei/matchmaker-in-depth.md#player-tracing) чтобы узнать, как найти серверные логи, связанные с жалобами игроков, * **региональные проблемы:** * местные интернет-провайдеры (ISP) могут временно устранять инцидент, * некоторые регионы (например, Китай, Россия) могут быть ограничены из-за местных санкций, * **уровень кэширования** - Edgegap будет отдавать приоритет быстрым развертываниям в кэшированных локациях: * [включите кэширование, чтобы разворачивать ваши серверы за считанные секунды](/ru/learn/orkestraciya/application-and-versions.md#other-parameters-optional), * **максимальное время развертывания** - развертывания могут не удаваться из-за медленного и тяжёлого процесса инициализации: * см. [Приложения и версии](/ru/learn/orkestraciya/application-and-versions.md#safety-guardrails) чтобы увеличить период тайм-аута, * откладывайте шаги инициализации до тех пор, пока это не станет абсолютно необходимым, * **проблемы с образом сервера или интеграцией**. {% hint style="success" %} **Отображайте ID развертываний в UI истории матчей клиента** чтобы отслеживать жалобы игроков при устранении неполадок. {% endhint %} {% hint style="info" %} Сообщайте пользователям о массовых ошибках, временных проблемах и сбоях, чтобы снизить негативный настрой. {% endhint %} ## 🔄 Жизненный цикл развертывания Развертывания Edgegap проходят несколько стадий жизненного цикла, обозначаемых статусом развертывания. #### 1. Запуск развертывания Развертывание для **целей тестирования** может быть запущено с помощью: * [Unreal Engine](/ru/unreal-engine.md) - расширения Docker или плагина для проектов Unreal Engine, * [Unity](/ru/unity.md) - плагина для проектов Unity, * [Веб-интерфейс панели](https://app.edgegap.com/deployment-management/deployments/list) - простой в использовании веб-интерфейс для тестирования интеграции сервера. Развертывание для **боевое production-окружение** должно запускаться с помощью: * [Подбор матчей](/ru/learn/podbor-matchei.md) - находить других игроков и запускать серверы по требованию ([#match-bound](#match-bound "mention")). * [Server Browser](/ru/learn/server-browser.md) - предварительно прогревать серверы с длительной инициализацией ([#regional-standby](#regional-standby "mention")). * [API развертывания](https://docs.edgegap.com/api/#tag/Deployments/operation/deploy) - индивидуальная интеграция сервер-сервер (кастомное масштабирование). {% hint style="success" %} **Сохранить** `request_id` **(ID развертывания) и помечайте развертывания** чтобы позже идентифицировать и устранять проблемы. {% endhint %} {% hint style="info" %} При тестировании с [API развертывания](https://docs.edgegap.com/api/#tag/Deployments/operation/deploy), вы можете переопределить стандартный Dockerfile `CMD` с помощью пользовательской команды. {% endhint %} #### 2. Развёртывание После запуска развертывания наша система быстро выполнит ряд шагов: * Телеметрия — мы измеряем сетевую отзывчивость от доступных дата-центров до каждого игрока, * Развертывание — мы резервируем мощность и готовим запуск контейнера вашего сервера, * Запуск контейнера — мы запускаем контейнер, устанавливаем зависимости и инициализируем, * Постобработка — мы добавляем хранение логов, мониторинг и завершаем развертывание. {% hint style="warning" %} **Слишком много запросов 429** - чтобы обеспечить стабильность и предотвратить неожиданные счета, мы ограничиваем частоту запросов для вашей организации до **40 запросов/с**. [Свяжитесь с нами](mailto:info@edgegap.com) чтобы планировать релизы, оценивать стартовый трафик и готовиться к успеху. {% endhint %} #### 3. Развертывание готово Ваш контейнер полностью инициализирован, и ваш сервер сейчас запускается. В течение нескольких секунд или минуты сервер всё ещё может инициализироваться и не отвечать на запросы игроков, пока ваш игровой движок (или пользовательская среда выполнения) не будет полностью готов принимать подключения игроков. {% hint style="success" %} Когда развертывание перейдёт в состояние Ready, **повторяйте попытку подключения игрока до успеха**или до заранее определённого тайм-аута клиента. {% endhint %} В зависимости от [Приложения и версии](/ru/learn/orkestraciya/application-and-versions.md#active-caching) конфигурации версии, вы можете получить: 🟢 **Попадание в кэш** Кэширование включено. Развертывание прошло быстрее благодаря повторному использованию образа, предварительно загруженного на этой машине. 🟡 **Тёплый старт** Кэширование отключено. Развертывание прошло быстрее благодаря повторному использованию образа, загруженного для предыдущего развертывания на той же машине. Включите кэширование, чтобы обеспечить стабильно быстрое развертывание по всему миру. 🔴 **Промах кэша** Кэширование включено. Развертывание было медленнее из-за внезапного всплеска трафика до завершения распространения кэша. Включение «требовать кэшированные локации» в вашем запросе на развертывание предотвратит это, но может привести к большему числу развертываний в состоянии Unprocessable во время неожиданных всплесков трафика. 🔴 **Холодный старт** Кэширование отключено. Развертывание было медленнее, образ загружался во время развертывания. Включите кэширование для более быстрого развертывания. #### 4. Ошибка развертывания Ваше развертывание может в любой момент перейти в состояние Unprocessable по неожиданным причинам. Это более вероятно при тестировании интеграции или новых серверных сборок. **За развертывания в состоянии Error плата не взимается; они автоматически останавливаются через 24 часа.** Шаги по устранению неполадок: * Проверьте статус сервиса Edgegap с помощью [нашей страницы мониторинга доступности](https://status.edgegap.com/). * Попробуйте протестировать контейнер сервера локально с помощью Docker Desktop, чтобы исключить проблемы Edgegap. {% hint style="success" %} **При обращении за помощью** **укажите ID развертывания и любые полезные сведения** чтобы мы могли оперативно разобраться! {% endhint %} #### 5. Развертывание остановлено **Мы никогда не останавливаем ваши серверы без вашей команды**, чтобы не ухудшать игровой опыт ваших игроков. Ваше развертывание может быть остановлено по следующим причинам: * **Самостоятельная остановка через** [**DELETE\_URL**](/ru/learn/orkestraciya/deployments.md#injected-environment-variables) - развертывание само остановилось после ухода игроков и завершения матча, * см. [Unreal Engine](/ru/unreal-engine.md#stop-deployments) и [Unity](/ru/unity.md#stop-deployments) руководства по корректной остановке развертываний, * **Остановка из вашего бэкенда** - ваш бэкенд остановил это развертывание с помощью [API развертываний](https://docs.edgegap.com/api/#tag/Deployments/operation/deployment-delete), * **Максимальная длительность игры** - отведённое время в вашем [Приложения и версии](/ru/learn/orkestraciya/application-and-versions.md#safety-guardrails) истекло, * [Частные флоты](/ru/learn/orkestraciya/chastnye-floty.md) Хост, на котором работало ваше развертывание, был удалён через запланированное действие. {% hint style="info" %} После остановки развертывания, **мы запускаем корректное завершение** путём отправки `SIGTERM` сигнала вашему основному процессу, предоставляя короткий период завершения. По его истечении `SIGKILL` посылается сигнал для остановки развертывания. {% endhint %} ## 👀 Наблюдаемость Позвольте игровым серверам взаимодействовать с третьими сторонами и получать операционные инсайты. ### Обнаруживаемость После перехода в Ready развертыванию назначается URL ([fqdn](https://en.wikipedia.org/wiki/Fully_qualified_domain_name)) и внешний порт для каждого внутреннего порта. {% hint style="success" %} Используйте **теги развертывания (до 40 символов), чтобы легко отмечать ваши развертывания** и [#filter-deployments](#filter-deployments "mention"). {% endhint %} {% hint style="info" %} **Исходящий трафик (к клиентам или бэкенду) от ваших игровых серверов никогда не блокируется** или не фильтруется. {% endhint %} #### **WebSocket (WS) и Secure WebSocket (WSS)** Чтобы использовать неткод на базе WebSocket с Edgegap, у вас есть два варианта: * **управляемый сертификат**, настраиваемый за 1 минуту без написания кода: * настройте ваш [Приложения и версии](/ru/learn/orkestraciya/application-and-versions.md) на **используйте WebSocket (WS) и включите TLS Upgrade,** * используйте URL Edgegap для подключения клиентов (например, `https://5fa53fa00a57.pr.edgegap.net/`) * **самоуправляемый сертификат**, если вы хотите использовать свой собственный домен: * настройте ваш [Приложения и версии](/ru/learn/orkestraciya/application-and-versions.md) на **используйте Secure WebSocket (WSS)**, * настройте собственный процесс TLS-сертификата с пользовательской DNS-записью (например, в [Cloudflare](https://www.cloudflare.com/application-services/products/ssl/)). {% hint style="danger" %} Необработанные исключения сервера приведут к перезапуску контейнера развертывания и нарушат TLS-безопасность. В таком случае, [остановите ваш сервер](#id-5.-deployment-stopped) и [снова подобрать игроков для нового развертывания](/ru/learn/podbor-matchei.md#custom-lobby). [Состояние сервера может быть утрачено](/ru/learn/orkestraciya/sokhranenie-sostoyaniya.md#state-management). {% endhint %} ### Внедрённые переменные Игровым серверам часто требуется дополнительная информация, такая как IP сервера, значения внутренних портов и другое. Внедрение переменных окружения только для чтения — надёжный, не зависящий от облака способ передавать параметры. {% hint style="success" %} Получайте значения переменных с помощью [GetEnvironmentVariable в C#](https://learn.microsoft.com/en-us/dotnet/api/system.environment.getenvironmentvariable?view=net-8.0) или [GetEnvironmentVariable в C++](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Runtime/Core/GenericPlatform/FGenericPlatformMisc/GetEnvironmentVariable). {% endhint %} {% hint style="info" %} См. [Переменные версии приложения](/ru/learn/orkestraciya/application-and-versions.md#injected-variables) и [Переменные матчмейкера](/ru/learn/podbor-matchei/matchmaker-in-depth.md#injected-variables) в дополнение к переменным развертывания ниже. {% endhint %} #### **Пользовательские переменные** Определите до 20 пользовательских переменных для каждого развертывания, каждая из которых содержит до 4 КБ строковых данных. {% hint style="warning" %} **Избегайте использования зарезервированных имён (ниже), иначе ваши пользовательские переменные будут перезаписаны!** {% endhint %} Получайте важную информацию, читая переменные, внедрённые Edgegap в ваши серверы: #### **Идентификаторы** * **`ARBITRIUM_REQUEST_ID`** - напр. `f68e011bfb01` . * Уникальный ID развертывания, также называемый request ID. Используется для получения дополнительной информации. * URL-адреса развертывания всегда имеют формат `{ARBITRIUM_REQUEST_ID}.pr.edgegap.net`. * **`ARBITRIUM_PUBLIC_IP`** - напр. `162.254.141.66` . * Публичный IP-адрес этого хоста, может использоваться для подключения вместо URL. * **`ARBITRIUM_HOST_ID`** - напр. `alpha-north-america-70364ef8` . * Уникальный идентификатор машины, на которой размещено ваше развертывание, общий для других развертываний. * **`ARBITRIUM_DEPLOYMENT_TAGS`** - напр. `tag1,tag2` . * Пользовательские теги развертывания, разделённые запятыми, [полезные для удобного поиска и фильтрации](#filter-deployments). * **`ARBITRIUM_PRIVATE_FLEET_ID`** - напр. `PUBLIC_CLOUD` , или ID флотилии, если размещено в [Частные флоты](/ru/learn/orkestraciya/chastnye-floty.md). #### Характеристики ресурсов * **`ARBITRIUM_HOST_IN_PRIVATE_FLEET`** - напр. `false` , указывающий, размещено ли на [Частные флоты](/ru/learn/orkestraciya/chastnye-floty.md). * **`ARBITRIUM_HOST_BASE_CLOCK_FREQUENCY`** - напр. `2000` , частота процессора в МГц. * **`ARBITRIUM_DEPLOYMENT_VCPU_UNITS`** - напр. `256`, выделенные единицы vCPU (1024 = 1 vCPU). * **`ARBITRIUM_DEPLOYMENT_MEMORY_MB`** - напр. `512`, выделенная оперативная память в МБ (1024 = 1 ГБ). #### **Управление жизненным циклом** * **`ARBITRIUM_DELETE_URL`** - напр. `https://api.edgegap.com/v1/self/stop/9f511e17/660`. * Вызывается из развертывания, [развертывание будет корректно остановлено](#id-5.-deployment-stopped). * Требует уникальный одноразовый `ARBITRIUM_DELETE_TOKEN` в `Authorization` заголовке. * **`ARBITRIUM_DELETE_TOKEN`** - напр. `7df4cd933df87084b34ae80d8abde293`. * **`ARBITRIUM_CONTEXT_URL`** - напр. `https://api.edgegap.com/v1/context/9170f5211e17/17`. * Вызывается только из развертывания, возвращает больше сведений о развертывании. * Требует уникальный `ARBITRIUM_CONTEXT_TOKEN` в `Authorization` заголовке. * **`ARBITRIUM_CONTEXT_TOKEN`** - напр. `dfaf50b9333b9ee07b22ed247e4a17e6`. #### **Обнаруживаемость** * **`ARBITRIUM_PORT_GAMEPORT_INTERNAL`** - напр. `7777` , внутренний порт для прослушивателя сервера. * **`ARBITRIUM_PORT_GAMEPORT_EXTERNAL`** - напр. `31504` , внешний порт для подключений клиентов. * Значения внешних портов случайным образом меняются для каждого развертывания в целях безопасности. * **`ARBITRIUM_PORT_GAMEPORT_PROTOCOL`** - напр. `UDP` , протокол вашего сетевого транспорта. {% hint style="success" %} В примерах предполагается, что вы назвали свой порт `gameport` (по умолчанию). **Каждый порт добавляет дополнительный набор очищенных** [Приложения и версии](/ru/learn/orkestraciya/application-and-versions.md#port-mapping) **переменных:** `@Супер порт!` ⇒ `ARBITRIUM_PORT_SUPER_PORT_INTERNAL` . {% endhint %} * **`ARBITRIUM_BEACON_ENABLED`** - напр. `true`, если развертывание выполняется на [Частные флоты](/ru/learn/orkestraciya/chastnye-floty.md) с [Ping Beacons](/ru/learn/orkestraciya/ping-beacons.md). * **`ARBITRIUM_HOST_BEACON_PUBLIC_IP`** - напр. `139.177.198.69` , публичный IP ближайшего маяка. * **`ARBITRIUM_HOST_BEACON_PORT_UDP_EXTERNAL`** - напр. `30199`, для измерения пинга по UDP. * **`ARBITRIUM_HOST_BEACON_PORT_TCP_EXTERNAL`** - напр. `30456`, для измерения пинга по TCP. #### **Структурированная информация (JSON как строка)** {% hint style="info" %} Переменные окружения **хранятся в виде JSON-строк**, разбирайте их с помощью SDK или собственного метода. {% endhint %}
ARBITRIUM_DEPLOYMENT_LOCATION:
- Подробная информация о местоположении развертывания. ```json ARBITRIUM_DEPLOYMENT_LOCATION="{ "city": "Монреаль", "country": "Канада", "continent": "Северная Америка", "administrative_division": "Квебек", "timezone": "Восточное время", "latitude": 45.513707, "longitude": -73.619073 }" ```
ARBITRIUM_PORTS_MAPPING:
- Подробная информация о ваших внутренних и внешних портах. ```json ARBITRIUM_PORTS_MAPPING="{ "ports": { "gameport": { "name": "Игровой порт", "internal": 7777, "external": 31504, "protocol": "UDP" }, "webport": { "name": "Веб-порт", "internal": 8888, "external": 31553, "protocol": "TCP" } } }" ```
### Мониторинг на панели управления Наш [Панель управления](https://app.edgegap.com/) предоставляет инструменты для мониторинга масштабируемости вашего сервера и помощи в эксплуатации. #### Аналитика {% hint style="success" %} Найдите [аналитические панели в боковом меню](https://app.edgegap.com/analytics/dashboards/list) в категории Хостинг серверов и оркестрация. {% endhint %} :star2: [**Перейдите на тариф Pay as You Go**](https://app.edgegap.com/user-settings?tab=memberships) **чтобы получить доступ к подробным метрикам и аналитике производительности сервера:** * **Общая аналитика:** отслеживайте релизы с текущим числом серверов по версиям + обзором использования ресурсов, * **Аналитика ЦП**: устраняйте задержки серверов из-за ресурсоёмких операций процессора, * **Аналитика памяти**: предотвращайте перезапуски сервера из-за превышения выделенной памяти, * **Аналитика сети:** выявляйте неэффективные сетевые паттерны и оптимизируйте netcode.
#### Карта развертываний {% hint style="success" %} Найдите карту развертываний в [на странице сведений о вашем развертывании на панели управления](https://app.edgegap.com/deployment-management/deployments/list). {% endhint %} Просматривайте на карте местоположение развертывания, доступные локации и предполагаемые местоположения игроков:
#### Точки баланса развертывания {% hint style="success" %} Найдите тепловую карту точек баланса развертывания в [на странице сведений о вашем приложении на панели управления](https://app.edgegap.com/application-management/applications/list). {% endhint %} Просматривайте тепловую карту точек баланса развертывания и фильтруйте по [Приложения и версии](/ru/learn/orkestraciya/application-and-versions.md). Точки баланса — это приблизительные локации с одинаковой сетевой близостью к каждому игроку в конкретном развертывании:
{% hint style="warning" %} Очаги точек баланса в необычных местах (например, в Гренландии) указывают на подбор игроков, находящихся далеко друг от друга. Узнайте о [#connection-quality](#connection-quality "mention") и [Ping Beacons](/ru/learn/orkestraciya/ping-beacons.md) том, как оптимизировать подбор игроков. {% endhint %} #### Логи развертывания {% hint style="success" %} Найдите логи развертывания в [на странице сведений о вашем развертывании на панели управления](https://app.edgegap.com/deployment-management/deployments/list). {% endhint %} Логи развертывания отображают информацию о [#deployment-lifecycle](#deployment-lifecycle "mention"):
#### Логи контейнера {% hint style="success" %} Найдите логи контейнера в [на странице сведений о вашем развертывании на панели управления](https://app.edgegap.com/deployment-management/deployments/list). {% endhint %} Просматривайте логи игрового сервера в случае проблем или при отладке:
{% hint style="warning" %} **После остановки развертывания логи контейнера удаляются.** Настройте [стороннее S3-хранилище логов](/ru/docs/endpoint-storage.md) для сохранения логов. {% endhint %} #### Метрики контейнера {% hint style="success" %} Найдите метрики контейнера в [на странице сведений о вашем развертывании на панели управления](https://app.edgegap.com/deployment-management/deployments/list). {% endhint %} Просматривайте метрики контейнера (процессор, память, сеть), чтобы: * выявлять распространённые проблемы с подключением, когда [#troubleshooting](#troubleshooting "mention"), * обнаруживать неэффективные шаблоны реализации, вызывающие всплески использования ресурсов, * выявлять неэффективное использование ресурсов в конкретных сценариях, * проверять изменения в использовании ресурсов вашего сервера во время оптимизации, * сравнивать потребление ресурсов и длительность инициализации вашего сервера. Исторические метрики отображают средние значения за 1-минутный период и доступны на тарифе Free. :star2: [**Перейдите на тариф Pay as You Go**](https://app.edgegap.com/user-settings?tab=memberships) **чтобы получить точные метрики с интервалом в 1 секунду.**
{% hint style="info" %} [Свяжитесь с нами](mailto:info@edgegap.com) до вашего релиза, чтобы запросить поддержку живого хостинга для релизов крупного масштаба. {% endhint %} ### Контекст и статус Дополнительную информацию о развертывании можно получить в формате JSON: * изнутри развертывания (игрового сервера) с помощью [API контекста развертывания](https://docs.edgegap.com/api/#tag/Context/operation/context-get), * снаружи развертывания (backend / сторонняя система) с помощью [API статуса развертывания](https://docs.edgegap.com/api/#tag/Deployments/operation/deployment-status-get). {% hint style="info" %} API контекста (из развертывания) требует токен API контекста, тогда как API статуса использует ваш токен Edgegap. {% endhint %} {% hint style="danger" %} **Слишком много запросов 429 — для API контекста и статуса действует ограничение 20 запросов/с на организацию.** {% endhint %} {% hint style="success" %} **Используйте** [#webhooks](#webhooks "mention") **для автоматизаций (пользовательского подбора игроков), чтобы избежать ограничений по частоте запросов и обеспечить масштабируемость.** API контекста и статуса предназначены только для разработки, QA и устранения неполадок. {% endhint %} ### Фильтрация развертываний Чтобы быстро искать среди всех развертываний, вы можете [использовать нашу панель управления](https://app.edgegap.com/deployment-management/deployments/list):
[Список развертываний через API](https://docs.edgegap.com/api/#tag/Deployments/operation/deployments-get) и применять фильтры с помощью интеграций backend:
Атрибут развертыванияОператорыПример значения
statuseq или neq"ready" или "error"
request_ideq "7e709a0d8efd"
в или nin[ "7e709a0d8efd", "4ba353100b4b" ]
tagseq или neq"tagA"
в или nin[ "tagA", "tagB" ]
created_ateq или lte или gte2025-05-12T20:03:20Z
applicationeq или neq"my-app"
в или nin[ "my-app", "my-other-app" ]
versioneq или neq"1.0.0"
в или nin[ "1.0.0", "prod" ]
fleet_nameeq или neq"my-app-fleet-europe"
в или nin[ "fleet-eu", "fleet-us" ]
ilike"%-eu%"
host_nameeq или neq"alpha-north-america-95fab093"
в или nin[ "alpha-north-america-95fab093" ]
ilike"%north-america%"
{% hint style="info" %} Каждый атрибут может иметь не более 1 оператора фильтра в одном запросе. См. [Справочник API](/ru/docs/api.md) подробнее. {% endhint %} Сортируйте результаты по нескольким полям в порядке их появления в запросе: | Атрибут развертывания | Порядок | | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | | [`created_at`](#id-1.-start-a-deployment) | [`asc`](#user-content-fn-11)[^11] или [`desc`](#user-content-fn-12)[^12] | | [`available_session_sockets`](broken://pages/af47f00633ef43a181ec41a0562bbc4e007a3046) | [`asc`](#user-content-fn-13)[^13] или [`desc`](#user-content-fn-14)[^14] | Примеры запросов фильтрации:
Список Развертывания с ошибкой для устранения неполадок и удаления. Закодированный URL: ``` https://api.edgegap.com/v1/deployments?query={"filters":[{"field":"status","operator":"eq","value":"error"},{"field":"application","operator":"eq","value":"my-app"},{"field":"version","operator":"eq","value":"green"}],"order_by":[{"field":"created_at","order":"desc"}]} ``` Форматированный JSON-запрос: ```json { "filters": [ { "field": "status", "operator": "eq", "value": "error" }, { "field": "application", "operator": "eq", "value": "my-app" }, { "field": "version", "operator": "eq", "value": "green" } ], "order_by": [ { "field": "created_at", "order": "desc" } ] } ```
Список Развертывания с устаревшей версией приложения чтобы подтвердить, что релиз завершён. Закодированный URL: ``` https://api.edgegap.com/v1/deployments?query={"filters":[{"field":"status","operator":"eq","value":"ready"},{"field":"application","operator":"eq","value":"my-app"},{"field":"version","operator":"eq","value":"blue"}],"order_by":[{"field":"created_at","order":"desc"}]} ``` Форматированный JSON-запрос: ```json { "filters": [ { "field": "status", "operator": "eq", "value": "ready" }, { "field": "application", "operator": "eq", "value": "my-app" }, { "field": "version", "operator": "eq", "value": "blue" } ], "order_by": [ { "field": "created_at", "order": "desc" } ] } ```
{% hint style="success" %} Не забудьте добавить `Authorization` заголовок с вашим токеном Edgegap API в запрос. {% endhint %} ### Вебхуки Получайте простые HTTP-уведомления в вашем игровом backend при изменениях в [#deployment-lifecycle](#deployment-lifecycle "mention") указав URL вебхука в вашем [запросе к API развертывания](/ru/docs/api/vydelennye-servery.md#post-deployments). Доступно для: * При готовности: контейнер развертывания [успешно запущен](#id-1.-start-a-deployment) (после этого сервер начинает инициализацию), * При ошибке: развертывание не удалось запустить и [#id-4.-deployment-error](#id-4.-deployment-error "mention") произошла ошибка, * При завершении: [#id-5.-deployment-stopped](#id-5.-deployment-stopped "mention") и игровой сервер больше недоступен. Вебхуки Ready и Error никогда не будут срабатывать для одного и того же развертывания.
Пример полезной нагрузки вебхука ```json { "request_id": "f68e011bfb01", "application": "my-game-server", "version": "2024.01.30-16.23.00-UTC", "fqdn": "f68e011bfb01.pr.edgegap.net", "public_ip": "162.254.141.66", "deployed_at": "2026-02-10T20:35:48Z", "termination_scheduled_at": "2026-02-10T21:35:48Z", "ports": { "gameport": { "external": 31504, "internal": 7777, "protocol": "UDP", "name": "gameport", "tls_upgrade": false, "link": "f68e011bfb01.pr.edgegap.net:31504", "proxy": null } }, "location": { "city": "Монреаль", "country": "Канада", "continent": "Северная Америка", "administrative_division": "Квебек", "timezone": "Восточное время", "latitude": 45.513707, "longitude": -73.619073 }, "tags": [ "tag1", "tag2" ], "host_id": "alpha-north-america-70364ef8", "host_in_private_fleet": false, "private_fleet_id": "PUBLIC_CLOUD", "vcpu_units": 256, "memory_mib": 512 } ```
{% hint style="success" %} **Вебхуки — основной рекомендуемый способ интеграции развертывания с пользовательским backend.** {% endhint %} {% hint style="warning" %} **Вебхуки не повторяются**, и могут быть потеряны, если ваш backend не обработает запрос из-за ограничения частоты или ошибки. В случае если вы не получили вебхук в ожидаемое время, используйте API статуса. {% endhint %} {% hint style="info" %} Вебхуки отслеживают жизненный цикл развертывания, но не знают о состоянии инициализации вашей сцены/уровня. Чтобы отслеживать прогресс загрузки вашей сцены/уровня, реализуйте собственный вебхук в вашем игровом сервере. {% endhint %} ## 🚨 Устранение неполадок При устранении неполадок развертываний: 1. убедитесь, что нет ошибок в вашем [#deployment-logs](#deployment-logs "mention") и [#container-logs](#container-logs "mention"), 2. запустите сервер локально, чтобы исключить ошибки интеграции, 3. изучите шаги по устранению неполадок на этой странице, 4. свяжитесь с нами в [Discord сообщества](https://discord.gg/MmJf8fWjnt) и укажите свой ID развертывания. {% hint style="info" %} См. [#player-issue-resolution](#player-issue-resolution "mention") чтобы ознакомиться с нашими рекомендациями по работе с отзывами игрового сообщества. {% endhint %}
Не удается подключить клиентов к серверу - Время ожидания запроса истекло., Время ожидания запроса истекло , Сбой подключения , или Проверка порта не удалась. * Сначала убедитесь, что развертывание находится в состоянии Ready, и что в журнале вашего развертывания нет исключений или ошибок во время выполнения. Если ваше развертывание остановилось, проверьте логи в нашем [Панель управления](https://app.edgegap.com/deployment-management/deployments/list). * Если вы используете netcode Mirror, вам нужно иметь [«Auto Start Server»](https://mirror-networking.gitbook.io/docs/hosting/edgegap-hosting-plugin-guide#build-and-push) выбранным в вашем `NetworkManager` , пересоберите, отправьте и разверните сервер заново. * Если вы используете netcode FishNet, вам нужно включить [«Start on Headless»](https://fish-networking.gitbook.io/docs/manual/components/managers/server-manager#settings-are-general-settings-related-to-the-servermanager) в вашем `ServerManager`, пересоберите, отправьте и разверните сервер заново. * Если вы используете netcode Photon Fusion 2, убедитесь, что ваш сервер передает публичный IP развертывания, внешний порт и `roomCode` на сервере, а также тот же код комнаты на клиенте в [«NeworkRunner.StartGame»](https://doc.photonengine.com/fusion/current/manual/network-runner#creating-or-joining-a-room) параметре `StartGameArgs`. ID развертывания (например, `b63e6003b19f`) — отличный выбор, поскольку он глобально уникален и легко доступен клиенту по назначению и для [Матчмейкер](/ru/learn/podbor-matchei/matchmaker-in-depth.md) назначения, а также для [Подробный обзор](/ru/learn/podbor-matchei/matchmaker-in-depth.md#injected-environment-variables). * Далее, пожалуйста, убедитесь, что настройка порта в параметрах netcode вашей серверной сборки совпадает с внутренним портом в вашем [версии приложения](https://app.edgegap.com/application-management/applications/list). Вы можете изменить сопоставление портов, отредактировав [версии приложения](https://app.edgegap.com/application-management/applications/list) без пересборки. Найдите свой протокол в интеграции netcode. * Пожалуйста, убедитесь, что ваш игровой клиент подключается к **внешнему порту** указанному на странице сведений о вашем развертывании; это значение всегда будет случайным из соображений безопасности. * Если вы используете в своей интеграции netcode протокол Secure Websocket (WSS), пожалуйста, убедитесь, что в вашей [версии приложения](https://app.edgegap.com/application-management/applications/list) конфигурации порта для WSS-порта включено TLS Upgrade. * Вы находитесь в Китае и используете [Smart Fleets](https://docs.edgegap.com/docs/deployment/session/fleet-manager/fleet)? Ваше соединение может быть заблокировано Великим китайским файрволом. Рассмотрите возможность добавить в ваш флот сервер, расположенный в Китае, или использовать VPN для подключения.
Мое развертывание остановилось/перезапустилось, и я больше не могу получить доступ к его логам. * Если процесс сервера завершается из-за исключения, наша система автоматически попытается перезапустить сервер. Рекомендуем протестировать сервер локально, чтобы выявить первопричину. * Мы храним логи только в течение срока действия развертывания; если вы хотите просматривать логи после остановки развертывания, пожалуйста, [интегрируйте стороннее хранилище логов](https://docs.edgegap.com/docs/deployment/endpoint-storage). * См. [#id-5.-deployment-stopped](#id-5.-deployment-stopped "mention") чтобы выявить все причины остановки вашего развертывания.
Мое развертывание автоматически остановилось через X минут. * Развертывания на Free Tier имеют ограничение по времени в 60 минут, пожалуйста, рассмотрите возможность обновления вашего аккаунта. * Все развертывания будут завершены после 24 часов работы в соответствии с нашей политикой очистки серверов, для обслуживания инфраструктуры и чтобы предотвратить неожиданные расходы, если развертывание не было корректно остановлено. Для серверов с длительным временем работы рассмотрите использование [Частные флоты](/ru/learn/orkestraciya/chastnye-floty.md) с [Сохранение состояния](/ru/learn/orkestraciya/sokhranenie-sostoyaniya.md). * См. [#id-5.-deployment-stopped](#id-5.-deployment-stopped "mention") чтобы выявить все причины остановки вашего развертывания.
Мое развертывание готово, но после этого я не могу подключиться в течение нескольких минут. * После того как развертывание становится Ready, начинается инициализация вашего игрового движка. Этот процесс может занять от нескольких секунд до нескольких минут, и в этот период сервер не принимает подключения игроков. * Рассмотрите возможность оптимизации инициализации сервера, чтобы сократить этот промежуток времени. * Игровые клиенты должны повторять попытку подключения с интервалом в 1 секунду в течение ограниченного времени (в зависимости от длительности инициализации), после чего они возвращаются в матчмейкинг. * Рассмотрите возможность добавления загрузочного уровня, чтобы сервер мог выполнять инициализацию (и переход в случае Unreal Engine) одновременно с клиентами, синхронизируя состояние обоих.
На моем устройстве Meta Quest возникает HTTP 0: Не удается разрешить адрес назначения . * При сборке приложений Unity для Android ваше разрешение на доступ в интернет может автоматически удаляться из выходного артефакта сборки клиента APK. * Снова добавьте разрешения в (после этого потребуется пересобрать клиент): * Project Settings / OpenXR / :gear: Поддержка Meta Quest / Принудительно удалить разрешения на доступ в интернет (снимите флажок). * Player Settings / Internet Access (установите в значение «Require»).
Что произойдет, если игрок покинет мое развертывание? * По умолчанию серверы не отклоняют подключения игроков. Аутентификация игроков зависит от ваших разработчиков, поскольку можно использовать множество различных методов и провайдеров аутентификации игроков. * Игровые клиенты могут локально сохранять информацию о подключении, чтобы попытаться переподключиться в случае непредвиденного сбоя клиента. * Чтобы позволить игрокам присоединяться к идущим играм, рассмотрите возможность использования [Подробный обзор](/ru/learn/podbor-matchei/matchmaker-in-depth.md#backfill) или [Сессии](https://docs.edgegap.com/docs/deployment/session).
После перехода в состояние Ready мой сервер показывает 100% загрузку CPU. * Это может не быть проблемой, поскольку игровые движки обычно выполняют ресурсоемкие операции CPU во время инициализации сервера. Если загрузка CPU не снизится через 2–3 минуты после запуска развертывания, возможно, вам нужно оптимизировать сервер или увеличить ресурсы версии приложения. * Снижение частоты тиков может повлиять на загрузку CPU, поскольку сервер выполняет меньше операций обмена сообщениями. * Если вы используете netcode Mirror, вам нужно иметь [«Auto Start Server»](https://mirror-networking.gitbook.io/docs/hosting/edgegap-hosting-plugin-guide#build-and-push) выбранным в вашем `NetworkManager` , пересоберите, отправьте и разверните сервер заново. * Если вы используете netcode FishNet, вам нужно включить [«Start on Headless»](https://fish-networking.gitbook.io/docs/manual/components/managers/server-manager#settings-are-general-settings-related-to-the-servermanager) в вашем `ServerManager`, пересоберите, отправьте и разверните сервер заново. * В Free Tier вы ограничены 1,5 vCPU и 3 ГБ памяти (RAM). * Вы можете увеличить выделенные ресурсы при создании новой версии приложения. Вы можете дублировать версию приложения в нашей панели управления и при необходимости изменять эти значения, без пересборки сервера или образа.
Мое развертывание постоянно перезапускается и показывает ошибку `OOM kill` . * Такое поведение вызвано превышением выделенного объема памяти. Рассмотрите возможность оптимизации использования памяти с помощью пула объектов, сжатия или удаления ненужных объектов в вашей сцене. * Убедитесь, что в вашем проекте загружается сцена по умолчанию, содержащая ваш `NetworkManager` и что сцена включена в Build Settings Unity. * В Free Tier вы ограничены 1,5 vCPU и 3 ГБ памяти (RAM). * Вы можете увеличить выделенные ресурсы при создании новой версии приложения. Вы можете дублировать версию приложения в нашей панели управления и при необходимости изменять эти значения, без пересборки сервера или образа.
Иногда использование памяти (RAM) моего сервера резко подскакивает до высокого значения — это проблема? * Пока вы укладываетесь в выделенный объем памяти версии приложения, это не проблема. * Превышение выделенного объема памяти версии приложения приведет к \`OOM kill\` (см. выше).
Будет ли производительность моего сервера затронута другими серверами, работающими на той же машине? * Нет, наша платформа гарантирует, что выделенные ресурсы не будут использоваться другими студиями или другими серверами на общей инфраструктуре. С Edgegap нет шумных соседей.
[^1]: сессии могут длиться до 24 часов [^2]: равно [^3]: не равно [^4]: request\_id (ID развертывания) [^5]: в массиве [^6]: не в массиве [^7]: меньше или равно [^8]: больше или равно [^9]: в массиве [^10]: сопоставление с шаблоном без учёта регистра: * используйте `%` для любой последовательности * используйте `_` для любого одного символа [^11]: по возрастанию, сначала самые старые [^12]: по убыванию, сначала самые новые [^13]: по возрастанию, сначала заполненные [^14]: по убыванию, сначала пустые --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.edgegap.com/ru/learn/orkestraciya/deployments.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.