Настройка серверной части хостинга приложений и управление ею

App Hosting разработан для простоты использования и низких затрат на обслуживание, с настройками по умолчанию, оптимизированными для большинства сценариев использования. В то же время App Hosting предоставляет инструменты для управления и настройки бэкэндов в соответствии с вашими конкретными потребностями. В этом руководстве описаны эти инструменты и процессы.

Установите и обновите переменные среды.

Иногда для процесса сборки может потребоваться дополнительная настройка. App Hosting предлагает конфигурацию среды для хранения и извлечения данных такого типа для вашего проекта через консоль Firebase , а также в apphosting.yaml .

Setting environment variables in the Firebase console is the quickest way to get started. Use apphosting.yaml if you need to store and access secret parameters , set variables that are only available at build or run time, or share environment variables across multiple environments. With both the console and apphosting.<env>.yaml , you can set different values for different environments .

env:
-   variable: STORAGE_BUCKET
    value: mybucket.firebasestorage.app

Обновить переменные

Вы можете добавлять, редактировать или удалять переменные среды в консоли Firebase или с помощью файла apphosting.yaml :

• Консоль Firebase :

  1. В консоли Firebase перейдите в раздел «Хостинг и бессерверные вычисления» > «Хостинг приложений» .

  2. Перейдите в раздел View Backend > Settings > Environment .

  3. Добавляйте, редактируйте или удаляйте переменные среды.

• apphosting.yaml :

  Узнайте, как создавать и редактировать файл вручную.

Ваши изменения вступят в силу только при следующем развертывании и не повлияют на текущее. Либо сохраните изменения и создайте новое развертывание, либо сохраните переменные и разверните изменения позже.

Установить переменную доступность

Environment variables created in the Firebase console are available at both build time and run time. This is also the default condition for variables defined in apphosting.yaml unless you have narrowed that scope using the availability property. In apphosting.yaml (but not in the console), you can restrict an environment variable to be available to only the build environment or available only to the runtime environment.

env:
-   variable: STORAGE_BUCKET
    value: mybucket.firebasestorage.app
    availability:
    -   BUILD
    -   RUNTIME

Для приложений Next.js вы также можете использовать префикс NEXT_PUBLIC_ так же, как и в файле dotenv , чтобы сделать переменную доступной в браузере.

env:
-   variable: NEXT_PUBLIC_STORAGE_BUCKET
    value: mybucket.firebasestorage.app
    availability:
    -   BUILD
    -   RUNTIME

Файлы dotenv для Next.js

Для приложений Next.js файлы dotenv , содержащие переменные окружения, работают с App Hosting.

При создании или обновлении бэкэнда вы можете перенести переменные окружения из файла dotenv в консоль Firebase , скопировав и вставив все содержимое файла dotenv в первое поле «Ключ» в форме «Добавить новый» в настройках переменных окружения .

Все переменные окружения, скопированные таким образом, должны быть аккуратно отформатированы в форме, и нет необходимости вводить каждую из них по отдельности, если ввод имеет следующий формат:

KEY1=value1
KEY2=value2
KEY3=value3

Для сложного или детального управления переменными окружения в любом фреймворке мы рекомендуем использовать apphosting.yaml .

Автоматически заполняемые переменные среды

Существуют переменные среды, которые автоматически заполняются App Hosting . К ним относятся переменные, заполняемые Google Cloud , а также переменные среды, специфичные для Firebase, если appId задан в бэкэнде во время настройки:

• FIREBASE_CONFIG : (доступен в средах сборки и выполнения) Предоставляет следующую информацию о конфигурации проекта Firebase:

  {
    "databaseURL": 'https://DATABASE_NAME.firebaseio.com',
    "storageBucket": 'PROJECT_ID.firebasestorage.app',
    "projectId": 'PROJECT_ID'
  }
  

  Эта конфигурация применяется автоматически при инициализации 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": 'PROJECT_ID.firebasestorage.app',
  }
  

  В процессе сборки SDK Firebase JS автоматически проверяет наличие переменной среды FIREBASE_WEBAPP_CONFIG в скрипте postinstall , что позволяет инициализировать клиентский SDK без каких-либо аргументов.

Дополнительные сведения об использовании этих переменных среды для инициализации SDK см. в разделе «Автоматическая инициализация Firebase Admin SDK и веб-SDK» .

Обратите внимание, что значения в вашей фактической конфигурации Firebase будут соответствовать конкретным ресурсам, которые вы выделили в своем проекте.

