地图与定位

灵萌的「定位」包含三类能力，配置入口分散在管理后台多个 Tab 与服务端 config.yaml：

能力	典型用途	主要配置
前端地图	H5/小程序选点、地图展示	`amap_webkey`、`amap_security_key`
服务端地理服务	POI 搜索、天气、距离计算	`amap_key`（Web 服务 Key）
IP 归属地	区域门禁、注册属地、内容 IP 快照	`ali_ip_location_provider` + AppCode / 高德 Key / ip2region xdb

灵萌定位能力分三层：前端高德地图（选点、展示）、服务端高德 Web 服务（POI/天气/高级 IP）、IP 归属地（区域门禁与内容属地）。管理后台在「高德地图 / 阿里云 / 区域配置」三个 Tab 配置；ip2region 离线库另在 config.yaml 指定 xdb 路径。

系统设置 → 系统配置地图与定位

前端地图：高德「Web 端（JS API）」Key + 安全密钥（jscode）
后端地理服务：高德「Web 服务」Key（POI、天气、选「高德高级 IP」时亦用此 Key）
IP 归属地：四选一——阿里云市场 AppCode、高德 Web 服务 Key，或 ip2region 离线 xdb
接入 CDN / 反向代理时：config.yaml 配置 trusted_proxy_cidrs，否则客户端 IP 可能解析错误

建议顺序

1
高德地图 Tab填写 Web 服务 Key、JS API Key、安全密钥，点「开始测试」
2
阿里云 Tab选择 IP 归属地接口；非 ip2region 时填写 AppCode（或复用高德 Key）
3
区域配置 Tab区域模式 + 距离限制（米），与区域列表中心点配合
4
config.yaml（按需）ip2region xdb 路径、可信代理 CIDR

高德地图（管理后台 Tab 7）

路径：系统设置 → 系统配置 → 高德地图。数据库字段 amap_key / amap_webkey / amap_security_key。

保存后无需重启。管理端 POST /api/admin/system/configs/amap-test 可测连通性；C 端 GET /api/system/amap-config 拉取前端 Key。

amap_key（Key 原生）必填高德「Web 服务」类型 Key。后端 POI 搜索、距离计算、天气代理、选「高德高级 IP」时的归属地查询

amap_webkey（WebKey）必填高德「Web 端（JS API）」类型 Key。H5 / 小程序地图组件加载，与 Web 服务 Key 不是同一个

amap_security_key（安全密钥）必填与 WebKey 同应用下的 securityJsCode（jscode）。2021 年后前端地图必配

IP 归属地（管理后台 Tab 8 · 阿里云）

字段 ali_ip_location_provider（四选一）与 ali_appcode。影响区域距离门禁、用户注册属地、笔记/评论发布时的 IP 快照。

已接入 CDN（如 EdgeOne）且用户可能走 IPv6 时，勿选「高精准全球 IP」（仅 IPv4）。应选 lundear、amap，或部署 ip2region v6 xdb。

lundear（IP/IPv6 归属地查询）必填阿里云市场接口，支持 IPv4 + IPv6。有 CDN / 双栈网络时系统优先用客户端 IPv6 查归属地。需 AppCode

kzipquery（高精准全球 IP）阿里云市场接口，仅 IPv4。适合无 CDN、用户纯 IPv4 访问。需 AppCode

amap（高德高级 IP）高德 Web 服务 v5/ip/location，支持 IPv4 + IPv6。复用「高德地图」Tab 的 amap_key，无需 AppCode 查 IP（快递等仍可能要 AppCode）

