GeoServer 插件安装与常用扩展推荐

wowwwai GIS研习社 · 工具流程与项目排障

GeoServer 插件（正式扩展）的安装核心很简单：先确认当前精确版本，下载匹配的扩展 ZIP，停止服务后把解压出的全部 JAR 直接放进 WEB-INF/lib，再重启即可生效。截至 2026 年 11 月，生产环境推荐使用 Stable 版 3.0.2 或 Maintenance 版 2.28.6；常用且下载量高的扩展包括 WPS、CSS/YSLD 样式、Vector Tiles、Control Flow、Importer、Monitor 等。安装成功后可在 Web Admin 的 About & Status → Modules 列表中看到新模块，或直接测试对应功能。社区模块仅随 Nightly 提供，版本易不匹配，不建议用于生产。

如何按官方标准安装 GeoServer 插件

几乎所有正式扩展都走同一套流程。版本必须完全一致，否则容易出现 ClassNotFoundException 或功能不出现。

1. 登录 GeoServer Web Admin，打开 About & Status → About GeoServer，记下 Build Information 里的精确版本号（例如 3.0.2）。
2. 前往 geoserver.org/download，进入对应版本的 release 页面，在 Extensions 区域下载需要的 ZIP（文件名类似 geoserver-3.0.2-wps-plugin.zip）。
3. 停止 GeoServer（Tomcat/Jetty 服务或 Docker 容器）。
4. 解压 ZIP，把里面所有 .jar 文件直接复制到安装目录的 WEB-INF/lib 下（不要建子目录）。二进制安装常见路径为 <GEOSERVER_ROOT>/webapps/geoserver/WEB-INF/lib；Tomcat 则为 <CATALINA_BASE>/webapps/geoserver/WEB-INF/lib。
5. 重启 GeoServer。
6. 验收：回到 About & Status → Modules 确认新模块已加载；或检查具体功能（Styles 出现 CSS/YSLD 选项、Stores 出现新数据源、Services 出现 WPS 等）。同时查看日志排查错误。

卸载时只需删除对应 JAR 并重启。部分扩展有额外要求：GDAL 需要系统先装好匹配的原生库；Printing 首次启动会在数据目录生成 printing/config.yaml。

当前推荐版本与扩展分类

选择版本时优先看稳定性与容器兼容性。3.0 系列数据目录格式仍兼容 2.28.x，但部分原核心模块（如 WCS 1.0/1.1、WorldImage、ArcGRID、KML）已移到扩展，H2 已移除，OIDC 成为正式扩展。

系列	版本	发布日期	Java 要求	主要容器
Stable（生产首选）	3.0.2	2026-10-19	17 / 21	Tomcat 11.0.x / Jetty 12.1
Maintenance	2.28.6	2026-10-19	17 / 21	Tomcat 9.x / Jetty 9.4

正式扩展按功能大致分为：矢量格式（Oracle、SQL Server、MongoDB、App Schema 等）、栅格/Coverage（GDAL、Image Pyramid 等图像扩展、NetCDF、GRIB）、制图样式（CSS、YSLD、MBStyle、Chart）、输出格式（Vector Tiles、GeoPkg、DXF、KML）、OGC 服务（WPS、CSW、WCS 1.0/1.1）、安全（OIDC、GeoFence、Key authentication）以及杂项（Control Flow、Importer、Monitor、INSPIRE、GWC S3）。完整列表以各版本 release 页面的 Extensions 为准。

常用扩展推荐与典型用途

结合社区下载热度与实际 GIS 项目需求，优先安装下面这些（名称以 Stable 扩展为准，版本匹配你的 GeoServer）：

