Geyser gRPC - 最佳實踐

本指南涵蓋構建健壯的生產就緒應用程式時使用 Geyser gRPC 的基本模式。Solana Stream SDK 支援 Geyser gRPC。

入門

從簡單開始：先使用 slot 訂閱熟悉流處理，然後再新增複雜過濾器。
明智使用過濾器：僅訂閱您需要的資料以減少頻寬/CPU 消耗。

rust

SubscribeRequestFilterTransactions {
    vote: Some(false),   // Exclude vote txs
    failed: Some(false), // Exclude failed txs
    ..Default::default()
}

SubscribeRequestFilterTransactions {
    vote: Some(false),   // Exclude vote txs
    failed: Some(false), // Exclude failed txs
    ..Default::default()
}

連線管理

自動重連：預期會有網路問題；使用指數退避進行重連。
Ping/pong 處理：Yellowstone gRPC 伺服器會傳送 ping。務必回覆 pong，否則伺服器可能關閉連線（約 30 秒斷連的常見原因）。

rust

if matches!(update.update_oneof, Some(UpdateOneof::Ping(_))) {
    subscribe_tx.send(SubscribeRequest {
        ping: Some(SubscribeRequestPing { id: 1 }),
        ..Default::default()
    }).await?;
}

if matches!(update.update_oneof, Some(UpdateOneof::Ping(_))) {
    subscribe_tx.send(SubscribeRequest {
        ping: Some(SubscribeRequestPing { id: 1 }),
        ..Default::default()
    }).await?;
}

間隙恢復：重連後使用 from_slot 避免資料丟失（允許重複）。

rust

subscribe_request.from_slot = if tracked_slot > 0 {
    Some(tracked_slot) // Optionally subtract a small buffer to dodge reorgs
} else {
    None
};

subscribe_request.from_slot = if tracked_slot > 0 {
    Some(tracked_slot) // Optionally subtract a small buffer to dodge reorgs
} else {
    None
};

架構模式

使用通道分離接收和處理，以解耦網路 IO 和業務邏輯並新增背壓控制。

rust

let (tx, rx) = mpsc::channel::<SubscribeUpdate>(10_000);
// ingress task reads stream and tx.send(...)
// processing task consumes rx and does business logic

let (tx, rx) = mpsc::channel::<SubscribeUpdate>(10_000);
// ingress task reads stream and tx.send(...)
// processing task consumes rx and does business logic

使用有界通道：根據處理速度和資料丟失容忍度選擇容量（較小 = 記憶體少，丟棄多；較大 = 記憶體多，丟棄少）。

效能和彈性

監控處理延遲，超過閾值時記錄日誌。
批次寫入資料庫；達到批次大小或時間間隔時再一次寫出。
對外部呼叫使用非同步 IO；將繁重的計算轉交給工作任務/執行緒處理。
重用訂閱請求以減少記憶體分配。

錯誤處理

區分錯誤類型（流 vs 處理 vs 通道）。
請先修正無效的請求再重試；只有在回應要求重試時，才使用能辨識暫停指示的指數退避。
記錄/統計丟棄的更新以跟蹤消費者過慢的情況。

先修正再重試，以及能辨識暫停的退避

在重連迴圈覆蓋之前，先保留第一個 gRPC 錯誤。記錄它的 status 與 message，以及實際存在的 x-erpc-error-code、x-erpc-error-reason、x-erpc-doc-url、x-erpc-retry-after-seconds 與 x-erpc-retry-at metadata。連線過早關閉時，看起來可能只是一般的傳輸錯誤，因此不一定包含每一個 trailer。

重試前，請先修正無效的請求、被拒絕的過濾器形式，或 IP 註冊不一致的問題。遇到 ERPC 暫停時，請等到回傳的截止時間；它比本機的退避更具體。對可用性失敗與其他可重試的回應，使用有上限的指數退避。不要只因為收到非零 status，就反覆重試未經修改的請求。

資源使用與處理能力

Shared 方案的保護機制可防止單一工作負載占用其他 ERPC 客戶所需的傳送容量。串流變慢的原因可能是實際可用頻寬、CPU、記憶體、消費端佇列、資料庫寫入或外部呼叫。資源必須足以應付工作負載；光憑接收端變慢，並無法判斷是哪一部分受到限制。

請在消費端測量資料速率的峰值。以 MB/s × 8 將 MB/s 換算成 Mbps，並在測得的峰值之上保留餘裕。沒有不經測量就能套用的固定最低值。讓接收處理保持簡短，將更新交給有界佇列；如果處理跟不上，請擴充處理能力或縮小訂閱範圍。有界佇列能限制記憶體用量，但無法解決持續性的消費端過慢問題。

資料管理

使用 from_slot 時處理重複資料（基於時間的快取或資料庫約束）。
按使用場景選擇確認級別：
- processed：最快的儀表盤，可能回滾
- confirmed：大多數應用/索引器的良好預設值
- finalized：需要絕對確定性時使用

動態訂閱

使用雙向流在執行時更新訂閱（熱切換過濾器、擴大覆蓋範圍），無需重新連線。

生產檢查清單

✅ 帶指數退避的自動重連
✅ 使用 from_slot 的間隙恢復
✅ Ping/pong 處理（避免 30 秒斷連）
✅ 使用有界通道/背壓分離接收和處理
✅ 錯誤日誌和指標/告警
✅ 處理延遲跟蹤
✅ 重複處理和過濾器最佳化
✅ 批次寫入（如有持久化需求）
✅ 優雅關閉和健康檢查

其他資源

Solana Stream SDK（Geyser gRPC 支援）：https://github.com/ValidatorsDAO/solana-stream