项目地址: https://github.com/geoserver/geoserver
REST API 文档: https://docs.geoserver.org/latest/en/user/rest/index.html
API 参考: https://docs.geoserver.org/stable/en/user/rest/api/index.html
最新版本: GeoServer 3.0.2(2026-10-17 发布,安全修复版;官方下载)
许可证: GPL-2.0
概述
GeoServer 是一个基于 Java 的开源地理空间数据服务器,实现了 OGC WMS、WFS、WCS、WMTS 等标准协议。GeoServer REST API 提供了完整的 RESTful 配置管理接口,可通过标准 HTTP 方法(GET / POST / PUT / DELETE)对 GeoServer 的各类资源进行编程式管理。
REST API 的典型用途包括:
- 自动化部署:批量创建工作空间、数据存储、发布图层
- CI/CD 集成:在持续集成流水线中自动配置 GeoServer
- AI 智能体:通过 HTTP 接口让 AI 自主管理地图服务
- 运维脚本:批量修改样式、更新数据源连接参数
基础 URL 格式: http://{host}:{port}/geoserver/rest
默认认证: 用户名 admin,密码 geoserver(HTTP Basic Auth)
数据格式: 支持 JSON 和 XML,通过 Accept / Content-Type 请求头或 URL 后缀(.json / .xml)指定。
环境准备与认证方式
所有写操作(POST / PUT / DELETE)均需认证。GeoServer 默认使用 HTTP Basic Auth:
推荐用 -u,curl 自动生成 Basic 头;需要显式传头时用下面的等价写法(YWRtaW46Z2Vvc2VydmVy 是 admin:geoserver 的 base64):
# 方式 1:curl -u(推荐)
curl -u admin:geoserver http://localhost:8080/geoserver/rest/about/version.json
# 方式 2:显式 Authorization 头
curl -H "Authorization: Basic YWRtaW46Z2Vvc2VydmVy" \
http://localhost:8080/geoserver/rest/about/version.json
凭据务必用环境变量传入(
curl -u "$GS_USER:$GS_PASS"),不要写进脚本或提交到仓库。
API 端点一览
REST API 按资源分组,完整端点清单见 reference/endpoints.md:
| 资源组 | 基础路径 | 资源组 | 基础路径 |
|---|---|---|---|
| 系统管理 | /rest/about/*、/rest/reload、/rest/reset |
图层 | /rest/layers |
| 工作空间 | /rest/workspaces |
图层组 | /rest/layergroups |
| 命名空间 | /rest/namespaces |
样式 | /rest/styles |
| 数据存储 | /rest/workspaces/{ws}/datastores |
OGC 服务设置 | /rest/services/{wms|wfs|wcs|wmts}/settings |
| 要素类型 | .../datastores/{ds}/featuretypes |
安全 | /rest/security/* |
| 覆盖存储 / 覆盖 | /rest/workspaces/{ws}/coveragestores |
GeoWebCache | /gwc/rest/* |
常用操作示例
1. 获取 GeoServer 版本
curl -u admin:geoserver \
"http://localhost:8080/geoserver/rest/about/version.json"
2. 创建工作空间
curl -u admin:geoserver -XPOST \
-H "Content-Type: application/json" \
-d '{"workspace":{"name":"myws"}}' \
"http://localhost:8080/geoserver/rest/workspaces"
3. 创建 PostGIS 数据存储
curl -u admin:geoserver -XPOST \
-H "Content-Type: application/json" \
-d '{
"dataStore": {
"name": "pgstore",
"connectionParameters": {
"entry": [
{"@key": "host", "$": "localhost"},
{"@key": "port", "$": "5432"},
{"@key": "database", "$": "geodata"},
{"@key": "user", "$": "postgres"},
{"@key": "passwd", "$": "postgres"},
{"@key": "dbtype", "$": "postgis"},
{"@key": "schema", "$": "public"}
]
}
}
}' \
"http://localhost:8080/geoserver/rest/workspaces/myws/datastores"
4. 上传 Shapefile 并自动发布图层
curl -u admin:geoserver -XPUT \
-H "Content-Type: application/zip" \
--data-binary @roads.zip \
"http://localhost:8080/geoserver/rest/workspaces/myws/datastores/roads/file.shp"
上传后自动创建同名数据存储和图层。Shapefile 需打包为 ZIP(包含 .shp、.shx、.dbf、.prj 文件)。
5. 发布 PostGIS 表为要素类型
curl -u admin:geoserver -XPOST \
-H "Content-Type: application/json" \
-d '{"featureType":{"name":"buildings","nativeName":"buildings"}}' \
"http://localhost:8080/geoserver/rest/workspaces/myws/datastores/pgstore/featuretypes"
6. 上传 GeoTIFF 栅格数据
curl -u admin:geoserver -XPUT \
-H "Content-Type: image/tiff" \
--data-binary @dem.tif \
"http://localhost:8080/geoserver/rest/workspaces/myws/coveragestores/dem/file.geotiff"
7. 创建并上传 SLD 样式
# 步骤 1:创建样式定义
curl -u admin:geoserver -XPOST \
-H "Content-Type: application/json" \
-d '{"style":{"name":"mystyle","filename":"mystyle.sld"}}' \
"http://localhost:8080/geoserver/rest/workspaces/myws/styles"
# 步骤 2:上传 SLD 文件内容
curl -u admin:geoserver -XPUT \
-H "Content-Type: application/vnd.ogc.sld+xml" \
--data-binary @mystyle.sld \
"http://localhost:8080/geoserver/rest/workspaces/myws/styles/mystyle"
8. 为图层设置默认样式
curl -u admin:geoserver -XPUT \
-H "Content-Type: application/json" \
-d '{"layer":{"defaultStyle":{"name":"mystyle","workspace":"myws"}}}' \
"http://localhost:8080/geoserver/rest/layers/myws:roads"
9. 创建图层组
curl -u admin:geoserver -XPOST \
-H "Content-Type: application/json" \
-d '{
"layerGroup": {
"name": "basemap",
"layers": {
"layer": [
{"name": "myws:roads"},
{"name": "myws:buildings"}
]
},
"styles": {
"style": [
{"name": "line"},
{"name": "polygon"}
]
}
}
}' \
"http://localhost:8080/geoserver/rest/workspaces/myws/layergroups"
10. 删除工作空间(级联删除所有内容)
curl -u admin:geoserver -XDELETE \
"http://localhost:8080/geoserver/rest/workspaces/myws?recurse=true"
典型工作流
发布矢量数据(Shapefile)完整流程
1. POST /rest/workspaces → 创建工作空间
2. PUT .../datastores/{ds}/file.shp → 上传 Shapefile(自动创建数据存储和图层)
3. POST /rest/workspaces/{ws}/styles → 创建样式
4. PUT .../styles/{style} → 上传 SLD 文件
5. PUT /rest/layers/{layer} → 绑定样式到图层
发布矢量数据(PostGIS)完整流程
1. POST /rest/workspaces → 创建工作空间
2. POST .../datastores → 创建 PostGIS 数据存储
3. POST .../datastores/{ds}/featuretypes → 发布数据库表为图层
4. PUT /rest/layers/{layer} → 配置图层样式
发布栅格数据(GeoTIFF)完整流程
1. POST /rest/workspaces → 创建工作空间
2. PUT .../coveragestores/{cs}/file.geotiff → 上传 GeoTIFF(自动创建存储和覆盖)
3. PUT /rest/layers/{layer} → 配置图层样式
C# 客户端(GeoServerDesktop.GeoServerClient)
本技能的配套教程系列以 C# 客户端库 GeoServerDesktop.GeoServerClient 为主线:它把上述 REST 端点封装为强类型、全异步的 .NET API,适用于桌面管理工具、CI/CD 集成与 .NET 运维脚本。
- 定位:面向 .NET 的 GeoServer REST API 完整封装,分层架构(Configuration / Http / Models / Services),客户端声明兼容 GeoServer 2.20+
- 仓库:github.com/znlgis/GeoServerDesktop(社区维护,2026-09 仍活跃)
- NuGet:
GeoServerDesktop.GeoServerClient(最新 1.1.1) - 环境要求:.NET Standard 2.0(支持 .NET Framework 4.6.1+、.NET 6/8+),依赖 Newtonsoft.Json
核心入口类:
| 类 | 职责 |
|---|---|
GeoServerClientOptions |
连接配置——BaseUrl / Username / Password / TimeoutSeconds |
GeoServerClientFactory |
服务工厂——CreateWorkspaceService() 等创建各类服务实例,IDisposable |
WorkspaceService / DataStoreService / FeatureTypeService / LayerService / StyleService 等 |
各资源组的异步 CRUD 服务 |
GeoServerRequestException |
统一异常——携带 StatusCode 与 ResponseContent |
using GeoServerDesktop.GeoServerClient.Configuration;
using GeoServerDesktop.GeoServerClient.Services;
var options = new GeoServerClientOptions
{
BaseUrl = "http://localhost:8080/geoserver",
Username = "admin",
Password = "geoserver"
};
using var factory = new GeoServerClientFactory(options);
var workspaceService = factory.CreateWorkspaceService();
// 与 REST 端点一一对应:列出 / 创建工作空间
var workspaces = await workspaceService.GetWorkspacesAsync();
await workspaceService.CreateWorkspaceAsync("myws");
与通用 REST 的关系: 该客户端是对前文
/rest/*端点的直接封装——请求路径、JSON 包装结构({"workspace":{...}})、认证方式完全一致;不使用该库时,用 curl 或任意 HTTP 客户端按前文示例直接调用即可。完整教程见 znlgis 博客:GeoServer REST API。
请求与响应格式
JSON 格式约定
请求和响应使用 JSON 时需注意 GeoServer 的 JSON 包装结构:
// 工作空间列表响应
{
"workspaces": {
"workspace": [
{"name": "cite", "href": "http://..."},
{"name": "tiger", "href": "http://..."}
]
}
}
// 单个工作空间响应
{
"workspace": {
"name": "myws",
"isolated": false,
"dataStores": "http://...",
"coverageStores": "http://...",
"wmsStores": "http://..."
}
}
常用 Content-Type
| 格式 | Content-Type |
|---|---|
| JSON | application/json |
| XML | application/xml 或 text/xml |
| SLD | application/vnd.ogc.sld+xml |
| ZIP (Shapefile) | application/zip |
| GeoTIFF | image/tiff |
| GeoPackage | application/geopackage+sqlite3 |
HTTP 状态码
| 状态码 | 含义 |
|---|---|
| 200 | 请求成功 |
| 201 | 资源创建成功 |
| 401 | 认证失败 |
| 403 | 权限不足 |
| 404 | 资源不存在 |
| 405 | 方法不允许 |
| 500 | 服务器内部错误 |
重要注意事项
- 认证必需:所有修改操作(POST / PUT / DELETE)必须提供有效认证凭据。
- recurse 参数:删除工作空间、数据存储时,添加
?recurse=true可级联删除所有子资源,否则存在子资源时删除会失败。 - JSON 包装:GeoServer REST API 的 JSON 请求 / 响应体均使用单层包装对象(如
{"workspace":{...}}),这与标准 REST 实践不同,使用时需注意。 - URL 后缀:可使用
.json或.xml后缀替代Accept请求头来指定响应格式。 - 文件上传:上传 Shapefile 时需打包为 ZIP 格式,且 ZIP 内必须包含
.shp、.shx、.dbf、.prj文件。 - 编码:图层名、工作空间名建议使用英文字母、数字和下划线,避免中文和特殊字符。
- GeoWebCache:通过 REST API 修改图层后,可能需要手动清空该图层的 GWC 缓存才能看到更新效果。
常见问题
| 问题 | 解决 |
|---|---|
| GET 正常但 POST/PUT 返回 401 | 补全 HTTP Basic Auth 凭据(默认 admin:geoserver),并确认 REST 访问规则未被安全设置禁用 |
| POST 返回 400 且资源未创建 | 检查 JSON 包装层(如 {"workspace":{...}})与 Content-Type: application/json 是否正确 |
| 上传 Shapefile 失败 | 必须打包为 ZIP(含 .shp/.shx/.dbf/.prj),PUT 到 .../datastores/{ds}/file.shp |
| 上传样式后图层样式未变化 | 确认 SLD 上传使用 application/vnd.ogc.sld+xml,并检查图层是否绑定到该样式 |
| 删除 Workspace / Store 报错 | 添加 ?recurse=true 级联删除子资源 |
| 修改配置后服务端未生效 | POST /rest/reload 重新加载配置;瓦片更新需清理 GWC 缓存 |
| 无法确认服务版本 | GET /rest/about/version.json 返回 GeoServer 与组件版本 |
AI 使用建议
- 本技能的组织:主文件给高频用法,完整参数表与高级示例在
reference/endpoints.md,需要时再展开;示例工程与生成的数据写到工作目录,不要改动技能目录本身。 - 执行环境:示例在终端 / shell 中执行(显式
curl.exe,Windows 的curl是别名、参数不同);\续行在 PowerShell 无效,压成单行;请求体先写成body.json,用curl.exe --data "@body.json"传,避开各 shell 的引号差异。 - 先探测版本:
curl.exe -s -u admin:geoserver http://localhost:8080/geoserver/rest/about/version.json,确认是 3.0.2 并顺带看到组件版本;返回 401 是凭据/安全规则问题,不是版本问题。 - 验证产物:写操作后立刻 GET 回读同一资源(
.../rest/workspaces/myws.json、.../rest/layers/myws:roads.json),再发一次 WMSGetMap取image/png确认非空图;不要只凭 201 或退出码报告成功。 - 幂等与坑:同名资源重复 POST 会报已存在(重跑脚本前先 GET 判断或改 PUT);改了样式记得清 GWC 缓存,否则瓦片还是旧的。
- 安全与权限:
admin:geoserver不要硬编码进脚本或回显到报告;?recurse=true删除 workspace、POST /rest/reset、清缓存均不可逆,执行前向用户确认。 - 批量脚本:循环建资源时检查
$LASTEXITCODE,一失败即停;半套配置留在服务端比报错更难排查。
相关技能
- geoserver — GeoServer 服务器运维配置:../geoserver/SKILL.md
- geoserver-cloud — 云原生微服务版本:../geoserver-cloud/SKILL.md
- gdal — 命令行数据预处理:../gdal/SKILL.md
- postgis — 空间数据库:../postgis/SKILL.md
参考资源
- GeoServer 源码仓库:https://github.com/geoserver/geoserver
- REST API 概述:https://docs.geoserver.org/latest/en/user/rest/index.html
- REST API 参考:https://docs.geoserver.org/stable/en/user/rest/api/index.html
- GeoServer 用户手册:https://docs.geoserver.org/stable/en/user/
- C# 客户端仓库:https://github.com/znlgis/GeoServerDesktop
- 端点清单补充文件:reference/endpoints.md
- 中文教程(znlgis):https://znlgis.github.io/gis/tutorial/geoserver-rest-api/