离线与内网私有化部署

约 2233 字大约 7 分钟

2026-10-10

内网、涉密、弱网或客户要求"数据不出域"的项目，需要把三维系统整体离线化部署。本文是离线部署的总览与清单，各类数据处理细节请按文中链接查看对应章节。

1. 需要离线的资源清单

类别	内容	要点
前端代码	自己的工程产物 + Mars3D SDK + mars3d-cesium	不能依赖 CDN，见第 5 节
底图影像	在线地图下载或 `tif` 切片后的 XYZ/WMTS 瓦片	见在线地图下载、影像图切片
地形	`terrain` 切片（含 `layer.json`）	见地形数据处理
三维模型	3DTiles（`tileset.json` + 瓦片）、glTF 小模型	见模型数据处理、obj 转 glTF
矢量数据	GeoJSON / shp 转换后的数据	见shp 转 GeoJSON
样式与字体	图标字体、地图库字体、UI 字体	避免外链字体导致的加载失败
第三方服务	第三方 POI/路径规划/天地图等	替换 token 或改为自有服务，见第 4 节
服务端	Nginx（推荐）或 IIS/Tomcat 等	见发布三维数据服务

2. 第一步：准备数据并按目录组织

建议按"一种数据类型一个子目录"统一组织，方便发布与替换地址：

mars3d-data/
├── tile/           # 影像/电子地图瓦片（{z}/{x}/{y}.png）
├── vec/            # 矢量瓦片（可选）
├── terrain/        # 地形（layer.json + 分级目录）
├── 3dtiles/        # 三维模型（各模型一个子目录）
└── file/           # geojson 等普通文件数据

网盘/移动硬盘交付的数据常是分卷压缩包，拷贝到服务器后需要解压到当前目录（保持原有目录层级），详见发布三维数据服务 - 准备数据。

3. 第二步：发布为 HTTP 静态服务

3.1 使用 Nginx（推荐）

把数据目录放到 Nginx 静态根目录下，验证方式：浏览器能直接打开文件即发布成功。

文件路径：D:\mars3d-data\3dtiles\qx-dyt\tileset.json
服务地址：http://192.168.0.87/mars3d-data/3dtiles/qx-dyt/tileset.json

完整安装、目录配置、服务注册步骤见发布三维数据服务。

3.2 非 Nginx 服务（IIS / Tomcat 等）

必须补充 MIME 映射，否则 .json、.terrain、.b3dm、.pnts、.glb 等文件会被服务器拒绝或按错误类型返回，表现为"模型/地形加载不出来"：

<mimeMap fileExtension=".json"    mimeType="application/json" />
<mimeMap fileExtension=".terrain" mimeType="application/octet-stream" />
<mimeMap fileExtension=".b3dm"    mimeType="application/octet-stream" />
<mimeMap fileExtension=".pnts"    mimeType="application/octet-stream" />
<mimeMap fileExtension=".i3dm"    mimeType="application/octet-stream" />
<mimeMap fileExtension=".cmpt"    mimeType="application/octet-stream" />
<mimeMap fileExtension=".gltf"    mimeType="application/octet-stream" />
<mimeMap fileExtension=".glb"     mimeType="application/octet-stream" />

3.3 配置跨域（CORS）

三维数据（瓦片、模型、地形）在浏览器中加载都受同源策略限制，必须让服务端允许跨域：

服务端可控：添加 Access-Control-Allow-Origin 等跨域响应头（Nginx 模板中已包含）；
服务端不可控：使用代理服务转发（Nginx 代理或 web-proxy），并在图层参数中配置 proxy。

跨域问题的详细判断与处理见外部资源加载跨域问题。

4. 第三步：替换代码与配置中的公网地址

4.1 批量替换示例数据的域名

平台示例与模板中大量使用 https://data.mars3d.cn/... 的演示数据。部署到内网时，建议在内网重新发布一份同名目录（或使用相同路径结构），然后全局替换域名：

假设内网服务地址为 192.168.0.87/mars3d-data
全局全字匹配替换：data.mars3d.cn → 192.168.0.87/mars3d-data

搜索范围要覆盖：config.json、所有 *.js / *.vue / *.ts 源码、HTML 模板中的引址，以及数据文件里的外链（如 GeoJSON 中的样式图片）。

4.2 修改 config.json（地形、底图、图层）

{
  "scene": {},
  "terrain": {
    "url": "//192.168.0.87/mars3d-data/terrain",
    "show": true
  },
  "basemaps": [
    {
      "name": "离线影像地图",
      "type": "xyz",
      "url": "//192.168.0.87/mars3d-data/tile/img/{z}/{x}/{y}.jpg",
      "minimumLevel": 0,
      "maximumLevel": 13,
      "show": true
    },
    {
      "name": "离线电子地图",
      "type": "xyz",
      "url": "//192.168.0.87/mars3d-data/vec/{z}/{x}/{y}.png",
      "minimumLevel": 0,
      "maximumLevel": 13
    }
  ],
  "layers": [
    {
      "name": "大雁塔",
      "type": "3dtiles",
      "url": "//192.168.0.87/mars3d-data/3dtiles/qx-dyt/tileset.json",
      "show": true
    }
  ]
}

