如果你在GeoServer里已经把Image Mosaic JDBC跑通能正常发布、能出图那说明你已经掌握了它的用法但想真正把它用明白甚至针对自己的场景去调并发、改查询、扩属性过滤就必须把这一层捅破进到GeoTools源码里去看它到底怎么读数据库。这篇是GeoServer栅格影像Image Mosaic JDBC源码解析系列的第二篇。上一篇把GeoServer层的配置、发布、REST接口、索引表生成流程讲完了这一篇聚焦底层GeoTools的image-mosaic-jdbc模块里核心类有哪些索引查询是怎么下推到数据库的瓦片从BLOB里被捞出来之后又是靠什么逻辑拼接成一张完整影像的。适合已经会配Image Mosaic JDBC、但想知道底层原理的开发者以及准备对影像服务做二次开发或性能调优的人。读源码不是为了把每个类都背下来而是为了建立一张“出了问题能定位到哪个类、哪一行逻辑”的地图。看完这篇你会发现整个JDBC插件其实就三件事查索引、读BLOB、拼瓦片。1. 源码模块全景先画一张“类地图”再动手1.1 模块定位GeoTools为什么单独做一个JDBC变种在GeoTools的Maven仓库里这个模块的坐标是org.geotools:gt-imagemosaic-jdbc代码位于modules/plugin/imagery/image-mosaic-jdbc目录。它和普通gt-imagemosaic基于文件系统索引的ImageMosaic是并列关系而不是替代关系。普通ImageMosaic用properties文件记录每个影像文件的路径、范围和分辨率好处是零数据库依赖部署简单。但瓦片数量超过几十万甚至上百万时文件系统索引就开始吃力冷启动扫描慢、NFS锁竞争、并发查询时频繁IO。Image Mosaic JDBC把索引换成了数据库表借助数据库的B树索引、空间索引、连接池和事务能力把“查哪些瓦片”这一步从磁盘扫描变成了数据库查询。源码层面它是个典型的SPI插件。ImageMosaicJDBCFormat实现GridFormatFactorySpi接口GeoServer在初始化CoverageStore时会扫描META-INF/services下的注册信息找到这个格式工厂然后由它创建ImageMosaicJDBCReader。所以你在GeoServer里看到的那种“ImageMosaicJDBC”类型本质上就是对这个SPI的包装。为什么要独立成模块而不是直接改造现有ImageMosaic因为读取路径差异太大JDBC版要先连数据库、查元数据表、拼SQL、解码BLOB再把Tile对象交给拼接逻辑。如果把这些全部塞进image-mosaic核心模块会让文件索引代码变得极其臃肿而且文件版和数据库版的可扩展方向不同硬耦合起来谁都难受。SPI解耦之后新增一种数据库方言只需要增加一个Access子类核心读取逻辑完全不用动。1.2 核心类清单与阅读顺序先看谁、再看谁打开源码包org.geotools.gce.imagemosaic.jdbc核心类不多但职责边界非常清楚。我按阅读优先级整理了一张表层次核心类职责SPI接入ImageMosaicJDBCFormat格式注册与工厂入口解析source参数配置管理Config保存数据库URL、账号、密码、表名、元数据表名等状态管理ImageMosaicJDBCState持有Config与ImageMosaicJdbcAccess管理读取时状态数据访问ImageMosaicJdbcAccess抽象类定义查询Tile的接口与公共逻辑方言实现PostGisAccess、OracleAccess、MySqlAccess、SqlServerAccess不同数据库的SQL构造与BLOB读取实现读取控制ImageMosaicJDBCReader继承AbstractGridCoverage2DReader实现read()主流程导入工具Import命令行工具把磁盘瓦片目录导入数据库表建议的阅读顺序是Format → Config → State → Access → Reader。Format解决“这个store是怎么被识别的”Config解决“连接信息从哪来”State解决“一次读取周期里状态放哪”Access解决“数据库查询怎么做的”Reader最终把所有这些串起来。ImageMosaicJDBCReader继承自AbstractGridCoverage2DReader这一点很关键。父类已经帮你搞定了CRS解析、范围裁剪、输出图像尺寸计算、颜色模型处理这些通用逻辑子类只需要专注一件事把数据库里的瓦片读出来拼成一张GridCoverage2D返回。所以读这个类时重点看它覆盖了哪些方法、在哪里调用了Access层而不是从头逐行啃。2. 索引表与现代码查询SQL数据是怎么被“按需”取出来的2.1 表结构设计tileindex与tilemetadata各司其职Image Mosaic JDBC的索引不是一张表而是两张配合主表存瓦片二进制和空间范围元数据表存金字塔级别Level信息。以PostGIS为例导入工具生成的主表结构大致如下CREATE TABLE tileindex ( tile_id INTEGER PRIMARY KEY, blob BYTEA NOT NULL, minx DOUBLE PRECISION, miny DOUBLE PRECISION, maxx DOUBLE PRECISION, maxy DOUBLE PRECISION, resx DOUBLE PRECISION, resy DOUBLE PRECISION, geom GEOMETRY(POLYGON, 4326), sensor VARCHAR(32), aquire_date DATE ); CREATE INDEX idx_tileindex_geom ON tileindex USING GIST (geom);每列都不是白设计的。tile_id是主键用来在拼接阶段快速定位瓦片blob是JPEG或PNG编码后的瓦片字节流minx/miny/maxx/maxy是瓦片外接矩形resx/resy是像元分辨率geom是空间索引列负责加速范围查询后面还可以跟着业务属性列比如传感器名称、采集时间、云量等。为什么要同时保留minx...maxy和geom这不是冗余。某些数据库的空间函数开销较高或者遇到不支持空间扩展的驱动时可以退化为普通数值比较minx ? AND maxx ? AND miny ? AND maxy ?。GeoTools源码里对这种退化路径做了兼容让同一个模块能跑在“有空间扩展”和“无空间扩展”两种数据库环境上。元数据表tileindex_metadata则小得多通常记录每个Level的分辨率和瓦片尺寸CREATE TABLE tileindex_metadata ( level INTEGER, resolution DOUBLE PRECISION, tilewidth INTEGER, tileheight INTEGER );每次read()的时候ImageMosaicJDBCState会先查这张小表拿到当前可用的Level列表再根据请求分辨率去匹配。元数据表必须小因为它几乎每请求都要查一次主表不管多大查询时都靠空间索引和主键过滤不会全表扫。2.2 空间查询下推同一套逻辑四种数据库各说各话ImageMosaicJdbcAccess的职责是构造查询并返回Tile集合。源码里它不是一个一揽子实现而是把“方言差异”交给了子类override。同样一个空间相交查询四种数据库写法完全不一样-- PostGIS SELECT tile_id, blob FROM tileindex WHERE ST_Intersects(geom, ST_MakeEnvelope(?, ?, ?, ?, 4326)); -- Oracle Spatial SELECT tile_id, blob FROM tileindex WHERE SDO_RELATE(geom, SDO_GEOMETRY(2003, 4326, NULL, SDO_ELEM_INFO_ARRAY(1, 1003, 3), SDO_ORDINATE_ARRAY(?, ?, ?, ?)), maskANYINTERACT) TRUE; -- MySQL SELECT tile_id, blob FROM tileindex WHERE MBRIntersects(geom, GeomFromText(POLYGON((...)))); -- SQL Server SELECT tile_id, blob FROM tileindex WHERE geom.Filter(geometry::STGeomFromText(POLYGON((...)), 4326)) 1;为什么必须下推而不是把候选瓦片全捞回内存再用JTS做空间过滤数据量稍大就撑不住假设一个金字塔有20万瓦片全量查出所有tile_id和blob光网络传输就是灾难更别提内存。下推到数据库之后空间索引瞬间把候选集缩到几十个性能差了几个数量级。源码中的SQL不是直接拼字符串执行的而是用PreparedStatement加参数绑定。这不仅是防注入更重要的是利用数据库的SQL预编译缓存同一结构SQL反复执行时数据库不需要重复解析生成执行计划。这也是为什么你在源码里看到的一定是prepareStatement(sql)而不是createStatement()。如果你在请求里带了属性过滤条件比如“只要某天的影像”GeoTools会把Filter解析成SQL的AND条件附加到查询上。这个拼接逻辑同样在Access子类里不同数据库对日期、字符串的语法差异也由方言层负责。2.3 金字塔Level匹配分辨率不是越精细越好多分辨率金字塔是影像服务的标配。入库时同一块区域可以生成多个Level比如0级原始分辨率、1级二分之一、2级四分之一。为什么要有金字塔因为当请求范围很大但分辨率很低时直接读原始分辨率瓦片会产生大量冗余IO金字塔让小比例尺出图只读低级别瓦片。read()里对Level的匹配逻辑简单说就是“找那个分辨率与请求最接近、又不低于请求分辨率的Level”。伪代码大致是这样Level selected levels[0]; for (Level level : levels) { if (level.getResolution() requestResolution level.getResolution() selected.getResolution()) { selected level; } }如果你请求的分辨率是0.5米而库里只有1米和2米两个Level那选1米而不是2米因为1米更接近请求精度如果库里只有2米选2米是唯一的次优解。选错Level的后果很直观要么图片发糊要么请求量暴涨。源码里的这个匹配函数虽然短却是出图质量和性能的平衡点。3. 核心读取链路解析从read()到BufferedImage的完整拆解3.1 入口参数解析与覆盖范围切分ImageMosaicJDBCReader.read()是整个流程的发动机。入口收到一个GridCoverageRequest或者包装过的ParameterBlock里面包含目标范围、输出宽度高度、CRS、图像读取参数。拿到这些参数后第一步不是查数据库而是做两件事坐标变换和瓦片网格计算。坐标变换是因为前端请求的CRS可能跟存储瓦片的CRS不一致比如前端用Web Mercator库里是WGS84。GeoTools会用父类的机制做Envelope变换确保后续所有空间比较都在同一个坐标系里做否则SQL里的空间查询结果就是错的。瓦片网格计算则是把请求范围切成行列int nTilesX (int) Math.ceil(request.getWidth() / (double) level.getTileWidth()); int nTilesY (int) Math.ceil(request.getHeight() / (double) level.getTileHeight());这里算出来的是“理论上覆盖请求范围需要多少瓦片”。但实际要查哪些瓦片不是全查而是把请求的Envelope传给Access层由数据库空间索引再过滤一遍。网格计算负责“大概齐”空间查询负责“精确到瓦片”。3.2 获取TileJDBC查询与BLOB解码的节奏感ImageMosaicJdbcAccess.getTiles()是数据库交互的核心方法。它的实现节奏很像一个标准的DAO查询从连接池拿一个Connection根据请求Envelope和Level构造方言SQL用PreparedStatement绑定范围参数和属性参数执行executeQuery()遍历ResultSet对每一行从BLOB列读出字节解码成BufferedImage把范围和图像一起封装成Tile对象加入结果列表在finally里关闭ResultSet、Statement、Connection这里有个容易踩的坑不同数据库读BLOB的方式不同。PostgreSQL的bytea用getBytes()就能拿到完整字节数组Oracle的BLOB直接getBytes()可能拿不全或者性能很差源码里通常会用getBinaryStream()按流读取MySQL则要看驱动版本对setBytes和getBytes的兼容。这就是为什么BLOB读取逻辑要在方言子类里各自实现而不是放在公共的Access基类里一刀切。解码这一步用的是标准ImageIO。拿到字节数组后包一层ByteArrayInputStream再走ImageIO.read()生成BufferedImage。瓦片入库时如果是JPEG解码出来就是三通道RGB如果是PNG带透明通道解码后还可能带Alpha通道。后续拼接时颜色模型不一致会导致花屏所以在State初始化阶段源码会统一约定好瓦片编码格式避免混用。3.3 Mosaic拼接像素偏移与边界融合所有Tile回到Reader之后最后一步是拼接。目标画布已经在父类里初始化好了大小就是请求的输出宽高。拼接逻辑看起来简单把每张瓦片的图像按它在目标画布中的位置画上去。int dx (int) Math.round((tileEnvelope.getMinX() - requestEnvelope.getMinX()) / scaleX); int dy (int) Math.round((requestEnvelope.getMaxY() - tileEnvelope.getMaxY()) / scaleY); graphics.drawImage(tileImage, dx, dy, null);dx/dy就是把地理坐标变成画布像素坐标的偏移量。这里的方向要注意地理坐标Y轴向上画布坐标Y轴向下所以算dy时要用requestEnvelope.getMaxY() - tileEnvelope.getMaxY()写反了整张图会上下颠倒。拼接最烦人的是接缝问题。瓦片之间为了误差容错往往有2到3个像素的重叠如果直接硬画重叠区会因为色彩差异出现明显拼接缝。源码里对这个问题的处理思路是边界羽化在瓦片边缘做透明度渐变让相邻瓦片的过渡区平滑融合。如果你在自己的二开版本里发现拼缝明显优先检查羽化半径和重叠像素数是否匹配。4. 方言适配与连接管理四种数据库的实现差异4.1 Access层设计一个抽象基类背后的扩展逻辑ImageMosaicJdbcAccess的设计是理解这个模块扩展性的钥匙。基类里实现了公共流程拿连接、发请求、收ResultSet、封装Tile。而所有数据库特有的行为都拆成少量抽象方法让子类去填空差异点PostGISOracleMySQLSQL Server空间列类型GEOMETRYSDO_GEOMETRYGEOMETRYGEOMETRY空间函数ST_IntersectsSDO_RELATEMBRIntersectsgeom.FilterBLOB读取getBytesgetBinaryStreamgetBytesgetBytes分页/序列无特殊需要为tile_id建序列自增主键IDENTITY这样做的好处非常实际如果你要接入一个新的数据库比如某国产数据库不需要动Reader、State、Config只需要继承ImageMosaicJdbcAccess实现空间查询SQL构造和BLOB读取两个方法再改一下工厂类的数据库类型判断就够了。我曾经在一周内用这个方式接入了第二种PostGIS兼容库核心修改只有几十行。4.2 连接池与事务并发场景容易踩的两块石头源码里的连接管理不是每次新建而是使用连接池。常见实现是基于BasicDataSourceDBCP的配置核心参数包括初始连接数、最大连接数、最大等待时间。你在GeoServer里调并发相关参数时实际生效的就是这套连接池配置。连接池最经典的故障是连接泄漏。如果某个查询路径异常时没有关闭连接池里的连接会被逐渐耗尽最终所有请求卡在getConnection()上直到超时。表现症状很迷惑WMS请求时好时坏过一段时间全部假死重启GeoServer后又恢复。排查手段是在源码的getTiles方法里确认finally块是否关闭了Connection和Statement或者直接开启DBCP的日志跟踪。事务方面影像读取是典型的只读场景。源码里默认是读已提交隔离级别并且尽量让连接处于readOnly模式。这样做的意义不仅是语义正确某些数据库在只读模式下会启用更激进的执行计划缓存和IO优化。另一方面如果两次查询先查metadata再查tileindex要保证一致性会在一段事务内完成但事务时间越长连接池的压力越大所以源码里对事务边界控制得很收敛不会把整个read()包在一个大事务里。5. 线上问题排查源码级定位方法与速查表5.1 高频故障与源码定位点做源码解析如果不落到排障上价值就少了一半。我在实际项目里整理了下面这套问题速查表每一行都对应一个可定位的源码位置问题症状可能原因源码定位点处理建议创建Store时报“No suitable reader”SPI注册失败或jar冲突ImageMosaicJDBCFormat的registration检查META-INF/services是否被多个jar覆盖清理旧版本依赖能发布但出图全白/全黑SQL空间函数查出空集Access子类的buildSQL用数据库客户端手动执行同一条SQL检查SRID是否一致拼接处有明显的缝或错位Level匹配错误或瓦片原点不一致State里的Level匹配逻辑检查metadata表的分辨率记录确认请求分辨率落到正确Level请求越来越慢直到卡死连接池耗尽或慢查询getTiles的finally块、数据库EXPLAIN增加连接池上限确认空间索引存在关闭无过滤全表扫描高分辨率请求内存溢出一次读取瓦片数量过大read里的网格切分限制请求最大尺寸启用金字塔低Level必要时设置fetchSize“能发布但出图空白”是我见过最多的坑。表面看是“图层没数据”实际上十有八九是空间查询条件根本没匹配到任何瓦片。最常见的原因是两个一是geom列的SRID跟查询Envelope的SRID不一致数据库做了隐式坐标解释但结果为空二是列名大小写问题比如Oracle里表结构默认大写而配置里写的是全小写SQL一执行就报列名无效被异常吞掉后返回空图。5.2 三个值得打断点的源码位置如果要在IDE里跑源码调试我建议在这三个位置打断点第一个是ImageMosaicJdbcAccess子类的getTiles()。这里能看到实际生成的SQL和绑定参数所有“为什么查不到”的问题在这个断点面前都会现原形。第二个是ImageMosaicJDBCState里初始化Level列表的地方分辨率记录有误时能第一时间发现。第三个是ImageMosaicJDBCReader.read()的入口确认GeoServer传进来的Envelope、宽度、高度是不是你以为的值。打断点不一定非要在源码工程里。如果你不方便编译整个GeoTools也可以在数据库端开log_statement直接看每条到达数据库的SQL是什么。效果差不多但更轻量适合排查线上环境。读源码这件事最有意思的不是把每个类都背下来而是找到那两三个决定行为的关键分支。Image Mosaic JDBC整个模块源码量不大但设计上把“查索引”和“拼影像”分得很清楚。我在实际项目中最常翻的三个位置就是Access子类的SQL构造、State里面的Level匹配、Reader的read入口。把这三处看懂遇到九成问题都能迅速判断是数据库层面的问题还是拼接层面的问题。后面如果你要自己扩展属性过滤或者接入新的数据库照着Access层增加一个子类就行。
如果你在GeoServer里已经把Image Mosaic JDBC跑通能正常发布、能出图那说明你已经掌握了它的用法但想真正把它用明白甚至针对自己的场景去调并发、改查询、扩属性过滤就必须把这一层捅破进到GeoTools源码里去看它到底怎么读数据库。这篇是GeoServer栅格影像Image Mosaic JDBC源码解析系列的第二篇。上一篇把GeoServer层的配置、发布、REST接口、索引表生成流程讲完了这一篇聚焦底层GeoTools的image-mosaic-jdbc模块里核心类有哪些索引查询是怎么下推到数据库的瓦片从BLOB里被捞出来之后又是靠什么逻辑拼接成一张完整影像的。适合已经会配Image Mosaic JDBC、但想知道底层原理的开发者以及准备对影像服务做二次开发或性能调优的人。读源码不是为了把每个类都背下来而是为了建立一张“出了问题能定位到哪个类、哪一行逻辑”的地图。看完这篇你会发现整个JDBC插件其实就三件事查索引、读BLOB、拼瓦片。1. 源码模块全景先画一张“类地图”再动手1.1 模块定位GeoTools为什么单独做一个JDBC变种在GeoTools的Maven仓库里这个模块的坐标是org.geotools:gt-imagemosaic-jdbc代码位于modules/plugin/imagery/image-mosaic-jdbc目录。它和普通gt-imagemosaic基于文件系统索引的ImageMosaic是并列关系而不是替代关系。普通ImageMosaic用properties文件记录每个影像文件的路径、范围和分辨率好处是零数据库依赖部署简单。但瓦片数量超过几十万甚至上百万时文件系统索引就开始吃力冷启动扫描慢、NFS锁竞争、并发查询时频繁IO。Image Mosaic JDBC把索引换成了数据库表借助数据库的B树索引、空间索引、连接池和事务能力把“查哪些瓦片”这一步从磁盘扫描变成了数据库查询。源码层面它是个典型的SPI插件。ImageMosaicJDBCFormat实现GridFormatFactorySpi接口GeoServer在初始化CoverageStore时会扫描META-INF/services下的注册信息找到这个格式工厂然后由它创建ImageMosaicJDBCReader。所以你在GeoServer里看到的那种“ImageMosaicJDBC”类型本质上就是对这个SPI的包装。为什么要独立成模块而不是直接改造现有ImageMosaic因为读取路径差异太大JDBC版要先连数据库、查元数据表、拼SQL、解码BLOB再把Tile对象交给拼接逻辑。如果把这些全部塞进image-mosaic核心模块会让文件索引代码变得极其臃肿而且文件版和数据库版的可扩展方向不同硬耦合起来谁都难受。SPI解耦之后新增一种数据库方言只需要增加一个Access子类核心读取逻辑完全不用动。1.2 核心类清单与阅读顺序先看谁、再看谁打开源码包org.geotools.gce.imagemosaic.jdbc核心类不多但职责边界非常清楚。我按阅读优先级整理了一张表层次核心类职责SPI接入ImageMosaicJDBCFormat格式注册与工厂入口解析source参数配置管理Config保存数据库URL、账号、密码、表名、元数据表名等状态管理ImageMosaicJDBCState持有Config与ImageMosaicJdbcAccess管理读取时状态数据访问ImageMosaicJdbcAccess抽象类定义查询Tile的接口与公共逻辑方言实现PostGisAccess、OracleAccess、MySqlAccess、SqlServerAccess不同数据库的SQL构造与BLOB读取实现读取控制ImageMosaicJDBCReader继承AbstractGridCoverage2DReader实现read()主流程导入工具Import命令行工具把磁盘瓦片目录导入数据库表建议的阅读顺序是Format → Config → State → Access → Reader。Format解决“这个store是怎么被识别的”Config解决“连接信息从哪来”State解决“一次读取周期里状态放哪”Access解决“数据库查询怎么做的”Reader最终把所有这些串起来。ImageMosaicJDBCReader继承自AbstractGridCoverage2DReader这一点很关键。父类已经帮你搞定了CRS解析、范围裁剪、输出图像尺寸计算、颜色模型处理这些通用逻辑子类只需要专注一件事把数据库里的瓦片读出来拼成一张GridCoverage2D返回。所以读这个类时重点看它覆盖了哪些方法、在哪里调用了Access层而不是从头逐行啃。2. 索引表与现代码查询SQL数据是怎么被“按需”取出来的2.1 表结构设计tileindex与tilemetadata各司其职Image Mosaic JDBC的索引不是一张表而是两张配合主表存瓦片二进制和空间范围元数据表存金字塔级别Level信息。以PostGIS为例导入工具生成的主表结构大致如下CREATE TABLE tileindex ( tile_id INTEGER PRIMARY KEY, blob BYTEA NOT NULL, minx DOUBLE PRECISION, miny DOUBLE PRECISION, maxx DOUBLE PRECISION, maxy DOUBLE PRECISION, resx DOUBLE PRECISION, resy DOUBLE PRECISION, geom GEOMETRY(POLYGON, 4326), sensor VARCHAR(32), aquire_date DATE ); CREATE INDEX idx_tileindex_geom ON tileindex USING GIST (geom);每列都不是白设计的。tile_id是主键用来在拼接阶段快速定位瓦片blob是JPEG或PNG编码后的瓦片字节流minx/miny/maxx/maxy是瓦片外接矩形resx/resy是像元分辨率geom是空间索引列负责加速范围查询后面还可以跟着业务属性列比如传感器名称、采集时间、云量等。为什么要同时保留minx...maxy和geom这不是冗余。某些数据库的空间函数开销较高或者遇到不支持空间扩展的驱动时可以退化为普通数值比较minx ? AND maxx ? AND miny ? AND maxy ?。GeoTools源码里对这种退化路径做了兼容让同一个模块能跑在“有空间扩展”和“无空间扩展”两种数据库环境上。元数据表tileindex_metadata则小得多通常记录每个Level的分辨率和瓦片尺寸CREATE TABLE tileindex_metadata ( level INTEGER, resolution DOUBLE PRECISION, tilewidth INTEGER, tileheight INTEGER );每次read()的时候ImageMosaicJDBCState会先查这张小表拿到当前可用的Level列表再根据请求分辨率去匹配。元数据表必须小因为它几乎每请求都要查一次主表不管多大查询时都靠空间索引和主键过滤不会全表扫。2.2 空间查询下推同一套逻辑四种数据库各说各话ImageMosaicJdbcAccess的职责是构造查询并返回Tile集合。源码里它不是一个一揽子实现而是把“方言差异”交给了子类override。同样一个空间相交查询四种数据库写法完全不一样-- PostGIS SELECT tile_id, blob FROM tileindex WHERE ST_Intersects(geom, ST_MakeEnvelope(?, ?, ?, ?, 4326)); -- Oracle Spatial SELECT tile_id, blob FROM tileindex WHERE SDO_RELATE(geom, SDO_GEOMETRY(2003, 4326, NULL, SDO_ELEM_INFO_ARRAY(1, 1003, 3), SDO_ORDINATE_ARRAY(?, ?, ?, ?)), maskANYINTERACT) TRUE; -- MySQL SELECT tile_id, blob FROM tileindex WHERE MBRIntersects(geom, GeomFromText(POLYGON((...)))); -- SQL Server SELECT tile_id, blob FROM tileindex WHERE geom.Filter(geometry::STGeomFromText(POLYGON((...)), 4326)) 1;为什么必须下推而不是把候选瓦片全捞回内存再用JTS做空间过滤数据量稍大就撑不住假设一个金字塔有20万瓦片全量查出所有tile_id和blob光网络传输就是灾难更别提内存。下推到数据库之后空间索引瞬间把候选集缩到几十个性能差了几个数量级。源码中的SQL不是直接拼字符串执行的而是用PreparedStatement加参数绑定。这不仅是防注入更重要的是利用数据库的SQL预编译缓存同一结构SQL反复执行时数据库不需要重复解析生成执行计划。这也是为什么你在源码里看到的一定是prepareStatement(sql)而不是createStatement()。如果你在请求里带了属性过滤条件比如“只要某天的影像”GeoTools会把Filter解析成SQL的AND条件附加到查询上。这个拼接逻辑同样在Access子类里不同数据库对日期、字符串的语法差异也由方言层负责。2.3 金字塔Level匹配分辨率不是越精细越好多分辨率金字塔是影像服务的标配。入库时同一块区域可以生成多个Level比如0级原始分辨率、1级二分之一、2级四分之一。为什么要有金字塔因为当请求范围很大但分辨率很低时直接读原始分辨率瓦片会产生大量冗余IO金字塔让小比例尺出图只读低级别瓦片。read()里对Level的匹配逻辑简单说就是“找那个分辨率与请求最接近、又不低于请求分辨率的Level”。伪代码大致是这样Level selected levels[0]; for (Level level : levels) { if (level.getResolution() requestResolution level.getResolution() selected.getResolution()) { selected level; } }如果你请求的分辨率是0.5米而库里只有1米和2米两个Level那选1米而不是2米因为1米更接近请求精度如果库里只有2米选2米是唯一的次优解。选错Level的后果很直观要么图片发糊要么请求量暴涨。源码里的这个匹配函数虽然短却是出图质量和性能的平衡点。3. 核心读取链路解析从read()到BufferedImage的完整拆解3.1 入口参数解析与覆盖范围切分ImageMosaicJDBCReader.read()是整个流程的发动机。入口收到一个GridCoverageRequest或者包装过的ParameterBlock里面包含目标范围、输出宽度高度、CRS、图像读取参数。拿到这些参数后第一步不是查数据库而是做两件事坐标变换和瓦片网格计算。坐标变换是因为前端请求的CRS可能跟存储瓦片的CRS不一致比如前端用Web Mercator库里是WGS84。GeoTools会用父类的机制做Envelope变换确保后续所有空间比较都在同一个坐标系里做否则SQL里的空间查询结果就是错的。瓦片网格计算则是把请求范围切成行列int nTilesX (int) Math.ceil(request.getWidth() / (double) level.getTileWidth()); int nTilesY (int) Math.ceil(request.getHeight() / (double) level.getTileHeight());这里算出来的是“理论上覆盖请求范围需要多少瓦片”。但实际要查哪些瓦片不是全查而是把请求的Envelope传给Access层由数据库空间索引再过滤一遍。网格计算负责“大概齐”空间查询负责“精确到瓦片”。3.2 获取TileJDBC查询与BLOB解码的节奏感ImageMosaicJdbcAccess.getTiles()是数据库交互的核心方法。它的实现节奏很像一个标准的DAO查询从连接池拿一个Connection根据请求Envelope和Level构造方言SQL用PreparedStatement绑定范围参数和属性参数执行executeQuery()遍历ResultSet对每一行从BLOB列读出字节解码成BufferedImage把范围和图像一起封装成Tile对象加入结果列表在finally里关闭ResultSet、Statement、Connection这里有个容易踩的坑不同数据库读BLOB的方式不同。PostgreSQL的bytea用getBytes()就能拿到完整字节数组Oracle的BLOB直接getBytes()可能拿不全或者性能很差源码里通常会用getBinaryStream()按流读取MySQL则要看驱动版本对setBytes和getBytes的兼容。这就是为什么BLOB读取逻辑要在方言子类里各自实现而不是放在公共的Access基类里一刀切。解码这一步用的是标准ImageIO。拿到字节数组后包一层ByteArrayInputStream再走ImageIO.read()生成BufferedImage。瓦片入库时如果是JPEG解码出来就是三通道RGB如果是PNG带透明通道解码后还可能带Alpha通道。后续拼接时颜色模型不一致会导致花屏所以在State初始化阶段源码会统一约定好瓦片编码格式避免混用。3.3 Mosaic拼接像素偏移与边界融合所有Tile回到Reader之后最后一步是拼接。目标画布已经在父类里初始化好了大小就是请求的输出宽高。拼接逻辑看起来简单把每张瓦片的图像按它在目标画布中的位置画上去。int dx (int) Math.round((tileEnvelope.getMinX() - requestEnvelope.getMinX()) / scaleX); int dy (int) Math.round((requestEnvelope.getMaxY() - tileEnvelope.getMaxY()) / scaleY); graphics.drawImage(tileImage, dx, dy, null);dx/dy就是把地理坐标变成画布像素坐标的偏移量。这里的方向要注意地理坐标Y轴向上画布坐标Y轴向下所以算dy时要用requestEnvelope.getMaxY() - tileEnvelope.getMaxY()写反了整张图会上下颠倒。拼接最烦人的是接缝问题。瓦片之间为了误差容错往往有2到3个像素的重叠如果直接硬画重叠区会因为色彩差异出现明显拼接缝。源码里对这个问题的处理思路是边界羽化在瓦片边缘做透明度渐变让相邻瓦片的过渡区平滑融合。如果你在自己的二开版本里发现拼缝明显优先检查羽化半径和重叠像素数是否匹配。4. 方言适配与连接管理四种数据库的实现差异4.1 Access层设计一个抽象基类背后的扩展逻辑ImageMosaicJdbcAccess的设计是理解这个模块扩展性的钥匙。基类里实现了公共流程拿连接、发请求、收ResultSet、封装Tile。而所有数据库特有的行为都拆成少量抽象方法让子类去填空差异点PostGISOracleMySQLSQL Server空间列类型GEOMETRYSDO_GEOMETRYGEOMETRYGEOMETRY空间函数ST_IntersectsSDO_RELATEMBRIntersectsgeom.FilterBLOB读取getBytesgetBinaryStreamgetBytesgetBytes分页/序列无特殊需要为tile_id建序列自增主键IDENTITY这样做的好处非常实际如果你要接入一个新的数据库比如某国产数据库不需要动Reader、State、Config只需要继承ImageMosaicJdbcAccess实现空间查询SQL构造和BLOB读取两个方法再改一下工厂类的数据库类型判断就够了。我曾经在一周内用这个方式接入了第二种PostGIS兼容库核心修改只有几十行。4.2 连接池与事务并发场景容易踩的两块石头源码里的连接管理不是每次新建而是使用连接池。常见实现是基于BasicDataSourceDBCP的配置核心参数包括初始连接数、最大连接数、最大等待时间。你在GeoServer里调并发相关参数时实际生效的就是这套连接池配置。连接池最经典的故障是连接泄漏。如果某个查询路径异常时没有关闭连接池里的连接会被逐渐耗尽最终所有请求卡在getConnection()上直到超时。表现症状很迷惑WMS请求时好时坏过一段时间全部假死重启GeoServer后又恢复。排查手段是在源码的getTiles方法里确认finally块是否关闭了Connection和Statement或者直接开启DBCP的日志跟踪。事务方面影像读取是典型的只读场景。源码里默认是读已提交隔离级别并且尽量让连接处于readOnly模式。这样做的意义不仅是语义正确某些数据库在只读模式下会启用更激进的执行计划缓存和IO优化。另一方面如果两次查询先查metadata再查tileindex要保证一致性会在一段事务内完成但事务时间越长连接池的压力越大所以源码里对事务边界控制得很收敛不会把整个read()包在一个大事务里。5. 线上问题排查源码级定位方法与速查表5.1 高频故障与源码定位点做源码解析如果不落到排障上价值就少了一半。我在实际项目里整理了下面这套问题速查表每一行都对应一个可定位的源码位置问题症状可能原因源码定位点处理建议创建Store时报“No suitable reader”SPI注册失败或jar冲突ImageMosaicJDBCFormat的registration检查META-INF/services是否被多个jar覆盖清理旧版本依赖能发布但出图全白/全黑SQL空间函数查出空集Access子类的buildSQL用数据库客户端手动执行同一条SQL检查SRID是否一致拼接处有明显的缝或错位Level匹配错误或瓦片原点不一致State里的Level匹配逻辑检查metadata表的分辨率记录确认请求分辨率落到正确Level请求越来越慢直到卡死连接池耗尽或慢查询getTiles的finally块、数据库EXPLAIN增加连接池上限确认空间索引存在关闭无过滤全表扫描高分辨率请求内存溢出一次读取瓦片数量过大read里的网格切分限制请求最大尺寸启用金字塔低Level必要时设置fetchSize“能发布但出图空白”是我见过最多的坑。表面看是“图层没数据”实际上十有八九是空间查询条件根本没匹配到任何瓦片。最常见的原因是两个一是geom列的SRID跟查询Envelope的SRID不一致数据库做了隐式坐标解释但结果为空二是列名大小写问题比如Oracle里表结构默认大写而配置里写的是全小写SQL一执行就报列名无效被异常吞掉后返回空图。5.2 三个值得打断点的源码位置如果要在IDE里跑源码调试我建议在这三个位置打断点第一个是ImageMosaicJdbcAccess子类的getTiles()。这里能看到实际生成的SQL和绑定参数所有“为什么查不到”的问题在这个断点面前都会现原形。第二个是ImageMosaicJDBCState里初始化Level列表的地方分辨率记录有误时能第一时间发现。第三个是ImageMosaicJDBCReader.read()的入口确认GeoServer传进来的Envelope、宽度、高度是不是你以为的值。打断点不一定非要在源码工程里。如果你不方便编译整个GeoTools也可以在数据库端开log_statement直接看每条到达数据库的SQL是什么。效果差不多但更轻量适合排查线上环境。读源码这件事最有意思的不是把每个类都背下来而是找到那两三个决定行为的关键分支。Image Mosaic JDBC整个模块源码量不大但设计上把“查索引”和“拼影像”分得很清楚。我在实际项目中最常翻的三个位置就是Access子类的SQL构造、State里面的Level匹配、Reader的read入口。把这三处看懂遇到九成问题都能迅速判断是数据库层面的问题还是拼接层面的问题。后面如果你要自己扩展属性过滤或者接入新的数据库照着Access层增加一个子类就行。
