Skip to main content

离线部署

一句话结论:mapviz-skills 的 49 个技能中,42 个在离线环境下的某个环节会断,只有 7 个可以完全离线出图。 断点不在“算法”,而在四类外部资源:前端库、底图瓦片、注记字体、要素数据接口。 全量口径:把范围扩到整个 skillpacks 的 67 个技能后,需处置 54 个、只需内网容器在位 3 个、完全无外部依赖 10 个。
离线部署时最容易踩的坑是:只盯着“数据取不到”,却发现页面连地图都渲染不出来。原因是这两个问题分属不同环节——页面能不能起来取决于前端库,地图有没有背景取决于底图瓦片,标注有没有文字取决于字体服务,图上有没有内容才取决于数据接口。本章按这四个环节统计受影响技能,并给出每一类的处置方向。 打个比方:一张在线地图页面像一家外卖店。前端库是店面的水电,水电不通店门都开不了;底图瓦片是店里的背景布景,没有它前台空荡但还能营业;注记字体是菜单上的字,字没了顾客看不懂菜名;数据接口才是食材,食材断了做菜这一步才真正停摆。离线部署要依次把水电、布景、字体、食材都换成本地供给,缺一样就缺一段效果。

本章在离线交付中的位置

离线交付要同时回答”机器和网络怎么准备”和”技能会断在哪一环”。本章只回答后者,前者已按《GIS Agent 离线部署用户手册》拆成三页:
  • 部署方案与前提:三机职责与推荐配置、端口与访问关系、公网与局域网模型选型、客户准备清单、部署前确认清单。
  • x86 + 银河麒麟 V11:x86_64 + 麒麟 V11 实测基线、源内缺项、容器发布端口与宿主自建端口的差异、四道现场闸门、从裸机到能对话的现场流程。
  • 龙芯 + 统信 UOS:LoongArch64 第二基线、MapGIS 边界、B1 混合拓扑、LoongArch 镜像打包与 52 例 E2E 结果。
  • 实施与运维要点:三个离线包关系、部署脚本职责、数据卷规则、部署后验收判据、联网能力矩阵、私网模型运行期判据、默认值速查与常见问题定位。
三页与本章同以 V3.25 手册为事实源。本章的 L1–L6 是制图产出面的断点,手册的联网能力矩阵是模型调用面的可用性,两个口径不同、结论互补,离线验收时都要过。

判定口径

为了避免把“文档里提到过的网址”误判成“运行时要请求的网址”,本章统计遵循以下口径: 其中“只出现在说明里的在线来源”单列在文末「边界与例外」,共 10 个技能。这类技能运行时不访问外网,但一旦用户要求“刷新成最新数据”,仍会失败。 L1–L6 的分母固定为 mapviz-skills 的 49 个制图技能;文末「技能面全景」把范围扩到整个 skillpacks 的 67 个技能,并追加了工具与规范面专用的口径,两套数字分开标注、不做混合。

影响分级总览

关键数字(均由扫描脚本对账得出,见文末「复核方式」):
  • 技能总数 49,受影响 42,不受影响 7。
  • 至少命中三个断点层级的技能 11 个,即“底图、字体、数据同时依赖外网”的重灾区。
  • 逐技能去重后累加的在线端点引用 171 处,全局唯一域名 105 个。
  • 底图与数据接口同时需要外网的技能 27 个(L2 ∩ L4)。

L1 前端库走公共 CDN(6 个)

