API Shield 常见陷阱

# 常见问题与故障排除 ## 常见错误 ### "迁移后模式验证 2.0 不工作" **原因:** 经典规则仍然处于活动状态，与新系统冲突 **解决方案:** 1. 删除所有经典模式验证规则 2. 清除 Cloudflare 缓存 (等待 5 分钟) 3. 通过新的模式验证 2.0 界面重新上传模式 4. 在 Security > Events 中验证 5. 检查操作是否已设置 (Log/Block) ### "模式验证阻止了合法请求" **原因:** 模式过于严格，缺少字段或类型不正确 **解决方案:** 1. 检查防火墙事件以获取违规详情 2. 在设置中查看模式 3. 在 Swagger Editor 中测试模式 4. 在阻止前使用 Log 模式进行验证 5. 使用正确的规范更新模式 6. 确保使用模式验证 2.0 (而非经典版) ### "JWT 验证失败" **原因:** JWKS 与 IdP 不匹配、令牌过期、标题/Cookie 名称错误或时钟偏差 **解决方案:** 1. 验证 JWKS 是否与 IdP 配置匹配 2. 检查令牌 `exp` 声明是否有效 3. 确认标题/Cookie 名称与配置匹配 4. 在 jwt.io 测试令牌 5. 考虑时钟偏差 (±5 分钟容差) 6. 使用现代语法: `is_jwt_valid(http.request.jwt.payload["{config_id}"][0])` ### "BOLA 检测误报" **原因:** 合法的顺序访问模式、批量操作或敏感度过高 **解决方案:** 1. 在 Security > Events 中查看 BOLA 事件 2. 降低敏感度阈值 (高 → 中 → 低) 3. 从检测中排除合法的批量操作 4. 确保会话标识符能唯一识别用户 5. 验证是否满足最低流量要求 (1000+ 请求/天) ### "风险标签未出现在防火墙规则中" **原因:** 功能未启用、流量不足或缺少会话标识符 **解决方案:** 1. 验证是否启用了模式验证 2.0 2. 在模式设置中启用 BOLA 检测 3. 配置会话标识符 (BOLA 所需) 4. 等待 24-48 小时进行机器学习模型训练 5. 检查是否满足最低流量阈值 ### "端点发现未找到 API" **原因:** 流量不足 (<500 请求/10天)、非 2xx 响应、Worker 直接请求或会话 ID 配置不正确 **解决方案:** 确保 10 天内有 500+ 请求，边缘返回 2xx 响应 (而非 Workers 直接返回)，正确配置会话 ID。机器学习模型每日更新。 ### "序列检测误报" **原因:** 回溯窗口问题、非唯一会话 ID 或模型敏感度 **解决方案:** 1. 查看回溯设置 (对受管端点的 10 次请求，10 分钟窗口) 2. 确保会话 ID 唯一