Konfigurowanie backendów App Hosting i zarządzanie nimi

App Hosting została zaprojektowana z myślą o łatwości obsługi i niskich kosztach utrzymania, ma domyślne ustawienia zoptymalizowane pod kątem większości zastosowań. Jednocześnie usługa App Hosting udostępnia narzędzia do zarządzania backendami i konfigurowania ich pod kątem Twoich konkretnych potrzeb. Z tego przewodnika dowiesz się, jak korzystać z tych narzędzi i procesów.

Ustawianie i aktualizowanie zmiennych środowiskowych

Czasami proces kompilacji może wymagać dodatkowej konfiguracji. App Hosting oferuje konfigurację środowiska, która umożliwia przechowywanie i pobieranie tego typu danych na potrzeby projektu w konsoli Firebase lub w pliku apphosting.yaml.

Najszybszym sposobem na rozpoczęcie jest ustawienie zmiennych środowiskowych w konsoli Firebase. Użyj apphosting.yaml, jeśli chcesz przechowywać tajne parametry i uzyskiwać do nich dostęp, ustawiać zmienne dostępne tylko w czasie kompilacji lub działania albo udostępniać zmienne środowiskowe w wielu środowiskach. Zarówno w konsoli, jak i w pliku apphosting.<env>.yaml możesz ustawić różne wartości dla różnych środowisk.

Firebase konsola

Zrzut ekranu z okna dialogowego konsoli Firebase służącego do dodawania zmiennych środowiskowych

apphosting.yaml 

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

Aktualizowanie zmiennych

Zmienne środowiskowe możesz dodawać, edytować i usuwać w konsoli Firebase lub za pomocą pliku apphosting.yaml:

  • Firebase konsola:

    1. W konsoli Firebase otwórz Hosting i usługi bezserwerowe > App Hosting.

    2. Otwórz Wyświetl backend > Ustawienia > Środowisko.

    3. Dodaj, edytuj lub usuń zmienne środowiskowe.

  • apphosting.yaml:

    Dowiedz się, jak ręcznie utworzyć i edytować plik.

Zmiany zaczną obowiązywać dopiero po następnym wdrożeniu i nie wpłyną na bieżące wdrożenie. Zapisz i utwórz nowe wdrożenie lub zapisz zmienne i wdróż je później.

Ustawianie dostępności zmiennych

Zmienne środowiskowe utworzone w konsoli Firebase są dostępne zarówno w czasie kompilacji , jak i w czasie działania. Jest to też domyślny warunek dla zmiennych zdefiniowanych w pliku apphosting.yaml, chyba że ograniczysz ten zakres za pomocą właściwości availability. W pliku apphosting.yaml (ale nie w konsoli) możesz ograniczyć dostępność zmiennej środowiskowej tylko do środowiska kompilacji lub tylko do środowiska wykonawczego.

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

W przypadku aplikacji Next.js możesz też użyć prefiksu NEXT_PUBLIC_ w taki sam sposób jak w pliku dotenv aby udostępnić zmienną w przeglądarce.

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

Pliki dotenv w Next.js

W przypadku aplikacji Next.js pliki dotenv zawierające zmienne środowiskowe działają z usługą App Hosting.

Podczas tworzenia lub aktualizowania backendu możesz przenieść zmienne środowiskowe z pliku dotenv do konsoli Firebase, kopiując i wklejając całą zawartość pliku dotenv w pierwszym polu „Klucz” w formularzu „Dodaj nowy” w sekcji Ustawienia zmiennych środowiskowych.

Wszystkie zmienne środowiskowe skopiowane w ten sposób powinny być prawidłowo sformatowane w formularzu. Nie trzeba ich wpisywać pojedynczo, o ile dane wejściowe mają format taki jak ten:

KEY1=value1
KEY2=value2
KEY3=value3

Aby uzyskać złożoną lub szczegółową kontrolę nad zmiennymi środowiskowymi w dowolnej platformie, zalecamy używanie apphosting.yaml.

Automatycznie wypełniane zmienne środowiskowe

Istnieją zmienne środowiskowe, które są automatycznie wypełniane przez App Hosting. Obejmują one zmienne wypełniane przez Google Cloud, a także zmienne środowiskowe specyficzne dla Firebase, gdy appId jest ustawiona w backendzie podczas konfiguracji:

  • FIREBASE_CONFIG(dostępna w środowiskach kompilacji i wykonawczym): zawiera te informacje o konfiguracji projektu w Firebase:

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

    Ta konfiguracja jest stosowana automatycznie, gdy inicjujesz pakiet Firebase Admin SDK bez argumentów.

  • FIREBASE_WEBAPP_CONFIG(dostępna tylko w środowisku kompilacji): zawiera te informacje o konfiguracji projektu w 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',
}

    Pakiet Firebase JS SDK automatycznie sprawdza tę FIREBASE_WEBAPP_CONFIG zmienną środowiskową w skrypcie postinstall podczas kompilacji, co pozwala też zainicjować pakiet SDK klienta bez argumentów.

