For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /zh-tw/docs/web/deploy-google-cloud.md (or send Accept: text/markdown).
部署到 Google Cloud
在 Cloud Build 上構建套件的 Docker 映象，用託管金鑰在 Cloud Run 上執行，並繫結你的域名。
初學者演練
前提條件：應用在本地可用、一個可以從網際網路訪問的真實資料庫（設定資料庫），以及你要上線的功能對應的服務商賬戶。你需要一個 Google 賬戶；配置結算時會要求繫結銀行卡，儘管輕度使用仍在免費額度內。
快速術語：容器映象是應用打包後的副本，任何主機都能執行。Artifact Registry 是 Google 存放映象的倉庫。Cloud Build 在 Google 的機器上構建映象——本地不需要 Docker。Cloud Run 把映象作為 HTTPS 服務執行並自動擴縮。Secret Manager 儲存密碼和金鑰。修訂版本（revision）是服務的一次部署版本。
你將構建的內容：一個 Google Cloud 專案、一個存放映象的 Artifact Registry 倉庫、一個通過 HTTPS 提供應用的 Cloud Run 服務、存放在 Secret Manager 中的金鑰，以及一個託管 Postgres。套件根目錄的 Dockerfile 已經能產出一個監聽 8080 埠的獨立 Next.js 伺服器——正是 Cloud Run 所期望的。
誠實的成本說明：Cloud Run 的免費額度可以覆蓋輕度流量，但 Cloud SQL——Google 的託管 Postgres——沒有免費層。Supabase 或 Neon 的免費資料庫是最便宜的起步方式；本指南走這條路。建議在 Billing → Budgets & alerts 下新增預算提醒，然後再開始折騰。
建立賬戶並安裝 CLI
1. 開啟 console.cloud.google.com，用你的 Google 賬戶登入並接受條款。
2. 按提示關聯結算：Billing → Link a billing account → Create billing account。啟用賬戶需要銀行卡；試用額度可以覆蓋早期實驗。
3. 點選專案下拉選單 → New Project，命名並 Create——或複用你為 Google 登入建立的專案；一個專案就夠了。
4. 從 cloud.google.com/sdk 安裝 Google Cloud CLI：下載適合你作業系統的安裝程式並完成安裝，然後開啟一個新終端，讓 gcloud 命令可用。
5. 執行下面兩條命令。第一條會開啟瀏覽器為 CLI 授權；第二條選擇你的專案——使用控制台儀錶板上顯示的專案 ID，它不一定和名稱相同。
預期結果：gcloud config list 顯示你的賬戶和專案。如果 gcloud 無法識別，重新開啟終端或先完成安裝程式。
gcloud auth login
gcloud config set project YOUR_PROJECT_ID建立生產資料庫
新手路徑——Google 之外的託管 Postgres。在 supabase.com：New project → 選擇名稱、資料庫密碼和區域 → 等待初始化 → Project Settings → Database。Supabase 提供兩種連線串：5432 埠的會話池/直連，和 6543 埠的事務池——5432 串用於遷移和長連線客戶端，6543 串用於無伺服器應用。在 neon.tech：New project → 複製它顯示的連線串。兩者都可以；保持密碼部分完整。
把直連/會話串放進根目錄 .env 的 DATABASE_URL——遷移工具讀取根目錄檔案且需要會話連線——以及 apps/web/.env.local 供本地開發伺服器使用。然後從倉庫根目錄執行一次遷移命令，在新資料庫中建立套件的表。已部署應用使用的 DATABASE_URL 金鑰也可以換成 6543 的池化串。
Google 原生替代方案是 Cloud SQL——同一專案內的託管 Postgres。它沒有免費層，且私有 IP 連線需要 VPC 聯結器——把它當作以後的升級，而不是起點。
# DATABASE_URL=<the direct/session Postgres string, port 5432> in .env + apps/web/.env.local, then:
corepack pnpm --filter @supastack/db db:migrate啟用服務並推送映象
從倉庫根目錄執行下面的命令。它們會啟用本次部署用到的四個 Google 服務、在 Artifact Registry 中建立 Docker 倉庫，並把倉庫提交給 Cloud Build——它在遠端構建根目錄的 Dockerfile，因此不需要 Docker Desktop。
替換 YOUR_PROJECT_ID，並選擇一個區域——下面是 us-central1——倉庫和服務都複用它。預期結果：構建日誌滾動數分鐘，以 DONE / STATUS: SUCCESS 結束。隨後映象會出現在控制台的 Artifact Registry → supastack → web 下。
gcloud services enable run.googleapis.com artifactregistry.googleapis.com cloudbuild.googleapis.com secretmanager.googleapis.com
gcloud artifacts repositories create supastack --repository-format=docker --location=us-central1
gcloud builds submit --tag us-central1-docker.pkg.dev/YOUR_PROJECT_ID/supastack/web:latest把金鑰存入 Secret Manager
金鑰絕不能進入 --set-env-vars 或映象——兩者都以明文儲存，任何能讀取服務配置的人都看得見。Secret Manager 讓它們保持加密並在執行時注入。
1. 在控制台開啟 Security → Secret Manager → Create Secret。
2. 建立 DATABASE_URL，值為完整的 Postgres 連線串——池化的無伺服器串對應用來說就可以；AUTH_SECRET，至少 32 個隨機字元（openssl rand -hex 32 可以生成一個）；以及 CREDENTIAL_ENCRYPTION_KEY，值為 Base64 編碼的 32 位元組金鑰（openssl rand -base64 32）；它用於加密工作區在應用中儲存的服務商金鑰。
3. 為每個已啟用的服務商各建一個金鑰——例如 STRIPE_SECRET_KEY 加 STRIPE_WEBHOOK_SECRET、RESEND_API_KEY、GOOGLE_CLIENT_SECRET、GITHUB_CLIENT_SECRET。像 EMAIL_PROVIDER=resend 這樣的非機密設定保持為普通環境變數，不要做成金鑰。
服務第一次引用某個金鑰時，它的執行時服務賬戶需要讀取許可權——通過控制台的服務編輯器掛載金鑰時，Google 會自動提供該授權；在 CLI 上，部署錯誤會報出需要授予的 Secret Manager 角色名。
# Secrets to create in Secret Manager:
DATABASE_URL # Postgres connection string — the pooled serverless string is fine
AUTH_SECRET # openssl rand -hex 32
CREDENTIAL_ENCRYPTION_KEY # openssl rand -base64 32
# plus one per enabled provider, e.g.:
STRIPE_SECRET_KEY
STRIPE_WEBHOOK_SECRET
RESEND_API_KEY
GOOGLE_CLIENT_SECRET
GITHUB_CLIENT_SECRET部署 Cloud Run 服務
控制台路徑：Cloud Run → Create service → Deploy one revision from an existing container image → 選擇剛推送的 …/supastack/web:latest 映象 → 選擇相同區域 → 在 Authentication 下選擇 Allow unauthenticated invocations（這是一個公開應用）→ Create。
下面的 CLI 等價命令在同一步驟中加上環境變數接線。明文配置放進 --set-env-vars；金鑰在 --set-secrets 中按 Secret Manager 名稱引用。把你的服務商開關（EMAIL_PROVIDER、BILLING_PROVIDER、AI_PROVIDER、JOB_PROVIDER）作為普通環境變數與 APP_URL 並列新增。
APP_ENV=production 是必需的——沒有它，應用會以 local 模式啟動：生產配置校驗被跳過，安全 cookie 字首保持關閉，僅限開發的 /mail-preview 頁面仍然公開可訪問（當 EMAIL_PROVIDER=local 時會洩露本地郵件發件箱）。生產環境在啟動時還需要另外四個值：EXPO_PUBLIC_API_URL 是移動應用訪問 API 所用的公開 https URL——設為服務 URL（純 Web 部署時與 APP_URL 相同）；EXPO_PUBLIC_APP_SCHEME 是移動端深鏈 scheme——不上線移動應用時，任何合法值如 supastack 都可以；MOBILE_ALLOWED_ORIGINS 是伺服器信任的精確 https origin 的逗號分隔列表——你的應用 URL 就是正確的起點，萬用字元會被拒絕；CREDENTIAL_ENCRYPTION_KEY 加密已儲存的服務商憑據，留在 Secret Manager 中。
首次部署時 Cloud Run 會分配一個 https://….run.app URL，而應用的 APP_URL 必須等於它的真實公開 URL，認證回撥和連結才能工作。所以先用佔位符部署一次，從服務頁面複製 *.run.app URL，然後更新服務（控制台：Edit & deploy new revision，或重新執行該命令），把 APP_URL——以及對應的 EXPO_PUBLIC_API_URL / MOBILE_ALLOWED_ORIGINS 值——設定為它。容器埠保持 8080——Cloud Run 的預設值已經與 Dockerfile 的 PORT 一致。
gcloud run deploy supastack --image us-central1-docker.pkg.dev/YOUR_PROJECT_ID/supastack/web:latest --region us-central1 --allow-unauthenticated --set-env-vars "APP_ENV=production,APP_URL=https://YOUR_SERVICE_URL,EXPO_PUBLIC_API_URL=https://YOUR_SERVICE_URL,EXPO_PUBLIC_APP_SCHEME=supastack,MOBILE_ALLOWED_ORIGINS=https://YOUR_SERVICE_URL" --set-secrets "DATABASE_URL=DATABASE_URL:latest,AUTH_SECRET=AUTH_SECRET:latest,CREDENTIAL_ENCRYPTION_KEY=CREDENTIAL_ENCRYPTION_KEY:latest"繫結你自己的域名（可選）
測試期間可以跳過——*.run.app URL 已經提供 HTTPS。準備好後：Cloud Run → 你的服務 → Custom Domains / Domain Mappings → Add mapping → 選擇服務並輸入你的域名。
如有提示請驗證域名所有權（Google 會引導你完成），然後在你的域名註冊商處建立對映螢幕列出的 DNS 記錄。記錄生效後，託管的 HTTPS 證書會自動簽發——通常幾分鐘，最長一天。
域名開始承載流量後，把 APP_URL 更新為 https://yourdomain.com，並註冊對應的 OAuth redirect URI（https://yourdomain.com/api/auth/callback/…）——登入指南會說明在哪裡配置。
驗證部署
開啟 https://YOUR_SERVICE_URL/api/health——應返回 ok。然後端到端走一遍應用：開啟 URL、註冊、請求郵件驗證碼、確認它能到達收件箱（這需要 EMAIL_PROVIDER=resend、RESEND_API_KEY 和已驗證的發件人——本地介面卡永遠到不了真實收件箱）、登入並使用一個你啟用的功能。
Cloud Run → 你的服務 → Logs 顯示請求和錯誤輸出。如果部署出問題，Revisions 選項卡提供一鍵回滾到上一個修訂版本。
移動端和桌面客戶端必須指向這個 HTTPS 後端：Expo 用 apps/mobile/.env.local 中的 EXPO_PUBLIC_API_URL，桌面外殼用 SUPASTACK_APP_URL。