Appearance
OGC 服务概览
平台为每个服务提供只读的 OGC 标准接口，供 QGIS、ArcGIS Pro、GDAL、OpenLayers、Cesium、MapLibre 等接入。OGC 客户端看到的内容与平台自身的出图、切片、要素查询一致，访问控制也相同。
| 协议 | 版本 | 能力（发布时勾选） | 适用数据 | 说明 |
|---|---|---|---|---|
| WMS | 1.1.1、1.3.0 | WMS | 矢量、栅格影像 | 出图、点查询、图例 |
| WFS | 1.1.0、2.0.0（Basic） | WFS | 矢量 | 要素读取、过滤、分页，支持 XML 请求体 |
| WMTS | 1.0.0 | WMTS | 矢量、栅格影像、栅格切片包 | 标准切片，KVP 与 RESTful 两种写法 |
| TMS | 1.0.0 | TMS | 矢量、栅格影像、切片包 | OSGeo 切片规范，行号自下而上 |
| WCS | 2.0.1 | WCS | 栅格影像 | 按原始分辨率下载栅格（GeoTIFF） |
| OGC API | Common、Features、Tiles、Maps | OGC API | 全部 | JSON / HTML 接口：要素、矢量与地图瓦片、地图 |
启用
- 发布服务时在「服务能力」中勾选对应的能力，见发布服务。
- 图层发布：矢量图层可选 WMS、WFS、WMTS、TMS、OGC API；栅格图层可选 WMS、WMTS、WCS、TMS、OGC API；栅格切片包可选 WMTS、TMS、OGC API，矢量切片包可选 TMS、OGC API。
- 地图发布：可选 WMS、WFS、WMTS、TMS、OGC API；地图中有栅格图层时另可选 WCS。
- WMS、WFS、WCS、TMS、OGC API 都不默认勾选；WMTS 在矢量、栅格影像与栅格切片包上默认勾选。
- 发布后要增减能力，需要回到发布来源（图层或地图）重新发布，服务详情里不能直接修改。
- 没有开启某个协议时，请求得到 404「服务未启用 …」（如「服务未启用 WMTS」）；服务已停止返回 503。
- 控制台服务详情的「访问与代码」页签列出已开启协议的入口地址，并给出 QGIS、OpenLayers、Cesium、MapLibre、GDAL 的接入片段。
开启前请确认
WFS 与 OGC API 可以分页导出整层要素，WCS 可以按原始分辨率下载栅格数据。公开与「API Key」级别的服务开启它们后，任何持有地址（或 Key）的客户端都能读取原始数据。只给确实要对外提供数据的服务开启。
地址
下表中 <服务路径> 为服务名，服务在目录中时为 目录/服务名（/ 不要编码成 %2F）。
| 协议 | 入口 | 能力文档 / 首页 |
|---|---|---|
| WMS | …/<服务路径>/MapServer/WMSServer | …/WMSServer?service=WMS&request=GetCapabilities |
| WFS | …/<服务路径>/MapServer/WFSServer | …/WFSServer?service=WFS&request=GetCapabilities |
| WMTS | …/<服务路径>/MapServer/WMTS | …/WMTS/1.0.0/WMTSCapabilities.xml |
| TMS | …/<服务路径>/MapServer/tms | …/tms/1.0.0 |
| WCS | …/<服务路径>/MapServer/WCS | …/WCS?service=WCS&request=GetCapabilities |
| OGC API | …/<服务路径>/ogcapi | …/ogcapi/（landing 页） |
… 为 https://map-demo.geobridge.cn/geobridge-mapserver/rest/geodata/services。注意 OGC API 直接挂在服务路径之下，不在 MapServer 之下。
- WMS、WFS、WMTS（KVP）、WCS 的参数名不区分大小写，参数值取第一个值并去掉首尾空白；OGC API 的参数名区分大小写。
- WMS、WFS、WCS 接受 GET 与 POST 表单（
application/x-www-form-urlencoded，表单与查询参数合并，同名时以表单为准）；WFS 另接受 XML 请求体。WMTS、TMS、OGC API 只有 GET。
API Key
「API Key」级别的服务需要带 Key，方式与其他接口相同，见 API Key 与来源白名单：
- 查询参数：地址后加
token=gb_xxx…。参数名不区分大小写（TOKEN、Token也可以）。GIS 软件、<img>与 OpenLayers 的图片源只能用这种方式。 - 请求头：
X-GeoBridge-Token: gb_xxx…。自己写的服务端程序请优先用请求头，Key 不会出现在地址与日志中。 - 表单里的
token不认，令牌只看查询参数或请求头。
请求在查询参数中带了 token 时，响应中指向本服务的地址自动带上 token，客户端按文档继续请求即可：
| 协议 | 自动带上 token 的地址 |
|---|---|
| WMS | 能力文档中的操作地址、图例地址；DescribeLayer 中的 WFS、WCS 地址 |
| WFS | 能力文档中的操作地址、翻页的 next 链接、schemaLocation 中的 DescribeFeatureType 地址 |
| WMTS | 能力文档中的 KVP 地址、ResourceURL 瓦片与 FeatureInfo 模板 |
| WCS | 能力文档中的操作地址 |
| TMS | TileMapService 与 TileMap 文档之间的链接；TileSet 的 href 不带（客户端在其后追加 /{x}/{y}.{扩展名}），见 TMS |
| OGC API | 文档中的每个链接，含 next、prev 与瓦片地址模板 |
只用请求头传 Key 时，这些地址不改写，客户端要给每个请求加请求头。
错误与异常
| 情形 | 返回 |
|---|---|
| 服务未开启该协议 | 404「服务未启用 …」：WMS、WFS、WMTS、WCS 为平台的 JSON 错误体；TMS 为 TileMapServerError；OGC API 为 application/problem+json |
| 服务已停止 | 503，格式同上 |
| 参数错误、数据错误 | 各协议自己的异常格式，见下表 |
| 访问被拒绝（缺少 Key、Key 无效、未登录、无权限） | 状态码为 401 或 403，正文按协议的异常格式，异常码为平台错误码 TOKEN_REQUIRED、TOKEN_INVALID、UNAUTHORIZED、FORBIDDEN（含义见错误码） |
| 协议 | 异常格式 | 内容类型 |
|---|---|---|
| WMS | ServiceExceptionReport；参数错误一律 HTTP 200（WMS 的惯例），GetMap 另可返回图片形式，见 WMS 异常 | 1.3.0 为 text/xml，1.1.1 为 application/vnd.ogc.se_xml |
| WFS | OWS ExceptionReport：2.0.0 为 OWS 1.1，1.1.0 为 OWS 1.0 | text/xml |
| WMTS | OWS 1.1 ExceptionReport | text/xml |
| WCS | OWS 2.0 ExceptionReport | text/xml |
| TMS | <TileMapServerError><Message>…</Message></TileMapServerError> | text/xml |
| OGC API | RFC 7807 problem：type、title、status、detail，另有 code | application/problem+json |
除 WMS 外，HTTP 状态码表示错误类别：400 参数错误，404 不存在或超出范围（WCS 的覆盖、子集、缩放类错误按规范也是 404），501 不支持的操作，503 服务繁忙、超时或数据源不可用（带 Retry-After: 5），500 其他内部错误。异常响应一律 Cache-Control: no-store。
json
{ "type": "about:blank", "title": "Not Found", "status": 404, "detail": "服务未启用 OGC API", "code": "NotFound" }能力文档的元数据
WMS、WFS、WMTS、WCS 的能力文档从同一处取服务的描述信息（OGC API landing 页的标题与描述同此）：
| 元数据 | 来源 |
|---|---|
| 标题 | 服务标题；为空时取地图名，再为空时取服务名 |
| 摘要 | 服务描述 |
| 关键词 | 发布或服务设置中填写的「关键词」，按逗号、分号、顿号切分去重 |
| 访问约束 | 按访问级别：公开为无；「API Key」级别说明需要 API Key；私有说明需要登录与权限 |
| 收费 | 无 |
| 署名 | 服务的署名（WMS 根图层的 Attribution） |
| 服务提供方 | 部署时配置的单位名称、网址、联系人、邮箱、电话；没有配置时只写提供方名称 GeoBridge（WMS 不写联系信息） |
updateSequence | 服务目录的版本号，随服务变化单调递增。GetCapabilities 带上与当前相同的值时，WFS、WMTS、WCS 返回不带正文的 304，WMS 返回 CurrentUpdateSequence 异常报告；大于当前值或不是整数时为 InvalidUpdateSequence |
本地部署时，服务提供方在 .env 中配置：GEOBRIDGE_OGC_PROVIDER_NAME（单位名称）、GEOBRIDGE_OGC_PROVIDER_SITE（网址）、GEOBRIDGE_OGC_PROVIDER_CONTACT（联系人）、GEOBRIDGE_OGC_PROVIDER_EMAIL、GEOBRIDGE_OGC_PROVIDER_PHONE，留空的项不输出。修改后执行 docker compose up -d。
名称规则
各协议中的图层、类型、覆盖与集合名称都从服务中的图层名生成：
| 名称 | 规则 | 示例 |
|---|---|---|
| WMS 图层名（WMTS 子图层同此） | 图层名中的空白、:、, 换成 _；图层名为空时为 layer_<序号>；重名的追加 _<序号> | 道路 线 → 道路_线 |
| WFS 类型名 | 在 WMS 名上，把字母、数字、_、-、. 以外的字符换成 _；首字符不是字母或 _ 时前加 _；加前缀 gb: | 1号线 → gb:_1号线 |
| WFS 字段名 | 同 WFS 类型名的处理（不加前缀）；与几何属性 geometry 冲突时追加 _1、_2… | 名 称 → 名_称 |
| WCS 覆盖标识 | 同 WFS 类型名的处理（不加前缀），只有栅格图层 | 高程 2024 → 高程_2024 |
| OGC API 集合 id | 矢量图层与 WFS 类型名相同（不带 gb:）；其他图层同上处理，与已有 id 冲突时追加 _<序号> | gb:道路_线 → 道路_线 |
序号为图层在服务中的下标（从 0 开始，与 MapServer export 的 layers 一致）。过滤、排序与 GeoJSON 的属性键都用改名后的名称。JS SDK 的 wmsLayerNames() 按同一规则生成 WMS 图层名。
坐标轴顺序
OGC 协议中地理坐标系的坐标顺序是最常见的接入问题。总的原则：
- 按 EPSG 官方轴序：WMS 1.3.0 的
EPSG:写法、WFS 2.0.0、WMTS 的BoundingBox、WCS、OGC API 中的 EPSG:4326、EPSG:4490 都是纬度在前。 - 经度在前：WMS 1.1.1、WFS 1.1.0 的
EPSG:写法，CRS:84与 OGC API 的缺省坐标系 CRS84，以及所有 GeoJSON 输出。 - 投影坐标系（如 EPSG:3857）一律东、北在前。
各协议的细节见 WMS 的坐标系与轴序、WFS 的 BBOX、OGC API 的坐标系。
已知限制
- 所有协议都是只读的：不支持 WFS-T（事务）、锁与写入。
- 能力文档中的操作地址、图例地址、翻页链接、瓦片模板都由平台配置的对外访问地址生成。本地部署时该地址必须是客户端能访问到的地址，否则 GIS 软件读完能力文档后的请求会发到错误的地方，见修改访问地址。
- 控制台显示的地址中，目录下的服务可能把
目录/服务名中的/编码为%2F，手工拼写时请写成/。 - 图例与 WMS 图片异常中的中文需要服务器上有中文字体。官方镜像已包含；自行部署且缺少中文字体时，中文显示为方框。