简介本资源面向需要在 GeoServer 中发布 ArcGIS 瓦片服务的 GIS 开发者与运维人员解决切片数据迁移、离线地图服务搭建及跨平台发布等实际问题适合具备一定 GIS 基础、希望打通 ArcGIS 与开源地图服务链路的中高级用户。压缩包共 1571 个文件约 137.36MB以 png 瓦片图片、jar 依赖库、xml 配置、prj 投影文件、sld 样式、shp/dbf/shx 矢量数据及 pgw 坐标文件为主另含 properties、bat 启动脚本与日志等运行支撑文件覆盖服务部署所需的完整目录结构。目前已有 1090 人学习下载。资源内含可直接运行的 GeoServer 环境与配套瓦片数据读者可据此完成瓦片图层发布、样式配置与切片预览并参考日志与配置文件排查发布过程中的常见问题快速复现 ArcGIS 瓦片在 GeoServer 中的发布流程。1. 从一次瓦片发布翻车说起为什么我坚持用 GeoServer 发 ArcGIS 瓦片去年帮一个做智慧园区的朋友处理地图服务他们前端用的是 ArcGIS JS API底图却想换成自己切的瓦片。我第一反应是拿 GeoServer 直接发结果第一次就翻车了——瓦片目录结构对不上缓存切片规则没配好前端加载出来全是灰块。折腾到凌晨两点才发现问题根本不在 GeoServer而在我切瓦片时用的坐标系和网格集没对齐。这件事让我意识到用 GeoServer 发布 ArcGIS 瓦片这件事看起来只是点几下鼠标实际上从环境准备到参数配置每一步都有坑。如果你也正卡在「GeoServer 怎么装」「ArcGIS 瓦片怎么发布」「GeoServer 环境搭建」这些问题上那这篇笔记就是我从零到跑通的全过程记录包括版本选择、安装步骤、配置参数和翻车后的补救办法。整套流程在 Windows 和 Linux 上都验证过新手照着走能跑通熟手也能看到我在参数取舍上的思考。2. 环境准备与版本选择GeoServer 装哪个版本、Java 怎么配2.1 GeoServer 版本与 Java 运行时的对应关系GeoServer 是基于 Java 的 Web 应用装之前第一件事不是下载 GeoServer而是确认 Java 版本。我见过太多人直接下最新版 GeoServer结果本机 Java 是 8启动直接报UnsupportedClassVersionError。常见做法是GeoServer 2.20 及以后版本要求 Java 11 或 172.19 及以前可以用 Java 8。如果你不确定去 GeoServer 官网的下载页看每个版本旁边的「Java Version」标注这是最稳的。我一般会选 GeoServer 2.23.x 配 Java 17原因是这个组合在 Windows 和 Linux 上都有长期支持且对 ArcGIS 瓦片缓存的支持比较成熟。如果你机器上已经有 Java 8 且不想动那就退到 GeoServer 2.19.x但要注意后续插件兼容性会差一些。GeoServer 版本推荐 Java 版本适用场景2.23.x 及以上Java 17新部署需要长期维护2.20.x ~ 2.22.xJava 11平衡稳定与新特性2.19.x 及以下Java 8老系统兼容不推荐新项目提示不要同时装多个 Java 版本后不设JAVA_HOMEGeoServer 启动脚本会优先读环境变量读不到才用默认路径很容易启动到错误的 Java 上。2.2 下载与安装 GeoServer 的两种方式GeoServer 官方提供两种安装包平台无关的二进制包zip/tar.gz和 Windows 安装程序。我强烈建议用二进制包因为安装程序会往系统里写服务、注册表卸载不干净而二进制包解压就能用迁移也方便。以 Linux 为例下载和解压命令如下# 下载 GeoServer 2.23.2 二进制包 wget https://sourceforge.net/projects/geoserver/files/GeoServer/2.23.2/geoserver-2.23.2-bin.zip # 解压到 /opt 目录 unzip geoserver-2.23.2-bin.zip -d /opt/ # 进入目录并设置环境变量 cd /opt/geoserver-2.23.2 export JAVA_HOME/usr/lib/jvm/java-17-openjdk-amd64 export GEOSERVER_HOME/opt/geoserver-2.23.2这段命令里JAVA_HOME必须指向 JDK 17 的根目录不是bin目录。GEOSERVER_HOME是 GeoServer 自己的环境变量启动脚本会用它定位数据目录和配置文件。如果你不设GEOSERVER_HOME启动脚本会默认用当前目录一旦你从别的路径执行startup.sh就会找不到配置。Windows 下同理解压后编辑startup.bat在开头加上set JAVA_HOMEC:\Program Files\Java\jdk-17然后双击运行。注意路径里如果有空格不要加引号set命令会自己处理。2.3 启动前必须检查的三个配置项解压完别急着启动先改三个地方否则后面发布瓦片时一定会回来改。第一data_dir的位置。默认在 GeoServer 安装目录下的data_dir但生产环境我一般会挪到独立磁盘比如/data/geoserver_data。改法是编辑bin/startup.sh找到-DGEOSERVER_DATA_DIR参数把路径改掉。这样升级 GeoServer 时直接替换程序目录数据不受影响。第二端口号。默认 8080如果机器上已经有 Tomcat 或其他服务占了改成 8088 或别的。改etc/jetty.xml里的jetty.port值。第三内存分配。默认启动脚本给的是 512MB 初始堆发布大量瓦片时不够用。在startup.sh里找到-Xms和-Xmx我一般设成-Xms1024m -Xmx2048m具体看机器内存别超过物理内存的 70%。# 编辑 startup.sh 中的 JAVA_OPTS JAVA_OPTS-Xms1024m -Xmx2048m -DGEOSERVER_DATA_DIR/data/geoserver_data改完保存执行./bin/startup.sh看到日志里出现Started SelectChannelConnector0.0.0.0:8088就说明起来了。浏览器访问http://你的IP:8088/geoserver默认账号admin密码geoserver能进管理界面就算环境通了。3. 发布 ArcGIS 瓦片从数据准备到服务配置的完整链路3.1 ArcGIS 瓦片目录结构与 GeoServer 的对应关系ArcGIS 瓦片也叫切片缓存的目录结构是固定的根目录下是Layers文件夹里面按缩放级别分_alllayers/L00、L01这样的子目录每个级别下再按行列号分R0000C0000.png这样的文件。GeoServer 要发布这种瓦片不能直接指向Layers目录而是要用 GeoServer 的「GeoWebCache」模块来识别。我一般会先把瓦片目录整理成 GeoServer 能读的格式。假设你的瓦片在/data/tiles/mytiles里面是Layers/_alllayers/L00/R00000000C00000000.png这样的结构。GeoServer 需要你在「Tile Caches」里新建一个缓存然后指定这个目录作为「Tile Directory」。但这里有个关键点GeoServer 默认的瓦片网格集是 EPSG:900913也就是 Web Mercator而 ArcGIS 瓦片可能是 EPSG:4326 或别的。如果网格集对不上GeoServer 会找不到瓦片文件前端加载就是空白。所以第一步是确认你的瓦片切图时用的坐标系和网格集。常见做法是在 ArcGIS 里切瓦片时如果用的是「Google Maps」或「Bing Maps」的切片方案那就是 EPSG:900913GeoServer 里选EPSG:900913网格集即可。如果是自定义的需要在 GeoServer 里新建一个对应的网格集参数包括缩放级别、分辨率、瓦片尺寸。3.2 在 GeoServer 中新建瓦片缓存并挂载目录登录 GeoServer 管理界面左侧菜单找到「Tile Caches」点击「Create a new tile cache」。填写时注意几个参数Name随便起比如arcgis_tilesTile Directory填你的瓦片根目录比如/data/tiles/mytilesGridset选EPSG:900913或你自定义的Format选image/png或image/jpeg要和瓦片文件后缀一致Zoom Start / Stop填你的瓦片实际有的级别比如 0 到 18填完保存GeoServer 会去扫描目录。如果目录结构不对它会报「No tiles found」。这时候去日志里看一般会提示它期望的路径格式。我踩过的坑是ArcGIS 的_alllayers目录名必须完全一致大小写敏感少个下划线都不行。# 检查瓦片目录结构是否正确 ls /data/tiles/mytiles/Layers/_alllayers/ # 应该输出 L00 L01 L02 ... 这样的级别目录如果输出的是L0而不是L00那说明你的瓦片不是标准 ArcGIS 格式可能是别的工具切的。这种情况要么重新切要么在 GeoServer 里手动改目录名但改完要确保每个级别下的行列号也是 8 位补零格式。3.3 配置 GeoWebCache 的磁盘配额与缓存策略瓦片目录挂上后GeoServer 默认会把它当成「已缓存的瓦片」直接读但如果你后续要更新瓦片或者想控制磁盘占用就得配 GeoWebCache 的磁盘配额。在「Tile Caches」里找到你刚建的缓存点进去有个「Disk Quota」选项。我一般会设两个值Disk Quota设成 10GB 或根据磁盘剩余空间定Eviction Policy选Least Frequently Used。这样当缓存超过配额时GeoServer 会自动清理不常用的瓦片避免磁盘写满。另外如果你希望 GeoServer 在找不到瓦片时自动去后端地图服务取图并缓存那就要在「Tile Layers」里把图层和缓存关联起来。但注意如果你只有静态瓦片没有后端 WMS 服务那就不要开「Auto Cache」否则 GeoServer 会不断尝试请求一个不存在的服务日志里全是报错。注意静态瓦片发布时Tile Layers里的图层必须和缓存名称一致否则前端请求的 URL 会 404。我一般会在「Layer Preview」里先预览一下确认能出图再给前端。4. 避坑与排查发布 ArcGIS 瓦片时最常见的五个问题4.1 瓦片加载出来是空白或灰块现象前端请求瓦片 URL 返回 200但图片是空白或灰色。原因最常见的是网格集不匹配。GeoServer 按 EPSG:900913 的网格去算行列号但你的瓦片是按 EPSG:4326 切的行列号对不上GeoServer 找不到文件就返回一个空图片。解决确认切图时的坐标系在 GeoServer 里新建对应的网格集。如果不想重建可以用gdal2tiles重新切一份 Web Mercator 的瓦片。我一般会在切图前就统一用 EPSG:900913省得后面折腾。4.2 启动报错 UnsupportedClassVersionError现象执行startup.sh后闪退日志里写UnsupportedClassVersionError: geoserver/web/... has been compiled by a more recent version of the Java Runtime。原因GeoServer 版本和 Java 版本不匹配。比如 GeoServer 2.23 需要 Java 17但你机器上JAVA_HOME指向的是 Java 8。解决java -version确认当前版本然后改startup.sh里的JAVA_HOME指向正确的 JDK。如果机器上有多个 Java用update-alternatives --config java切换默认版本但更稳的是直接在启动脚本里写死路径。4.3 瓦片目录扫描不到文件现象在 Tile Caches 里填了目录保存后提示「No tiles found」但目录里明明有图片。原因ArcGIS 瓦片目录结构是Layers/_alllayers/L00/R00000000C00000000.png但 GeoServer 期望的可能是Layers/_alllayers/L00/R00000000C00000000.png这种格式差一个字符都不行。另外如果目录权限不对GeoServer 进程读不到也会报这个错。解决用ls -R看目录结构对比 GeoServer 日志里提示的期望路径。权限问题用chown -R geoserver:geoserver /data/tiles改一下确保运行 GeoServer 的用户有读权限。4.4 前端跨域请求被拦截现象浏览器控制台报CORS policy: No Access-Control-Allow-Origin header。原因GeoServer 默认没开 CORS前端从别的域名请求瓦片时被浏览器拦截。解决编辑webapps/geoserver/WEB-INF/web.xml找到cross-origin相关的 filter把allowedOrigins改成*或你的前端域名。改完重启 GeoServer。如果用的是 Jetty也可以在etc/jetty.xml里加 CORS 配置但改web.xml更通用。4.5 瓦片更新后前端还是旧图现象重新切了瓦片覆盖上去但前端加载的还是旧图。原因浏览器缓存或 GeoServer 的瓦片缓存没刷新。GeoServer 的 GeoWebCache 会缓存瓦片元数据即使文件变了它可能还读旧的。解决在 Tile Caches 里找到对应缓存点「Seed/Truncate」选「Truncate」清空缓存然后重新访问。如果只是浏览器缓存强制刷新CtrlF5或加个版本号参数。我一般会在瓦片 URL 后面加?t时间戳来绕过缓存。5. 装完怎么验证跑通三个必做的检查与一个习惯5.1 用 Layer Preview 做第一轮验证GeoServer 装完、瓦片发布完第一件事不是直接给前端而是用自带的「Layer Preview」看能不能出图。在左侧菜单点「Layer Preview」找到你发布的图层点「OpenLayers」预览。如果能看到地图说明 GeoServer 本身配置没问题。如果看不到按 F12 看网络请求哪个瓦片 404 或 500就去日志里找对应错误。这一步能过滤掉 80% 的配置问题比如网格集不对、目录权限不对、瓦片格式不对。我一般会在这个页面多缩放几级确认每个级别都能正常加载因为有些问题只在特定级别出现。5.2 用 curl 模拟前端请求瓦片Layer Preview 能出图不代表前端就能用。因为前端请求的 URL 可能和 GeoServer 内部用的不一样。我一般会用curl模拟一下# 模拟请求一个瓦片替换成你的实际 URL curl -I http://你的IP:8088/geoserver/gwc/service/tms/1.0.0/arcgis_tilesEPSG:900913png/0/0/0.png看返回的 HTTP 状态码。如果是 200且Content-Type是image/png说明瓦片能正常访问。如果是 404检查 URL 里的缓存名称、网格集、格式是否和 GeoServer 里配的一致。如果是 500去日志里看具体报错。这一步能发现 URL 拼写错误、缓存名称大小写不一致等问题。我踩过的坑是GeoServer 里缓存名是arcgis_tiles但前端写成了arcgis-tiles横线和下划线搞混了排查了半天。5.3 检查日志里的警告和错误GeoServer 的日志在logs/geoserver.log启动后如果有配置问题日志里会有WARN或ERROR。我一般会tail -f盯着日志然后在前端刷新页面看有没有新的报错。常见的警告包括「Could not find tile」「GridSet not found」「Permission denied」每个都对应一个具体的配置问题。如果日志里全是INFO没有报错但瓦片就是出不来那可能是前端的问题比如请求的 URL 路径不对或者跨域被拦截。这时候用浏览器的开发者工具看网络请求比看日志更直接。5.4 我养成的习惯每次改配置前先备份 data_dir从那以后我每次动 GeoServer 配置前都会先cp -r /data/geoserver_data /data/geoserver_data_bak。因为 GeoServer 的配置全在data_dir里改坏了直接回滚目录比重新配一遍快得多。这个习惯帮我省过至少三次通宵。另外发布瓦片时我会先用一个小范围的瓦片目录测试确认能跑通再挂全量避免一上来就扫几十万个文件把 GeoServer 卡死。希望帮到你。本文还有配套的精品资源点击获取
