Tile38 Cluster H3 Geo Proxy 是一个面向大规模城市级地理数据的高性能代理层，它构建在 Tile38 上方，为多城市、多分片、多节点部署提供：
- 自动 H3 网格映射 → 城市 → Shard → Tile38 节点 路由
- 高并发写入能力（百万级对象 / 40 城市）
- 完整的地理空间查询 API（SET / GET / DEL / NEARBY / WITHIN / SCAN）
- 支持 Weighted Shards（城市内部多节点负载均衡）
- 配置文件热更新，无需重启
- 工业级 Circuit Breaker + Retry 稳定性保障
- 自带可视化 Web Debugger 工具
适用于：
- 楼盘字典 / 城市基础数据中心
- 城市 POI 大库
- 选址分析
- 实时地理位置 IoT 系统
- 高并发区域写入与检索业务
| 特性 | 描述 |
|---|---|
| 🗺 H3 自动路由 | lat/lon → H3 cell → 城市 → Tile38 节点 |
| 📡 完整地理指令支持 | SET / GET / DEL / NEARBY / WITHIN / SCAN |
| ⚡ 高性能转发 | 内置 Circuit Breaker + 自动重试 |
| 🏙 多城市分片调度 | 支持 Weighted Shards |
| 🔥 配置文件热更新 | shard & cell 映射实时加载 |
| 🌐 三种调用模式 | JSON / 结构化参数 / 原始 Tile38 命令 |
| 🧭 可视化工具 | 自带 Tile38 Geo Debugger HTML |
Client (SET/GET/NEARBY/WITHIN)
│
▼
┌──────────────────────┐
│ Tile38 H3 Geo Proxy │
│ /api /geo │
└──────────────────────┘
│
H3 Resolution=6 网格 → 城市字典
│
▼
┌──────────────────────┐
│ Shard Host Map │
└──────────────────────┘
│ │ │
▼ ▼ ▼
Tile38-BJ Tile38-SH1 Tile38-SH2
.
├── cmd/proxy # Proxy 主程序入口
├── internal
│ ├── h3router # 路由逻辑 (/geo + /api)
│ ├── forward # Tile38 请求转发
│ ├── config # 配置管理
│ └── util # 热更新文件 Watcher
├── configs
│ ├── config.yaml # 主配置
│ ├── h3_cell_map.json # H3 → 城市字典
│ └── shard_host_map.json # 城市 → Tile38 host 列表
├── docker-compose.yml
└── geo-debugger.html # Web 可视化调试工具
{
"北京": ["8631aa42fffffff", "8631a8447ffffff"],
"上海": ["8630994a7ffffff"]
}{
"上海": [
{"host": "http://tile38-sh1:9851", "weight": 2},
{"host": "http://tile38-sh2:9851", "weight": 1}
],
"北京": [
{"host": "http://tile38-bj:9851", "weight": 1}
]
}系统提供 两个官方 API：
/api → JSON 数组格式（业务正式接口）
/geo → URL 调试接口（结构化参数 OR 原始命令）
curl -XPOST http://localhost:8000/api -H "Content-Type: application/json" -d '{"command":["SET","proxy_test","id1","POINT",116.3975,39.9087]}'curl -XPOST http://localhost:8000/api -H "Content-Type: application/json" -d '{"command":["GET","proxy_test","id1"]}'curl -XPOST http://localhost:8000/api -H "Content-Type: application/json" -d '{"command":["NEARBY","proxy_test","POINT",116.3975,39.9087,1000]}'curl -XPOST http://localhost:8000/api -H "Content-Type: application/json" -d '{"command":["WITHIN","proxy_test","CIRCLE",116.3975,39.9087,5000]}'/geo?cmd=SET&key=proxy_test&id=id1&lat=39.9&lon=116.3
/geo?cmd=GET&key=proxy_test&id=id1
/geo?cmd=NEARBY&key=proxy_test&lat=39.9&lon=116.3&radius=1000
/geo?cmd=WITHIN&key=proxy_test&shape=CIRCLE&lat=39.9&lon=116.3&radius=3000
/geo?cmd=SET proxy_test id1 POINT 116.3 39.9
/geo?cmd=NEARBY proxy_test POINT 116.3 39.9 2000
/geo?cmd=GET proxy_test id1
services:
proxy:
build: .
ports:
- "8000:8000"
volumes:
- ./configs:/app/configs
depends_on:
- tile38-bj
- tile38-sh1
- tile38-sh2
tile38-bj:
image: tile38/tile38:1.36.5
command: tile38-server -p 9851
tile38-sh1:
image: tile38/tile38:1.36.5
command: tile38-server -p 9851
tile38-sh2:
image: tile38/tile38:1.36.5
command: tile38-server -p 9851启动：
docker compose up -d
POST /api
["SET","building","bj001","POINT",116.3975,39.9087]
日志：
cell:8631aa42fffffff
city:北京
route host:http://tile38-bj:9851
/geo?cmd=GET&key=building&id=bj001
项目包含：
geo-debugger.html
打开即可使用：
- 输入坐标 → 自动计算 H3 cell / 城市 / 节点
- 执行所有 Tile38 地理指令
- NEARBY / WITHIN 结果地图展示
- 支持 Raw / Structured / JSON 三种调用模式
- 基于 Leaflet 可视化渲染
- 配置热更新（watch h3_cell_map & shard_host_map）
- Circuit Breaker 自动熔断
- Weighted shard host 选择
- 原始命令直通
- /debug/config 查看实时映射
- H3 resolution=6 适合城市级数据
- 多 shard 提升写入性能
- Proxy 可水平扩容（无状态）
- 前置 Nginx 提供 TLS/Rate-limit
- Tile38 节点建议持久化存储
Tile38 H3 Geo Proxy v2 是一个为 城市级地理数据中心 / 楼盘字典 / LBS 平台 定制的高性能中间层。
如需：
- Web 管理后台
- 监控 Dashboard（Grafana）
- 多 Region 多活
- 更高分辨率 H3（7/8）
- 对象轨迹跟踪（Channels）
欢迎继续扩展本项目。