如果没有地形数据或不需要地形，把 terrain 节点删除，或将 terrain.show 设为 false，避免持续请求失败拖慢加载。

4.3 代码中直接创建的图层

// 地形
const map = new mars3d.Map("mars3dContainer", {
  terrain: {
    url: "http://192.168.0.87/mars3d-data/terrain",
    show: true
  }
})

// 三维模型
const tiles3dLayer = new mars3d.layer.TilesetLayer({
  name: "大雁塔",
  url: "http://192.168.0.87/mars3d-data/3dtiles/qx-dyt/tileset.json",
  maximumScreenSpaceError: 1
})
map.addLayer(tiles3dLayer)

5. 第四步：前端依赖与资源离线

5.1 SDK 本地化

使用静态方式集成时，把 mars3d.js、mars3d-cesium（或 mars3d-cesium 的 Widgets、Assets、ThirdParty、Workers）等整个目录拷贝到项目 public/lib/ 下，用相对路径引用，不要使用 CDN：

<link href="./lib/mars3d/mars3d.css" rel="stylesheet" />
<script src="./lib/mars3d/mars3d.js"></script>

各集成方式的差异见静态方式集成、NPM 方式集成。

5.2 注意需要随包发布的静态资源

资源	说明
Cesium `Assets/`、`Widgets/`、`Workers/`、`ThirdParty/`	Cesium 运行必需，缺失会出现控件样式错乱或部分功能报错
图标字体（如 `mapfont`、字体图标 css）	平台部分控件、标注使用图标字体，缺失会显示为方块
演示图片/纹理	文档、示例中的 `data.mars3d.cn/img/...` 纹理需替换为本地文件
地图库资源	mapbox-gl、echarts 等第三方库的 js/css 需本地化

5.3 检查项

断网（或在无外网的内网环境）打开系统，F12 网络面板中不应出现任何外网请求；
控制台无 404、无 CORS 报错；
底图、地形、模型、图标字体、控件样式全部正常显示。

6. 第五步：第三方 token 与外部服务

平台内置了天地图、百度、高德、Cesium ion、mapbox、bing 等第 3 方服务的演示 token（mars3d.Token.*）。这些 token 访问量大有额度限制，且内网环境根本访问不到，必须替换：

不需要的服务直接不用：离线项目最常见做法是不加载在线地图与 POI 查询，改用本地瓦片与自有接口。

7. 部署验证清单

#	验证项	通过标准
1	静态服务可用	浏览器可打开 `http://内网IP/mars3d-data/terrain/layer.json`、`.../3dtiles/qx-dyt/tileset.json`
2	底图	地图上有影像/电子地图，缩放不出白块
3	地形	开启地形三角网后可见网格，起伏正常
4	模型	三维模型位置、高度正确，可点击弹窗
5	矢量	GeoJSON/瓦片矢量数据正常显示、可交互
6	无外网请求	F12 网络面板中无 `data.mars3d.cn`、天地图、百度、高德等外网请求
7	无报错	控制台无 404、无 CORS、无 WebGL 报错
8	样式资源	图标字体、控件图标、控件样式显示正常
9	性能	打开首屏时间、帧率满足项目要求（对比见性能优化与调优）
10	授权	若使用商业授权版 SDK，确认已按授权交付包替换为无 Logo 的 SDK（见 SDK授权版）

8. 离线部署常见问题

8.1 加载不出来 + 控制台 CORS 报错？

服务端未允许跨域。Nginx 添加跨域响应头，或使用代理服务并在图层参数中配置 proxy。详见外部资源加载跨域问题。

8.2 浏览器能打开文件，但地图里加载不出来？

MIME 不对：检查响应头 Content-Type，.json 应为 application/json，.b3dm/.terrain/.pnts 应为 application/octet-stream（非 Nginx 服务必须配置）；
目录层级不对：tileset.json 内部引用的瓦片是相对路径，需要保持原始目录结构，不能把文件打散；
大小写敏感：Linux 服务器区分大小写，注意文件名与引用一致。

8.3 提示"The request client is not a secure context..."？

这是 Chrome 94+ 对"公网页面访问私网资源"的安全限制，处理方式（改用 https、改内网/外网一致、修改浏览器 flags）见外部资源加载跨域问题。

8.4 提示超流量 / 403？

第 3 方 token 超量或被封，按第 6 章替换为自己的 token，或直接去掉该服务。

8.5 图标显示为方块/乱码？

图标字体文件（如 mapfont）未随包发布或路径不对，检查字体文件是否在发布目录中且 css 中的字体路径正确。

8.6 内网地图能显示但很卡？

依次检查：瓦片层级是否没有限制（请求量暴增）、是否缺少 gzip 压缩与缓存、是否一次加载了过多模型图层，详见性能优化与调优。