命中技能:sld-admin-boundary、sld-dem-terrain、sld-poi-icons、sld-realtime-alert、sld-statistical-thematic、sld-utility-pipeline。 这是最容易被低估的一类。这 6 个技能的样式、数据和瓦片来源本身都不依赖外网(其中 sld-admin-boundary、sld-dem-terrain 还支持把瓦片地址注入本地瓦片服务),唯独“让页面跑起来的库”还挂在公共 CDN 上。离线打开时控制台先报脚本加载失败,整页白板,容易被误判成“技能坏了”。 其余 38 个技能已改为引用产品内置的本地前端库路径(/lib/maplibre/4.7.1/),不依赖 CDN。三维相关页面所需的 Cesium 库同样已内置为本地路径(/lib/cesium/1.122/)。 处置方向:把这 6 个技能预览页的前端库引用改为产品内置本地路径即可,无需改动样式与数据链路。改造前可通过“打开页面是否发起 unpkg 请求”来确认命中。 需要注意 spatial-analysis:它的清单文件里记录了内置分析库的公共下载来源,但实际计算用的是技能自带的本地文件,属于“出处记录”,不计入 L1。 另外,MapLibre 与 Cesium 的前端库都已随产品发布到本地目录(分别为版本 4.7.1 与 1.122),因此 L1 的改造只是把页面引用从 CDN 换回已有的本地路径,不需要额外引入依赖。

L2 底图瓦片需要外网(34 个)

命中技能:3d-building-map、3d-terrain-map、biodiversity-map、change-detection-map、china-airport-map、china-historical-map、china-metro-map、city-isochrone-map、classic-hiking-route-map、cobalt-mine-map、coral-reef-map、earthquake-realtime-map、eonet-event-map、fishing-zone-map、flight-tracker-map、ndvi-vegetation-map、nightlight-map、nowcasting-map、ocean-current-map、openmeteo-contour-forecast-map、personal-footprint-map、poi-heatmap-map、postgis-poi-address、protected-area-map、route-navigation、sea-level-rise-map、self-driving-escape-map、shipping-ais-map、stac-browser-map、statistical-thematic-map、storymap-template、tide-gauge-map、typhoon-track-map、weather-visualization-map。 离线表现是“图层逻辑正常、背景全空”:叠加的矢量或栅格数据按坐标画出来了,但底下没有地图可参照。 这一类的构成并不是单一的: 处置方向分三步:
  1. 密钥问题先与网络问题分开确认。有外网但密钥失效,现象是瓦片请求返回鉴权错误;完全没有外网,现象是请求根本不通。
  2. 底图来源切到本地。产品自带 postgis-gateway 容器(默认对外端口 3000)与本地瓦片服务;已有 2 个技能通过命令行参数把瓦片地址注入样式,可复用这一模式为本地底图供片。
  3. 确无本地底图时退化为“无底图专题图”。多数技能在纯数据图层下仍可读,此时应显式去掉底图图层,避免残留在线瓦片请求导致长时间转圈。

L3 注记字体需要外网(15 个)

命中技能:china-metro-map、city-isochrone-map、classic-hiking-route-map、flight-tracker-map、openmeteo-contour-forecast-map、poi-heatmap-map、self-driving-escape-map、shipping-ais-map、storymap-template、sld-admin-boundary、sld-dem-terrain、sld-poi-icons、sld-realtime-alert、sld-statistical-thematic、sld-utility-pipeline。 这 15 个技能的样式把注记字体地址写成公共字体服务。离线下底图或数据即使补齐,标注文字仍出不来;部分场景还会因为字体请求失败而中断样式初始化,表现为“地图整层不渲染”,比单纯的“没有注记”更严重。 处置方向:把注记字体地址切到产品网关的字体接口。china-metro-map 已支持用命令行参数直接指定字体地址,属于可以直接落地的样板;其余技能按同一方式改造。需要中文标注时,字体必须由本地服务提供,不能退回浏览器本地字体,否则跨端字形不一致。

L4 要素数据来自在线接口(30 个)