Иерархия переменных

Firebase App Hosting применяет ваши переменные в порядке приоритета, основанном на их источнике. Например, значения, заданные в консоли Firebase , всегда переопределяют или имеют приоритет над значениями, заданными в файлах apphosting.yaml и dotenv .

Вот полный порядок приоритета:

1. Консоль Firebase → переменные, установленные в консоли
2. apphosting.<env>.yaml → переменные, указанные в YAML-файле, специфичном для конкретной среды, например, apphosting.staging.yaml (см. Развертывание нескольких сред ).
3. apphosting.yaml → переменные, указанные в файле apphosting.yaml
4. Системные переменные Firebase → переменные, устанавливаемые Firebase, которые содержат значения для firebase_config json или firebase_webapp_config , а также переменные среды, которые задают имена хостов и порты для приложений SSR (устанавливаются адаптерами App Hosting в bundle.yaml ).

Зарезервированные имена и ограничения

Переменные среды, определенные в контракте среды выполнения контейнеров Cloud Run зарезервированы и не могут быть установлены.

Переменные среды, предоставляемые средой выполнения, помимо тех, которые устанавливаются автоматически, могут изменяться в будущих версиях среды выполнения. В качестве рекомендации мы советуем не зависеть от каких-либо переменных среды, которые вы не установили явно, и рассмотреть возможность добавления уникального ключа к любым переменным среды во избежание конфликтов.

Некоторые ключи переменных окружения зарезервированы для внутреннего использования. Не используйте ни один из этих ключей в своих конфигурационных файлах:

• Пустые строки ("")
• Ключи, содержащие "="
• Ключи, начинающиеся с X_FIREBASE_ , X_GOOGLE_ или CLOUD_RUN_
• PORT
• K_SERVICE
• K_REVISION
• K_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 – Количество процессоров, используемых для каждого экземпляра сервиса (по умолчанию 0).
• memoryMiB – Объем памяти, выделяемый для каждого экземпляра сервиса в МиБ (по умолчанию 512)
• maxInstances – Максимальное количество контейнеров, которые могут работать одновременно (по умолчанию 100, регулируется квотой).
• minInstances – Количество контейнеров, которые всегда должны оставаться активными (по умолчанию 0).
• concurrency – максимальное количество запросов, которое может получить каждый экземпляр сервиса (по умолчанию 80).

Обратите внимание на важную взаимосвязь между cpu и memoryMiB ; объем памяти может быть установлен на любое целое число от 128 до 32768, но увеличение лимита памяти может потребовать увеличения лимитов CPU:

• Для работы с объёмом данных более 4 ГБ требуется как минимум 2 процессора.
• Для работы с объёмом данных более 8 ГБ требуется как минимум 4 процессора.
• Для работы с объёмом данных более 16 ГБ требуется как минимум 6 процессоров.
• Для работы с объёмом данных более 24 ГБ требуется как минимум 8 процессоров.

Аналогично, значение параметра cpu влияет на настройки параллельного выполнения. Если вы установите значение меньше 1 CPU, вам необходимо установить параметр Concurrency равным 1, и CPU будет выделяться только во время обработки запроса.

Переопределите скрипты сборки и запуска.

App Hosting определяет команду сборки и запуска вашего приложения на основе обнаруженной платформы. Если вы хотите использовать собственную команду сборки или запуска, вы можете переопределить значения по умолчанию в apphosting.yaml App Hosting

scripts:
  buildCommand: next build --no-lint
  runCommand: node dist/index.js

The build command override takes precedence over any other build commands and opts your app out of the framework adapters and disables any framework specific optimizations that App Hosting provides. It's best used when your app features are not well supported by the adapters. If you want to change your build command but still use our provided adapters, set your build script in package.json instead as described in App Hosting framework adapters .

Используйте переопределение команды запуска, если для запуска приложения вам нужна конкретная команда, отличающаяся от команды, определяемой с помощью параметра -inferred App Hosting .

Настройка выходных данных сборки

По умолчанию App Hosting оптимизирует развертывание вашего приложения, удаляя неиспользуемые выходные файлы в соответствии с указаниями фреймворка. Если вы хотите дополнительно оптимизировать размер развертывания приложения или игнорировать оптимизацию по умолчанию, вы можете переопределить это в apphosting.yaml .

outputFiles:
  serverApp:
    include: [dist, server.js]

