將 Mastra 部署至 Kubernetes

在多個 Kubernetes pod 上執行 Mastra 應用程式，讓它可在負載平衡器後方橫向擴展。由於每個 pod 都是獨立程序，各 pod 必須共用發佈／訂閱後端及資料庫，否則在其中一個 pod 啟動的工作，其他 pod 將無法得知。

資訊

本指南涵蓋如何部署 Mastra 伺服器。如你使用伺服器適配器或網頁框架，請依照該框架慣常的方式部署。

注意

多 pod 支援依賴目前仍處於 beta 階段的持久 Agent。API 可能會在次要版本中變更。在正式環境採用前，請先閱讀已知限制。

開始之前
開始之前的直接連結

你需要：

一個 Mastra 應用程式
一個 Kubernetes 叢集及 kubectl
一個叢集可從中提取映像檔的容器登錄檔
一個所有 pod 均可連線的共享 Redis 執行個體
一個所有 pod 均可連線的共享 PostgreSQL 資料庫

為何多個 pod 需要共享基礎設施
為何多個 pod 需要共享基礎設施的直接連結

單一 pod 會將執行狀態保留在自己的記憶體內。只有一個 pod 時並無問題，因為每個請求都會到達同一程序。但跨 pod 時便會失效：瀏覽器可能正從 pod A 串流，而使用者的下一個請求卻被路由至 pod B；pod B 並沒有 pod A 上該次執行的記錄。

Redis 和 Postgres 可填補這個缺口：

發佈／訂閱會在 pod 之間傳送事件。當事件在一個 pod 上發佈，其他 pod 都會收到。Mastra 使用 RedisStreamsPubSub，它亦提供按對話串租用的機制，確保同一時間只有一個 pod 擁有某段對話。請參閱 PubSub。
儲存空間會保存執行狀態。持久 Agent 會將每次執行儲存為 Workflow 快照，因此重新啟動後，或請求被路由至其他位置時，任何 pod 都可從資料庫恢復執行。

設定共享基礎設施
設定共享基礎設施的直接連結

讓 Mastra 執行個體指向 Redis 和 Postgres。從環境變數讀取連線資料，令同一映像檔可在每個 pod 中執行。

安裝後端依賴套件：

npm
pnpm
Yarn
Bun

npm install @mastra/redis-streams @mastra/pg @mastra/redis ioredis

pnpm add @mastra/redis-streams @mastra/pg @mastra/redis ioredis

yarn add @mastra/redis-streams @mastra/pg @mastra/redis ioredis

bun add @mastra/redis-streams @mastra/pg @mastra/redis ioredis

在 Mastra 執行個體上設定發佈／訂閱、儲存空間及共享快取：

src/mastra/index.ts
import { Mastra } from '@mastra/core'
import { RedisStreamsPubSub } from '@mastra/redis-streams'
import { RedisServerCache } from '@mastra/redis'
import { PostgresStore } from '@mastra/pg'
import Redis from 'ioredis'

export const mastra = new Mastra({
  // Carries events between pods, and provides
  // per-thread leases so one pod owns a conversation at a time.
  pubsub: new RedisStreamsPubSub({
    url: process.env.REDIS_URL!,
  }),
  // Persists run state so any pod can resume a run.
  storage: new PostgresStore({
    id: 'mastra-storage',
    connectionString: process.env.DATABASE_URL!,
  }),
  // Shared event cache so a reconnecting client can replay missed chunks
  // from any pod, not only the one that started the run.
  cache: new RedisServerCache({ client: new Redis(process.env.REDIS_URL!) }),
})

cache 令可恢復的串流能夠跨 pod 運作。重新連線的用戶端會從此快取重播錯過的事件，因此它必須共用。預設的記憶體內快取只可在同一程序內提供重播。

使用持久 Agent
使用持久 Agent 的直接連結

一般 Agent 會將串流及核准狀態保留在一個 pod 的記憶體內，因此請求落在另一個 pod 時，這些狀態無法保留。持久 Agent 會在 Workflow 內執行 Agent 迴圈並保存其狀態，讓任何 pod 都可觀察或恢復同一次執行。

使用 createDurableAgent() 包裝 Agent：

src/mastra/agents/assistant.ts
import { Agent } from '@mastra/core/agent'
import { createDurableAgent } from '@mastra/core/agent/durable'

const agent = new Agent({
  id: 'assistant',
  name: 'Assistant',
  instructions: 'You are a helpful assistant.',
  model: 'openai/gpt-5.6-sol',
})

export const durableAssistant = createDurableAgent({ agent })

在上述 Mastra 執行個體註冊持久 Agent。其執行狀態現會存放於 Postgres，而事件則透過 Redis 傳送，因此每個 pod 都可存取該次執行。

部署
部署的直接連結

建置 Mastra 伺服器並將它容器化，然後把映像檔推送至你的登錄檔。請依照 Mastra 伺服器指南進行建置，並確保伺服器讀取 process.env.PORT 及監聽 0.0.0.0。

將共享連線字串儲存為 Secret：

kubectl create secret generic mastra-secrets \
  --from-literal=REDIS_URL='redis://redis:6379' \
  --from-literal=DATABASE_URL='postgresql://user:pass@postgres:5432/mastra'

套用 Deployment，讓它執行映像檔並讀取共享 Secret。先以一個副本開始，讓第一個 pod 自行建立資料庫結構，然後在下一步擴展：

deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: mastra
spec:
  replicas: 1
  selector:
    matchLabels:
      app: mastra
  template:
    metadata:
      labels:
        app: mastra
    spec:
      containers:
        - name: mastra
          image: your-registry/mastra:latest
          ports:
            - containerPort: 8080
          env:
            - name: PORT
              value: '8080'
          envFrom:
            - secretRef:
                name: mastra-secrets
          readinessProbe:
            tcpSocket:
              port: 8080
          livenessProbe:
            tcpSocket:
              port: 8080
          resources:
            requests:
              cpu: 500m
              memory: 512Mi

下方 HorizontalPodAutoscaler 需要 resources.requests.cpu 值。Kubernetes 以使用量除以請求量來計算 CPU 使用率；若沒有 CPU 請求，自動擴展器便無法計算目標，亦不會擴展。

kubectl apply -f deployment.yaml

第一個 pod 準備就緒後，進行擴展：

kubectl wait --for=condition=available deployment/mastra
kubectl scale deployment/mastra --replicas=3

備註

每個副本都執行同一映像檔，並連線至同一 Redis 和 Postgres。令執行可跨 pod 的關鍵是共享基礎設施，而非 pod 數量。

使用 Service 公開 Deployment：

service.yaml
apiVersion: v1
kind: Service
metadata:
  name: mastra
spec:
  selector:
    app: mastra
  ports:
    - port: 80
      targetPort: 8080

kubectl apply -f service.yaml

使用 HorizontalPodAutoscaler 自動擴展副本：

hpa.yaml
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: mastra
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: mastra
  minReplicas: 3
  maxReplicas: 10
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 70

kubectl apply -f hpa.yaml

備註

以 CPU 為基礎的自動擴展需要叢集內執行 metrics-server。GKE、EKS 和 AKS 等託管叢集已包含它；kind 和 minikube 等本機叢集則沒有，因此請先啟用它（例如 minikube addons enable metrics-server）。

確認 pod 正在執行：
```
kubectl get pods -l app=mastra
```
在一個終端機轉送服務。此命令會持續在前景執行：
```
kubectl port-forward service/mastra 8080:80
```
在另一個終端機呼叫 API：
```
curl http://localhost:8080/api/agents
```
若回傳 Agent 的 JSON 清單，即表示部署已開始提供服務。
注意
公開端點前，請先設定驗證。

串流與重新連線
串流與重新連線的直接連結

持久 Agent 會透過共享發佈／訂閱，把串流區塊發佈至每次執行專屬的主題。中斷連線的用戶端可使用執行 ID 呼叫 observe() 重新連線，並從共享快取重播錯過的區塊：

src/server/reconnect.ts
const { output, cleanup } = await durableAssistant.observe(runId)

for await (const chunk of output.fullStream) {
  // Chunks from the run, including any missed while disconnected
}

cleanup()

由於執行狀態位於 Postgres，而事件位於 Redis，重新連線的請求可由任何 pod 處理，不限於啟動該次執行的 pod。請參閱可恢復串流。

多個用戶端可同時觀察同一次執行。每次 observe() 呼叫都會收到完整串流，因此無論一名使用者從兩部裝置觀看，還是兩人追蹤同一次執行，都會保持同步。

跨 pod 核准 Tool
跨 pod 核准 Tool 的直接連結

持久 Agent 會在呼叫 Tool 時暫停，直至有人核准。由於已暫停的執行儲存於 Postgres，核准可到達任何 pod，不限於啟動該次執行的 pod。

啟動需要核准的執行：

src/server/approval.ts
const { runId } = await durableAssistant.stream('Delete the archived records', {
  requireToolApproval: true,
  memory: { thread: 'thread-1', resource: 'user-1' },
})

執行會在 Tool 運行前暫停。稍後可從任何 pod 核准：

await durableAssistant.resume(runId, { approved: true })

處理核准的 pod 會從 Postgres 載入已暫停的執行，然後執行已核准的 Tool，並透過共享發佈／訂閱發佈結果，讓觀察該次執行的用戶端收到後續內容。請參閱 Tool 核准。

已知限制
已知限制的直接連結

預設的程序內設定會將執行狀態保留在一個 pod 的記憶體內，不會在 pod 之間共享。請配合共享 Redis 和 Postgres 使用持久 Agent，令串流、核准及重新連線可跨 pod 運作。
跨 pod 的串流、核准及重新連線需要使用持久 Agent 路徑。一般 Agent 會將執行狀態保留於記憶體，無法在另一個 pod 上恢復。
多個 pod 同時針對尚未初始化的資料庫啟動時，可能會爭相建立結構，令其中一個 pod 無法啟動。先以一個副本開始，讓結構只建立一次，然後再擴展。
如要採用更嚴格的設定，請在應用程式外初始化結構（例如使用一次性的 Kubernetes Job），並在每個 pod 的 PostgresStore 上設定 disableInit: true。

PubSub
持久 Agent
Worker：在 Kubernetes 上將背景處理拆分至獨立容器
Worker 部署指南：用於編排、排程器及背景工作 Worker 的完整 Kubernetes manifest
Mastra 伺服器
部署概覽

開始之前開始之前 的直接連結

為何多個 pod 需要共享基礎設施為何多個 pod 需要共享基礎設施 的直接連結

設定共享基礎設施設定共享基礎設施 的直接連結

使用持久 Agent使用持久 Agent 的直接連結

部署部署 的直接連結

串流與重新連線串流與重新連線 的直接連結

跨 pod 核准 Tool跨 pod 核准 Tool 的直接連結

已知限制已知限制 的直接連結

相關內容相關內容 的直接連結