命中技能:3d-building-map、biodiversity-map、china-airport-map、china-historical-map、china-metro-map、city-isochrone-map、classic-hiking-route-map、cobalt-mine-map、earthquake-realtime-map、eonet-event-map、fishing-zone-map、flight-tracker-map、nowcasting-map、ocean-current-map、openmeteo-contour-forecast-map、personal-footprint-map、poi-heatmap-map、protected-area-map、route-navigation、sea-level-rise-map、self-driving-escape-map、sld-realtime-alert、stac-browser-map、statistical-thematic-map、storymap-template、tianditu-geocoder、tide-gauge-map、tourist-attraction-map、typhoon-track-map、weather-visualization-map。 这一类内部差异最大,按离线可行性分成四组: 按端点数看,cobalt-mine-map(40 个)和 china-historical-map(15 个)远超其余技能:前者汇总了全球矿产项目、交易所披露与多国地质目录,后者汇总了各级在线历史底图与标准地图服务。这两个技能在离线环境不建议按原样交付,应改为“内置数据 + 本地底图”的精简版本。

L5 自有服务写死公网地址(2 个)

命中技能:china-historical-map、sld-admin-boundary。 这两个技能引用的并不是第三方公共服务,而是产品自己的网关与瓦片服务,但地址固化成了公网 IP 或公网域名。离线部署时它们会指向外部,内网访问不通,现象与 L2 类似但根因完全不同。 处置方向:部署时改为内网可达地址,或使用相对路径形式由当前站点同源提供。这类改造属于配置替换,不涉及逻辑变更。

L6 不受影响(7 个)

cesium-common、map-poster-maker、maplibre-common、self-improving-agent、spatial-analysis、tianditu-1m-atlas(原名 sld-tianditu-gb100)、tourism-heatmap。 其中三个属于规范或工具类技能(前端使用约束、三维使用约束、空间分析算子),本身不出图;spatial-analysis 的分析库已内置为本地文件;tourism-heatmap 直接使用自带的地理数据与内置基准值;sld-tianditu-gb100 走本地网关;map-poster-maker 通过参数指定本地网关与样式。 需要注意的是,两个规范类技能(maplibre-common、cesium-common)的说明文档里以天地图在线底图作为默认示例。它们自身不受影响,但会引导新生成的页面去引用在线底图——离线环境里这一点必须同步调整,否则新做的页面会继续复现 L2 问题。

逐技能矩阵

按影响等级排序,同级内按技能名排序。数字口径见「判定口径」。

离线改造抓手:可覆盖参数

技能自带的地址参数是离线改造成本最低的一条路,不需要改代码就能把外部端点换成内网服务。 此外还有一类环境变量形式的开关(密钥、路由服务基址、要素导出服务基址),改造时与上述参数等效。

部署检查清单

按顺序执行,每一步都先确认现象再进下一步,避免把四类断点混成一个“地图不出来”。
  1. 先验证前端库。用浏览器开发者工具确认页面没有对公共 CDN 的请求。若有,先处理 L1,这是其他一切现象的前提。
  2. 再验证底图。确认页面没有对外部瓦片服务的请求,底图改由本地瓦片服务或网关供片。
  3. 再验证注记字体。确认注记字体地址指向内网网关;有中文标注需求时,字体必须本地提供。
  4. 然后处理数据链路。能自建的先自建(路由、地址编码、行政区边界);不能自建的预先抓取并随包发布;本质依赖实时的,在交付说明里明确数据截止时刻。
  5. 替换自有服务的公网地址(2 个技能),改为内网地址或相对路径。
  6. 调整规范类技能的默认示例,避免新生成页面继续引入在线底图与在线字体。
  7. 回归验证:逐个技能打开产物,确认无外部请求、有底图、有标注、有数据。

技能面全景:从 49 个制图技能到 67 个技能

上面的 L1–L6 只覆盖 mapviz-skills。把范围扩到整个 skillpacks,分母从 49 变成 67:14 个技能包目录里 13 个含技能、1 个是空目录,技能按「目录内含 SKILL.md」计数——mapviz-skills 49 个,其余 12 个包 18 个(ui-ux-pro-max 独占 7 个)。 合并后的全量结论,三类互斥且闭合: 打个比方:制图面的 49 个技能像 49 家门店,断的是水电、布景、字体、食材;工具类技能则像后厨的一台进口设备——清单上没有任何采购网址,但设备本身要么出厂就装好了才转得起来,要么第一次开机就要联网激活。只看门店的账单,永远查不出后厨的问题。

