App Hosting – это простое в использовании и обслуживании решение, настройки по умолчанию которого подходят для большинства случаев. В то же время App Hosting предоставляет инструменты для управления и настройки бэкендов в соответствии с вашими потребностями. В этом руководстве описаны инструменты и процессы, которые помогут вам в этом.
Как задавать и обновлять переменные среды и секреты
App Hosting позволяет использовать переменные среды для неконфиденциальных значений конфигурации и секреты для конфиденциальных параметров, таких как ключи API, учетные данные базы данных и токены сервисов.
- Стандартные переменные среды. Используются для неконфиденциальных конфигураций в виде обычного текста, например URL общедоступных API, флагов функций или целей сборки. Значения видны всем участникам проекта.
- Секреты. Используются для конфиденциальных параметров, таких как секретные коды клиентов OAuth, токены API или пароли баз данных. Секреты поддерживаются Cloud Secret Manager. Значения секретов защищены и никогда не отображаются в виде обычного текста в консоли Firebase. Вместо этого в консоли предоставляются ссылки на контент для просмотра значений секретов и управления ими непосредственно в Cloud Secret Manager.
Определять параметры среды и управлять ими можно двумя способами:
- Консоль Firebase. Быстро добавляйте, редактируйте и прикрепляйте секреты или переменные динамически во время первоначального создания бэкенда или после развертывания в настройках бэкенда.
Сначала код (
apphosting.yaml). Объявите переменные среды и ссылки на секреты в файле конфигурации репозитория для развертываний с контролем версий или используйтеapphosting.<env>.yaml, чтобы задать разные значения для разных сред.
Консоль Firebase

