ArcGIS Portal接入天地图底图：密钥申请、WMTS配置与代理注入全攻略

做内网GIS平台的人应该都有同感ArcGIS Portal本身不产底图业务图层再漂亮底下没一张能打的地图垫着整个系统就飘着。这几年我经手的项目里至少有四五个单位的Portal最终都把底图定成了天地图——官方背景、国内范围全、坐标系还和国土业务数据对得上。但“定成天地图”这六个字背后其实藏着一堆坑key怎么申请、WMTS地址怎么填、为什么Portal添加时看不到自定义参数栏、瓦片加载出来为什么位置偏了。这篇文章就把我在Portal里接天地图底图的完整过程和排查记录写出来包括直接能用的URL模板、代理注入token的方案以及“没有自定义参数栏”的绕行办法给准备做同样事的人省点时间。无论你是刚接手Portal还是已经跑了好几个项目这套思路都能直接用上。1. 天地图底图的本质与方案选型1.1 天地图的瓦片服务到底长什么样天地图是国家地理信息公共服务平台提供的基础底图分成两大类影像类和矢量类每类底下又带对应的注记层。从技术协议上看它对外提供的是标准WMTS服务但同时也兼容一套接近“XYZ”风格的瓦片请求格式这就决定了它在ArcGIS体系里可以走两条路一条是按OGC WMTS标准接口接入另一条是把它当成一个自定义切片服务模板去加载。天地图的服务地址并不复杂核心参数就几个图层名LAYER、请求方式REQUEST、切片方案TILEMATRIXSET以及开发者密钥tk。图层名方面vec是矢量底图img是影像底图ter是地形晕渲cva是矢量注记cia是影像注记cta是地形注记。切片方案只有两套w开头的是CGCS2000经纬度坐标切图方式按经纬度网格c开头的是CGCS2000投影坐标切图方式与Web墨卡托一致也就是三大互联网地图通用的那套规则。这中间最关键的一个判断点是如果你的业务图层是Web墨卡托坐标系底图就用c开头的切片集如果你是经纬度坐标系的数据底图就用w开头的切片集。混着用也不是不能显示Portal会动态投影但一来性能损耗明显二来很容易出现“图能出来位置就是差口气”的诡异偏移后面排查起来很费劲。1.2 Portal加载天地图的四条路线在Portal里加载天地图绕来绕去无非四条路我把优劣一次性列清楚。方案实现方式优点缺点适用场景A. Tile Layer模板直连在Map Viewer里以“切片图层”方式输入带占位符的WMTS/XYZ地址步骤最少不需要额外中间件依赖UI对URL模板的识别部分版本会挑占位符写法快速验证、临时底图、小项目B. OGC WMTS标准接入在Map Viewer里选WMTS服务输入GetCapabilities地址标准协议理论上最正规Portal的WMTS解析器不好加自定义参数token很容易丢不太推荐在Portal里用C. 代理中转Nginx或Esri resource-proxy做转发统一注入tk参数key不暴露可加缓存、可统一管控多维护一个服务配置稍重生产环境、多人共用、安全要求高D. 离线瓦片发布在公网环境下载瓦片包用ArcGIS Pro发布为Portal自有切片图层内网可用不受公网波动影响数据更新慢下载量大合规上要注意条款内外网隔离、政务网环境我的建议很明确个人测试和初期验证走方案A正式生产环境直接上方案C。方案B在桌面端ArcMap里是可行的但在Portal的网页端界面里十有八九会卡在token这一步后面我会专门讲这个坑。方案D属于终极兜底单位要求数据不出内网时别无选择。2. 准备工作申请密钥与拼服务地址2.1 天地图开发者密钥的正确打开方式天地图的key分为浏览器端和服务端两类这个选择直接决定你后面能不能跑通但很多教程一句话带过导致不少人拿着浏览器端key去代理场景里用结果请求一直403。登录天地图官网进入控制台创建应用时系统会让你选应用类型。如果Portal是直接通过浏览器向天地图服务器拉瓦片用“浏览器端key”就行但一定要在域名白名单里加上Portal的访问域名比如portal.example.com不然浏览器请求会被Referer校验拦下来。如果是走Nginx代理或某个后端服务统一转发瓦片请求就用“服务端key”服务端key不限制来源域名更适合藏在代理层。提交之后系统会生成两个key分别是浏览器端和服务端别搞混。一个小经验key的配额是按日调用量算的一个小团队做验证没有问题但如果Portal用户量到了几十上百人建议还是套一层代理并在代理里做瓦片缓存否则很容易把当天的配额刷穿。2.2 常用服务地址模板与参数说明有了key之后下面这组URL模板是我实际验证过可用的直接复制后把KEY替换掉就行。推荐优先用投影坐标切片集c因为Portal的Web地图默认底图坐标系就是Web墨卡托省去动态投影的麻烦。矢量底图c投影https://t0.tianditu.gov.cn/vec_c/wmts?SERVICEWMTSREQUESTGetTileVERSION1.0.0LAYERvecSTYLEdefaultTILEMATRIXSETcFORMATtilesTILEMATRIX{z}TILEROW{y}TILECOL{x}tkYOUR_KEY影像底图c投影https://t0.tianditu.gov.cn/img_c/wmts?SERVICEWMTSREQUESTGetTileVERSION1.0.0LAYERimgSTYLEdefaultTILEMATRIXSETcFORMATtilesTILEMATRIX{z}TILEROW{y}TILECOL{x}tkYOUR_KEY对应注记层https://t0.tianditu.gov.cn/cva_c/wmts?SERVICEWMTSREQUESTGetTileVERSION1.0.0LAYERcvaSTYLEdefaultTILEMATRIXSETcFORMATtilesTILEMATRIX{z}TILEROW{y}TILECOL{x}tkYOUR_KEY这里的参数拆开解释一下SERVICE必须等于WMTSREQUEST是GetTileVERSION目前天地图用1.0.0STYLE固定defaultFORMAT固定tilesTILEMATRIX/TILEROW/TILECOL分别对应缩放级别、行号和列号在Portal里也可能要写成{level}/{row}/{col}后面实操时会说。tk就是你的密钥。很少有人提的是天地图同时提供了t0到t7一共8个子域名也就是t0.tianditu.gov.cn、t1.tianditu.gov.cn一直到t7。浏览器对同一域名的并发请求是有限制的如果项目对地图加载速度有硬性要求可以用前端写法把子域名打散来做并发轮询。但在Portal的“从URL添加图层”里单条URL写死一个子域就行不需要自己实现轮询。3. 实操主流程Map Viewer添加天地图切片图层3.1 能被Portal识别的切片图层URL怎么拼这一步是整个流程的关键也是网上教程最含糊的地方。Portal的Map Viewer从URL添加图层的界面里并没有一个“天地图”的专属选项你需要选“切片图层”或者“Tile Layer”然后希望Portal能把你贴进去的URL识别为一个可用的瓦片服务。但Portal的识别逻辑很挑剔对占位符参数有自己的一套约定。我实际测试下来下面这个写法在经典Map Viewer里是最稳的https://t0.tianditu.gov.cn/vec_c/wmts?SERVICEWMTSREQUESTGetTileVERSION1.0.0LAYERvecSTYLEdefaultTILEMATRIXSETcFORMATtilesTILEMATRIX{level}TILEROW{row}TILECOL{col}tkYOUR_KEY注意我把{z}换成了{level}把{y}{x}换成了{row}{col}。Portal的切片图层识别逻辑沿袭自ArcGIS JS API的WebTileLayer它最兼容的占位符是{level}、{row}、{col}这三个。部分新版本也开始认{z}/{x}/{y}如果你用{z}风格没被识别换成{level}风格就好。还有一种说法是直接改成纯XYZ风格的简化地址但天地图的官方接口本身不是纯XYZ格式硬要改容易漏参数所以我不建议在一开始就把WMTS参数去掉。还有一个容易踩的细节URL里的大写参数名不要动SERVICE、REQUEST、VERSION、TILEMATRIXSET、FORMAT都是大写开头Portal识别模板时是按字符串匹配的大小写不一致会直接被判定为“无法识别图层”。3.2 经典Map Viewer添加并保存为底图拿经典Map Viewer举例整套操作流程分六步我第一次走通的时候花了差不多半小时所以这里把步骤写细一点。第一步登录Portal打开Map Viewer Classic先随便建一个空白地图。第二步点“添加”按钮选择“从URL添加图层”。第三步在类型里选“切片图层”不要选“OGC WMTS”这一步很多人一开始就选错了后面的坑都是从这里埋下的。第四步把上一节整理好的带{level}/{row}/{col}占位符的URL贴进去点击添加。第五步如果URL格式没毛病地图画布上应该立刻出现天地图瓦片这时候右键点击图层列表里的这个图层能正常看到“图层属性”和“缩放至图层”等选项说明这个图层已经被Portal当成一个标准的底图服务了。第六步把这个图层保存进底图库点击底图按钮在底图面板底部找到“添加底图”选择当前地图里的天地图图层确认保存。保存完后底图面板里会多出一个“天地图矢量”之类的自定义底图以后新建地图时就能直接切换不需要再粘贴一遍URL。这一步很多教程没有提导致大家每次新建地图都要重新添加一遍图层操作重复而且容易出错。3.3 新版Map Viewer差异与“没有自定义参数栏”的真相不少人在新版Map Viewer里操作时发现从URL添加WMTS服务界面压根没有给自定义参数留地方token不知道该往哪填。这个“没有自定义参数栏”的问题本质原因是Portal对OGC服务的解析器没有开放参数注入入口它默认你输入的URL就是最终请求URL后续瓦片请求里参数无法追加自然就没法在这种方式下携带tk。所以正确的反应不是满世界找自定义参数栏而是换道改用“切片图层”方式把token直接写在URL里。新版Map Viewer的入口略有不同点“添加”后选“来自URL的图层”在图层类型里选“切片图层”然后粘贴完整带token的模板URL。新版对{z}/{x}/{y}的兼容性比旧版好一些但为了保险我仍然建议用{level}/{row}/{col}。另外必须提醒一点无论新旧Map Viewer添加天地图后地图的坐标系都会跟随Portal当前地图的坐标系走。如果你的Portal组织配置的默认坐标系是CGCS2000/3度带之类的地方投影建议先在Portal的“组织设置→地图”里确认好默认坐标系不然底图和数据坐标系不一致后面各种怪问题都来了。4. 进阶方案代理注入token的透明加载4.1 什么场景下必须走代理直接通过Tile Layer方式加载天地图步骤够简单适合一个人调试但到了生产环境就有几个现实问题一是浏览器端key要把Portal域名加进白名单如果Portal域名隔三差五改白名单同步跟不上二是key明晃晃地写在URL里用户通过F12看网络请求就能捞走三是天地图接口有并发和配额限制整栋楼的人同时刷瓦片配额消耗极快。代理方案解决的就是这三件事把key收进服务端对外只暴露一个自己的地址在代理层做缓存相同瓦片只向上游请求一次如果有需要还能统一统计调用量。所以我的建议是一旦Portal正式上线且用户量可预期地超过十人就别再用直连方案了。4.2 Nginx透明代理配置示例用Nginx做转发是成本最低的方式。思路是让Portal请求你自己的地址Nginx把它原样转发给天地图并在转发前自动把tk参数拼到请求串里。这样Portal那端完全无感知它看到的只是一个普通切片服务地址。下面是一段精简配置假设代理服务的访问路径是https://your-portal.example.com/tianditu/vec_c/wmtslocation ~ ^/tianditu/(.*)$ { set $args $argstkYOUR_SERVER_KEY; proxy_pass https://t0.tianditu.gov.cn/$1?$args; proxy_set_header Host t0.tianditu.gov.cn; proxy_buffering on; proxy_cache_path /data/nginx/tianditu_cache levels1:2 keys_zonetianditu_cache:10m max_size5g inactive30d; proxy_cache tianditu_cache; proxy_cache_valid 200 30d; }这里的思路就是正则捕获/tianditu/后面的路径转发给真实天地图域名同时通过set $args把tk注入进查询串。proxy_cache部分是可选的但在生产环境强烈建议打开一次缓存30天能明显降低对天地图的请求量和网络延迟。配置好后Portal里添加图层时URL填你的代理地址就可以了https://your-portal.example.com/tianditu/vec_c/wmts?SERVICEWMTSREQUESTGetTileVERSION1.0.0LAYERvecSTYLEdefaultTILEMATRIXSETcFORMATtilesTILEMATRIX{level}TILEROW{row}TILECOL{col}注意这个URL里不用再带tk代理已经帮你加好了。如果你不想自己写Nginx也可以用Esri官方的resource-proxy项目在proxy.config的serverUrls里加一条指向天地图的记录原理一样但配置文件是XML格式没有Nginx这么直观。二选一即可。5. 常见问题与排查实录5.1 高频问题速查表现象可能原因解决方案备注添加图层时报“无法识别的URL”占位符格式不对或参数名大小写错误换成{level}/{row}/{col}检查SERVICE等大写参数最常出现在新版Map Viewer地图画布灰白一片无瓦片tk无效、配额耗尽、请求被Referer拦截核对key查看浏览器Network面板的返回码403多半是白名单问题底图能显示但位置明显偏移切片方案与地图坐标系不一致统一用c切片集或w切片集别混用偏移在几百米级别注记层永远压在业务图层下面注记层没有单独添加或添加后层级不对注记层单独再添一次然后把两个图层都设为底图组件注记层必须浮在底图上缩放到某一级开始白屏天地图最高级数不支持或超出范围确认比例级别上限在应用层限制最大缩放级别一般不超过18级加载速度慢瓦片偶发加载失败域名并发限制或天地图服务波动走代理做缓存或用t0~t7子域分流生产环境必做这几个问题里最容易被忽视的是Referer白名单。如果你用的浏览器端key只配置了localhost而Portal的访问域名是https://portal.example.com浏览器请求天地图瓦片时会把后者作为来源域头发出去天地图校验不通过就直接403。所以配好Portal域名之后务必用无痕模式重新测一遍因为浏览器缓存常常会把旧的错误状态留很久。5.2 坐标系与投影偏移识别“底图显示了但位置不对”这个问题我至少被问过五次。最常见的情形是业务图层坐标是CGCS2000经纬度但Portal默认地图底图是Web墨卡托你在Portal里加载天地图w切片集时Web端显示层面进行了动态投影初次打开肉眼看着没问题一旦叠加业务图层就能明显感到要素位置整体往某个方向飘。判断方法很简单打开天地图官方坐标拾取工具或第三方拾取页面取一个你熟悉的地标点把拾取到的经纬度和你地图上同一地标对比如果经纬度数值差到小数点后两位以上基本就是底图切片方案和地图坐标系不匹配。解决方案也清晰要么把业务图层转成Web墨卡托、使用c切片集要么把业务层保持原坐标系、使用w切片集然后在Portal里把地图坐标系显式设为经纬度。不要指望靠“拖动图层微调”来对齐那治标不治本。5.3 并发限制与缓存优化心得天地图免费key的并发并不高一个Portal组织几十号人同时浏览地图时瓦片请求是像瀑布一样打过去的运气差的时候一个用户刷地图其他人都卡住。我在代理缓存配置里把瓦片缓存时间设成30天这是有讲究的天地图的栅格瓦片更新频率以月为单位30天缓存既不影响“偶尔更新”的数据新鲜度又能在绝大多数场景下直接命中缓存。政务内网用户经常访问的区域就那么大缓存命中率到90%以上是很正常的。缓存目录的容量按5G起步设置估算方式是每级瓦片大概几十到几百KB按常用10~18级来算5G已经能覆盖一个城市范围的常用级别如果地表范围是全省级最好给到20G以上。空间不够时优先淘汰旧瓦片而不是直接把缓存关了。6. 离线部署与周边扩展6.1 离线瓦片的获取与发布很多单位的内网和公网物理隔离Portal跑在内网直接访问天地图公网服务不现实。这种场景下的路子就是把瓦片“搬”进内网。在条件允许且符合天地图服务条款的前提下可以在外网机器上用脚本按z/x/y批量拉取瓦片或者使用支持天地图源的地图下载工具把特定行政区划、特定缩放级别的瓦片下载下来。下载后的数据有几种归宿最省事的是整理成标准瓦片目录用ArcGIS Pro的“创建切片缓存”功能导入并共享为Portal切片图层也可以先转成TPK包再发布为Portal项。这里有一个很现实的忠告离线瓦片数据量比你想象的大得多。如果只是给领导演示下载十几个GB就够如果要覆盖全省并支持到18级动辄上TB。所以下载前一定要先确定范围和级数宁可少下后面再补也不要一次性把全国数据拉回来磁盘空间和下载时间都不现实。另外离线方案涉及数据合规问题请务必严格按照天地图的服务条款来使用不要忽略版权标识。6.2 从Portal延伸到WebApp和小程序Portal里配好天地图底图后沉淀出来的是一张Web地图这张地图可以嵌入到各种前端应用里。ArcGIS JS API调用门户里的WebMap底图自动就是天地图。这种方式比在前端重新加载天地图JS API要省事得多而且能继承Portal已有的权限体系和图层列表。另外这些年经常有人问天地图怎么和微信小程序结合。小程序的map组件本身不支持直接塞WMTS地址常规做法是天地图Web API在网页端生成地图再用web-view组件把小程序的页面内容嵌进去。至于逆地址解析之类的功能天地图也提供了REST风格的WebService接口返回JSON格式数据非常适合计算坐标点对应的行政区划或地名。放在Portal的应用里做个“点击地图显示位置描述”的小功能还是很顺手的。我在实际项目里最常用的组合方式说出来你可能不信不是代理也不是离线包而是“Tile Layer直连底图库保存”这一套。原因很简单很多单位Portal刚上线的阶段用户量不大先把流程走通、让业务数据展示出来比一上来就搞高大上的代理架构更符合实际情况。等用户量上来或者安全问题变敏感了再在Nginx层加代理也不迟。最后提醒一句如果你部署的Portal启用了HTTPS强制访问代理服务也一定要挂HTTPS证书不然浏览器会把瓦片请求识别为混合内容直接拦截页面上一片空白。这个坑我踩过一次排查了一下午才发现是证书没配全。希望这篇东西能帮你把该绕的弯都绕过去。