跳至主要內容

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 環境變數（服務帳戶金鑰檔案的路徑）
  2. 在 GCP 上執行時的預設服務帳戶（Compute Engine、Cloud Run、GKE 等）
  3. 透過 gcloud auth application-default login 取得的使用者認證資訊（供本機開發使用）

使用金鑰檔案路徑
「使用金鑰檔案路徑」的直接連結

你也可以傳入服務帳戶金鑰檔案的路徑：

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
服務帳戶金鑰 JSON 物件或金鑰檔案路徑。如未提供，則使用 Application Default Credentials。

prefix?:

string
所有鍵可使用的選用前綴（作用如同子目錄）。

id?:

string
= Auto-generated
此檔案系統執行個體的唯一識別碼

displayName?:

string
在 UI 中顯示的易讀名稱

icon?:

FilesystemIcon
UI 使用的圖示識別碼

description?:

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

readOnly?:

boolean
= false
設為 true 時，會封鎖所有寫入操作

endpoint?:

string
自訂 API 端點 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) - 取得檔案或目錄的中繼資料

init()
「init」的直接連結

初始化檔案系統。確認 bucket 存取權與認證資訊。

await filesystem.init()

getInfo()
「getinfo」的直接連結

傳回此檔案系統執行個體的中繼資料。

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