ngx_http_geo_module通过small_pool查表和tree前缀树实现O(1)地域匹配：small_pool处理/24及更细粒度IP，tree按比特逐层遍历实现最长前缀匹配，IPv6采用high/low双树折叠优化。
nginx 的 ngx_http_geo_module 模块用于根据客户端 IP 地址快速映射出对应的地域变量（如国家、省份、运营商等），其核心不依赖外部数据库，而是通过预编译的内存索引结构实现 O(1) 或近似 O(1) 的查找效率。理解它的源码逻辑，关键在于搞清“树状前缀索引”如何构建与遍历。
geo 指令如何生成两级索引结构
模块在配置解析阶段（ngx_http_geo_init）将所有 geo 规则按 CIDR 或 IP 段归类，最终构造出两个核心数组：
- small_pool：存储 /32 ~ /24 等小范围 IP（通常为单 IP 或 /24 内），直接用 IP 最后一个字节作下标，查表即得值；
- tree：对 /23 及更宽泛的网段，构建成一棵 32 层（IPv4）的二叉前缀树（trie），每个节点含 left/right 指针及可选 value；实际实现中做了压缩，只保留有分支或带值的节点（类似 patricia trie）。
例如配置 geo $country { default "ZZ"; 192.168.1.0/24 "CN"; 2001:db8::/32 "US"; }，IPv4 部分会进入 tree，而具体 192.168.1.x 若显式列出，则可能落入 small_pool。
IP 查找过程：从高位到低位逐比特匹配
运行时调用 ngx_http_geo_value，对 client IP 执行如下步骤：
- 先尝试 small_pool：若 IP 属于 /24 内且规则足够细粒度，直接取
small_pool[ip & 0xFF]； - 否则进入 tree 遍历：将 IP 转为网络字节序整数，从根节点开始，每次取当前 bit（从最高位第 0 bit 开始），bit=0 走 left，bit=1 走 right；
- 每经过一个带 value 的节点就暂存该值（最长前缀匹配原则），直到无路可走或到达叶子；最终返回最后命中的非空 value，未命中则回退到 default。
注意：它不回溯，也不穷举所有可能前缀，靠树结构天然保证“最长匹配”——因为更长的前缀必然处于更深的子路径上，且模块在插入时已确保更具体的规则覆盖更宽泛的同前缀规则。
支持 IPv6 的关键改动：双树 + 地址折叠
IPv6 不是简单把树扩展到 128 层（性能灾难）。模块采用“地址折叠”策略：
- 将 IPv6 地址前 64 位作为 high key，后 64 位作为 low key；
- 维护一棵 high tree，每个 high 节点下挂一棵独立的 low tree；
- 查找时先查 high tree 得到对应 low tree 根，再查该 low tree；
- 若某 IPv6 段前缀 ≤ 64，high tree 即完成匹配，low tree 不触发；若 >64，则需两级联合判断。
这种设计平衡了内存占用与查询速度，避免 128 层深度带来的缓存不友好问题。
调试与验证：如何确认 geo 值是否生效
不依赖日志也可快速验证 geo 变量行为：
- 在 location 中用
add_header X-Geo-Country $country;，curl 时观察响应头； - 配合
error_log debug;并开启ngx_http_geo_module相关 debug 日志（需编译时加--with-debug），搜索geo:关键字； - 用
nginx -t -v查看配置加载详情，确认 geo block 是否被识别、default 是否设置成功； - 注意：geo 变量是 lazy-eval 的，仅当首次引用时才执行查找，多次使用不会重复计算。
真正影响性能的是初始树构建，而非运行时查找——这也是它适合高并发地域分流的根本原因。
