最後更新: 2026 年 2 月 | 版本: v2.0
認證安全
Access Token 機制
ChainStream 使用基於 OAuth 2.0 的認證機制,透過 Client ID 和 Client Secret 生成 JWT Access Token 進行 API 認證。 認證流程: 憑據規範Access Token 獲取
憑據安全
儲存要求程式碼示例
多 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 天的呼叫趨勢
- 月維度 — 檢視歷史月度統計
安全監控
🚧 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 系統進行日誌分析
- 制定安全事件響應流程
常見問題
Client Secret 洩露了怎麼辦?
Client Secret 洩露了怎麼辦?
立即登入 Dashboard 刪除該 App,建立新 App,然後更新所有使用該憑據的應用配置。詳見上方”憑據洩露響應”章節。
Access Token 過期了怎麼辦?
Access Token 過期了怎麼辦?
Access Token 有效期為 24 小時。建議:
- 快取 Token — 在有效期內複用同一個 Token
- 提前重新整理 — 在過期前 1 小時左右重新整理 Token
- 錯誤重試 — 收到 401 錯誤時自動獲取新 Token
如何檢視 API 呼叫情況?
如何檢視 API 呼叫情況?
登入 Dashboard → Metrics,可以檢視請求 IP、響應碼、耗時、消耗的 Units 等資訊,以及時間維度的圖表資料。
Webhook 簽名驗證失敗如何排查?
Webhook 簽名驗證失敗如何排查?
常見原因:
- Secret 不匹配 — 確認使用正確的 Webhook Secret
- Payload 處理錯誤 — 確保使用原始的 JSON 字串進行簽名計算
- 簽名頭缺失 — 確認請求頭中包含
X-Webhook-Signature
是否支援建立多個 App?
是否支援建立多個 App?
支援。建議為不同環境(生產/測試)和不同服務建立獨立的 App,便於管理和問題排查。
相關文件
認證
認證與憑據管理
資料隱私
資料隱私政策
錯誤碼
完整錯誤碼列表
Webhook 基礎
Webhook 配置與使用

