用 CesiumLab2 把 DEM 数据切成地形瓦片再用 nginx 把瓦片发布成三维地形服务最后在浏览器里用 CesiumJS 加载渲染——这条链路我前后搭过好几遍踩过的坑比教程里的步骤还多。今天把从数据准备到浏览器出效果的全流程捋一遍每个环节该选什么、为什么这么选、参数怎么配、报错怎么查一次性讲透。这篇适合刚接触三维 GIS、不想被商业地形服务绑死、又需要在内网或离线环境自建地形服务的同学参考。也欢迎已经在用 Cesium 的朋友对照着优化自己的发布方案。1. 为什么是CesiumLab2nginx这套组合1.1 商业地形服务解决不了的问题很多人一开始接触 Cesium会用官方示例里的Cesium.createWorldTerrain()一行代码就能得到全球地形而且效果很好。但真正的生产环境会立刻碰到几个头疼的问题Cesium ion 的地形服务需要联网请求 token 和配额内网机房根本没外网项目里有自己采集的高精度 DEM数据不能传到第三方平台商业授权费用按请求量或并发数算规模一大就是一笔不小的开支。这几个问题综合下来自建地形服务基本是绕不开的。所谓“零成本”不是指数据本身不要钱而是整个工具链都是免费或开源的CesiumLab2 免费切片nginx 免费发布CesiumJS 开源使用DEM 数据可以用公开遥感数据集。把这条路走通之后不管是一个县的精细地形还是一个城市范围的 DEM都能在自己服务器上稳定跑起来数据完全可控。1.2 CesiumLab2在链路中的角色原始 DEM 数据通常是 GeoTIFF 或 IMG 格式本质是一张带着地理坐标的灰度图像素值代表海拔。这种格式 CesiumJS 不能直接用必须先切成分层分块的地形瓦片。CesiumLab2 干的就是这件事把输入的 DEM 做重投影、重采样、金字塔切片输出一套 Cesium 原生支持的layer.json加.terrain瓦片文件。可能有人问能不能用 GDAL 或者 Cesium 官方命令行工具来切可以但 CesiumLab2 胜在免费、界面直观、参数集中尤其适合一次性处理多个 DEM 文件。你不需要写脚本把数据拖进去设置好层级点开始等着出结果就行。它输出的瓦片结构是静态文件后面接什么 HTTP 服务器都无所谓这也给 nginx 上场留好了位置。1.3 一次完整的自建地形服务流程整体链路其实非常简单准备 DEM 数据统一坐标系裁剪到目标范围。用 CesiumLab2 做地形切片生成.terrain瓦片和layer.json。用 nginx 把瓦片目录发布成 HTTP 静态服务。在 CesiumJS 里通过CesiumTerrainProvider加载layer.json的地址。浏览器根据相机视角自动请求对应层级的瓦片并渲染出三维地形。nginx 在这套链路里看似只是个文件服务器但它承担了很多隐形工作路径映射、跨域头、缓存策略、HTTPS、同端口多项目分发。后面你会看到这些配置缺一个前端就可能白屏或者加载失败。2. DEM数据准备与CesiumLab2切片配置2.1 免费DEM数据源与预处理做地形服务第一步是拿到 DEM。公开可用的数据源不少常见的有 SRTM、ASTER GDEM、ALOS AW3D30国内也有地理空间数据云这类平台。下载的时候注意选 GeoTIFF 格式单位是米坐标系一般是 WGS84。如果你的源数据是 UTM 投影切片前最好先用 GIS 软件转成地理坐标系否则可能出现位置偏移或层级计算错乱。拿到原始数据后别急着直接拖进 CesiumLab2。我一般会先做三步预处理第一把多块分幅数据拼接成一块大区域的 GeoTIFF第二按项目范围裁剪去掉周边不需要的区域这样切片大小和耗时都能显著降低第三检查数据精度和分辨率比如 SRTM 1 弧秒大概是 30 米分辨率如果切片最大层级超过数据实际精度后面大量瓦片其实是插值出来的意义不大。有个很容易忽略的点CesiumLab2 对输入文件的大小和格式有隐性要求。我踩过的一个坑是直接把 IMG 格式的高分影像 DEM 拖进去结果识别不出高程值切出来的地形一片平滑。后来用 GIS 工具转成 GeoTIFF 就好了。如果你的 DEM 是浮点型 tif最好先检查像素类型确保是 16 位或 32 位浮点别是 8 位灰度图转存的假 DEM。2.2 CesiumLab2切片参数怎么设打开 CesiumLab2 后入口一般是“地形切片”或者“数据处理”模块版本不同按钮位置会变但核心逻辑一样。第一次用的时候建议先拿一小块区域的小文件做测试配置一遍走通再处理正式数据省得白等几个小时。关键参数我按优先级排序输出格式选 Cesium 地形对应layer.json和.terrain瓦片不要选成 Mapbox 之类的地形格式。最高层级根据 DEM 分辨率定。30 米分辨率一般到 13 到 15 层就够90 米分辨率到 11 到 12 层就差不多了。层级设太高不仅切片慢还会产生大量空瓦片前端请求到不存在的瓦片会反复 404。坐标系统选 WGS84 或 CGCS2000。国内项目如果要求国家坐标系要在切片前把 DEM 转到对应坐标系。输出目录找一个磁盘空间充足的路径一个省的地形切片动辄几十 GB别放在 C 盘系统盘里。切片过程有进度条时间段取决于数据大小和机器配置。等它跑完后回到工具主页可以用它自带的预览功能先看效果这一步很关键。如果预览都加载不出地形那问题大概率出在数据或切片参数上别急着去配 nginx。2.3 切片输出目录和layer.json校验切片完成后的输出目录通常长这样terrain/ layer.json 0/ 0/ 0.terrain 1/ 0/ 0.terrain ...layer.json是整个地形服务的元数据文件里面有投影、切片方案、可用层级、水印等配置。CesiumJS 加载地形时第一步请求的就是layer.json拿到它才知道往哪些路径请求.terrain瓦片。所以发布服务时nginx 的根目录必须能通过 HTTP 访问到这个文件否则地形永远加载不出来。我会习惯性地用浏览器直接访问一次http://localhost:8088/terrain/layer.json能返回 JSON 内容就说明路径没问题。如果返回目录列表或者 404先别调前端代码把服务端路径弄对再说。3. nginx发布地形服务的完整配置3.1 安装nginxWindows、Ubuntu和离线环境nginx 的安装在这里不详细展开但必须说清楚几个常见场景。Windows 下最简单官网下载稳定版压缩包解压后直接运行nginx.exe即可默认监听 80 端口浏览器访问http://localhost能看到欢迎页就代表成功了。开发调试时我喜欢用 Windows 版本改完配置直接双击运行省事。Ubuntu 这类 Linux 系统一行apt install nginx就能装好然后systemctl enable --now nginx设置开机自启。如果项目环境是完全离线的那就需要提前下载安装包和依赖。比如在 aarch64 架构的机器上把对应架构的 deb 包或者源码包拷进去源码方式就是./configure make make install三步走编译前记得装好 PCRE、zlib、openssl 这些依赖库。还有像银河麒麟这类国产系统本质也是 Linux离线安装思路一样找对应发行版的包管理器源就行。装完 nginx 后先用nginx -v验证版本再通过nginx -t检查配置。这个习惯能帮你避免很多低级错误改完配置不检查就 reload一旦语法有问题服务可能直接挂掉。3.2 地形Static服务核心配置地形瓦片是纯静态文件nginx 只需要配置一个server块和location指向瓦片目录。下面是我平时用的一套基础配置server { listen 8088; server_name localhost; location /terrain/ { alias /data/cesium-terrain/; add_header Access-Control-Allow-Origin *; add_header Access-Control-Allow-Headers *; expires 7d; gzip on; gzip_types application/json application/octet-stream; } }这里最容易踩的坑是alias和root搞混。alias /data/cesium-terrain/的含义是当请求路径匹配/terrain/时直接映射到/data/cesium-terrain/目录。所以请求/terrain/layer.json时nginx 去找/data/cesium-terrain/layer.json。如果你用了root /data/cesium-terrain/nginx 会去找/data/cesium-terrain/terrain/layer.json多出一层目录结果就是 404。加add_header Access-Control-Allow-Origin *是为了解决跨域。前端页面如果跑在 8089 端口地形服务在 8088 端口浏览器就会拦截跨域请求。静态地形服务只做 GET 请求加上这个头就够了。expires 7d是让浏览器把瓦片缓存 7 天地形数据基本不变这个策略能省不少流量。3.3 同一端口部署前端、地形和后端API实际项目里不太可能一台服务器只跑一个地形服务。前端页面、影像图层、地形瓦片、后端接口最好能在一个 nginx 端口下统一调度。比如我在 80 端口上同时部署三个 Web 项目前端静态站点用/app/地形服务用/terrain/后端接口走/api/反代。server { listen 80; server_name localhost; location /terrain/ { alias /data/cesium-terrain/; expires 7d; } location /app/ { alias /web/cesium-app/; index index.html; try_files $uri $uri/ /app/index.html; } location /api/ { proxy_pass http://127.0.0.1:8080/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } }try_files $uri $uri/ /app/index.html主要给前端 history 路由用的这样用户在/app/some/path刷新时不会 404。proxy_pass末尾有没有斜杠差别很大proxy_pass http://127.0.0.1:8080/;会把/api/去掉后转发而proxy_pass http://127.0.0.1:8080;会保留完整 URI。如果后端接口定义里包含/api前缀用后者否则用前者。这样配置完前端代码里所有请求都指向同源地址天然没有跨域问题。需要部署第二个前端项目时再加一个location /admin/就好了非常简单。3.4 HTTPS与自签名证书的那点事浏览器对 WebGL 和很多现代 API 都要求安全上下文地形服务虽然不强制 HTTPS但如果你后面要做在线编辑、摄像机、麦克风等能力或者页面本身通过 HTTPS 访问所有资源都得是 HTTPS否则会出现混合内容拦截。内网测试时自签名证书完全够用。生成证书一行命令openssl req -x509 -nodes -days 365 -newkey rsa:2048 \ -keyout /etc/nginx/cert/server.key \ -out /etc/nginx/cert/server.crt \ -subj /CNlocalhost然后在 nginx 里加一个 443 的 server 块指定ssl_certificate和ssl_certificate_key。最好再配一个 80 跳 443server { listen 80; server_name localhost; return 301 https://$host$request_uri; }自签名证书唯一的问题是客户端不信任浏览器会红屏警告。如果是项目团队内部使用可以把自签证书导出后导入到系统证书库里如果面向外部用户还是建议用正规证书或者走内部 CA 签发。4. 从DEM到浏览器渲染的CesiumJS接入4.1 本地化引入CesiumJS网上很多示例直接引 Cesium 在线 CDN本地自建地形时最好把 CesiumJS 构建包也放到 nginx 里彻底摆脱外网依赖。把 Cesium 的 Build 目录拷到/web/cesium-app/libs/cesium/下页面里这样引入link href/app/libs/cesium/Widgets/widgets.css relstylesheet script src/app/libs/cesium/Cesium.js/script引入后建议设置Cesium.CesiumWidget或Viewer的静态资源根路径。最稳的做法是在脚本前定义window.CESIUM_BASE_URL /app/libs/cesium/;否则 Cesium 内部的Assets、Workers等目录可能因为相对路径问题加载不到。4.2 地形Provider加载代码实战完整页面代码我直接放一个最小可用版本测试时复制就能跑!DOCTYPE html html langzh-CN head meta charsetUTF-8 title本地地形服务测试/title link href/app/libs/cesium/Widgets/widgets.css relstylesheet script src/app/libs/cesium/Cesium.js/script style html, body, #cesiumContainer { width: 100%; height: 100%; margin: 0; } /style /head body div idcesiumContainer/div script window.CESIUM_BASE_URL /app/libs/cesium/; const viewer new Cesium.Viewer(cesiumContainer, { baseLayer: false, baseLayerPicker: false, geocoder: false, sceneModePicker: false, navigationHelpButton: false, animation: false, timeline: false }); async function loadTerrain() { try { const provider await Cesium.CesiumTerrainProvider.fromUrl(/terrain/); viewer.terrainProvider provider; } catch (e) { console.error(地形加载失败, e); } } loadTerrain(); viewer.camera.setView({ destination: Cesium.Cartesian3.fromDegrees(108.0, 34.0, 8000) }); /script /body /html这里用了CesiumTerrainProvider.fromUrl这是新版本推荐的异步构造方式。如果你用的 Cesium 版本比较老可以改成var provider new Cesium.CesiumTerrainProvider({ url: /terrain/ }); viewer.terrainProvider provider;注意/terrain/要和 nginx 里的location /terrain/对应。打开浏览器开发者工具Network 里如果能看到请求/terrain/layer.json并返回 200还能看到一堆.terrain瓦片请求说明链路已经通了。4.3 影像图层与地形叠加纯地形加载后会看到一片灰色或者单一颜色的起伏表面因为baseLayer: false把影像底图关掉了。想要真实感必须叠加影像图层。离线环境可以自己用 GeoServer 发布影像服务或者先把影像瓦片切好再用TileMapServiceImageryProvider加载。简单示例const imageryProvider await Cesium.TileMapServiceImageryProvider.fromUrl( /images/{z}/{x}/{y}.png ); viewer.imageryLayers.addImageryProvider(imageryProvider);格式需要根据你自己的影像瓦片结构来调整。如果只是本地测试也可以临时使用在线影像服务但注意在全离线环境里这行代码会报错所以要封装成有网络时才加载。4.4 几个提升观感的调整技巧地形服务和平面地图最大的区别就是立体感默认参数下可能看不太出来。我调试时会调三样东西首先是viewer.scene.globe.terrainExaggeration 1.5把高差放大 1.5 倍起伏更明显特别适合平缓地区其次是开启光照viewer.scene.globe.enableLighting true能看到山体阴影渲染效果瞬间上一个档次最后是相机位置用setView把视角飞到 DEM 覆盖区域中心高度不要太高否则只看到弧面看不到地形细节。5. 常见问题与排查技巧实录5.1 地形瓦片404页面一片空白这是最常见的问题。现象是layer.json可能加载成功但后面的.terrain请求大量 404地形根本不出来。原因基本有两个一是 nginx 路径映射错误alias和root混用导致文件不在预期位置二是 CesiumLab2 切片的层级范围和你请求的层级不匹配比如浏览器当前视角要求第 18 层但切片只生成到第 14 层。排查技巧先用浏览器直接访问http://ip:端口/terrain/layer.json确认能返回 JSON再随意找一个瓦片 URL比如http://ip:端口/terrain/10/100/200.terrain能返回文件就说明 nginx 没问题。如果 fromUrl 报错把 console 里的完整错误信息贴出来重点看是网络 404 还是解析失败。5.2 浏览器控制台报CORS跨域错误如果你把前端页面和地形服务放在不同的端口比如前端在 8089地形在 8088就一定会遇到跨域。报错一般长这样Access to fetch at http://localhost:8088/terrain/layer.json from origin http://localhost:8089 has been blocked by CORS policy。解决方式就是我在 3.2 节写的add_header Access-Control-Allow-Origin *;。如果配置生效了还报错检查 nginx 是不是开了expires但没开 CORS 头在错误的位置。注意add_header在location里配置后同一location如果有多个add_header都有效但如果你在server里配了越权之类的子级会覆盖。最简单的做法是把 CORS 头加到对应的location里。5.3 地形加载了但看着是平的之前有个朋友调试半天地形服务加载正常瓦片请求也 200但屏幕上就是一片平的颜色。后来发现他把 DEM 范围设置得很小但相机高度在 100 公里外一个县的 DEM 在那么高的视角里看起来就和平面没区别。把相机飞近拉到 3 到 5 公里高度起伏就出来了。另一个原因是 DEM 本身精度太低。比如全球 90 米分辨率的 SRTM 数据在很多平原地区的高差只有几米甚至不到一米默认比例尺下确实看不出起伏。这时候可以调大terrainExaggeration或者只用它研究山地地形。还有一种情况是被坑的有的地方下载的“DEM”其实是坡度图或彩色高程渲染图不是真实高程栅格CesiumLab2 切出来自然不会对。5.4 nginx大量瓦片并发时的性能调优地形瓦片加载是典型的多文件并发场景几百个瓦片同时请求很常见。默认配置下 nginx 可能不够快我一般会加几行worker_processes auto; events { worker_connections 1024; } http { open_file_cache max10000 inactive30s; open_file_cache_valid 60s; }open_file_cache能减少重复打开文件的开销对静态瓦片效果显著。另外地形瓦片一旦生成就不会变expires 30d不会影响正确性反而能避免用户每次打开页面都重新下载几千个文件。如果机器内存足够可以考虑把瓦片目录放到内存盘或 SSD加载速度会有肉眼可见的提升。5.5 反向代理和多项目部署的隐蔽坑同一个 nginx 部署多个 Web 项目时最隐蔽的坑是location匹配顺序。比如你配置了location /app/和location /app/terrain/这两个前缀都能匹配/app/terrain/xxxnginx 会选最长前缀匹配所以把地形放/app/terrain/这种嵌套路径时顺序其实没影响优先匹配更长的。真正容易出问题的是root和alias混用以及proxy_pass末尾斜杠。反向代理到后端接口时proxy_set_header Host $host一定要加。后端如果基于 Host 判断域名或做权限校验不加这个头就可能会返回 403 或者跳转到错误地址。同理X-Real-IP和X-Forwarded-For也要带上不然后端日志里全是 nginx 的 IP排查问题都没法查。6. 这套方案的扩展空间与我的实操习惯6.1 从地形服务到三维场景的一站式发布nginx 把地形瓦片发好后完全可以顺手把影像瓦片、3D Tiles 倾斜摄影模型、前端静态页面全部放进来。CesiumLab2 本身也能处理点云、倾斜摄影和建筑白模输出 3D Tiles 后同样放在 nginx 下用Cesium3DTileset加载。一个 nginx 进程一台普通服务器地形、影像、模型、业务前端全部就地解决这就是零成本三维服务的完整形态。我现在的项目架构基本是/terrain/放地形/images/放影像瓦片/models/放 3D Tiles/api/反代后端 Java 服务另外加两个 location 放 PC 端和移动端前端。nginx 的配置用include拆成多个文件每个项目一个 conf互不干扰改哪个也不会影响其他项目。6.2 开机自启和服务维护nginx 本身不会自己开机启动。Linux 下用 systemd 很省心写一个 service 文件[Unit] Descriptionnginx service Afternetwork.target [Service] Typeforking ExecStart/usr/local/nginx/sbin/nginx ExecReload/usr/local/nginx/sbin/nginx -s reload ExecStop/usr/local/nginx/sbin/nginx -s quit PrivateTmptrue [Install] WantedBymulti-user.targetWindows 下可以把它注册成系统服务重启机器后服务自动拉起。因为地形服务本质是文件读取只要瓦片目录在nginx 起来后立刻就能恢复访问比那些重型 GIS 服务稳妥得多。6.3 数据更新与版本管理DEM 数据不是一成不变的更新时不需要停机。我习惯把切好的地形按版本放目录/data/cesium-terrain/v1/、/data/cesium-terrain/v2/。要切换版本改一下 nginx 里alias指向新的目录nginx -s reload就行旧版本目录留着做回滚。这样比直接覆盖文件安全万一新数据有问题一条命令切回来。浏览器端可能会缓存旧的瓦片所以切换版本后最好让前端带一个版本参数比如/terrain/v2/而不是请求同一个路径。这也是为什么我宁愿多占一点磁盘空间把版本目录分得清清楚楚也不愿意原地覆盖。6.4 最后分享两个小技巧一是调试地形问题时把浏览器 Network 面板打开过滤layer.json和.terrain所有请求一目了然。如果地形空白先看layer.json是否 200再看瓦片是否 200问题在前端还是后端一秒定位。二是用 nginx 服务 CesiumLab 生成好的地形时尽量保持目录纯净不要放无关文件和中文路径。Cesium 内部对 URL 的解析比较严格中文路径或空格有时会导致编码不一致。前期多花几分钟把目录命名规范好后期能省非常多的时间。这套从 DEM 到浏览器的零成本方案我已经在多个项目里跑过稳定性和加载速度都不输商业服务。如果你也在折腾离线三维地形先按这个流程搭起来再根据自己的项目去调整细节就好。