apphosting.yaml
env:
- variable: STORAGE_BUCKET
value: mybucket.firebasestorage.app
- variable: API_KEY
secret: myApiKeySecret
Управление переменными и секретами в консоли Firebase
Вы можете настроить переменные среды и секреты в консоли Firebase при создании бэкенда или в любое время в его настройках. Изменения, сохраненные без развертывания, вступят в силу при следующем развертывании и не повлияют на текущее.
Как настроить переменные и секреты при создании бэкенда
При создании нового бэкенда App Hosting в консоли Firebase вы можете настроить стандартные переменные среды и секреты на шаге Configure your backend (Настройка бэкенда) мастера настройки.
- В консоли Firebase перейдите в раздел Hosting & Serverless (Хостинг и бессерверная архитектура) > App Hosting (Хостинг приложений) и нажмите Create backend (Создать серверную часть).
- Выполните начальные шаги мастера, чтобы выбрать основной регион и репозиторий кода.
- В разделе Настройка бэкенда найдите сворачиваемые карточки Переменные среды и Секреты, где можно добавить стандартные переменные и прикрепить секреты.
- Завершите работу с мастером создания серверной части и нажмите Finish & deploy (Завершить и развернуть).
Управление переменными и секретами в настройках бэкенда
Вы можете просматривать, добавлять, изменять и удалять переменные среды и секреты для активных бэкендов на панели настроек бэкенда.
- В консоли Firebase выберите серверную часть App Hosting и откройте Settings (Настройки) > Environment (Среда).
- Проверьте существующие конфигурации в таблице Переменные среды:
- Стандартные переменные. Значения отображаются в виде обычного текста в блоках кода, которые можно скопировать.
- Секреты. Отображаются в виде кликабельной ссылки с названием секрета (открывает Cloud Secret Manager в консоли Google Cloud) и его целевой версией (например,
latestили конкретным номером версии, таким как2).
- Чтобы добавить переменную или секрет:
- Нажмите Добавить.
- В разделе Шаг 1. Выберите тип выберите Стандартная переменная среды (для неконфиденциальных данных, видимых всем участникам проекта) или Секрет (для ключей API и конфиденциальных учетных данных с ограниченным доступом), а затем нажмите Далее.
- В разделе Шаг 2. Задайте настройки укажите название ключа и либо значение в виде обычного текста (для стандартных переменных), либо идентификатор и версию секрета (для секретов).
- Сохраните изменения, выбрав один из следующих вариантов:
- Сохранить и развернуть. Конфигурация бэкенда будет обновлена немедленно, после чего начнется сборка и развертывание.
- Просто сохранить (из значка раскрывающегося списка рядом с кнопкой Сохранить и развернуть). Изменения в конфигурации будут сохранены, но немедленного развертывания не произойдет. Обновленные настройки вступят в силу при следующем развертывании.
- Чтобы изменить или удалить существующую запись, нажмите на меню Дополнительные действия (
...) в конце строки.- Нажмите Изменить, чтобы изменить ключ, значение, сопоставление секрета или версию, а затем нажмите Сохранить и развернуть или Сохранить.
- Нажмите Удалить и подтвердите действие в диалоговом окне.
Перенос переменных из dotenv файлов
Для приложений Next.js файлы dotenv, содержащие переменные среды, работают с App Hosting.
При создании или обновлении бэкенда вы можете перенести переменные среды из файла dotenv в консоль Firebase, скопировав и вставив все содержимое файла dotenv в первое поле Ключ в форме Добавить в разделе Настройки > Среда.
Все переменные среды, скопированные таким образом, автоматически форматируются в форму без необходимости вводить каждую из них по отдельности, если входные данные используют стандартное форматирование KEY=value:
KEY1=value1
KEY2=value2
KEY3=value3
Для сложного или детального управления переменными среды в любом фреймворке мы рекомендуем использовать apphosting.yaml.
Управление переменными и секретами в apphosting.yaml
Если вы используете рабочие процессы, в которых код имеет приоритет, объявите стандартные переменные среды и ссылки на секреты в ключе env: в файле конфигурации apphosting.yaml репозитория проекта (см. раздел Создание и редактирование файла apphosting.yaml).
env:
# Standard environment variables
- variable: PUBLIC_API_URL
value: https://api.example.com
availability:
- BUILD
- RUNTIME
- variable: FEATURE_FLAG_NEW_UI
value: "true"
# Secret references backed by Cloud Secret Manager
- variable: DATABASE_URL
secret: projects/PROJECT_ID/secrets/db-connection-string/versions/latest
- variable: GEMINI_API_KEY
secret: myGeminiApiKeySecret@1
Каждая запись в env: поддерживает следующие поля:
variable– имя переменной среды, доступной процессу приложения.value– строковое значение в виде обычного текста (для стандартных переменных среды).secret– ссылка на секрет Cloud Secret Manager (для секретов). Вы можете использовать короткое название секрета (например,myGeminiApiKeySecretили закрепленноеmyGeminiApiKeySecret@1) или полный путь к ресурсу (projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION). Подробнее о хранении секретных параметров и доступе к ним…availabilityопределяет, доступна ли переменная или секретный ключ на этапеBUILD,RUNTIMEили на обоих.
Как настроить доступность переменной
Переменные среды и секреты, настроенные в консоли Firebase, доступны как во время сборки, так и во время выполнения. Это также режим работы по умолчанию для записей, определенных в apphosting.yaml, если вы не сузите область действия с помощью свойства availability. В apphosting.yaml (но не в консоли) вы можете ограничить переменную или секрет только средой сборки (BUILD) или только средой выполнения (RUNTIME).
Как получить доступ к переменным и секретам в коде приложения
Независимо от того, где вы настраиваете переменные среды и секреты (в консоли Firebase или apphosting.yaml), они доступны среде выполнения приложения как стандартные переменные среды (например, process.env в Node.js).
// Accessing a standard environment variable
const apiUrl = process.env.PUBLIC_API_URL;
// Accessing a secret
const apiKey = process.env.GEMINI_API_KEY;
export async function fetchData() {
const response = await fetch(`${apiUrl}/data`, {
headers: {
'Authorization': `Bearer ${apiKey}`
}
});
return response.json();
}
- Доступ на стороне сервера. Все переменные среды и секреты доступны в контекстах выполнения на стороне сервера (например, в компонентах сервера Next.js, маршрутах API или обработчиках серверной части Node.js).
Доступность на стороне клиента. Чтобы стандартные переменные среды были доступны браузеру во фреймворках, таких как Next.js, убедитесь, что ключ переменной соответствует соглашениям фреймворка (например, имеет префикс
NEXT_PUBLIC_).env: - variable: NEXT_PUBLIC_STORAGE_BUCKET value: mybucket.firebasestorage.app availability: - BUILD - RUNTIME
Иерархия переменных
Firebase App Hosting применяет переменные среды и секреты в порядке приоритета, основанном на их источнике. Конфигурации, заданные в консоли Firebase, всегда переопределяют параметры, объявленные в файлах apphosting.yaml и dotenv. Если переменная среды или секретный ключ с одним и тем же названием существует и в apphosting.yaml, и в консоли Firebase, то во время сборки и выполнения приоритет будет иметь значение из консоли.
Ниже приведен полный список в порядке приоритета.
- Консоль Firebase – переменные и секреты, заданные в консоли.
apphosting.<env>.yaml– переменные и секреты, указанные в YAML-файле для конкретной среды, напримерapphosting.staging.yaml(см. раздел Развертывание нескольких сред).apphosting.yaml– переменные и секреты, указанные в файлеapphosting.yaml.- Система Firebase – переменные, заданные Firebase и содержащие значения для
FIREBASE_CONFIGилиFIREBASE_WEBAPP_CONFIG, а также переменные среды, которые задают имена хостов и порты для приложений SSR (задаются адаптерами App Hosting вbundle.yaml).
Автоматически заполняемые переменные среды
Переменные среды автоматически заполняются App Hosting. К ним относятся переменные, заполняемые Google Cloud, а также переменные среды, относящиеся к Firebase, если во время настройки на сервере задано значение appId.
FIREBASE_CONFIG(доступно в средах сборки и выполнения) – предоставляет следующую информацию о конфигурации проекта Firebase:{ "databaseURL": "https://DATABASE_NAME.firebaseio.com", "storageBucket": " ", "projectId": "PROJECT_ID" }PROJECT_ID.firebasestorage.appЭта конфигурация применяется автоматически, когда вы инициализируете Firebase Admin SDK без аргументов.
FIREBASE_WEBAPP_CONFIG(доступно только в среде сборки) – предоставляет следующую информацию о конфигурации проекта Firebase:{ "apiKey": "API_KEY", "appId": "APP_ID", "authDomain": "AUTH_DOMAIN.firebaseapp.com", "databaseURL": "https://DATABASE_NAME.firebaseio.com", "messagingSenderId": "PROJECT_NUMBER", "projectId": "PROJECT_ID", "storageBucket": "/span> " }<PROJECT_ID.firebasestorage.appFirebase JS SDK автоматически проверяет эту
FIREBASE_WEBAPP_CONFIGпеременную среды в скрипте postinstall во время сборки, что позволяет инициализировать клиентский SDK без аргументов.
Подробнее о том, как использовать эти переменные среды для инициализации SDK, рассказывается в статье Автоматическая инициализация Firebase Admin SDK и веб-SDK.
Обратите внимание, что значения в вашей конфигурации Firebase будут соответствовать ресурсам, которые вы подготовили в своем проекте.
Иерархия переменных
Firebase App Hosting применяет переменные в порядке приоритета в зависимости от их источника. Например, значения, заданные в консоли Firebase, всегда переопределяют значения, заданные в файлах apphosting.yaml и dotenv.
Ниже приведен полный список в порядке приоритета.
- Консоль Firebase – переменные, заданные в консоли.
apphosting.<env>.yaml– переменные, указанные в YAML-файле для конкретной среды, напримерapphosting.staging.yaml(см. раздел Развертывание нескольких сред).apphosting.yaml– переменные, указанные в файлеapphosting.yaml.- Система Firebase – переменные, заданные Firebase и содержащие значения для
firebase_config jsonилиfirebase_webapp_config, а также переменные среды, которые задают имена хостов и порты для приложений SSR (задаются адаптерами App Hosting вbundle.yaml).
Зарезервированные названия и ограничения
Переменные среды, определенные в контракте среды выполнения контейнера Cloud Run, зарезервированы и не могут быть заданы.
Переменные среды, предоставляемые средой, за исключением тех, которые устанавливаются автоматически, могут измениться в будущих версиях среды выполнения. Рекомендуем не полагаться на переменные среды, которые вы не задавали явным образом, и не изменять их. Чтобы избежать конфликтов, добавляйте к переменным среды уникальный префикс.
Некоторые ключи переменных среды зарезервированы для внутреннего использования. Не используйте в файлах конфигурации следующие ключи:
- Пустые строки ("")
- Ключи, содержащие символ "="
- Ключи, начинающиеся с
X_FIREBASE_,X_GOOGLE_илиCLOUD_RUN_ PORTK_SERVICEK_REVISIONK_CONFIGURATION- Повторяющиеся ключи
Создание и редактирование apphosting.yaml
Для расширенной настройки, например секретов или параметров среды выполнения, таких как параллелизм, ЦП и ограничения памяти, вам нужно будет создать и отредактировать файл apphosting.yaml в корневом каталоге вашего приложения. Этот файл поддерживает ссылки на секреты, управляемые с помощью Cloud Secret Manager, что делает его безопасным для проверки в системе контроля версий.
Чтобы создать apphosting.yaml, выполните следующую команду:
firebase init apphosting
Будет создан базовый файл apphosting.yaml с примером конфигурации (в виде комментария). После редактирования типичный файл apphosting.yaml может выглядеть следующим образом, с настройками для сервиса Cloud Run бэкенда, некоторыми переменными среды и некоторыми ссылками на секреты, управляемые Cloud Secret Manager:
# Settings for Cloud Run
runConfig:
minInstances: 2
maxInstances: 100
concurrency: 100
cpu: 2
memoryMiB: 1024
# Environment variables and secrets
env:
- variable: STORAGE_BUCKET
value: mybucket.firebasestorage.app
availability:
- BUILD
- RUNTIME
- variable: API_KEY
secret: myApiKeySecret
# Same as API_KEY above but with a pinned version.
- variable: PINNED_API_KEY
secret: myApiKeySecret@5
# Same as API_KEY above but with the long form secret reference as defined by Cloud Secret Manager.
- variable: VERBOSE_API_KEY
secret: projects/test-project/secrets/secretID
# Same as API_KEY above but with the long form secret reference with pinned version.
- variable: PINNED_VERBOSE_API_KEY
secret: projects/test-project/secrets/secretID/versions/5
В этом руководстве вы найдете подробную информацию и контекст для этих примеров настроек.
Настройте параметры сервиса Cloud Run
В настройках apphosting.yaml можно задать параметры предоставления сервиса Cloud Run. Доступные настройки для сервиса Cloud Run указаны в объекте runConfig:
cpu– количество ЦП, используемых для каждого экземпляра обслуживания (по умолчанию1).memoryMiB– объем памяти, выделенный для каждого экземпляра показа, в МиБ (по умолчанию512).maxInstances– максимальное количество контейнеров, которые могут работать одновременно (по умолчанию100, управляется квотой).minInstances– количество контейнеров, которые должны быть всегда активны (по умолчанию0).concurrency– максимальное количество запросов, которое может получить каждый экземпляр (по умолчанию80).cpuAlwaysAllocated– выделен ли ЦП всегда, даже когда запросы не обрабатываются (по умолчаниюfalse).
Обратите внимание, что ограничения для cpu, memoryMiB и concurrency взаимозависимы. Например, для конфигураций с большим объемом памяти требуются более высокие минимальные ограничения ЦП, а для дробных ЦП требуется параллелизм 1. Допустимые диапазоны и необходимые комбинации указаны в документации Cloud Run по ограничениям ЦП и ограничениям памяти.
Переопределить скрипты сборки и запуска
App Hosting определяет команды сборки и запуска приложения на основе обнаруженного фреймворка. Если вы хотите использовать собственную команду сборки или запуска, вы можете переопределить значения по умолчанию App Hosting в apphosting.yaml.
scripts:
buildCommand: next build --no-lint
runCommand: node dist/index.js
Переопределение команды сборки имеет приоритет над любыми другими командами сборки, отключает адаптеры фреймворка для вашего приложения и отключает любые оптимизации, специфичные для фреймворка, которые предоставляет App Hosting. Этот вариант лучше всего подходит, если функции вашего приложения не поддерживаются адаптерами. Если вы хотите изменить команду сборки, но по-прежнему использовать предоставленные адаптеры, задайте скрипт сборки в package.json, как описано в разделе Адаптеры фреймворка App Hosting.
Используйте переопределение команды запуска, если вы хотите запустить приложение с помощью определенной команды, отличной от команды, выведенной App Hosting.
Настроить выходные данные сборки
По умолчанию App Hosting оптимизирует развертывание приложения, удаляя неиспользуемые выходные файлы, указанные фреймворком. Если вы хотите дополнительно оптимизировать размер развертывания приложения или игнорировать оптимизацию по умолчанию, вы можете переопределить это в apphosting.yaml.
outputFiles:
serverApp:
include: [dist, server.js]
Параметр include принимает список каталогов и файлов, связанных с корневым каталогом приложения, которые необходимы для развертывания приложения. Если вы хотите сохранить все файлы, задайте для параметра include значение [.], и все файлы будут развернуты.
Хранение секретных параметров и доступ к ним
Конфиденциальную информацию, например ключи API, следует хранить в секретах. Вы можете прикрепить секреты к серверной части в консоли Firebase или сослаться на них в apphosting.yaml, чтобы не добавлять конфиденциальную информацию в систему управления исходным кодом.
Параметры типа secret представляют собой строковые параметры, значение которых хранится в Cloud Secret Manager.
Вместо того чтобы получать значение напрямую, секретные параметры проверяют наличие в Cloud Secret Manager и загружают значения во время развертывания.
env:
- variable: API_KEY
secret: myApiKeySecret
У секретов в Cloud Secret Manager может быть несколько версий. По умолчанию значение секретного параметра, доступного вашему работающему бэкенду, привязано к последней доступной версии секрета на момент создания бэкенда. Если у вас есть требования к управлению версиями и жизненным циклом параметров, вы можете закрепить определенные версии в консоли Firebase или в apphosting.yaml. Например, чтобы закрепить версию 5 в apphosting.yaml, выполните следующие действия:
env:
- variable: PINNED_API_KEY
secret: myApiKeySecret@5
Вы можете создать секреты с помощью команды CLI Firebase.
firebase apphosting:secrets:set Вам будет предложено добавить необходимые разрешения. В этом случае вы сможете автоматически добавить ссылку на секрет в apphosting.yaml.
Предоставьте доступ к Cloud Secret Manager
Чтобы App Hosting мог получать секретные значения во время развертывания сборки и среды выполнения, у сервисного аккаунта бэкенда App Hosting должно быть разрешение на доступ к Cloud Secret Manager.
Если вы создаете секреты с помощью консоли Cloud Secret Manager или CLI gcloud, а не firebase apphosting:secrets:set, предоставьте доступ к серверной части с помощью CLI Firebase:
firebase apphosting:secrets:grantaccess SECRET_NAME
Вы также можете назначить роль Secret Manager Secret Accessor (roles/secretmanager.secretAccessor) агенту сервиса App Hosting (service-PROJECT_NUMBER@gcp-sa-apphosting.iam.gserviceaccount.com) или сервисному аккаунту среды выполнения вашего бэкенда с помощью CLI gcloud:
gcloud secrets add-iam-policy-binding SECRET_NAME \
--member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-apphosting.iam.gserviceaccount.com" \
--role="roles/secretmanager.secretAccessor"
Доступ к консоли и разрешения на основе ролей
Консоль Firebase динамически ограничивает функции управления средой и Secret Manager на основе разрешений IAM пользователя:
- Роль "Читатель". Пользователи с разрешением на чтение могут просматривать существующие настройки конфигурации, но не могут вносить изменения.
- Во время создания серверной части кнопка Создать серверную часть отключена.
- В разделе Settings (Настройки) > Environment (Среда) кнопка Add new (Добавить) отключена, а меню More actions (Ещё) (
...) скрыты.
- Отсутствие разрешений Secret Manager. Пользователи, у которых нет разрешений IAM на взаимодействие с Cloud Secret Manager, увидят в консоли предупреждение Запросите у владельца проекта разрешение на добавление секретов.
- При создании бэкенда карточка Секреты отключена.
- В разделе Settings (Настройки) > Environment (Среда) параметр Secret (Секрет) отключен при нажатии Add new (Добавить), а некоторые параметры в меню строки More actions (Дополнительные действия) (
...) скрыты в существующих секретных записях.
Настройте доступ к VPC
Бэкенд App Hosting может подключаться к сети виртуального частного облака (VPC). Подробную информацию и пример можно найти в статье Как подключить Firebase App Hosting к сети VPC.
Чтобы настроить доступ, используйте сопоставление vpcAccess в файле apphosting.yaml.
Используйте полное название сети/коннектора или идентификатор. Использование идентификаторов позволяет переносить данные между тестовой и рабочей средами с разными коннекторами и сетями.
Конфигурация прямого исходящего трафика VPC (apphosting.yaml):
runConfig:
vpcAccess:
egress: PRIVATE_RANGES_ONLY # Default value
networkInterfaces:
# Specify at least one of network and/or subnetwork
- network: my-network-id
subnetwork: my-subnetwork-id
Конфигурация бессерверного коннектора (apphosting.yaml):
runConfig:
vpcAccess:
egress: ALL_TRAFFIC
connector: connector-id
Управление бэкендами
Команды для базового управления бэкендами App Hosting доступны в консоли Firebase и CLI Firebase. В этом разделе описаны некоторые из наиболее распространенных задач управления, включая создание и удаление бэкендов.
Создание серверной ВМ
Бэкенд App Hosting – это набор управляемых ресурсов, которые App Hosting создает для сборки и запуска веб-приложения.
Консоль Firebase. Перейдите в раздел Hosting & Serverless (Хостинг и бессерверная архитектура) > App Hosting (Хостинг приложений) и нажмите Create backend (Создать серверную часть). Если это первая серверная часть в вашем проекте Firebase, нажмите Get started (Начать).
Firebase CLI (версия 13.15.4 или более поздняя). Чтобы создать серверную часть, выполните следующую команду из корневого каталога локального проекта, указав идентификатор проекта в качестве аргумента:
firebase apphosting:backends:create --project PROJECT_ID
В консоли или CLI следуйте инструкциям, чтобы выбрать регион, настроить подключение к GitHub и задать следующие базовые настройки развертывания:
Укажите корневой каталог приложения (по умолчанию –
/).Обычно именно там находится файл
package.json.
Как настроить активную ветку
Это ветвь хранилища GitHub, которая развертывается на URL опубликованной страницы. Часто это ветка, в которую объединяются ветки функций или ветки разработки.
Принять или отклонить автоматическое развертывание.
Автоматическое развертывание включено по умолчанию. После создания серверной части вы можете сразу развернуть приложение в App Hosting.
Укажите название бэкенда.
Выберите среду выполнения. По умолчанию выбрана последняя рекомендуемая версия Node.js.
- Настройте автоматическое обновление базового образа. Функция ABIU включена по умолчанию и автоматически применяет исправления системы безопасности к вашей базовой среде. Чтобы отказаться от ABIU, выберите вариант "Не указано" для среды выполнения.
Удаление серверной ВМ
Чтобы полностью удалить бэкенд, сначала удалите его в консоли Firebase или с помощью интерфейса командной строки Firebase, а затем вручную удалите связанные объекты. Будьте осторожны, чтобы не удалить ресурсы, которые могут использоваться другими бэкендами или другими аспектами вашего проекта Firebase.
Консоль Firebase. В меню Settings (Настройки) выберите Delete backend (Удалить серверную часть).
Firebase CLI (версия 13.15.4 или более поздняя)
Чтобы удалить бэкенд App Hosting, выполните следующую команду: Это отключит все домены для вашего бэкенда и удалит связанный сервис Cloud Run:
firebase apphosting:backends:delete BACKEND_ID --project PROJECT_IDВ консоли Google Cloud на вкладке Artifact Registry удалите образ для своего бэкенда в firebaseapphosting-images (необязательно).
В Cloud Secret Manager удалите все секреты, в названии которых есть "apphosting". Убедитесь, что эти секреты не используются другими серверными частями или другими аспектами вашего проекта Firebase.