跳至主要內容

GCSFilesystem

將檔案儲存在 Google Cloud Storage。有關介面詳情，請參閱 WorkspaceFilesystem 介面。

安裝
安裝 的直接連結

npm install @mastra/gcs

用法
用法 的直接連結

將 GCSFilesystem 加入 Workspace，並指派給 Agent：

import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { GCSFilesystem } from '@mastra/gcs'

const workspace = new Workspace({
  filesystem: new GCSFilesystem({
    bucket: 'my-gcs-bucket',
    projectId: 'my-project-id',
    credentials: JSON.parse(process.env.GCS_SERVICE_ACCOUNT_KEY),
  }),
})

const agent = new Agent({
  id: 'file-agent',
  name: 'file-agent',
  model: 'anthropic/claude-opus-4-7',
  workspace,
})

使用 Application Default Credentials
使用 Application Default Credentials 的直接連結

若在 Google Cloud 上運行，或已設定 gcloud CLI，便可省略憑證：

import { GCSFilesystem } from '@mastra/gcs'

const filesystem = new GCSFilesystem({
  bucket: 'my-gcs-bucket',
  // Uses Application Default Credentials automatically
})

Application Default Credentials (ADC) 會按以下次序自動尋找憑證：

  1. GOOGLE_APPLICATION_CREDENTIALS 環境變數（服務帳戶 key 檔案的路徑）
  2. 在 GCP（Compute Engine、Cloud Run、GKE 等）上運行時的預設服務帳戶
  3. 來自 gcloud auth application-default login 的使用者憑證（用於本機開發）

使用 key 檔案路徑
使用 key 檔案路徑 的直接連結

你亦可傳入服務帳戶 key 檔案的路徑：

import { GCSFilesystem } from '@mastra/gcs'

const filesystem = new GCSFilesystem({
  bucket: 'my-gcs-bucket',
  projectId: 'my-project-id',
  credentials: '/path/to/service-account-key.json',
})

建構函式參數
建構函式參數 的直接連結

bucket:

string
GCS bucket 名稱

projectId?:

string
GCS 項目 ID。使用服務帳戶憑證時必須提供。

credentials?:

object | string
服務帳戶 key JSON 物件或 key 檔案路徑。若未提供，則使用 Application Default Credentials。

prefix?:

string
所有 key 的選用前綴（作用類似子目錄）

id?:

string
= 自動產生
此檔案系統實例的唯一識別碼

displayName?:

string
在 UI 中顯示、方便使用者理解的名稱

icon?:

FilesystemIcon
UI 的圖示識別碼

description?:

string
此檔案系統在 UI 中顯示的簡短說明

readOnly?:

boolean
= false
若為 true，所有寫入操作都會遭到封鎖

endpoint?:

string
自訂 API endpoint URL。用於透過模擬器進行本機開發。

屬性
屬性 的直接連結

id:

string
檔案系統實例識別碼

name:

string
Provider 名稱（'GCSFilesystem'）

provider:

string
Provider 識別碼（'gcs'）

bucket:

string
GCS bucket 名稱

readOnly:

boolean | undefined
檔案系統是否處於唯讀模式

方法
方法 的直接連結

GCSFilesystem 實作 WorkspaceFilesystem 介面，並提供所有標準檔案系統方法：

  • readFile(path, options?) - 讀取檔案內容
  • writeFile(path, content, options?) - 將內容寫入檔案
  • appendFile(path, content) - 將內容附加至檔案
  • deleteFile(path, options?) - 刪除檔案
  • copyFile(src, dest, options?) - 複製檔案
  • moveFile(src, dest, options?) - 移動檔案或重新命名
  • mkdir(path, options?) - 建立目錄
  • rmdir(path, options?) - 移除目錄
  • readdir(path, options?) - 列出目錄內容
  • exists(path) - 檢查路徑是否存在
  • stat(path) - 取得檔案或目錄的 metadata

init()
init 的直接連結

初始化檔案系統。驗證 bucket 存取權及憑證。

await filesystem.init()

getInfo()
getinfo 的直接連結

傳回此檔案系統實例的 metadata。

const info = filesystem.getInfo()
// { id: '...', name: 'GCSFilesystem', provider: 'gcs', status: 'ready' }

getMountConfig()
getmountconfig 的直接連結

傳回掛載設定，供支援掛載此檔案系統類型的 Sandbox 使用。

const config = filesystem.getMountConfig()
// { type: 'gcs', bucket: 'my-bucket', ... }

掛載至 E2B Sandbox
掛載至 E2B Sandbox 的直接連結

GCSFilesystem 可掛載至 E2B Sandbox，讓 bucket 能以本機目錄形式存取：

import { Workspace } from '@mastra/core/workspace'
import { GCSFilesystem } from '@mastra/gcs'
import { E2BSandbox } from '@mastra/e2b'

const workspace = new Workspace({
  mounts: {
    '/data': new GCSFilesystem({
      bucket: 'my-gcs-bucket',
      projectId: 'my-project-id',
      credentials: JSON.parse(process.env.GCS_SERVICE_ACCOUNT_KEY),
    }),
  },
  sandbox: new E2BSandbox({ id: 'dev-sandbox' }),
})

有關掛載的更多詳情，請參閱 E2BSandbox 參考。

On this page