Định cấu hình và quản lý phần phụ trợ Lưu trữ ứng dụng

App Hosting được thiết kế để dễ sử dụng và ít cần bảo trì, với các chế độ cài đặt mặc định được tối ưu hoá cho hầu hết các trường hợp sử dụng. Đồng thời, App Hosting cung cấp các công cụ để bạn quản lý và định cấu hình phần phụ trợ cho các nhu cầu cụ thể của mình. Hướng dẫn này mô tả các công cụ và quy trình đó.

Đặt và cập nhật biến môi trường

Đôi khi, bạn có thể cần định cấu hình bổ sung cho quy trình xây dựng. App Hosting cung cấp tính năng định cấu hình môi trường để lưu trữ và truy xuất loại dữ liệu này cho dự án của bạn thông qua Firebase và trong apphosting.yaml.

Việc đặt biến môi trường trong bảng điều khiển Firebase là cách nhanh nhất để bắt đầu. Hãy sử dụng apphosting.yaml nếu bạn cần lưu trữ và truy cập các tham số bí mật, đặt các biến chỉ có sẵn tại thời điểm bản dựng hoặc thời gian chạy, hoặc chia sẻ các biến môi trường trên nhiều môi trường. Với cả bảng điều khiển và apphosting.<env>.yaml, bạn có thể đặt các giá trị khác nhau cho các môi trường khác nhau.

Bảng điều khiển Firebase

Ảnh chụp màn hình hộp thoại bảng điều khiển của Firebase để thêm các biến môi trường

apphosting.yaml 

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

Cập nhật biến

Bạn có thể thêm, chỉnh sửa hoặc xoá các biến môi trường trong bảng điều khiển Firebase hoặc bằng cách sử dụng apphosting.yaml:

  • Firebase bảng điều khiển:

    1. Trong Bảng điều khiển Firebase, hãy chuyển đến Lưu trữ và không máy chủ > App Hosting.

    2. Chuyển đến Xem phần phụ trợ > Cài đặt > Môi trường.

    3. Thêm, chỉnh sửa hoặc xoá các biến môi trường.

  • apphosting.yaml:

    Tìm hiểu cách tạo và chỉnh sửa tệp theo cách thủ công.

Các thay đổi của bạn sẽ chỉ có hiệu lực với lần triển khai tiếp theo và sẽ không ảnh hưởng đến lần triển khai hiện tại. Bạn có thể lưu và tạo một lần triển khai mới hoặc lưu các biến rồi triển khai sau.

Đặt phạm vi áp dụng của biến

Các biến môi trường được tạo trong Firebase bảng điều khiển có sẵn ở cả thời gian xây dựng và thời gian chạy. Đây cũng là điều kiện mặc định cho các biến được xác định trong apphosting.yaml, trừ phi bạn đã thu hẹp phạm vi đó bằng thuộc tính availability. Trong apphosting.yaml (nhưng không có trong bảng điều khiển), bạn có thể hạn chế một biến môi trường chỉ có sẵn cho môi trường tạo bản dựng hoặc chỉ có sẵn cho môi trường thời gian chạy.

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

Đối với các ứng dụng Next.js, bạn cũng có thể sử dụng tiền tố NEXT_PUBLIC_ theo cách tương tự như trong tệp dotenv để giúp một biến có thể truy cập trong trình duyệt.

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

Tệp dotenv cho Next.js

Đối với các ứng dụng Next.js, dotenv tệp chứa các biến môi trường hoạt động với App Hosting.

Khi tạo hoặc cập nhật phần phụ trợ, bạn có thể chuyển các biến môi trường từ tệp dotenv sang Bảng điều khiển Firebase bằng cách sao chép và dán toàn bộ nội dung của tệp dotenv vào trường "Khoá" đầu tiên trong biểu mẫu "Thêm mới" trong Cài đặt biến môi trường.

Tất cả các biến môi trường được sao chép theo cách này phải được định dạng gọn gàng vào biểu mẫu mà không cần nhập từng biến, miễn là thông tin đầu vào có định dạng như sau:

KEY1=value1
KEY2=value2
KEY3=value3

Để kiểm soát biến môi trường phức tạp hoặc chi tiết với bất kỳ khung nào, chúng tôi khuyên bạn nên sử dụng apphosting.yaml.

Biến môi trường được tự động điền

