最后更新: 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 配置与使用

