7.10 私有化部署开发指南

适用对象：私有化部署客户——部署环境无公网（或受限网络），船讯网在线海图GIS平台（ElaneMap H5 API 3.5）的瓦片服务、船位数据接口、气象数据接口均不可直接访问，需要把地图、船舶、轨迹、气象图层全部改为本地数据源 + 本地渲染。
本指南基于船讯网官方文档，把在线平台的业务绘制能力"平移"到离线 Leaflet 引擎上实现。全套共 4 个文档：

文档	内容
总览（本文）	私有化部署总体架构、与在线平台的差异对照、环境准备、阅读路径
私有化地图加载绘制	私有瓦片数据（SQLite/MBTiles 与瓦片图文件两种形态）发布为标准 XYZ 瓦片服务，并用 Leaflet 加载海图底图
船舶与轨迹绘制实践	用 Canvas 复现在线平台的区域船/船队船绘制效果，自建数据源接入（对应 `getAreaShipsCallBack` ）、船舶选中/定位/筛选、历史轨迹绘制与回放
气象图层效果绘制	基于离线气象数据（CurrentWeather JSON / GRIB / 台风接口数据）自绘风场粒子、海浪等值面、台风路径与风圈等图层

1. 为什么在线平台的写法在私有化环境不可用

在线平台的典型接入方式（官方 7.1 快速入门）：

这条链路里有三处强依赖船讯网在线服务：

JS API 主文件从 api.shipxy.com 加载，密钥（k 参数 / ak）由在线鉴权；

海图底图瓦片来自 //m12.shipxy.com/tile.c?l=Na&m=o&x={x}&y={y}&z={z}（官方 7.2 中 tileLayer.sea.url 的默认值）；

业务数据接口（区域船 Getmanyship、轨迹、气象 apicall 等）全部指向船讯网数据服务器。

私有化环境无公网，以上三项都不可达。但平台底座是 Leaflet（官方 7.1 明确说明"底层基于开源地图引擎 Leaflet，全局同时暴露 L 与 ShipxyAPI"），因此正确的平移思路是：

引擎：直接使用开源 Leaflet（私有化包），替代 ShipxyAPI.Map —— ShipxyAPI.Map 的返回值本来就是 L.Map，官方 7.2 的自定义图源也是用 L.tileLayer 构造的；

底图：把客户自有的瓦片数据（SQLite/MBtiles 或瓦片图文件）发布成本地 XYZ 瓦片服务，用 L.tileLayer 加载 —— 等价于官方 7.2 的 addTileLayer 自定义图源 / 7.5 的 customeTileLayerService；

船舶/轨迹：用 Canvas 自绘船舶符号与轨迹线，数据结构对齐官方 CanvasShip、Track 对象 —— 官方 7.3 本身就提供了 getAreaShipsCallBack 外部数据源回调钩子，说明这套数据契约就是为"数据在外、绘制在内"设计的；

气象：解析离线气象数据（CurrentWeather JSON / GRIB / 台风 JSON），自绘风场粒子、海浪等值面、台风路径，数据字段与官方 6.x 气象接口的返回结构保持一致。

2. 私有化部署总体架构

┌──────────────────────────── 客户内网（无公网） ────────────────────────────┐
│                                                                              │
│  浏览器（Leaflet 页面）                                                       │
│    ├── 底图:    L.tileLayer("http://内网瓦片服务/{z}/{x}/{y}.png")            │
│    ├── 船舶层:  Canvas 绘制（数据来自内网船位接口/AIS 解析服务）                 │
│    ├── 轨迹层:  Canvas/Polyline 绘制（数据来自内网轨迹库）                     │
│    └── 气象层:  Canvas 粒子/等值面（数据来自内网气象文件服务）                  │
│                                                                              │
│  服务端                                                                       │
│    ├── 瓦片服务:  ① Node.js + better-sqlite3 读 MBTiles/SQLite               │
│    │              ② Nginx 直接托管瓦片图文件目录                               │
│    ├── 业务接口:  客户自有（船位、轨迹）或船讯网离线数据包                       │
│    └── 气象数据:  CurrentWeather JSON / GRIB 文件 / 台风 JSON 定时更新         │
└──────────────────────────────────────────────────────────────────────────┘

3. 与在线平台的能力对照

在线平台能力	在线 API（参考）	私有化实现	详见
海图底图	`new ShipxyAPI.Map(...)` + 内置 sea 瓦片	本地瓦片服务 + `L.tileLayer`	文档 01
图源切换	`map.basemapsControl.changeMap("MT_SEA")`	多个 `L.tileLayer` + `L.control.layers` 切换	文档 01
自定义瓦片叠加	`customeTileLayerService.addLayer` / `options.addTileLayer`	`L.tileLayer` 叠加 + 图层控制	文档 01
区域船/船队船	`ShipxyAPI.ShipService(map, {...})`（CanvasShipService）	Canvas 船舶层（数据结构对齐 CanvasShip）	文档 02
外部船位数据源	`getAreaShipsCallBack` 回调	本地数据接口轮询 + `addShips` 等价方法	文档 02
船舶选中/事件	`addSelectedListener`	Canvas 命中检测 + 选中高亮	文档 02
历史轨迹	`map.trackService.addAndShow(mmsi, btime, etime, options)`	本地轨迹数据 + 分段彩绘 polyline	文档 02
轨迹回放	`options.isEnablePlayer: true`	自实现播放器（进度条/倍速/暂停）	文档 02
风场粒子	`weatherService.showWindFiel()`	Canvas 风场粒子动画（风速风向格点数据）	文档 03
海浪图层	`weatherService.showSeaWaves()`	波高等值面/等值线填充绘制	文档 03
台风图层	`weatherService.showTyphoonInfoList()`	台风路径 + 7/10 级风圈 + 预报锥	文档 03
单点气象	`GetWeatherByPoint`	本地气象格点插值查询	文档 03

4. 环境准备

前端（浏览器端）

Leaflet 1.9.x（私有化包，内网 CDN 或随工程打包）：leaflet.js + leaflet.css

jQuery 2.x+（仅当沿用官方示例代码习惯时需要；纯 Leaflet 方案不需要）

服务端

方案 A（SQLite/MBTiles）：Node.js ≥ 16 + better-sqlite3（读 .mbtiles / 自定义 SQLite 瓦片库）

方案 B（瓦片图文件）：Nginx（静态文件托管 + 缓存头）

可选：Python 3（GRIB 解析，pygrib 或离线预转 JSON）

数据

海图瓦片数据（客户提供，两种形态之一：MBTiles/SQLite 单文件，或 {z}/{x}/{y}.png 目录树）

船位/轨迹数据（客户内网接口，或船讯网离线数据包）

气象数据（离线 JSON / GRIB，字段结构参照官方气象接口）

5. 阅读路径

只做底图加载：直接读文档 01；

做船位/轨迹监控大屏：文档 01 → 02；

做气象辅助决策（航线避风、台风预警）：文档 01 → 03；

全部能力：按 01 → 02 → 03 顺序，每篇自带可运行的完整代码与示例效果图。

各文档中的示例效果图均为本地真实渲染（Leaflet + 本地瓦片/数据）后截图，私有化环境可直接复现。

7.10 私有化部署开发指南

1. 为什么在线平台的写法在私有化环境不可用#

2. 私有化部署总体架构#

3. 与在线平台的能力对照#

4. 环境准备#

5. 阅读路径#

1. 为什么在线平台的写法在私有化环境不可用

2. 私有化部署总体架构

3. 与在线平台的能力对照

4. 环境准备

5. 阅读路径