Więcej informacji o tym, jak używać tych zmiennych środowiskowych do inicjowania pakietów SDK, znajdziesz w artykule Automatyczne inicjowanie pakietu Firebase Admin SDK i pakietów SDK na potrzeby internetu.

Pamiętaj, że wartości w rzeczywistej konfiguracji Firebase będą odpowiadać konkretnym zasobom, które zostały udostępnione w Twoim projekcie.

Hierarchia zmiennych

Usługa Firebase App Hosting stosuje zmienne w kolejności priorytetów na podstawie ich źródła. Na przykład wartości ustawione w konsoli Firebase zawsze zastępują wartości ustawione w plikach apphosting.yaml i dotenv lub mają nad nimi pierwszeństwo.

Oto pełna kolejność priorytetów:

  1. Firebase konsola → zmienne ustawione w konsoli
  2. apphosting.<env>.yaml → zmienne określone w pliku YAML specyficznym dla środowiska, np. apphosting.staging.yaml (patrz Wdrażanie w wielu środowiskach)
  3. apphosting.yaml → zmienne określone w pliku apphosting.yaml
  4. System Firebase → zmienne ustawione przez Firebase, które zawierają wartości dla firebase_config json lub firebase_webapp_config, a także zmienne środowiskowe ustawiające nazwy hostów i porty aplikacji SSR (ustawiane przez adaptery App Hosting w pliku bundle.yaml)

Zarezerwowane nazwy i ograniczenia

Zmienne środowiskowe zdefiniowane w Cloud Run umowie dotyczącej środowiska wykonawczego kontenera są zarezerwowane i nie można ich ustawić.

Zmienne środowiskowe udostępniane przez środowisko (inne niż te, które są ustawiane automatycznie) mogą się zmienić w przyszłych wersjach środowiska wykonawczego. Zalecamy, aby nie polegać na żadnych zmiennych środowiskowych, których nie ustawisz bezpośrednio, ani ich nie modyfikować. Warto też dodać do każdej zmiennej środowiskowej unikalny prefiks, aby uniknąć konfliktów.

Niektóre klucze zmiennych środowiskowych są zarezerwowane do użytku wewnętrznego. Nie używaj żadnego z tych kluczy w plikach konfiguracyjnych:

  • Puste ciągi znaków („”)
  • Klucze zawierające znak „=”
  • Klucze zaczynające się od X_FIREBASE_, X_GOOGLE_ lub CLOUD_RUN_
  • PORT
  • K_SERVICE
  • K_REVISION
  • K_CONFIGURATION
  • Zduplikowane klucze

Tworzenie i edytowanie pliku apphosting.yaml

Aby skonfigurować zaawansowane ustawienia, takie jak obiekty tajne lub ustawienia środowiska wykonawczego, np. limity współbieżności, procesora i pamięci, musisz utworzyć i edytować plik apphosting.yaml w katalogu głównym aplikacji. Ten plik obsługuje odwołania do obiektów tajnych zarządzanych za pomocą usługi Cloud Secret Manager, dzięki czemu można go bezpiecznie sprawdzić w systemie kontroli wersji.

Aby utworzyć plik apphosting.yaml, uruchom to polecenie:

firebase init apphosting

Spowoduje to utworzenie podstawowego pliku apphosting.yaml z przykładową (zakomentowaną) konfiguracją. Po edycji typowy plik apphosting.yaml może wyglądać tak jak poniżej. Zawiera ustawienia usługi Cloud Run backendu, kilka zmiennych środowiskowych i kilka odwołań do obiektów tajnych zarządzanych przez usługę 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

W dalszej części tego przewodnika znajdziesz więcej informacji i kontekstu dotyczących tych przykładowych ustawień.

Konfigurowanie ustawień usługi Cloud Run

Za pomocą ustawień apphosting.yaml możesz skonfigurować sposób udostępniania usługi Cloud Run. Dostępne ustawienia dla usługi Cloud Run są dostępne w obiekcie runConfig:

  • cpu – liczba procesorów używanych przez każdą instancję obsługującą (domyślnie 0).
  • memoryMiB – ilość pamięci przydzielonej do każdej instancji obsługującej w MiB (domyślnie 512).
  • maxInstances – maksymalna liczba kontenerów, które mogą działać jednocześnie (domyślnie 100, zarządzana przez limit).
  • minInstances – liczba kontenerów, które mają być zawsze aktywne (domyślnie 0).
  • concurrency – maksymalna liczba żądań, które może otrzymać każda instancja obsługująca (domyślnie 80).

