App Hosting została zaprojektowana z myślą o łatwości użycia i niskich kosztach utrzymania. Ma ustawienia domyślne zoptymalizowane pod kątem większości przypadków użycia. Jednocześnie App Hosting udostępnia narzędzia do zarządzania backendami i konfigurowania ich pod kątem konkretnych potrzeb. Ten przewodnik opisuje te narzędzia i procesy.
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 za pomocą konsoli Firebase, a także w apphosting.yaml.
Ustawianie zmiennych środowiskowych w konsoli Firebase to najszybszy sposób na rozpoczęcie pracy. 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 apphosting.<env>.yaml możesz ustawiać różne wartości dla różnych środowisk.
Firebase konsola
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ą apphosting.yaml:
Konsola Firebase:
W konsoli Firebase otwórz Hosting i usługi bezserwerowe > Hosting aplikacji.
Kliknij Wyświetl zaplecze > Ustawienia > Środowisko.
Dodawanie, edytowanie i usuwanie zmiennych środowiskowych.
apphosting.yaml:Dowiedz się, jak tworzyć i edytować plik ręcznie.
Zmiany zaczną obowiązywać dopiero przy następnym wdrożeniu i nie wpłyną na bieżące. Możesz zapisać i utworzyć nowe wdrożenie lub zapisać zmienne i wdrożyć je później.
Ustawianie dostępności zmiennej
Zmienne środowiskowe utworzone w Firebase konsoli są dostępne zarówno w czasie kompilacji, jak i w czasie działania. Jest to też domyślny warunek dla zmiennych zdefiniowanych w apphosting.yaml, chyba że zawęzisz ten zakres za pomocą właściwości availability. W apphosting.yaml (ale nie w konsoli) możesz ograniczyć zmienną środowiskową tak, aby była dostępna tylko w środowisku kompilacji lub tylko w środowisku wykonawczym.
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 zmienna była dostępna w przeglądarce.
env:
- variable: NEXT_PUBLIC_STORAGE_BUCKET
value: mybucket.firebasestorage.app
availability:
- BUILD
- RUNTIME
dotenv plików dla Next.js
W przypadku aplikacji Next.js w App Hosting działają dotenvpliki zawierające zmienne środowiskowe.
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 do pierwszego pola „Klucz” w formularzu „Dodaj nowe” w ustawieniach zmiennych środowiskowych.
Wszystkie zmienne środowiskowe skopiowane w ten sposób powinny być starannie sformatowane w formularzu bez konieczności wpisywania każdej z nich osobno, o ile dane wejściowe mają format podobny do tego:
KEY1=value1
KEY2=value2
KEY3=value3
W przypadku złożonej lub szczegółowej kontroli zmiennych środowiskowych w dowolnej strukturze 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 na backendzie podczas konfiguracji:
FIREBASE_CONFIG: (dostępne w środowiskach kompilacji i wykonawczym) Zawiera te informacje o konfiguracji projektu w Firebase:{ "databaseURL": 'https://DATABASE_NAME.firebaseio.com', "storageBucket": '', "projectId": 'PROJECT_ID' }PROJECT_ID.Ta konfiguracja jest stosowana automatycznie, gdy inicjujesz pakiet Firebase Admin SDK bez argumentów.
FIREBASE_WEBAPP_CONFIG: (dostępne 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.Pakiet Firebase JS SDK automatycznie sprawdza tę
FIREBASE_WEBAPP_CONFIGzmienną środowiskową w skrypcie postinstall podczas kompilacji, co umożliwia zainicjowanie pakietu SDK klienta bez żadnych 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 internetowych.
Pamiętaj, że wartości w rzeczywistej konfiguracji Firebase będą odpowiadać konkretnym zasobom udostępnionym w Twoim projekcie.
Hierarchia zmiennych
Firebase App Hosting stosuje zmienne w kolejności pierwszeństwa 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.
Oto pełna kolejność pierwszeństwa:
- Firebase konsola → zmienne ustawione w konsoli
apphosting.<env>.yaml→ zmienne określone w pliku YAML specyficznym dla środowiska, np.apphosting.staging.yaml(patrz Wdrażanie wielu środowisk)apphosting.yaml→ zmienne określone w plikuapphosting.yaml- System Firebase – zmienne ustawiane przez Firebase, które zawierają wartości dla
firebase_config jsonlubfirebase_webapp_config, a także zmienne środowiskowe, które ustawiają nazwy hostów i porty dla aplikacji SSR (ustawiane przez adaptery hostingu aplikacji wbundle.yaml).
Zarezerwowane nazwy i ograniczenia
Zmienne środowiskowe zdefiniowane w Cloud Runumowie środowiska wykonawczego kontenera są zarezerwowane i nie można ich ustawić.
Zmienne środowiskowe dostarczane przez środowisko, inne niż te, które są ustawiane automatycznie, mogą ulec zmianie w przyszłych wersjach środowiska wykonawczego. Zalecamy, aby nie polegać na żadnych zmiennych środowiskowych, których nie ustawiono wyraźnie, ani ich nie modyfikować. Warto też rozważyć dodanie do nich unikalnego klucza, aby uniknąć konfliktów.
Niektóre klucze zmiennych środowiskowych są zarezerwowane do użytku wewnętrznego. Nie używaj w plikach konfiguracji żadnego z tych kluczy:
- Puste ciągi znaków („”)
- Klucze zawierające znak „=”
- Klucze zaczynające się od
X_FIREBASE_,X_GOOGLE_lubCLOUD_RUN_ PORTK_SERVICEK_REVISIONK_CONFIGURATION- Dorabianie kluczy
Tworzenie i edytowanie apphosting.yaml
W przypadku zaawansowanej konfiguracji, takiej jak obiekty tajne lub ustawienia środowiska wykonawczego, np. ograniczenia dotyczące równoczesnoś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ć 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, z ustawieniami usługi backendu Cloud Run, niektórymi zmiennymi środowiskowymi i odwołaniami do kluczy tajnych zarządzanych przez 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 kontekst dotyczący 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 usługi Cloud Run są podane w obiekcie runConfig:
cpu– liczba procesorów używanych w każdej instancji obsługującej (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ą być uruchomione w danym momencie (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 wartościami cpu i memoryMiB. Pamięć można ustawić na dowolną liczbę całkowitą z zakresu od 128 do 32 768, ale zwiększenie limitu pamięci może wymagać zwiększenia limitów procesora:
- Ponad 4 GiB wymaga co najmniej 2 procesorów
- W przypadku ponad 8 GiB wymagane są co najmniej 4 procesory.
- 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 CPU, 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 wnioskuje polecenie kompilacji i uruchomienia aplikacji na podstawie wykrytego frameworka. Jeśli chcesz użyć niestandardowej kompilacji lub polecenia uruchamiania, możesz zastąpić domyślne ustawienia App Hosting w apphosting.yaml.
scripts:
buildCommand: next build --no-lint
runCommand: node dist/index.js
Zastąpienie polecenia kompilacji ma pierwszeństwo przed innymi poleceniami kompilacji i wyłącza w aplikacji adaptery platformy oraz wszelkie optymalizacje specyficzne dla platformy, które zapewnia 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ć dostarczonych przez nas adapterów, ustaw skrypt kompilacji w package.json, jak opisano w App Hosting adapterach platformy.
Użyj zastąpienia polecenia uruchamiania, jeśli 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 wdrażanie aplikacji, usuwając nieużywane pliki wyjściowe wskazane przez platformę. Jeśli chcesz jeszcze bardziej zoptymalizować rozmiar wdrożenia aplikacji lub zignorować domyślne optymalizacje, możesz zastąpić to ustawienie w 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 parametrów tajnych 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 wpisów tajnych w apphosting.yaml, aby uniknąć sprawdzania informacji poufnych w systemie kontroli wersji.
Parametry typu secret reprezentują parametry tekstowe, których wartość jest przechowywana w Cloud Secret Manager.
Zamiast bezpośrednio uzyskiwać wartość, parametry tajne sprawdzają, czy istnieją w usłudze Cloud Secret Manager, i wczytują wartości podczas wdrażania.
- variable: API_KEY
secret: myApiKeySecret
Obiekty tajne w usłudze Cloud Secret Manager mogą mieć wiele wersji. Domyślnie wartość parametru tajnego dostępnego dla backendu na żywo jest przypięta do najnowszej dostępnej wersji obiektu tajnego w momencie tworzenia backendu. Jeśli masz wymagania dotyczące obsługi wersji i zarządzania cyklem życia parametrów, możesz przypinać je do określonych wersji za pomocą usługi Cloud Secret Manager. Na przykład, aby przypiąć wersję 5:
- variable: PINNED_API_KEY
secret: myApiKeySecret@5
Możesz utworzyć klucze tajne za pomocą Firebasepolecenia CLIfirebase apphosting:secrets:set. Zostanie wyświetlony monit o dodanie niezbędnych uprawnień. Ten proces umożliwia automatyczne dodanie odwołania do klucza tajnego do apphosting.yaml.
Aby korzystać z pełnego zestawu funkcji Cloud Secret Manager, możesz użyć konsoli Cloud Secret Manager. W takim przypadku musisz przyznać uprawnienia do backendu App Hosting za pomocą polecenia interfejsu wiersza poleceń Firebasefirebase apphosting:secrets:grantaccess.
Konfigurowanie dostępu do VPC
Twój backend App Hosting może łączyć się z siecią prywatnego środowiska wirtualnego w chmurze (VPC). Więcej informacji i przykład znajdziesz w artykule Łączenie Firebase App Hosting z siecią VPC.
Użyj mapowania vpcAccess w pliku apphosting.yaml, aby skonfigurować dostęp. Użyj w tym celu pełnej i jednoznacznej nazwy sieci lub oprogramowania sprzęgającego albo identyfikatora. Używanie identyfikatorów umożliwia przenoszenie danych między środowiskami testowym i produkcyjnym z różnymi oprogramowaniami sprzęgającymi lub sieciami.
Konfiguracja bezpośredniego połączenia VPC w ruchu wychodzącym (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 podstawowych funkcji zarządzania App Hosting backendami są dostępne w Firebase konsoli i Firebase interfejsie wiersza poleceń. W tej sekcji opisujemy niektóre z najczęstszych zadań związanych z zarządzaniem, w tym tworzenie i usuwanie backendów.
Utworzenie backendu
App HostingBackend to zbiór zarządzanych zasobów, które App Hosting tworzy w celu zbudowania i uruchomienia aplikacji internetowej.
Firebase konsola: otwórz Hosting i usługi bezserwerowe > App Hosting, a następnie kliknij Utwórz backend (jeśli to pierwszy backend w projekcie Firebase, kliknij Rozpocznij).
Firebase CLI: (wersja 13.15.4 lub nowsza) Aby utworzyć backend, uruchom to polecenie w katalogu głównym lokalnego projektu, podając jako argument identyfikator projektu:
firebase apphosting:backends:create --project PROJECT_ID
W przypadku konsoli lub interfejsu CLI postępuj zgodnie z instrukcjami, aby wybrać region, skonfigurować połączenie z GitHubem i skonfigurować te podstawowe ustawienia wdrożenia:
Ustaw główny katalog aplikacji (domyślnie
/).Zwykle w tym miejscu znajduje się 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łąź, do której są scalane gałęzie funkcji lub gałęzie deweloperskie.
Akceptowanie i odrzucanie automatycznych wdrożeń
Automatyczne wdrażanie jest domyślnie włączone. Po zakończeniu tworzenia backendu możesz od razu wdrożyć aplikację w App Hosting.
Przypisz nazwę do backendu.
Wybierz środowisko wykonawcze. Domyślnie wstępnie wybrana jest najnowsza zalecana wersja Node.js.
- Skonfiguruj automatyczne aktualizacje obrazu podstawowego. ABIU jest domyślnie włączone i automatycznie stosuje poprawki zabezpieczeń w środowisku bazowym. Aby zrezygnować z ABIU, wybierz „Nieokreślony” jako czas działania.
Usunięcie backendu
Aby całkowicie usunąć backend, najpierw użyj Firebase konsoli lub Firebase interfejsu CLI, a potem ręcznie usuń powiązane zasoby. Uważaj, 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 Interfejs wiersza poleceń: (wersja 13.15.4 lub nowsza)
Aby usunąć App Hosting backend, uruchom to polecenie: Spowoduje to wyłączenie wszystkich domen backendu i usunięcie powiązanej usługi Cloud Run:
firebase apphosting:backends:delete BACKEND_ID --project PROJECT_ID(Opcjonalnie) Na karcie konsoli Google Cloud dla Artifact Registry usuń obraz backendu w sekcji „firebaseapphosting-images”.
W Cloud Secret Manager usuń wszystkie obiekty tajne, których nazwa zawiera „apphosting”. Zwróć szczególną uwagę na to, aby te obiekty tajne nie były używane przez inne backendy ani inne aspekty projektu w Firebase.