PERFORMANCE.md

性能要点（精简版）

批处理

• 建议批大小：1000（兼顾网络与内存）
• 客户端分批、顺序或小并发提交；失败可按批重试

接口与网络

• JSON 体尽量精简，仅传必要字段
• 默认启用压缩与限流；避免超大单次请求

数据校验

• 仅提交有效指纹 fingerprint（64位十六进制 SHA256）；无效条目服务端会拒绝/跳过

服务器侧优化（对接方无需改动）

布隆过滤器配置

布隆过滤器是性能优化的关键组件，可减少90%+的不必要数据库查询。

关键配置参数：

• BLOOM_FILTER_ENABLED=true - 强烈建议开启
• BLOOM_FILTER_MIN_CAPACITY - 最小容量，根据指纹规模设置：
  • 小规模(< 1万): 20000
  • 中规模(1-5万): 100000
  • 大规模(5-10万): 150000
  • 超大规模(> 10万): 200000+
• BLOOM_FILTER_GROWTH_MULTIPLIER - 增长预估倍数(5-15)
• BLOOM_FILTER_FALSE_POSITIVE_RATE - 误报率(0.01推荐)

容量计算策略：

• 动态计算：max(当前数量×基础倍数, 当前数量×增长倍数, 最小容量)
• 内存消耗：约15万容量需要2.3MB内存
• 误报率控制：容量不足时误报率会显著上升

其他优化

• 缓存：热点数据与会话差异缓存
• 数据库：复合唯一索引 { userKey, fingerprint }，查询使用投影与 lean()
• 限流：全局基础限流（100次/分钟），敏感操作额外严格限流（10次/5分钟）

限流与请求频率

客户端请求频率建议

• 安全频率：每0.6秒发送1次请求（约100次/分钟）
• 预留缓冲：实际建议每1秒1次请求，确保稳定性
• 敏感操作：5分钟内最多10次（如差异分析、缓存清理）

初始化上传性能预估

• 单批处理能力：1000个指纹需要3次请求（预检查 + 差异检测 + 批量添加）
• 理论最大吞吐量：33,333个指纹/分钟
• 100万指纹上传时间：约30分钟

建议的客户端实践

• 先 /check 再决定是否继续
• 分批+重试（指数退避）；幂等提交避免重复写
• 记录批次进度，支持断点续传

目标指标（参考）

• 单用户 4-5 万指纹
• 预检查 < 100ms；批次差异 < 1s（取决于数据与硬件）
• 并发用户：~10（可按部署水平扩展）