最後更新: 2026 年 2 月 | 版本: v2.0
認證安全
Access Token 機制
ChainStream 使用基於 OAuth 2.0 的認證機制,透過 Client ID 和 Client Secret 生成 JWT Access Token 進行 API 認證。 認證流程: 憑據規範| 專案 | 規範 |
|---|---|
| Client ID | 應用唯一識別符號 |
| Client Secret | 64 位隨機字元 |
| Access Token | JWT 格式,包含過期時間和許可權範圍 |
| Token 有效期 | 24 小時 |
Access Token 獲取
憑據安全
儲存要求| 儲存方式 | 安全等級 | 說明 |
|---|---|---|
| 環境變數 | ✅ 推薦 | 不進入版本控制 |
| 金鑰管理服務 | ✅ 最佳 | AWS Secrets Manager, HashiCorp Vault 等 |
| 配置檔案 | ⚠️ 注意 | 必須加入 .gitignore |
| 程式碼硬編碼 | ❌ 禁止 | 極易洩露 |
程式碼示例
多 App 管理
建議為不同環境和服務建立獨立的 App:| 用途 | App 名稱建議 | 說明 |
|---|---|---|
| 生產環境 | prod-main | 生產業務使用 |
| 測試環境 | test-dev | 開發測試使用 |
| CI/CD | ci-pipeline | 自動化測試使用 |
| 監控服務 | monitoring | 監控告警使用 |
傳輸安全
TLS 要求
| 專案 | 要求 |
|---|---|
| 最低版本 | TLS 1.2 |
| 推薦版本 | TLS 1.3 |
| 證書驗證 | 必須啟用 |
| 不支援 | HTTP、TLS 1.0/1.1 |
證書驗證
Webhook 安全
Webhook 訊息透過簽名機制確保訊息來源的可靠性。簽名驗證
當您收到 Webhook 訊息時,需要使用 Webhook Secret 驗證簽名,確認訊息來自 ChainStream 且未被篡改。| 專案 | 說明 |
|---|---|
| 演算法 | HMAC-SHA256 |
| 金鑰 | Webhook Secret(在 Dashboard 配置) |
| 簽名頭 | X-Webhook-Signature |
驗證示例
Webhook Secret 輪換
如需輪換 Webhook Secret:使用量監控
Metrics 面板
在 Dashboard 的 Metrics 面板中,可以檢視 API 和 WebSocket 的呼叫情況:| 指標 | 說明 |
|---|---|
| 請求 IP | 請求來源 IP 地址 |
| User Agent | 請求的客戶端標識 |
| 響應碼 | HTTP 狀態碼 |
| 耗時 | 請求響應時間 |
| 消耗 Units | 本次請求消耗的用量單位 |
| 總計用量 | 累計消耗的用量 |
圖表資料
Metrics 面板提供多種時間維度的圖表:- 小時維度 — 檢視最近 24 小時的呼叫趨勢
- 天維度 — 檢視最近 30 天的呼叫趨勢
- 月維度 — 檢視歷史月度統計
安全監控
🚧 Coming Soon — 安全監控功能正在開發中,即將上線。
- 異常檢測 — 自動檢測認證失敗激增、異常地理位置等
- 告警通知 — 郵件和 Webhook 告警
- 自動防護 — 臨時封禁、請求限流等
IP 白名單
🚧 Coming Soon — IP 白名單功能正在開發中,即將上線。
- 單個 IP 配置(如
203.0.113.50) - IP 段配置(如
203.0.113.0/24) - 多 IP 配置(逗號分隔)
常見攻擊防護
中間人攻擊
攻擊方式: 攻擊者在客戶端和伺服器之間攔截通訊。 防護措施:| 措施 | 說明 |
|---|---|
| 強制 HTTPS | 僅支援 TLS 1.2+ |
| 證書驗證 | 必須啟用證書驗證 |
| HSTS | 強制 HTTPS 連線 |
注入攻擊
攻擊方式: 攻擊者透過輸入惡意資料嘗試執行未授權操作。 防護措施:| 措施 | 說明 |
|---|---|
| 輸入驗證 | 嚴格的引數型別檢查 |
| 引數化查詢 | 防止 SQL/NoSQL 注入 |
| 輸出編碼 | 防止 XSS |
憑據洩露響應
如果懷疑 Client Secret 已洩露,請立即執行以下步驟:安全錯誤碼
認證相關
| 錯誤碼 | HTTP 狀態 | 說明 |
|---|---|---|
UNAUTHORIZED | 401 | 未提供認證資訊 |
EXPIRED_TOKEN | 401 | Access Token 已過期 |
INVALID_TOKEN | 401 | Access Token 無效 |
INVALID_CREDENTIALS | 401 | Client ID 或 Secret 錯誤 |
訪問控制相關
| 錯誤碼 | HTTP 狀態 | 說明 |
|---|---|---|
FORBIDDEN | 403 | 無許可權訪問或用量不足 |
RATE_LIMITED | 429 | 請求頻率超限 |
INSUFFICIENT_SCOPE | 403 | Token 許可權不足 |
Webhook 相關
| 錯誤碼 | 說明 |
|---|---|
INVALID_SIGNATURE | Webhook 簽名驗證失敗 |
MISSING_SIGNATURE | 缺少簽名頭 |
錯誤響應示例
安全配置清單
基礎配置(必須)
- 使用 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 配置與使用

