Cloud Run 權限設定

實驗性功能：Cloud Run 目前處於 Alpha 狀態，並未積極開發中。

本文件描述 Remotion Cloud Run 所需的 GCP IAM 權限，說明每個權限的必要原因，以及如何正確設定服務帳戶以執行渲染。

如需逐步設定權限的指引，請參閱設定指南。

自動設定（建議）

使用 Remotion 提供的安裝腳本，在 Google Cloud Shell 中一鍵完成所有 IAM 設定：

curl -L https://github.com/remotion-dev/remotion/raw/main/packages/cloudrun/src/gcpInstaller/gcpInstaller.tar \
  | tar -x -C . && node install.mjs

依提示選擇 1（設定 Remotion Cloud Run），腳本會自動建立服務帳戶、指派角色並產生金鑰。

手動建立服務帳戶

若需手動設定，首先建立服務帳戶：

gcloud iam service-accounts create remotion-sa \
  --display-name="Remotion Cloud Run Service Account" \
  --project=YOUR_PROJECT_ID

服務帳戶權限

以下政策應指派給 Remotion 服務帳戶。自動化設定流程會建立名為 Remotion API Service Account 的自訂角色，並將其指派給服務帳戶。

若要在 GCP 專案中查看和手動編輯角色，請前往 IAM 管理員中的角色頁面。

若要查看和手動編輯指派給使用者或服務帳戶的權限/角色，請前往 IAM 管理員中的 IAM 頁面。

提示：您隨時可以透過輸入 npx remotion cloudrun permissions 來取得適合您 Remotion Cloud Run 版本的最新權限清單。

所需權限清單

權限	原因
`iam.serviceAccounts.actAs`	在部署時，以預設服務帳戶身分行事，這將授予部署期間所需的進一步權限。
`run.operations.get`	在部署期間需要確認部署是否成功。
`run.routes.invoke`	呼叫已部署的 Cloud Run 服務以執行渲染。
`run.services.create`	部署新的或編輯現有的 Cloud Run 服務。
`run.services.get`	取得現有 Cloud Run 服務的詳細資訊。
`run.services.delete`	刪除不再需要的 Cloud Run 服務。
`run.services.list`	列出 GCP 專案中所有現有的 Cloud Run 服務。
`run.services.update`	更新現有 Cloud Run 服務的設定。
`storage.buckets.create`	在您的 GCP 專案中建立 Cloud Storage Bucket，用於存放網站和渲染結果。
`storage.buckets.get`	取得 Cloud Storage Bucket 的詳細資訊。
`storage.buckets.list`	列出 GCP 專案中所有 Cloud Storage Bucket。
`storage.objects.create`	將檔案上傳到 Cloud Storage Bucket（包含網站檔案及渲染結果）。
`storage.objects.delete`	刪除 Cloud Storage Bucket 中的物件。
`storage.objects.list`	列出 Cloud Storage Bucket 中的物件。
`logging.logEntries.list`	讀取 Cloud Logging 中的日誌條目，以便在渲染失敗時進行除錯。

驗證

有兩種方法可以測試服務帳戶的權限是否已正確設定。

方法一：使用 CLI

npx remotion cloudrun permissions

方法二：以程式方式驗證

使用 testPermissions() 函數進行程式化驗證：

import { testPermissions } from "@remotion/cloudrun";
 
const results = await testPermissions({
  region: "us-east1",
});
 
console.log(results);

指派權限腳本

使用以下腳本批次指派所有必要的細粒度權限：

PROJECT_ID="your-project-id"
SA_EMAIL="remotion-sa@${PROJECT_ID}.iam.gserviceaccount.com"
 
# 建立自訂角色並指派細粒度權限
gcloud iam roles create RemotionCloudRunRole \
  --project=$PROJECT_ID \
  --permissions=\
iam.serviceAccounts.actAs,\
run.operations.get,\
run.routes.invoke,\
run.services.create,\
run.services.get,\
run.services.delete,\
run.services.list,\
run.services.update,\
storage.buckets.create,\
storage.buckets.get,\
storage.buckets.list,\
storage.objects.create,\
storage.objects.delete,\
storage.objects.list,\
logging.logEntries.list
 
# 將自訂角色指派給服務帳戶
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:${SA_EMAIL}" \
  --role="projects/${PROJECT_ID}/roles/RemotionCloudRunRole"

最小權限原則

建議遵循最小權限原則，確保服務帳戶僅擁有執行 Remotion Cloud Run 所需的最少權限。

針對不同使用情境，可區分為以下服務帳戶：

情境	建議角色
部署服務（DevOps / CI）	`run.services.create`、`run.services.update`、`artifactregistry.reader`
上傳站台（應用程式）	`storage.buckets.create`、`storage.objects.create`
觸發渲染（應用程式）	`run.routes.invoke`、`storage.objects.create`、`storage.objects.list`

定期使用 GCP IAM Recommender 審查並移除不必要的權限，降低安全風險。

環境變數設定

產生服務帳戶金鑰後，將憑證加入 .env 檔案：

REMOTION_GCP_PROJECT_ID=your-project-id
REMOTION_GCP_CLIENT_EMAIL=remotion-sa@your-project-id.iam.gserviceaccount.com
REMOTION_GCP_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nMIIE...\n-----END PRIVATE KEY-----\n"

安全提醒：切勿將 .env 提交到版本控制。請確認 .gitignore 已包含 .env。