ip2region（离线库）本地 xdb 离线查询，无需 AppCode / 高德 Key。须部署 static/ip2region/*.xdb 并在 config.yaml 配置 ip2region 路径；无 xdb 时系统照常运行，仅 IP 定位暂不可用

ali_appcode阿里云市场 AppCode。lundear / kzipquery 查 IP 必填；选 amap / ip2region 查 IP 时可不填，但快递物流、地址解析等仍可能需要

区域与距离限制（管理后台 Tab 9 · 区域配置）

平台入口用 platform_distance_limit + 平台中心坐标；各区域用 regions.distance_limit + 区域中心点。与区域模式配合判断用户是否在服务范围内。

距离校验可同时依赖：客户端 GPS 定位（需用户授权）与 IP 归属地（依赖上一节接口配置）。
IP 归属地精度低于 GPS；生产环境建议引导用户开启定位权限。

区域模式平台模式 / 多区域自选 / 固定区域。决定用户是否绑定区域、是否必须先选区域

platform_distance_limit多区域自选下进入「平台」入口时的最大距离（米）；0 表示不限制

platform_latitude / platform_longitude平台中心坐标（GCJ-02），与平台距离限制配合使用

regions.distance_limit各区域独立距离限制（米），在区域列表编辑中配置

区域列表各区域的中心经纬度、展示名等。详见区域管理文档

服务端 config.yaml

以下项不在管理后台表单中，部署时在 config.yaml 维护。

xdb 下载命令见项目 static/ip2region/README.md。未部署 xdb 不影响系统启动与主业务。

ip2region.v4_xdb_pathIPv4 xdb 路径，默认 static/ip2region/base_full_v4.xdb（官方商业包）。文件存在且 ali_ip_location_provider=ip2region 时启用离线 IP 定位

ip2region.v6_xdb_pathIPv6 xdb 路径，默认 static/ip2region/base_full_v6.xdb（官方商业包）。缺失时仅禁用 IPv6 离线查询，不影响 IPv4

ip2region.searcher_pool_size查询实例池大小，默认 20。高并发时可适当调大

deployment.trusted_proxy_cidrs可信反向代理 / CDN 回源网段。用于从 X-Forwarded-For 正确解析客户端 IP；未配置时可能把 CDN 出口 IP 当成用户 IP，导致归属地错误

# ip2region 离线 IP 归属地（ali_ip_location_provider=ip2region 时使用）
ip2region:
  v4_xdb_path: static/ip2region/base_full_v4.xdb
  v6_xdb_path: static/ip2region/base_full_v6.xdb
  searcher_pool_size: 20

deployment:
  trusted_proxy_cidrs:
    - 127.0.0.1/32
    - 10.0.0.0/8
    # 接入 CDN 时追加回源网段，例如 EdgeOne：
    # - 223.109.0.0/16

业务使用场景

前端地图选点 / 展示依赖 amap_webkey + amap_security_key，通过 /api/system/amap-config 下发

外卖 / 跑腿 / 服务表单起终点解析、距离计价、配送范围——依赖 amap_key 与各业务区域配置

区域距离门禁regions.distance_limit + 用户 GPS/IP 坐标 + 区域中心点；平台入口用 platform_distance_limit

用户注册属地注册或访问 /api/system/location 时写入 users.register_location

笔记 / 评论 IP 属地发布时尽力查询 IP 快照；ip2region 无 xdb 或 AppCode 未配时静默跳过

业务侧区域配置（地图 Key 全站共用）

地图 Key 与 IP 归属地接口为全站统一配置；配送半径、服务范围按区域或页面单独维护。

商户管理 → 外卖 → 区域外卖配置外卖配送范围、起送价、派单策略等

区域管理 → 服务表单配置跑腿 / 帮取帮送等服务范围与计价

统一订单 → 服务表单订单查看服务表单类订单（含跑腿）

验证是否生效

高德地图 Tab：「开始测试」原生 Key 与 WebKey 均通过
阿里云 Tab：已选合适的 IP 归属地接口，AppCode / xdb / 高德 Key 已就绪
区域配置 Tab：距离限制与区域模式符合预期
GET /api/system/location 返回合理省市区（生产环境用真实公网 IP 测）
客户端带地图页面正常加载、可定位、POI 搜索可用
外卖 / 跑腿：配送范围与距离计算合理

常见问题

地图空白或报 INVALID_USER_KEYWebKey 须为 JS API 类型；安全密钥须与 WebKey 配对；amap_key 须为 Web 服务类型，二者不可填反。

IP 归属地全是 CDN 节点城市检查 deployment.trusted_proxy_cidrs 是否包含 CDN 回源网段；并确认 ali_ip_location_provider 支持 IPv6（勿用 kzipquery）。

选了 ip2region 但 IP 定位无结果确认 static/ip2region/base_full_v4.xdb 已部署；启动日志不应长期报 xdb 未就绪；v6 缺失仅影响 IPv6 客户端。

本地开发 IP 定位不准local/dev/test 环境对内网 IP 会回退测试公网 IP；生产环境须用真实客户端 IP 验证。

距离限制误拦用户调大对应区域的 distance_limit 或 platform_distance_limit；引导用户开启 GPS。

外卖派单找不到骑手地图 Key 仅解决坐标；派单还依赖区域外卖配置、骑手在线与派单策略。

配置项速查（数据库 `system_config`）

管理后台 系统设置 → 系统配置 保存后即时生效（ip2region xdb 路径除外，须改 config.yaml 并重启）。

高德地图 Tab

字段	类型	说明
`amap_key`	Web 服务 Key	后端 POI、天气、距离；选「高德高级 IP」时也用于 IP 归属地
`amap_webkey`	JS API Key	前端地图组件，与 Web 服务 Key 不是同一个
`amap_security_key`	jscode	2021 年后前端地图必配的安全密钥

申请：高德控制台

阿里云 Tab

字段	说明
`ali_ip_location_provider`	IP 归属地提供方，见下表
`ali_appcode`	阿里云市场 AppCode；lundear/kzipquery 查 IP 必填；快递、地址解析等仍可能需要

值	显示名	IPv6	凭证
`lundear`	IP/IPv6 归属地查询	支持，优先 IPv6	AppCode
`kzipquery`	高精准全球 IP	不支持（仅 IPv4）	AppCode
`amap`	高德高级 IP	支持，优先 IPv6	`amap_key`（Web 服务 Key）
`ip2region`	ip2region 离线库	v6 xdb 存在时支持	无（本地 xdb）

CDN / IPv6

站点已接入 CDN（如 EdgeOne）且用户可能走 IPv6 时，不要选 kzipquery。应选 lundear、amap，或部署 ip2region 的 v4 + v6 xdb。

区域配置 Tab

字段	说明
区域模式	平台 / 多区域自选 / 固定区域
`platform_distance_limit`	多区域自选下进入「平台」的最大距离（米，默认 1000；0=不限制）
`platform_latitude` / `platform_longitude`	平台中心坐标（GCJ-02）

各区域的距离限制在 区域管理 → 区域列表 的 distance_limit 字段单独配置。

与区域管理中各区域中心经纬度配合，用于距离门禁。

服务端 config.yaml

ip2region 离线库

当 ali_ip_location_provider = ip2region 时使用。xdb 放在 static/ip2region/（与上传、日志同属运行期静态目录）。

yaml

ip2region:
  v4_xdb_path: static/ip2region/base_full_v4.xdb
  v6_xdb_path: static/ip2region/base_full_v6.xdb
  searcher_pool_size: 20

从 ip2region 官方渠道下载商业包后，将 base_full_v4.xdb、base_full_v6.xdb 放入 static/ip2region/（详见该目录 README）。

v4 xdb 缺失：ip2region 整体不可用，系统仍可正常启动，IP 离线定位跳过（不影响发帖等主流程）。
v6 xdb 缺失：仅 IPv6 客户端无法走 ip2region，IPv4 不受影响。

可信反向代理（CDN）

yaml

deployment:
  trusted_proxy_cidrs:
    - 127.0.0.1/32
    - 10.0.0.0/8
    - 172.16.0.0/12
    - 192.168.0.0/16
    # 接入 CDN 时追加回源网段，例如腾讯云 EdgeOne：
    - 223.109.0.0/16
    - 111.4.0.0/16

未正确配置时，Gin 可能把 CDN 出口 IP 当作客户端 IP，导致 IP 归属地偏差、区域距离误判。

API 一览

方法	路径	说明
GET	`/api/system/location`	IP 定位；`ip` 留空则按提供方取客户端 IP
GET	`/api/system/amap-config`	C 端拉取前端高德 Key
GET	`/api/system/amap/place/text`	POI 关键字搜索
GET	`/api/system/amap/weather`	城市天气
POST	`/api/admin/system/configs/amap-test`	管理端高德连通性测试

开发环境：local / dev / test 下，内网 IP（127.0.0.1、局域网）会自动回退到测试公网 IP，便于联调 IP 属地。

业务行为说明

发布笔记 / 评论：尽力写入 IP 属地快照；查询失败或凭证未配时不阻塞发布。
已登录用户访问 /api/system/location：成功后会更新 users.register_location。
IP 定位不走熔断器：ip2region 离线查询与在线 API 分离；xdb 不可用时不影响系统其它模块。

地图与定位

建议顺序

高德地图（管理后台 Tab 7）

IP 归属地（管理后台 Tab 8 · 阿里云）

区域与距离限制（管理后台 Tab 9 · 区域配置）

服务端 config.yaml

相关 API

业务使用场景

业务侧区域配置（地图 Key 全站共用）

验证是否生效

常见问题

配置项速查（数据库 `system_config`）

高德地图 Tab

阿里云 Tab

区域配置 Tab

服务端 config.yaml

ip2region 离线库

可信反向代理（CDN）

API 一览

业务行为说明

相关文档

地图与定位 ​

建议顺序

高德地图（管理后台 Tab 7）

IP 归属地（管理后台 Tab 8 · 阿里云）

区域与距离限制（管理后台 Tab 9 · 区域配置）

服务端 config.yaml

相关 API

业务使用场景

业务侧区域配置（地图 Key 全站共用）

验证是否生效

常见问题

相关文档

配置项速查（数据库 system_config） ​

高德地图 Tab ​

阿里云 Tab ​

区域配置 Tab ​

服务端 config.yaml ​

ip2region 离线库 ​

可信反向代理（CDN） ​

API 一览 ​

业务行为说明 ​

相关文档 ​

地图与定位

配置项速查（数据库 `system_config`）

高德地图 Tab

阿里云 Tab

区域配置 Tab

服务端 config.yaml

ip2region 离线库

可信反向代理（CDN）

API 一览

业务行为说明

相关文档