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

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

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

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

Самый быстрый способ начать — это установить переменные окружения в консоли. Используйте apphosting.yaml если вам нужно хранить и получать доступ к секретным параметрам , устанавливать переменные, доступные только во время сборки или выполнения, или совместно использовать переменные окружения в нескольких средах. Как в консоли, так и apphosting.<env>.yaml вы можете устанавливать разные значения для разных сред .

Консоль Firebase

Скриншот диалогового окна консоли Firebase для добавления переменных среды.

apphosting.yaml 

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

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

Вы можете добавлять и редактировать переменные среды в консоли Firebase на вкладке «Настройки» для бэкэнда. Перейдите в раздел «Просмотр бэкэнда» >> «Настройки» >> «Среда» , а затем добавьте, отредактируйте или удалите переменные среды.

Чтобы добавить и отредактировать переменные среды в apphosting.yaml, создайте и отредактируйте файл вручную.

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

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

Переменные среды, созданные в консоли Firebase, доступны как во время сборки, так и во время выполнения. Это также условие по умолчанию для переменных, определенных в файле apphosting.yaml , если вы не сузили область их действия с помощью свойства availability . В apphosting.yaml (но не в консоли) вы можете ограничить доступность переменной среды только для среды сборки или только для среды выполнения.

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 .

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

Firebase App Hosting применяет ваши переменные в порядке приоритета, основанном на их источнике. Например, значения, заданные в консоли, всегда переопределяют или имеют приоритет над значениями, заданными в файлах 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 ).

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

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

  • Пустые строки ("")
  • Переменные, содержащие "="
  • Любая переменная, начинающаяся с X_FIREBASE_
  • 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

Команда переопределения сборки имеет приоритет над любыми другими командами сборки и исключает ваше приложение из адаптеров фреймворка, а также отключает любые оптимизации, специфичные для фреймворка, которые предоставляет App Hosting . Лучше всего использовать её, если функции вашего приложения плохо поддерживаются адаптерами. Если вы хотите изменить команду сборки, но при этом использовать предоставленные нами адаптеры, укажите скрипт сборки в package.json , как описано в разделе «Адаптеры фреймворка App Hosting .

Используйте переопределение команды запуска, если для запуска приложения вам нужна конкретная команда, отличающаяся от команды, определяемой с помощью параметра -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

В Cloud Secret Manager секреты могут иметь несколько версий. По умолчанию значение параметра секрета, доступного вашему бэкенду, привязано к последней доступной версии секрета на момент создания бэкенда. Если вам требуется версионирование и управление жизненным циклом параметров, вы можете привязать их к определенным версиям с помощью Cloud Secret Manager. Например, чтобы привязать к версии 5: 

  - variable: PINNED_API_KEY
    secret: myApiKeySecret@5

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

Для использования всех функций Cloud Secret Manager вы можете использовать консоль Cloud Secret Manager. В этом случае вам потребуется предоставить разрешения бэкэнду вашего App Hosting с помощью команды 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 CLI и консоли Firebase . В этом разделе описаны некоторые из наиболее распространенных задач управления, включая создание и удаление бэкэндов.

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

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

Консоль Firebase : В меню «Сборка» выберите App Hosting , а затем «Создать бэкенд» (если это первый бэкенд в вашем проекте Firebase, выберите «Начать »).

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

firebase apphosting:backends:create --project PROJECT_ID

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

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

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

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

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

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

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

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

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

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

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

Интерфейс командной строки: (Версия 13.15.4 или более поздняя)

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

    firebase apphosting:backends:delete BACKEND_ID --project PROJECT_ID

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

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