Zwróć uwagę na ważną zależność między cpu a memoryMiB. Pamięć można ustawić na dowolną liczbę całkowitą z zakresu od 128 do 32768, ale zwiększenie limitu pamięci może wymagać zwiększenia limitów procesora:

  • Ponad 4 GiB wymaga co najmniej 2 procesorów.
  • Ponad 8 GiB wymaga co najmniej 4 procesorów.
  • Ponad 16 GiB wymaga co najmniej 6 procesorów.
  • Ponad 24 GiB wymaga co najmniej 8 procesorów.

Podobnie wartość cpu wpływa na ustawienia współbieżności. Jeśli ustawisz wartość mniejszą niż 1 procesor, musisz ustawić współbieżność na 1, a procesor będzie przydzielany tylko podczas przetwarzania żądań.

Zastępowanie skryptów kompilacji i uruchamiania

App Hosting określa polecenie kompilacji i uruchamiania aplikacji na podstawie wykrytego frameworka. Jeśli chcesz użyć niestandardowego polecenia kompilacji lub uruchamiania, możesz zastąpić domyślne ustawienia usługi App Hosting's w pliku apphosting.yaml.

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

Zastąpienie polecenia kompilacji ma pierwszeństwo przed wszystkimi innymi poleceniami kompilacji i wyłącza adaptery platformy w aplikacji oraz wszelkie optymalizacje specyficzne dla platformy, które udostępnia usługa App Hosting. Najlepiej używać go, gdy funkcje aplikacji nie są dobrze obsługiwane przez adaptery. Jeśli chcesz zmienić polecenie kompilacji ale nadal używać naszych adapterów, ustaw skrypt kompilacji w package.json zamiast tego zgodnie z opisem w App Hosting adaptery frameworka.

Użyj zastąpienia polecenia uruchamiania, gdy chcesz użyć konkretnego polecenia do uruchomienia aplikacji, które różni się od App Hosting-wywnioskowanego polecenia.

Konfigurowanie danych wyjściowych kompilacji

App Hosting domyślnie optymalizuje wdrożenia aplikacji, usuwając nieużywane pliki wyjściowe zgodnie z informacjami podanymi przez framework. Jeśli chcesz dodatkowo zoptymalizować rozmiar wdrożenia aplikacji lub zignorować domyślne optymalizacje, możesz zastąpić to ustawienie w pliku apphosting.yaml.

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

Parametr include przyjmuje listę katalogów i plików względem katalogu głównego aplikacji, które są niezbędne do wdrożenia aplikacji. Jeśli chcesz mieć pewność, że wszystkie pliki zostaną zachowane, ustaw wartość include na [.], a wszystkie pliki zostaną wdrożone.

Przechowywanie tajnych parametrów i uzyskiwanie do nich dostępu

Informacje poufne, takie jak klucze interfejsu API, powinny być przechowywane jako obiekty tajne. Możesz odwoływać się do obiektów tajnych w pliku apphosting.yaml, aby uniknąć sprawdzania informacji poufnych w systemie kontroli wersji.

Parametry typu secret reprezentują parametry ciągu znaków, których wartość jest przechowywana w usłudze Cloud Secret Manager. Zamiast bezpośrednio pobierać wartość, parametry tajne sprawdzają istnienie w usłudze Cloud Secret Manager i wczytują wartości podczas wdrożenia.

  -   variable: API_KEY
      secret: myApiKeySecret

Obiekty tajne w usłudze Cloud Secret Manager mogą mieć wiele wersji. Domyślnie wartość parametru tajnego dostępnego w backendzie na żywo jest przypisana do najnowszej dostępnej wersji obiektu tajnego w momencie tworzenia backendu. Jeśli masz wymagania dotyczące zarządzania wersjami i cyklem życia parametrów, możesz przypiąć je do konkretnych wersji za pomocą usługi Cloud Secret Manager. Aby na przykład przypiąć do wersji 5:

  - variable: PINNED_API_KEY
    secret: myApiKeySecret@5

Obiekty tajne możesz tworzyć za pomocą polecenia CLI Firebase firebase apphosting:secrets:set. Zostaniesz poproszony(-a) o dodanie niezbędnych uprawnień. Ten proces umożliwia automatyczne dodanie odwołania do obiektu tajnego w pliku apphosting.yaml.

