查询治理
通过设置基于Token的速率限制、查询配额和行数限制来控制资源使用。保护集群免受失控查询的影响，并确保团队之间公平分配资源，或者用于服务提供商实现多租户隔离和服务分级（SLA）。
概述
查询治理在 API Token级别强制执行限制：
- 速率限制——每分钟和每小时的最大查询次数
- 查询配额——每小时和每天的最大查询次数
- 行数限制——每次查询返回的最大行数
- 精确策略——为特定的Token设置个性化策略，覆盖系统默认的全局限制。
- 使用情况监控——跟踪当前使用情况和剩余配额
使用前提
- 必须启用身份验证（IEDB_AUTH_ENABLED=true`）——治理是按Token强制执行的。
- 企业许可证
配置
默认限制
设置适用于所有未指定策略的Token的全局默认值：
[governance]
enabled = true
default_rate_limit_per_min = 60 # 0 = 无限制
default_rate_limit_per_hour = 1000
default_max_queries_per_hour = 500
default_max_queries_per_day = 5000
default_max_rows_per_query = 100000
默认无限制
将任何限制设置为0“无限制”都意味着无限制。如果您希望启用治理功能但没有任何默认限制，请将所有默认值设置为“无限制”，0并为需要限制的Token创建明确的策略。
应用行为
当超过限制时，会做出如下响应：
| 条件 | HTTP 状态 | 行为 |
|---|---|---|
| 超出速率限制 | 429 Too Many Requests | 包含Retry-After标题 |
| 查询配额已用完 | 429 Too Many Requests | 配额在下一个周期边界重置 |
| 超出最大行数限制 | 200 OK | 返回部分结果并附带警告 |
速率限制响应示例：
{
"success": false,
"error": "Rate limit exceeded. Try again in 45 seconds.",
"retry_after": 45
}
响应中包含一个Retry-AfterHTTP 标头，客户端可以使用该标头进行自动退避。
治理策略
覆盖特定Token的默认限制。这对于为关键服务设置更高的限制或为外部集成设置更严格的限制非常有用。
创建策略
curl -X POST http://localhost:8000/api/v1/governance/policies \
-H "Authorization: Bearer $ADMIN_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"token_id": 1,
"rate_limit_per_minute": 120,
"rate_limit_per_hour": 5000,
"max_queries_per_hour": 2000,
"max_queries_per_day": 20000,
"max_rows_per_query": 500000
}'
回复：
{
"success": true,
"data": {
"token_id": 1,
"rate_limit_per_minute": 120,
"rate_limit_per_hour": 5000,
"max_queries_per_hour": 2000,
"max_queries_per_day": 20000,
"max_rows_per_query": 500000,
"created_at": "2026-02-13T10:00:00Z",
"updated_at": "2026-02-13T10:00:00Z"
}
}
列出所有策略
curl -H "Authorization: Bearer $ADMIN_TOKEN" \
http://localhost:8000/api/v1/governance/policies
获取治理策略
curl -H "Authorization: Bearer " \
http://localhost:8000/api/v1/governance/policies/1
更新政策
curl -X PUT http://localhost:8000/api/v1/governance/policies/1 \
-H "Authorization: Bearer $ADMIN_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"rate_limit_per_minute": 200,
"max_rows_per_query": 1000000
}'
删除策略
移除基于Token的策略。Token将恢复为全局默认值。
curl -X DELETE http://localhost:8000/api/v1/governance/policies/1 \
-H "Authorization: Bearer $ADMIN_TOKEN"
使用情况监控
查看任意Token的当前使用情况和剩余配额。
curl -H "Authorization: Bearer $ADMIN_TOKEN" \
http://localhost:8000/api/v1/governance/usage/1
回复：
{
"success": true,
"data": {
"token_id": 1,
"current_minute_count": 15,
"rate_limit_per_minute": 120,
"current_hour_count": 342,
"max_queries_per_hour": 2000,
"current_day_count": 1580,
"max_queries_per_day": 20000,
"remaining_minute": 105,
"remaining_hour": 1658,
"remaining_day": 18420
}
}
最佳实践
- 设置保守的默认值——适中的限制（例如，60/min，500/hour）开始，根据需求增加限制。
- 提高关键服务的限额——为需要更高吞吐量的写入和仪表板创建明确的策略。
- 使用行限制进行外部集成——防止第三方工具查询过多数据
max_rows_per_query。 - 监控使用模式——通过API用量，及时发现即将达到限制的Token。
- 配合查询管理——使用查询管理来确定哪些查询消耗的资源最多。