工具/规范面:18 个技能断在哪一环

下表按「需处置 12 → 只需内网容器在位 3 → 无外部依赖 3」排序,行序即分类。 | 技能 | 所属面 | 离线断点 | 离线时的表现 | 处置方向 | | arnis-cli | 三维体素建模 | 二进制内部联网取数 | 无要素可建,产物为空场景 | 随包内置抽取好的要素与地形副本,或改交付内置样本 | | geoscan-cli | 扫描件要素提取 | 需镜像预装识别与制图运行时 | 命令缺失即整链中断 | 镜像预装并做版本自检,只用包内自带运行时 | | mapgis10-cli | 环境/数据源配置 | 需镜像预装桌面套件,且授权是图形界面流程 | 无头容器内无法完成授权交互 | 预置授权与配置目录,不在现场做在线激活 | | 3dtiles-cli | 三维瓦片生成 | 需镜像预装转换内核与可选格式依赖;同时依赖内网数据库 | 特定点云或模型格式缺依赖即被跳过 | 先自检缺失格式再预装;保证数据库容器在位 | | geomoder-cli | 三维地质建模 | 重型数值依赖不随包发布 | 首次运行需要公网包源 | 离线镜像源或预装到镜像 | | ui-ux-pro-max/design | 视觉方案生成 | 公网包源 + 模板内嵌在线字体与图片 | 依赖装不上,产出的字与图全部丢失 | 预装依赖;模板字体与图片改本地路径并内置素材 | | ui-ux-pro-max/ui-styling | 样式工程 | 公网包源(框架与插件) | 构建阶段取包失败 | 内网包源或离线包 | | ui-ux-pro-max/ui-ux-pro-max | 设计工作流入口 | 公网包源(解释器安装指引) | 指引在内网机器不可执行 | 直接用镜像内已有解释器 | | ui-ux-pro-max/design-system | 设计系统与成片 | 产出样式内嵌 23 个在线图片地址与在线字体 | 版式正确但背景图与文字全部缺失 | 内置背景图池并提供本地字体 | | ui-ux-pro-max/slides | 幻灯片模板 | 模板内嵌公共 CDN 图表库与在线背景图 | 图表不绘制、背景空白 | 图表库改本地路径、背景图内置 | | ui-ux-pro-max/brand | 品牌规范 | 模板内嵌公共字体服务 | 字形回落到浏览器默认 | 由内网字体服务供字 | | cesium-common | 三维使用规范 | 说明示例给在线底图(引导型) | 新生成页面继续继承在线瓦片与密钥依赖 | 示例改本地瓦片服务与内网密钥注入 | | postgis-cli | 空间数据库操作 | 依赖内网数据库容器 | 容器不在位则全部命令失败 | 部署即离线可用 | | postgis-service-cli | 服务发布与切片导出 | 依赖内网网关供瓦片、要素、栅格、字体、图标;前端库随包 | 网关不在位则无可用服务地址 | 部署即离线可用,注记字体天然本地化 | | knowledge-cli | 知识库问答与图谱 | 依赖内网知识服务容器;图前端库随包 | 服务不在位则问答为空、图无内容 | 部署知识服务容器 | | ui-ux-pro-max/banner-design | 横幅规格 | 无外部依赖 | 不受影响 | — | | mapgis-custom-skill | 技能加载链路自检 | 无外部依赖 | 不受影响,可当离线自检用例 | 用作离线验收探针 | | hello-gis | 技能模板自检 | 无外部依赖 | 不受影响 | 用作离线验收探针 | 分类计数(同一技能可同时命中多类,故各类之和大于 18):需镜像预装软件 3、需公网包源 3、重型依赖不随包 1、二进制内部联网取数 1、授权激活形态 1、产出物内嵌在线素材 4、依赖内网容器 4、引导型示例 1、无外部依赖 3。其中 3dtiles-cli 同时命中「需预装」与「依赖内网容器」,ui-ux-pro-max/design 同时命中「公网包源」与「素材内嵌」。