Aby korzystać z pełnego pakietu funkcji usługi Cloud Secret Manager, możesz użyć konsoli Cloud Secret Manager. W takim przypadku musisz przyznać uprawnienia do backendu App Hosting za pomocą polecenia CLI Firebase firebase apphosting:secrets:grantaccess.

Konfigurowanie dostępu do VPC

Twój App Hosting backend może łączyć się z siecią Virtual Private Cloud (VPC). Więcej informacji i przykład znajdziesz w artykule Łączenie Firebase App Hosting z siecią VPC.

Aby skonfigurować dostęp, użyj mapowania vpcAccess w pliku apphosting.yaml. Użyj pełnej i jednoznacznej nazwy sieci lub oprogramowania sprzęgającego albo identyfikatora. Używanie identyfikatorów umożliwia przenoszenie między środowiskami testowymi i produkcyjnymi z różnymi oprogramowaniami sprzęgającymi lub sieciami.

Konfiguracja bezpośredniego połączenia VPC dla ruchu wychodzącego (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

Konfiguracja bezserwerowego oprogramowania sprzęgającego (apphosting.yaml):

runConfig:
  vpcAccess:
    egress: ALL_TRAFFIC
    connector: connector-id

Zarządzanie backendami

Polecenia do podstawowego zarządzania backendami App Hosting są dostępne w konsoli Firebase i Firebase CLI. W tej sekcji opisujemy niektóre z najczęstszych zadań związanych z zarządzaniem, w tym tworzenie i usuwanie backendów.

Tworzenie backendu

Backend App Hosting to zbiór zarządzanych zasobów, które App Hosting tworzy na potrzeby kompilowania i uruchamiania aplikacji internetowej.

Firebase konsola: otwórz Hosting i usługi bezserwerowe > App Hosting, i kliknij Utwórz backend (jeśli jest to pierwszy backend w Twoim Firebase projekcie, kliknij Rozpocznij).

Firebase CLI: (wersja 13.15.4 lub nowsza) aby utworzyć backend, uruchom to polecenie w katalogu głównym lokalnego projektu, podając identyfikator projektu jako argument:

firebase apphosting:backends:create --project PROJECT_ID

Zarówno w konsoli, jak i w interfejsie wiersza poleceń postępuj zgodnie z instrukcjami, aby wybrać region, skonfigurować połączenie z GitHub, i skonfigurować te podstawowe ustawienia wdrożenia:

  • Ustaw katalog główny aplikacji (domyślnie /)

    Zwykle znajduje się w nim plik package.json.

  • Ustaw gałąź na żywo

    Jest to gałąź repozytorium GitHub, która jest wdrażana pod adresem URL wersji opublikowanej. Często jest to gałąź, w której scalane są gałęzie funkcji lub gałęzie deweloperskie.

  • Zaakceptuj lub odrzuć automatyczne wdrożenia

    Automatyczne wdrożenia są domyślnie włączone. Po utworzeniu backendu, możesz od razu wdrożyć aplikację w usłudze App Hosting.

  • Przypisz nazwę do backendu.

  • Wybierz środowisko wykonawcze. Domyślnie jest wstępnie wybrana najnowsza zalecana wersja Node.js.

    • Skonfiguruj automatyczne aktualizacje obrazu podstawowego (ABIU). Automatyczne aktualizacje obrazu podstawowego są domyślnie włączone i automatycznie stosują poprawki zabezpieczeń w środowisku bazowym. Możesz zrezygnować z automatycznych aktualizacji obrazu podstawowego, wybierając „Nie określono” w przypadku środowiska wykonawczego.

Usuwanie backendu

Aby całkowicie usunąć backend, najpierw usuń go za pomocą konsoli Firebase lub Firebase CLI, a potem ręcznie usuń powiązane zasoby, uważając, aby nie usunąć żadnych zasobów, które mogą być używane przez inne backendy lub inne aspekty projektu w Firebase.

Firebase konsola: w menu Ustawienia wybierz Usuń backend.

Firebase CLI: (wersja 13.15.4 lub nowsza)

  1. Aby usunąć backend App Hosting, uruchom to polecenie. Spowoduje to wyłączenie wszystkich domen backendu i usunięcie powiązanej Cloud Run usługi:

    firebase apphosting:backends:delete BACKEND_ID --project PROJECT_ID

  2. (Opcjonalnie) Na karcie konsoli Google Cloud Artifact Registry usuń obraz backendu w sekcji "firebaseapphosting-images".

  3. W Cloud Secret Manager, usuń wszystkie obiekty tajne, których nazwa zawiera "apphosting", uważając, aby te obiekty tajne nie były używane przez inne backendy ani inne aspekty projektu w Firebase.