Параметр include принимает список каталогов и файлов относительно корневого каталога приложения, необходимых для развертывания вашего приложения. Если вы хотите убедиться, что все файлы сохранены, установите параметр include в значение [.] , и все файлы будут развернуты.

Хранение и доступ к секретным параметрам

Конфиденциальную информацию, такую ​​как ключи API, следует хранить в виде секретов. Вы можете ссылаться на секреты в apphosting.yaml , чтобы избежать добавления конфиденциальной информации в систему контроля версий.

Параметры типа secret представляют собой строковые параметры, значение которых хранится в Cloud Secret Manager . Вместо прямого вычисления значения, параметры secret проверяются на наличие в Cloud Secret Manager и загружают значения во время развертывания.

  -   variable: API_KEY
      secret: myApiKeySecret

Secrets in Cloud Secret manager can have multiple versions. By default, the value of a secret parameter available to your live backend is pinned to the latest available version of the secret at the time the backend was built. If you have requirements for versioning and lifecycle management of parameters, you can pin to specific versions with Cloud Secret Manager. For example, to pin to version 5:

  - variable: PINNED_API_KEY
    secret: myApiKeySecret@5

Вы можете создавать секреты с помощью команды Firebase CLI firebase apphosting:secrets:set , после чего вам будет предложено добавить необходимые разрешения. Этот процесс позволяет автоматически добавлять ссылку на секрет в apphosting.yaml .

Для использования всех функций Cloud Secret Manager можно использовать консоль Cloud Secret Manager. В этом случае потребуется предоставить разрешения бэкэнду вашего App Hosting с помощью команды Firebase CLI firebase apphosting:secrets:grantaccess .

Настройка доступа к 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 и Firebase CLI . В этом разделе описаны некоторые из наиболее распространенных задач управления, включая создание и удаление бэкендов.

Создайте бэкэнд.

Бэкенд App Hosting — это набор управляемых ресурсов, которые App Hosting создает для сборки и запуска вашего веб-приложения.

В консоли Firebase перейдите в раздел «Хостинг и бессерверные вычисления» > «Хостинг приложений» , а затем нажмите «Создать бэкенд» (если это первый бэкенд в вашем проекте Firebase , нажмите « Начать »).

Firebase CLI: (версия 13.15.4 или более поздняя) Для создания бэкенда выполните следующую команду из корневого каталога вашего локального проекта, указав в качестве аргумента идентификатор вашего проекта :

firebase apphosting:backends:create --project PROJECT_ID

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

• Укажите корневой каталог вашего приложения (по умолчанию — / ).

  Обычно именно здесь находится ваш файл package.json .

• Установить рабочую ветку

  Это ветка вашего репозитория GitHub, которая развертывается на ваш рабочий URL. Часто это ветка, в которую объединяются ветки с новыми функциями или ветки разработки.

• Принять или отклонить автоматическое развертывание

  Автоматическое развертывание включено по умолчанию. После завершения создания бэкэнда вы можете выбрать вариант немедленного развертывания вашего приложения на App Hosting .

• Присвойте имя своему бэкэнду.

• Выберите среду выполнения. По умолчанию для вас предварительно выбрана новейшая рекомендуемая версия Node.js.

  • Настройте автоматическое обновление базового образа (ABIU) . ABIU включено по умолчанию и автоматически применяет исправления безопасности к вашей базовой среде. Вы можете отключить ABIU, выбрав «Не указано» для вашей среды выполнения.

Удалить бэкэнд

Для полного удаления бэкэнда сначала используйте консоль Firebase или Firebase CLI для его удаления, а затем вручную удалите связанные ресурсы, уделяя особое внимание тому, чтобы не удалять ресурсы, которые могут использоваться другими бэкэндами или другими аспектами вашего проекта Firebase.

Консоль Firebase : В меню «Настройки» выберите «Удалить бэкенд» .

Firebase CLI: (версия 13.15.4 или более поздняя)

1. Выполните следующую команду, чтобы удалить бэкэнд App Hosting . Это отключит все домены для вашего бэкэнда и удалит связанную с ним службу Cloud Run :

   firebase apphosting:backends:delete BACKEND_ID --project PROJECT_ID
   

2. (Необязательно) На вкладке консоли Google Cloud для Artifact Registry удалите образ для вашего бэкэнда в папке "firebaseapphosting-images".

3. В Cloud Secret Manager удалите все секреты, в названии которых содержится "apphosting", при этом убедитесь, что эти секреты не используются другими бэкэндами или другими аспектами вашего проекта Firebase .