为什么制图面的方法直接套到工具类会漏判

按原口径不做修改地扩到全量,会得到「67 个技能、179 处端点引用、113 个唯一域名」,但相对制图面新增的 8 处端点里 5 处是假阳性:1 处样式的 XML 文档类型声明、2 处打包库自带的许可证头、2 处纯参考外链。把这类噪声排除、并把「说明里写明要执行的动作」计入运行行为之后,两个方向的问题同时暴露:
  • 漏判:静态网址扫描把 11 个工具/规范技能判成不受影响,逐条核实后只有 3 个成立。另外 8 个里,5 个断点静态完全不可见(arnis-cli、geoscan-cli、mapgis10-cli、3dtiles-cli、geomoder-cli),占该面 12 个需处置技能的 42%;其余 3 个取决于内网容器是否在位。最典型的是 arnis-cli:技能文件里一个网址都没有,联网取数发生在包内可执行文件的内部逻辑中。
  • 误判方向相反:若把说明文档中的模板代码块也算作运行态,制图面的 L6 从 7 降到 3(只剩 map-poster-maker、spatial-analysis、tianditu-1m-atlas),改判的 4 个分别是 2 个底图示例、1 个安装期取包、1 个数据刷新路径。这正是前文「规范类技能会引导新页面联网」的量化版本。
结论是离线验收必须跑两套判据:网址静态扫描管制图产出面,文档记载的运行行为加上「包内是否自带可执行文件」管工具与规范面。

工具/规范面的口径补充

边界与例外

  • 只出现在说明里的在线来源:cesium-common、china-historical-map、city-isochrone-map、cobalt-mine-map、flight-tracker-map、maplibre-common、openmeteo-contour-forecast-map、route-navigation、storymap-template、tourism-heatmap 共 10 个技能,其说明中列有运行态未使用的备用来源或替代端点。它们按上表不计入受影响项,但只要用户要求“取最新数据”,仍会走到外网。
  • 实时性无法补偿:地震、台风、临近降水、潮汐、航空器位置、海洋气象、灾害事件这类数据源本身要求联网获取,离线环境只能交付快照。
  • 本章不覆盖联网白名单方案。如果部署环境允许部分外网访问,可以只放行必要域名以缩短改造量;这种情况下优先保留底图与注记字体的本地化,因为它们是所有产出的共同依赖。
  • 两个边界读数。技能包目录 geology-knowledge 是空目录,不产生技能、不进 67 的分母;cesium-common 同时以顶层技能包和 mapviz-skills 内技能两种形态存在,全量计数按两个独立目录计入两次,跨页引用时必须带包名前缀,否则会当成同一个技能而少算一个。

复核方式

本章全部数字来自对 skillpacks/mapviz-skills 的静态扫描,统计脚本按「判定口径」逐技能提取运行态与配置态文件中的外部地址,归一化后按角色(前端库、底图、注记字体、数据、自有服务)分类,再合成影响等级。逐技能矩阵、分级总览与关键数字由同一份扫描结果生成,因此表内每一行与汇总数字始终一致;技能目录有增删时重新执行扫描即可刷新本章全部数据。 「技能面全景」一节由同一套扫描器的两个模式加上一个工具面判定器生成:先用与上文完全相同的口径重跑 mapviz-skills,逐项复现 49、42、7、171、105、11、27 与 L1–L6 六个计数、两份技能名单(复现不一致即中止,不允许直接出全量数字);再扩到全量分母,并按工具面口径逐条给出文件与行号证据。三个汇总数(54、3、10)在生成时强制校验相加等于 67、且与两个面板的分项相加一致,任一格被手改都会导致脚本失败而不是静默出一个新数字。