• WPS：OGC 地理处理服务，可在服务器端跑几何运算、栅格分析、矢量处理，安装后 Services 下出现 WPS。
• CSS Styling / YSLD Styling：用类似 CSS 或 YAML 的语法写样式，比纯 SLD 好维护，支持嵌套与级联。YSLD 细节可参考官方 YSLD 扩展说明。
• Vector Tiles：输出 Mapbox Vector Tile / GeoJSON / TopoJSON，方便前端瓦片缓存与高性能渲染。
• Control Flow：请求限流与优先级控制，防止并发过高拖垮服务。
• Importer：批量导入数据并自动创建图层/样式的向导，适合数据入库流程。
• Monitor：请求监控与审计，方便排查性能与安全问题。
• CSW / INSPIRE：元数据目录服务与欧洲 INSPIRE 指令扩展，做规范发布时常用。
• GDAL / Image Pyramid / Printing / GeoPkg：分别解决多格式栅格、大影像金字塔、PDF 打印、GeoPackage 输出。

数据库连接类（Oracle、SQL Server、MySQL）和安全类（OIDC、GeoFence）按实际环境按需安装即可。Docker 官方镜像常见默认示例也包含 wps、css、ysld、vectortiles、control-flow、printing、pyramid 等。

Docker 环境一键安装扩展

官方镜像（docker.osgeo.org/geoserver:版本）支持环境变量自动下载并安装正式扩展，无需手动拷 JAR。

1. 启动时加 INSTALL_EXTENSIONS=true。
2. 用 STABLE_EXTENSIONS 指定逗号分隔的扩展短名，例如 wps,ysld,css,vectortiles,control-flow,printing。
3. 社区模块用 COMMUNITY_EXTENSIONS（仅测试）。
4. 也可把本地 JAR 目录挂载进容器覆盖。

示例命令：

docker run -it -p 8080:8080 –env INSTALL_EXTENSIONS=true –env STABLE_EXTENSIONS=”wps,ysld,css” docker.osgeo.org/geoserver:3.0.2

启动后同样到 Modules 列表验收。若自动下载失败，可手动下载匹配 ZIP 后挂载，或检查 build.geoserver.org 可用性。

安装注意事项与环境要求

• Java 最低 17（推荐 OpenJDK LTS 17 或 21）；3.x 需要 Jakarta EE 容器（Tomcat 11 / Jetty 12.1），2.28.x 主要用 Tomcat 9 / Jetty 9.4。
• 数据目录务必放在 webapp 外部，升级前完整备份；部分扩展会写额外配置文件（如 Printing 的 config.yaml，可用 GEOSERVER_PRINT_CONFIG_DIR 指定）。
• GDAL 扩展必须系统安装匹配版本的原生库，并正确设置 java.library.path，否则会报 UnsatisfiedLinkError。
• WPS 进程数量受 WFS feature limit 影响；集群环境做 WPS 时注意共享存储。
• 升级时先备份，再重新下载并安装所有旧扩展的新版本匹配包；3.x 尤其注意容器与部分模块位置变化。

常见问题

扩展版本和 GeoServer 不一致会怎样？

会出现 ClassNotFound、NoSuchMethodError，或 Modules 里根本看不到新模块。务必用 About 页面显示的精确版本去下载对应 ZIP，社区模块不要硬套正式版。

JAR 放进去重启后功能还是没有？

检查 JAR 是否直接在 WEB-INF/lib 根目录（没有子文件夹）、服务是否真正重启、日志有无报错，再到 Modules 列表确认。Docker 环境则核对环境变量拼写与扩展短名是否正确。

GDAL 扩展报 UnsatisfiedLinkError 怎么办？

系统缺少匹配的原生 GDAL 库或 bindings 版本不对。先安装系统 GDAL，保证 Java bindings JAR 与之对应，并设置好 java.library.path 后重启。

社区模块可以直接用在生产吗？

不推荐。社区模块只随 Nightly 发布，与正式版版本常不匹配，稳定性与安全无保障。生产只用 SourceForge 上与版本精确对应的正式扩展。

安装 GeoServer 插件时，永远以“版本精确匹配 + JAR 直接进 lib + 重启后 Modules 验证”为验收标准；优先装 WPS、CSS/YSLD、Vector Tiles、Control Flow 这类高频扩展即可覆盖大部分 GIS 发布与处理需求。建议先在测试环境用 3.0.2 或 2.28.6 跑通一套完整流程，再同步到生产，并定期备份数据目录。