map 必须定义在 http 块顶层，否则启动报错；geoip2 变量需提前在 http 块中声明且路径、权限、大小写严格匹配；proxy_pass 须引用 upstream 名而非 IP 字符串，并设 default 分支防 502。
必须在 http 块顶层定义 map，否则 Nginx 启动直接报错 unknown directive "map" —— 这是 90% 配置失败的根源。
map 指令只能写在 http 块最外层
map 不是运行时逻辑指令，而是变量预声明机制，Nginx 启动时就完成注册和查表结构初始化。一旦嵌套进 server 或 location，语法解析器根本找不到上下文。
- 正确位置：在
/etc/nginx/nginx.conf的http { }块内，include语句之后、所有server块之前 - 错误写法：
server { map $geoip2_data_country_code $upstream { ... } }→ 必报错 - 宝塔用户注意：面板自动生成的站点配置（
/www/server/panel/vhost/nginx/xxx.conf）只包含server块，map必须手动加到主配置的http块里，不能塞进站点配置文件
geoip2 变量必须先于 map 被提取
map 的源变量（如 $geoip2_data_country_code）必须已由 geoip2 指令提前定义，且该指令也必须在 http 块顶层，顺序上要早于 map 声明。
Skill Weave Chains — 技能链路由引擎
下载
开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景，三层路由架构（触发词→SAD反馈→DAG编排），recall@10=96.97%。配置驱动（chains.yaml），零代码扩展。pip install skill-weave-chains 一键安装。
-
geoip2加载数据库路径需绝对准确，例如/www/server/geoip2/GeoLite2-Country.mmdb，权限设为644 - 变量名必须与
map中引用的完全一致，包括大小写：“CN” 和 “cn” 是两个不同值，匹配严格区分大小写 - 若用了代理（如 CDN），记得先配
set_real_ip_from和real_ip_header，否则$remote_addr是代理 IP，地理信息全错
proxy_pass 必须动态引用 upstream 名称，不能拼接 URL
proxy_pass 后面跟变量时，只接受已声明的 upstream 名称，不支持 http://192.168.1.10:8080 这类硬编码地址字符串。
- 错误写法：
proxy_pass http://$backend_upstream;且$backend_upstream值为"192.168.1.10:8080"→ 502 - 正确写法：用
map映射出 upstream 名（如"cn_backend"），再配对应upstream cn_backend { server 192.168.1.10:8080; } - 务必设
default分支，未匹配时变量为空会导致proxy_pass解析失败，返回 502 - 如果想用单机直连而非 upstream，可用
return 302或rewrite配合if，但性能和可维护性不如 upstream + map
ISP 或城市级分流需额外数据库与字段
国家代码（country iso_code）用 GeoLite2-Country.mmdb 就够；但运营商（ISP）或城市名需 GeoLite2-ISP.mmdb 或 GeoLite2-City.mmdb，且字段路径不同。
- ISP 字段：在
geoip2块中写$geoip2_data_isp source=$remote_addr isp，不是isp_name或其他别名 - 城市名字段：
$geoip2_data_city_name source=$remote_addr city names en，中文需改zh-CN - 省份字段（subdivision）：
$geoip2_data_subdivision_iso_code source=$remote_addr subdivisions.0.iso_code，注意.0.索引不可省略 - 所有新字段都得重新在
map中引用，且变量名不能含点号或中划线（Nginx 变量命名限制）
真正难的不是写几行 map，而是确保 geoip2 提取的变量在启动时就存在、类型是字符串、值非空且大小写匹配——漏掉任意一环，proxy_pass 就会静默失败成 502。
