跳转到主要内容
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 配置与使用