如何在Cloudflare Workers KV中存储IP区间数据实现单IP查询

核心思路 #

利用IP区间的有序性，通过预排序分片+两级查找实现单IP查询，全程只需要2次KV get操作，总KV条目数仅为3万左右（远低于IP总数）。

实现步骤 #

1. 原始数据预处理 #

• 先将所有IP地址统一转换为整数格式：IPv4转32位无符号整数，IPv6转128位大整数
• 合并所有重叠、相邻的IP区间，消除冗余条目
• 将合并后的所有区间按「Start IP整数」升序排序

2. KV存储结构化设计 #

• 全局目录索引：固定key为ip_global_directory，value为序列化的块元数据列表，每个元数据包含「块内最小Start IP、块内最大End IP、对应块存储的key」
• 区间块存储：将排序后的区间按固定大小（建议每块1000~2000条）拆分，每个块的key格式为ip_block_${序号}，value为块内所有区间的[StartIP整数, EndIP整数, Location]的序列化集合，推荐用MessagePack/Protobuf等二进制序列化格式压缩体积

3. 查询流程 #

1. 把待查询的目标IP转换为整数target_ip_int
2. 调用KV get('ip_global_directory') 拿到全局目录，通过二分查找定位到target_ip_int所属的区间块对应的key
3. 调用KV get(对应块key) 拿到块内所有区间数据，再做一次块内二分查找，匹配到StartIP ≤ target_ip_int ≤ EndIP的条目即可返回对应的Location

优化方案 #

• 可以给所有KV条目设置较长的缓存TTL（比如30天），利用Cloudflare的边缘缓存能力，绝大多数查询可以直接命中边缘节点，延迟在10ms以内
• 如果存在热点IP段，可以针对高频访问的/16或/24段单独做一级索引，直接映射到对应Location，进一步减少查询步骤

存储成本测算 #

3000万条原始区间，按每块1000条拆分，总KV条目仅为30001个（3万个数据块+1个全局目录），单块序列化后体积平均在30KB以内，总存储占用不到1GB，完全符合Cloudflare Workers KV的使用限制。

内容的提问来源于stack exchange，提问作者Martin