App Hosting được thiết kế để dễ sử dụng và ít phải 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 các phần phụ trợ cho nhu cầu cụ thể của mình. Hướng dẫn này mô tả những công cụ và quy trình đó.
Tạo và chỉnh sửa apphosting.yaml
Đối với cấu hình nâng cao, chẳng hạn như biến môi trường hoặc chế độ cài đặt thời gian chạy (chẳng hạn 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 cũng hỗ trợ các tham chiếu đến dữ liệu bí mật được quản lý bằng Cloud Secret Manager, giúp bạn có thể kiểm tra một cách an toàn vào chế độ kiểm soát nguồn.
Để tạo apphosting.yaml, hãy chạy lệnh sau:
firebase init apphosting
Thao tác này sẽ tạo một tệp apphosting.yaml cơ bản để bắt đầu với cấu hình mẫu (được nhận xét). Sau khi chỉnh sửa, một tệp apphosting.yaml thông thường 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ố thông tin 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 ví dụ này.
Định cấu hình chế độ cài đặt dịch vụ Cloud Run
Với chế độ cài đặt apphosting.yaml, bạn có thể định cấu hình cách dịch vụ Cloud Run của mình được cung cấp. Các chế độ cài đặt hiện có cho dịch vụ Cloud Run được cung cấp trong đối tượng runConfig:
cpu– Số lượng CPU được dùng cho mỗi phiên bản phân phát (mặc định là 0).memoryMiB– Lượng bộ nhớ được phân bổ cho mỗi phiên bản phân phát tính bằng 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à được quản lý theo hạn mức)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 phiên bản phân phát có thể nhận được (mặc định là 80).
Lưu ý mối quan hệ quan trọng giữa cpu và memoryMiB; bạn có thể đặt bộ nhớ thành bất kỳ giá trị 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:
- Nếu dung lượng lớn hơn 4 GiB, bạn cần có ít nhất 2 CPU
- Nếu trên 8 GiB thì cần có ít nhất 4 CPU
- Nếu có dung lượng trên 16 GiB, bạn cần có ít nhất 6 CPU
- Dung lượng trên 24 GiB yêu cầu ít nhất 8 CPU
Tương tự, giá trị của cpu ảnh hưởng đến chế độ cài đặt đồng thời. Nếu đặ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.
Định cấu hình môi trường
Đôi khi, bạn sẽ cần thêm cấu hình cho quy trình tạo, chẳng hạn như khoá API của bên thứ ba hoặc các chế độ cài đặt có thể điều chỉnh. App Hosting cung cấp cấu hình môi trường trong apphosting.yaml để lưu trữ và truy xuất loại dữ liệu này cho dự án của bạn.
env:
- variable: STORAGE_BUCKET
value: mybucket.firebasestorage.app
Đối với các ứng dụng Next.js, các tệp dotenv chứa biến môi trường cũng sẽ hoạt động với App Hosting. Bạn nên sử dụng apphosting.yaml để kiểm soát biến môi trường chi tiết bằng mọi khung.
Trong apphosting.yaml, bạn có thể chỉ định những quy trình có quyền truy cập vào biến môi trường bằng cách sử dụng thuộc tính availability. Bạn có thể hạn chế một biến môi trường chỉ có sẵn cho môi trường xây dựng hoặc chỉ có sẵn cho môi trường thời gian chạy. Theo mặc định, cả hai đều có thể sử dụng.
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
Khoá biến hợp lệ bao gồm các ký tự A-Z hoặc dấu gạch dưới. 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 dùng bất kỳ khoá nào trong số này trong tệp cấu hình:
- Mọi biến bắt đầu bằng
X_FIREBASE_ PORTK_SERVICEK_REVISIONK_CONFIGURATION
Ghi đè tập lệnh tạo và chạy
App Hosting suy luận lệnh tạo và lệnh khởi động của ứng dụng dựa trên khung được phát hiện. Nếu muốn sử dụng lệnh tạo hoặc lệnh khởi động tuỳ chỉnh, bạn có thể ghi đè các giá trị mặc định của App Hosting trong apphosting.yaml.
scripts:
buildCommand: next build --no-lint
runCommand: node dist/index.js
Lệnh ghi đè bản dựng được ưu tiên hơn mọi lệnh bản dựng khác và chọn loại trừ ứng dụng của bạn khỏi các bộ chuyển đổi khung cũng như tắt mọi hoạt động tối ưu hoá dành riêng cho khung mà App Hosting cung cấp. Bạn nên dùng cách này khi các tính năng của ứng dụng không được bộ chuyển đổi hỗ trợ đầy đủ. Nếu bạn muốn thay đổi lệnh tạo nhưng vẫn sử dụng các bộ chuyển đổi mà chúng tôi cung cấp, hãy đặt tập lệnh tạo trong package.json thay vì như mô tả trong bộ chuyển đổi khung App Hosting.
Sử dụng lệnh ghi đè lệnh chạy khi có một lệnh cụ thể mà bạn muốn dùng để khởi động ứng dụng khác với lệnh App Hosting được suy luận.
Định cấu hình đầu ra bản dựng
App Hosting tối ưu hoá các hoạt động triển khai ứng dụng theo mặc định bằng cách xoá các tệp đầu ra không dùng đến như được chỉ ra bởi khung. 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 chế độ tối ưu hoá mặc định, bạn có thể ghi đè chế độ 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 tương ứng với 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 thông số bí mật
Thông tin nhạy cảm như khoá API phải được lưu trữ dưới dạng thông tin bí mật. Bạn có thể tham chiếu các khoá bí mật trong apphosting.yaml để tránh kiểm tra thông tin nhạy cảm vào chế độ 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ì trực tiếp lấy 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ợ trực tiếp của bạn sẽ đượ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 phần phụ trợ được tạo. 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 khoá bí mật bằng lệnh CLI 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 thông tin tham chiếu bí mật vào apphosting.yaml.
Để sử dụng toàn bộ 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 sẽ cần cấp quyền cho phần phụ trợ App Hosting bằng lệnh CLI firebase
apphosting:secrets:grantaccess.
Định cấu hình quyền truy cập vào VPC
Phần phụ trợ App Hosting có thể kết nối với mạng Virtual Private Cloud (VPC). Để biết thêm thông tin và xem ví dụ, hãy xem phần Kết nối Firebase App Hosting với một mạng VPC.
Sử dụng ánh xạ vpcAccess trong tệp apphosting.yaml để định cấu hình quyền truy cập.
Sử dụng tên mạng đủ điều kiện hoặc mã nhận dạng. Việc sử dụng mã nhận dạng cho phép khả năng di chuyển giữa các môi trường dàn dựng và môi trường phát hành công khai với các trình kết nối/mạng khác nhau.
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
Quản lý các phần phụ trợ
Các lệnh để quản lý cơ bản các phần phụ trợ App Hosting được cung cấp trong CLI Firebase và bảng điều khiển Firebase. 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á các phần phụ trợ.
Tạo một 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 ra để xây dựng và chạy ứng dụng web của bạn.
Bảng điều khiển của Firebase: Trong trình đơn Tạo, hãy chọn Lưu trữ ứng dụng rồi chọn Bắt đầu.
CLI: (Phiên bản 13.15.4 trở lên) Để tạo một phần phụ trợ, hãy chạy lệnh sau từ gốc của thư mục dự án cục bộ, cung cấp projectID 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 lưu trữ tệp
package.jsoncủa bạn.
Đặt nhánh trực tiếp
Đây là nhánh của kho lưu trữ GitHub được triển khai vào URL trực tiếp của bạn. Đây thường 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 tính năng phát hành tự động
Tính năng phát hành tự động được bật theo mặc định. Sau khi hoàn tất quá trình 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.
Đặt tên cho phần phụ trợ của bạn.
Xoá một phần phụ trợ
Để xoá hoàn toàn một phần phụ trợ, trước tiên, hãy dùng CLI Firebase hoặc bảng điều khiển Firebase để xoá phần phụ trợ đó, rồi xoá các tài sản có liên quan theo cách thủ công. Bạn cần đặc biệt chú ý để không xoá bất kỳ tài nguyên nào mà các phần phụ trợ khác hoặc các khía cạnh khác trong dự án Firebase của bạn có thể sử dụng.
Bảng điều khiển Firebase: Trong trình đơn Cài đặt, hãy chọn Xoá phần phụ trợ.
CLI: (Phiên bản 13.15.4 trở lên)
Chạy lệnh sau để xoá App Hosting Backend. Thao tác này sẽ vô hiệu hoá tất cả các miền cho phần phụ trợ của bạn và xoá dịch vụ Cloud Run được liên kết:
firebase apphosting:backends:delete BACKEND_ID --project PROJECT_ID(Không bắt buộc) Trong thẻ Google Cloud Console cho Artifact Registry, hãy xoá hình ảnh cho phần phụ trợ của bạn trong "firebaseapphosting-images".
Trong Cloud Secret Manager, hãy xoá mọi bí mật có "apphosting" trong tên bí mật, đặc biệt chú ý để đảm bảo rằng các bí mật này không được dùng bởi các phần phụ trợ khác hoặc các khía cạnh khác của dự án Firebase.