Có một số biến môi trường được tự động điền bởi App Hosting. Các biến này bao gồm những biến được Google Cloud, cũng như các biến môi trường dành riêng cho Firebase khi appId được đặt trên phần phụ trợ trong quá trình thiết lập:

  • FIREBASE_CONFIG: (có trong môi trường bản dựng và thời gian chạy) Cung cấp thông tin cấu hình dự án Firebase sau:

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

    Cấu hình này được áp dụng tự động khi bạn khởi chạy SDK Firebase Admin mà không có đối số.

  • FIREBASE_WEBAPP_CONFIG: (chỉ có trong môi trường tạo bản dựng) Cung cấp thông tin cấu hình dự án Firebase sau:

    {
  "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 tự động kiểm tra biến môi trường FIREBASE_WEBAPP_CONFIG này trong một tập lệnh postinstall trong quá trình xây dựng, cho phép bạn cũng khởi chạy SDK máy khách mà không có đối số.

Hãy xem phần Tự động khởi chạy SDK của Firebase dành cho quản trị viên và SDK web để biết thêm thông tin về cách sử dụng các biến môi trường này để khởi chạy SDK.

Xin lưu ý rằng các giá trị trong cấu hình Firebase thực tế sẽ tương ứng với các tài nguyên cụ thể mà bạn đã cung cấp trong dự án.

Hệ phân cấp biến

Firebase App Hosting áp dụng các biến của bạn theo thứ tự ưu tiên dựa trên nguồn của chúng. Ví dụ: các giá trị được đặt trong bảng điều khiển Firebase luôn ghi đè hoặc có quyền ưu tiên cao hơn các giá trị được đặt trong apphosting.yaml và dotenv tệp.

Sau đây là thứ tự ưu tiên đầy đủ:

  1. Firebase bảng điều khiển → các biến được đặt trong bảng điều khiển
  2. apphosting.<env>.yaml → các biến được chỉ định trong một tệp yaml dành riêng cho môi trường, chẳng hạn như apphosting.staging.yaml (xem Triển khai nhiều môi trường)
  3. apphosting.yaml → các biến được chỉ định trong tệp apphosting.yaml
  4. Hệ thống Firebase → các biến do Firebase đặt chứa các giá trị cho firebase_config json hoặc firebase_webapp_config, cũng như các biến môi trường đặt tên máy chủ và cổng cho các ứng dụng SSR (do bộ chuyển đổi App Hosting đặt trong bundle.yaml)

Tên và giới hạn dành riêng

Các biến môi trường được xác định trong hợp đồng thời gian chạy vùng chứa Cloud Run được dành riêng và không thể đặt.

Các biến môi trường do môi trường cung cấp, ngoài những biến được đặt tự động, có thể thay đổi trong các phiên bản thời gian chạy trong tương lai. Để có kết quả tốt nhất, bạn không nên phụ thuộc vào hoặc sửa đổi bất kỳ biến môi trường nào mà bạn chưa đặt một cách rõ ràng và cân nhắc thêm tiền tố cho bất kỳ biến môi trường nào bằng một khoá duy nhất để tránh xung đột.

Một số khoá biến môi trường được dành riêng cho mục đích sử dụng nội bộ. Đừng sử dụng bất kỳ khoá nào trong số này trong tệp cấu hình:

  • Chuỗi trống ("")
  • Các khoá chứa "="
  • Các khoá bắt đầu bằng X_FIREBASE_, X_GOOGLE_ hoặc CLOUD_RUN_
  • PORT
  • K_SERVICE
  • K_REVISION
  • K_CONFIGURATION
  • Khoá trùng lặp

Tạo và chỉnh sửa apphosting.yaml

Đối với cấu hình nâng cao như bí mật hoặc chế độ cài đặt thời gian chạy như giới hạn về mức độ đồng thời, CPU và bộ nhớ, bạn cần tạo và chỉnh sửa tệp apphosting.yaml trong thư mục gốc của ứng dụng. Tệp này hỗ trợ các tham chiếu đến các bí mật được quản lý bằng Cloud Secret Manager, giúp bạn kiểm tra an toàn vào hệ thống kiểm soát nguồn.

Để tạo apphosting.yaml, hãy chạy lệnh sau:

firebase init apphosting

Lệnh này tạo một tệp apphosting.yaml cơ bản với cấu hình mẫu (đã nhận xét). Sau khi chỉnh sửa, một tệp apphosting.yaml điển hình có thể có dạng như sau, với các chế độ cài đặt cho dịch vụ Cloud Run của phần phụ trợ, một số biến môi trường và một số tham chiếu đến các bí mật do Cloud Secret Manager quản lý:

# 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

Phần còn lại của hướng dẫn này cung cấp thêm thông tin và bối cảnh cho các chế độ cài đặt mẫu này.

Định cấu hình chế độ cài đặt dịch vụ Cloud Run

Với apphosting.yaml chế độ cài đặt, bạn có thể định cấu hình cách cung cấp dịch vụ Cloud Run. Các chế độ cài đặt có sẵn cho dịch vụ Cloud Run được cung cấp trong đối tượng runConfig:

  • cpu – Số lượng CPU được sử dụng cho mỗi thực thể phân phát (mặc định là 0).
  • memoryMiB – Lượng bộ nhớ được phân bổ cho mỗi thực thể phân phát trong MiB (mặc định là 512)
  • maxInstances – Số lượng vùng chứa tối đa có thể chạy cùng một lúc (mặc định là 100 và do hạn mức quản lý)
  • minInstances – Số lượng vùng chứa luôn hoạt động (mặc định là 0).
  • concurrency – Số lượng yêu cầu tối đa mà mỗi thực thể phân phát có thể nhận (mặc định là 80).

Lưu ý mối quan hệ quan trọng giữa cpu và memoryMiB; bộ nhớ có thể được đặt thành bất kỳ giá trị số nguyên nào từ 128 đến 32768, nhưng việc tăng giới hạn bộ nhớ có thể yêu cầu tăng giới hạn CPU:

  • Trên 4GiB yêu cầu tối thiểu 2 CPU
  • Trên 8GiB yêu cầu tối thiểu 4 CPU
  • Trên 16GiB yêu cầu tối thiểu 6 CPU
  • Trên 24GiB yêu cầu tối thiểu 8 CPU

Tương tự, giá trị của cpu ảnh hưởng đến chế độ cài đặt mức độ đồng thời. Nếu bạn đặt một giá trị nhỏ hơn 1 CPU, bạn phải đặt mức độ đồng thời thành 1 và CPU sẽ chỉ được phân bổ trong quá trình xử lý yêu cầu.

Ghi đè tập lệnh xây dựng và chạy

App Hosting suy luận lệnh xây dựng và lệnh bắt đầu của ứng dụng dựa trên khung được phát hiện. Nếu muốn sử dụng bản dựng hoặc lệnh bắt đầu tuỳ chỉnh, bạn có thể ghi đè App Hosting's mặc định trong apphosting.yaml.

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

Lệnh ghi đè lệnh xây dựng có quyền ưu tiên cao hơn mọi lệnh xây dựng khác và chọn không sử dụng bộ chuyển đổi khung cũng như tắt mọi tính năng tối ưu hoá dành riêng cho khung mà App Hosting cung cấp. Bạn nên sử dụng lệnh này khi các tính năng của ứng dụng không được bộ chuyển đổi hỗ trợ tốt. Nếu bạn muốn thay đổi lệnh xây dựng nhưng vẫn sử dụng các bộ chuyển đổi do chúng tôi cung cấp, hãy đặt tập lệnh xây dựng trong package.json thay vì như mô tả trong App Hosting bộ chuyển đổi khung.

Sử dụng lệnh ghi đè lệnh chạy khi có một lệnh cụ thể mà bạn muốn sử dụng để bắt đầu ứng dụng khác với lệnh do App Hosting-suy luận.

Định cấu hình đầu ra bản dựng

App Hosting theo mặc định tối ưu hoá việc triển khai ứng dụng bằng cách xoá các tệp đầu ra không sử dụng như được khung chỉ định. Nếu muốn tối ưu hoá thêm kích thước triển khai ứng dụng hoặc bỏ qua các tính năng tối ưu hoá mặc định, bạn có thể ghi đè tính năng này trong apphosting.yaml.

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

Tham số include nhận một danh sách các thư mục và tệp liên quan đến thư mục gốc của ứng dụng cần thiết để triển khai ứng dụng của bạn. Nếu bạn muốn đảm bảo rằng tất cả các tệp đều được giữ lại, hãy đặt include thành [.] và tất cả các tệp sẽ được triển khai.

Lưu trữ và truy cập các tham số bí mật

Thông tin nhạy cảm như khoá API phải được lưu trữ dưới dạng bí mật. Bạn có thể tham chiếu các bí mật trong apphosting.yaml để tránh kiểm tra thông tin nhạy cảm vào hệ thống kiểm soát nguồn.

Các tham số thuộc loại secret biểu thị các tham số chuỗi có giá trị được lưu trữ trong Cloud Secret Manager. Thay vì lấy trực tiếp giá trị, các tham số bí mật sẽ kiểm tra sự tồn tại trong Cloud Secret Manager và tải các giá trị trong quá trình triển khai.

  -   variable: API_KEY
      secret: myApiKeySecret

Các bí mật trong Cloud Secret Manager có thể có nhiều phiên bản. Theo mặc định, giá trị của một tham số bí mật có sẵn cho phần phụ trợ đang hoạt động của bạn được ghim vào phiên bản mới nhất có sẵn của bí mật tại thời điểm xây dựng phần phụ trợ. Nếu có yêu cầu về việc quản lý phiên bản và vòng đời của các tham số, bạn có thể ghim vào các phiên bản cụ thể bằng Cloud Secret Manager. Ví dụ: để ghim vào phiên bản 5:

  - variable: PINNED_API_KEY
    secret: myApiKeySecret@5

Bạn có thể tạo bí mật bằng lệnh CLI Firebase firebase apphosting:secrets:set và bạn sẽ được nhắc thêm các quyền cần thiết. Quy trình này cho phép bạn tự động thêm tham chiếu bí mật vào apphosting.yaml.

Để sử dụng đủ bộ chức năng của Cloud Secret Manager, bạn có thể sử dụng bảng điều khiển Cloud Secret Manager. Nếu làm như vậy, bạn cần cấp quyền cho phần phụ trợ App Hosting bằng lệnh CLI Firebase firebase apphosting:secrets:grantaccess.

Định cấu hình quyền truy cập VPC

Phần phụ trợ App Hosting có thể kết nối với mạng Đám mây riêng ảo (VPC). Để biết thêm thông tin và ví dụ, hãy xem phần Kết nối Firebase App Hosting với mạng VPC.

Sử dụng tính năng ánh xạ vpcAccess trong tệp apphosting.yaml để định cấu hình quyền truy cập. Sử dụng tên hoặc mã trình kết nối/mạng đủ điều kiện. Việc sử dụng mã cho phép tính di động giữa các môi trường dàn dựng và môi trường sản xuất với các trình kết nối/mạng khác nhau.

Cấu hình lưu lượng truy cập trực tiếp 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

Cấu hình trình kết nối không máy chủ (apphosting.yaml):

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

Quản lý phần phụ trợ

Các lệnh để quản lý cơ bản phần phụ trợ App Hosting được cung cấp trong Bảng điều khiển Firebase và Firebase CLI. Phần này mô tả một số tác vụ quản lý phổ biến hơn, bao gồm cả việc tạo và xoá phần phụ trợ.

Tạo phần phụ trợ

Phần phụ trợ App Hosting là tập hợp các tài nguyên được quản lý mà App Hosting tạo để xây dựng và chạy ứng dụng web của bạn.

Firebase bảng điều khiển: Chuyển đến Lưu trữ và không máy chủ > App Hosting, sau đó nhấp vào Tạo phần phụ trợ (nếu đây là phần phụ trợ đầu tiên trong dự án Firebase của bạn, hãy nhấp vào Bắt đầu).

Firebase CLI: (phiên bản 13.15.4 trở lên) Để tạo phần phụ trợ, hãy chạy lệnh sau từ thư mục gốc của thư mục dự án cục bộ, cung cấp mã dự án của bạn làm đối số:

firebase apphosting:backends:create --project PROJECT_ID

Đối với cả bảng điều khiển hoặc CLI, hãy làm theo lời nhắc để chọn một khu vực, thiết lập kết nối GitHub, và định cấu hình các chế độ cài đặt triển khai cơ bản sau:

  • Đặt thư mục gốc của ứng dụng (mặc định là /)

    Đây thường là nơi đặt tệp package.json.

  • Đặt nhánh đang hoạt động

    Đây là nhánh của kho lưu trữ GitHub được triển khai đến URL đang hoạt động của bạn. Thông thường, đây là nhánh mà các nhánh tính năng hoặc nhánh phát triển được hợp nhất.

  • Chấp nhận hoặc từ chối triển khai tự động

    Tính năng triển khai tự động được bật theo mặc định. Khi hoàn tất việc tạo phần phụ trợ, bạn có thể chọn triển khai ứng dụng của mình ngay lập tức lên App Hosting.

  • Chỉ định tên cho phần phụ trợ.

Xoá phần phụ trợ

Để xoá hoàn toàn một phần phụ trợ, trước tiên, hãy sử dụng Firebase console hoặc Firebase CLI để xoá phần phụ trợ đó, sau đó xoá các tài sản liên quan theo cách thủ công, đặc biệt cẩn thận để không xoá bất kỳ tài nguyên nào có thể được các phần phụ trợ khác hoặc các khía cạnh khác của dự án Firebase sử dụng.

Firebase bảng điều khiển: Trên trình đơn Cài đặt, hãy chọn Xoá phần phụ trợ.

Firebase CLI: (phiên bản 13.15.4 trở lên)

  1. Chạy lệnh sau để xoá phần phụ trợ App Hosting. Lệnh này sẽ vô hiệu hoá tất cả miền cho phần phụ trợ của bạn và xoá dịch vụ được liên kết Cloud Run:

    firebase apphosting:backends:delete BACKEND_ID --project PROJECT_ID

  2. (Không bắt buộc) Trong thẻ bảng điều khiển Google Cloud cho Artifact Registry, hãy xoá hình ảnh cho phần phụ trợ của bạn trong "firebaseapphosting-images".

  3. Trong Cloud Secret Manager, hãy xoá mọi bí mật có "apphosting" trong tên bí mật, đặc biệt cẩn thận để đảm bảo rằng các bí mật này không được các phần phụ trợ khác hoặc các khía cạnh khác của dự án Firebase sử dụng.