跳轉到主要內容
ChainStream 採用多層安全機制保護 API 訪問。本文件介紹 API 安全最佳實踐、常見威脅防護及安全配置指南。
最後更新: 2026 年 2 月 | 版本: v2.0

認證安全

Access Token 機制

ChainStream 使用基於 OAuth 2.0 的認證機制,透過 Client ID 和 Client Secret 生成 JWT Access Token 進行 API 認證。 認證流程: 憑據規範

Access Token 獲取

憑據安全

儲存要求
Client Secret 是訪問 ChainStream 服務的核心憑證,洩露可能導致服務濫用和費用損失。

程式碼示例

多 App 管理

建議為不同環境和服務建立獨立的 App:

傳輸安全

TLS 要求

證書驗證

生產環境中絕不跳過證書驗證,這會使您的應用暴露於中間人攻擊風險。

Webhook 安全

Webhook 訊息透過簽名機制確保訊息來源的可靠性。

簽名驗證

當您收到 Webhook 訊息時,需要使用 Webhook Secret 驗證簽名,確認訊息來自 ChainStream 且未被篡改。

驗證示例

Webhook Secret 輪換

如需輪換 Webhook Secret:
1

生成新 Secret

Dashboard → Webhooks → 選擇 Endpoint → 輪換 Secret
2

更新應用配置

在應用中更新為新的 Webhook Secret
3

驗證簽名

確認新 Secret 可以正確驗證簽名

使用量監控

Metrics 面板

在 Dashboard 的 Metrics 面板中,可以檢視 API 和 WebSocket 的呼叫情況:

圖表資料

Metrics 面板提供多種時間維度的圖表:
  • 小時維度 — 檢視最近 24 小時的呼叫趨勢
  • 天維度 — 檢視最近 30 天的呼叫趨勢
  • 月維度 — 檢視歷史月度統計
檢視路徑: Dashboard → Metrics

安全監控

🚧 Coming Soon — 安全監控功能正在開發中,即將上線。
上線後將支援:
  • 異常檢測 — 自動檢測認證失敗激增、異常地理位置等
  • 告警通知 — 郵件和 Webhook 告警
  • 自動防護 — 臨時封禁、請求限流等

IP 白名單

🚧 Coming Soon — IP 白名單功能正在開發中,即將上線。
上線後將支援:
  • 單個 IP 配置(如 203.0.113.50
  • IP 段配置(如 203.0.113.0/24
  • 多 IP 配置(逗號分隔)

常見攻擊防護

中間人攻擊

攻擊方式: 攻擊者在客戶端和伺服器之間攔截通訊。 防護措施:

注入攻擊

攻擊方式: 攻擊者透過輸入惡意資料嘗試執行未授權操作。 防護措施:

憑據洩露響應

如果懷疑 Client Secret 已洩露,請立即執行以下步驟:
1

立即刪除 App

Dashboard → Apps → 選擇 App → 刪除
2

建立新 App

Dashboard → Apps → 建立新 App
3

更新應用配置

在所有使用該憑據的應用中更新為新 Client ID 和 Secret
4

檢查 Metrics

Dashboard → Metrics → 檢查是否有異常呼叫
5

審查安全實踐

檢查憑據洩露原因,改進安全措施

安全錯誤碼

認證相關

訪問控制相關

Webhook 相關

錯誤響應示例


安全配置清單

基礎配置(必須)

  • 使用 HTTPS 訪問 API
  • Client ID 和 Client Secret 儲存在環境變數或金鑰管理服務
  • 不在程式碼倉庫中提交憑據
  • 生產/測試環境使用不同 App
  • 正確驗證 Webhook 簽名

進階配置(推薦)

  • 整合金鑰管理服務(AWS Secrets Manager / HashiCorp Vault)
  • 定期檢查 Metrics 面板的呼叫情況
  • 為不同服務建立獨立的 App

企業配置(可選)

  • 整合 SIEM 系統進行日誌分析
  • 制定安全事件響應流程

常見問題

立即登入 Dashboard 刪除該 App,建立新 App,然後更新所有使用該憑據的應用配置。詳見上方”憑據洩露響應”章節。
Access Token 有效期為 24 小時。建議:
  1. 快取 Token — 在有效期內複用同一個 Token
  2. 提前重新整理 — 在過期前 1 小時左右重新整理 Token
  3. 錯誤重試 — 收到 401 錯誤時自動獲取新 Token
登入 Dashboard → Metrics,可以檢視請求 IP、響應碼、耗時、消耗的 Units 等資訊,以及時間維度的圖表資料。
常見原因:
  1. Secret 不匹配 — 確認使用正確的 Webhook Secret
  2. Payload 處理錯誤 — 確保使用原始的 JSON 字串進行簽名計算
  3. 簽名頭缺失 — 確認請求頭中包含 X-Webhook-Signature
支援。建議為不同環境(生產/測試)和不同服務建立獨立的 App,便於管理和問題排查。

相關文件

認證

認證與憑據管理

資料隱私

資料隱私政策

錯誤碼

完整錯誤碼列表

Webhook 基礎

Webhook 配置與使用