PostGIS in CloudNativePG-北京尧图网络

PostGIS in CloudNativePG【免费下载链接】cloudnative-pgThe most popular Kubernetes Operator for PostgreSQL.项目地址: https://gitcode.com/GitHub_Trending/cl/cloudnative-pg在 Kubernetes 上为 PostgreSQL 部署 PostGIS 的完整指南CloudNativePGCloudNative PostgreSQL是目前最流行的 Kubernetes PostgreSQL Operator。本文聚焦于如何在 CloudNativePG 管理的 PostgreSQL 集群中启用 PostGIS——一个为 PostgreSQL 引入 GIS地理信息系统对象存储与 SQL 空间查询能力的著名开源扩展。本文假定你已经熟悉 PostGIS 的基本概念将系统讲解两种官方支持的 PostGIS 安装方式Image Volume Extensions 与 PostGIS Operand Images如何在数据库内部声明式地启用扩展以及如何使用kubectl cnpg psql验证安装结果。读完本文你将掌握在 Kubernetes 上从零构建一个带 PostGIS 空间数据库的生产级方案。支持的安装方式总览根据你的环境PostgreSQL 版本、Kubernetes 版本以及 CloudNativePG 版本项目官方文档给出了两种主要的 PostGIS 供给方式方式原理适用场景Image Volume Extensions将扩展二进制直接从 OCI 镜像以只读卷方式挂载进 Postgres 容器PG 18 与 Kubernetes 1.35推荐PostGIS Operand Images使用社区预构建的、已包含 PostGIS 库的 PostgreSQL 镜像较老的 PostgreSQL/Kubernetes 版本或偏好专用镜像仓库需要特别注意的是无论采用上述哪种方式完成 PostGIS 二进制文件的供给你都必须再在数据库内部启用并管理扩展详见下文 Enabling the Extension 章节。方法一Image Volume Extensions推荐从PostgreSQL 18与Kubernetes 1.35在 1.33 和 1.34 上需要显式开启ImageVolumefeature gate开始你可以利用 CloudNativePG 的 image volume extensions 能力。这是当前管理扩展的现代方式使用官方的精简版 PostgreSQL 镜像minimal在运行时通过将扩展 OCI 镜像的内容作为只读卷挂载进 Postgres 容器的方式即插即用 PostGIS。这种方式将扩展的生命周期与基础 PostgreSQL 镜像彻底解耦让你的 operand 镜像保持精简与安全。CloudNativePG 社区通过postgres-extensions-containers项目分发独立的 PostGIS 扩展容器镜像。底层原理ExtensionConfiguration 与 GUC 注入从源码层面看.spec.postgresql.extensions字段的类型定义在 api/v1/cluster_types.go 的ExtensionConfiguration结构体中name扩展名必填限长 59 字符由小写字母、数字、下划线或连字符组成首尾必须是字母数字该限制是为了给 Operator 派生的 Kubernetes 卷名前缀留出空间卷名被限制在 RFC 1123 的 63 字符以内。image.reference扩展镜像地址遵循 KubernetesImageVolumeAPI。extension_control_path镜像内需要追加到 PostgreSQLextension_control_path的目录列表默认/share。dynamic_library_path镜像内需要追加到 PostgreSQLdynamic_library_path的目录列表默认/lib。ld_library_path需要追加到 Postgres 进程LD_LIBRARY_PATH环境变量的目录列表PostGIS 等扩展需要系统库时必须配置且修改后需要手动重启集群。bin_path需要追加到 Postgres 进程PATH的目录列表。env注入 Postgres 进程的自定义环境变量列表。每个扩展会被挂载为 pod 内/extensions/EXTENSION_NAME下的只读卷。CloudNativePG 默认自动设置两个 GUCextension_control_path指向/extensions/EXTENSION_NAME/sharedynamic_library_path指向/extensions/EXTENSION_NAME/lib这些值按extensions列表的定义顺序追加保证 PostgreSQL 路径解析的确定性。扩展名中的下划线如pg_ivm会被转换为连字符以符合 RFC 1123 规范。通过 image catalog 使用CloudNativePG 1.29从 CloudNativePG 1.29 起你可以借助 image catalogs with image volume extensions 来自动化这些版本的管理与升级工作。在 api/v1/imagecatalog_types.go 中CatalogImage结构体包含majorPostgreSQL 主版本号须在单个 catalog 内唯一、image以及可选的Extensions列表——这正是 catalog 支持扩展镜像的字段。按照 image volume extensions 页面的指引将扩展加入 PostgreSQL 集群时确保使用postgis这个 keyapiVersion: postgresql.cnpg.io/v1 kind: Cluster metadata: name: cluster-postgis spec: # ... snip imageCatalogRef: apiGroup: postgresql.cnpg.io kind: ClusterImageCatalog name: postgresql-minimal-trixie major: 18 postgresql: extensions: # ... snip - name: postgis # ... snip使用 image catalog 的好处是catalog 集中管理了image.reference及所需文件系统路径等复杂细节Cluster资源只需按名字opt-in扩展。如果Cluster中同时定义了同名扩展则Cluster内的配置优先name字段除外——它是唯一标识改名即定义一个新条目。最终生效的解析后配置会体现在status.pgDataImageInfo.extensions中便于校验 catalog 解析结果与覆盖情况。直接在 Cluster 资源中定义下面的示例演示了如何将 PostGIS 3.6.2 加载到一个 PostgreSQL 18 集群——直接将扩展定义在Cluster资源中这是 CloudNativePG 1.29 之前唯一可用的方式也适用于测试自定义镜像apiVersion: postgresql.cnpg.io/v1 kind: Cluster metadata: name: cluster-postgis spec: imageName: ghcr.io/cloudnative-pg/postgresql:18.6-minimal-trixie instances: 1 storage: size: 1Gi postgresql: extensions: - name: postgis image: reference: ghcr.io/cloudnative-pg/postgis-extension:3.6.2-18-trixie ld_library_path: - system示例中ld_library_path: [system]的含义是PostGIS 依赖系统库需要把扩展镜像内system目录追加到 Postgres 进程的LD_LIBRARY_PATH。CloudNativePG 会将其解析为/extensions/postgis/system从而让 PostgreSQL 在运行时定位并加载这些系统库。由于ld_library_path必须在进程启动时设置修改该字段后需要手动执行集群重启如kubectl cnpg restart才能生效Operator 不会自动触发重启。关于 PostGIS 扩展镜像的最新版本与构建/使用说明请参阅postgres-extensions-containers项目。方法二PostGIS Operand Images对于偏好继续使用专用postgis-containers镜像仓库的用户或是运行在不支持 image volume extensions 的较老 PostgreSQL/Kubernetes 版本上的用户社区依然维护着预装 PostGIS 的镜像基于 PostgreSQL Container images 构建。相关信息可查阅postgis-containers项目postgis-containers容器镜像仓库使用该方法只需将.spec.imageName指向期望的 PostGIS 镜像apiVersion: postgresql.cnpg.io/v1 kind: Cluster metadata: name: cluster-postgis spec: instances: 1 imageName: ghcr.io/cloudnative-pg/postgis:18.6-3.6.2-system-trixie storage: size: 1Gi镜像 tag 的语义可以从命名规律推断18.6-3.6.2-system-trixie表示 PostgreSQL 18.6、PostGIS 3.6.2、基于 Debian trixie 的系统级构建。该方式将 PostGIS 直接编译/打包进数据库镜像省去了运行时挂载环节但镜像体积更大、扩展生命周期与基础镜像绑定。启用扩展Enabling the Extension无论通过哪种方式完成二进制供给你都必须在数据库内部启用扩展。CloudNativePG 通过Database资源提供扩展生命周期的声明式管理包括版本升级。更多细节参见 declarative_database_management.md 中 Managing Extensions in a Database 一节。apiVersion: postgresql.cnpg.io/v1 kind: Database metadata: name: cluster-postgis-app spec: name: app owner: app cluster: name: cluster-postgis extensions: - name: postgis version: 3.6.2 - name: postgis_raster - name: postgis_sfcgal - name: fuzzystrmatch - name: address_standardizer - name: address_standardizer_data_us - name: postgis_tiger_geocoder - name: postgis_topology这个清单覆盖了 PostGIS 生态的核心成员postgis几何/地理空间类型与函数、postgis_raster栅格类型与函数、postgis_sfcgalSFCGAL 3D 函数、postgis_tiger_geocoderTiger 地理编码与反向地理编码、postgis_topology拓扑空间类型与函数以及辅助的fuzzystrmatch、address_standardizer与address_standardizer_data_us。从源码看api/v1/database_types.go 中ExtensionSpec支持以下属性name必填扩展名。ensurepresent确保安装默认或absent确保移除。version要安装或升级到的具体版本为空时 Operator 安装扩展 control 文件指定的默认版本。schema扩展对象的安装 schema若扩展允许对象重定位。Operator 在底层使用 PostgreSQL 的CREATE EXTENSION、DROP EXTENSION与ALTER EXTENSION限于UPDATE TO与SET SCHEMA命令完成调协。之所以提供这一声明式接口是因为部分扩展的安装需要超级用户权限而 CloudNativePG 默认建议禁用超级用户——通过DatabaseAPI 可以在不提升权限的前提下规模化、可控地管理扩展。:::tip 强烈建议在extensions段落中显式指定version。CloudNativePG 会将其与数据库中当前安装的版本进行比较若不一致会自动执行必要的ALTER EXTENSION ... UPDATE TO ...命令完成升级。 :::验证VerificationPostGIS 供给与启用完成后可以用kubectl cnpg psql该插件命令的实现位于 internal/cmd/plugin/psql/cmd.go它会在 CloudNativePG 创建的 PostgreSQL Pod 内启动交互式psql会话连接app数据库并查询 PostgreSQL 系统目录验证容器内可用的 PostGIS 版本kubectl cnpg psql cluster-postgis -- app -c \ SELECT * FROM pg_available_extensions WHERE name ~ ^postgis ORDER BY 1返回结果类似如下实际输出可能因版本不同而有差异name | default_version | installed_version | comment -------------------------------------------------------------------------------------------------------------------------- postgis | 3.6.2 | 3.6.2 | PostGIS geometry and geography spatial types and functions postgis-3 | 3.6.2 | | PostGIS geometry and geography spatial types and functions postgis_raster | 3.6.2 | 3.6.2 | PostGIS raster types and functions postgis_raster-3 | 3.6.2 | | PostGIS raster types and functions postgis_sfcgal | 3.6.2 | 3.6.2 | PostGIS SFCGAL functions postgis_sfcgal-3 | 3.6.2 | | PostGIS SFCGAL functions postgis_tiger_geocoder | 3.6.2 | 3.6.2 | PostGIS tiger geocoder and reverse geocoder postgis_tiger_geocoder-3 | 3.6.2 | | PostGIS tiger geocoder and reverse geocoder postgis_topology | 3.6.2 | 3.6.2 | PostGIS topology spatial types and functions postgis_topology-3 | 3.6.2 | | PostGIS topology spatial types and functions (10 rows)上表中带-3后缀的条目是 PostGIS 提供的版本化别名versioned alias便于用户在default_version变化时锁定大版本其installed_version为空说明它们只是可选别名无需单独安装。下一步是验证Database资源中列出的扩展是否已在app数据库内正确安装kubectl cnpg psql cluster-postgis -- app -c \dx命令返回类似如下内容List of installed extensions Name | Version | Default version | Schema | Description -------------------------------------------------------------------------------------------------------------------- address_standardizer | 3.6.2 | 3.6.2 | public | Used to parse an address into constituent ... address_standardizer_data_us | 3.6.2 | 3.6.2 | public | Address Standardizer US dataset example fuzzystrmatch | 1.2 | 1.2 | public | determine similarities and distance between... plpgsql | 1.0 | 1.0 | pg_catalog | PL/pgSQL procedural language postgis | 3.6.2 | 3.6.2 | public | PostGIS geometry and geography spatial type... postgis_raster | 3.6.2 | 3.6.2 | public | PostGIS raster types and functions postgis_sfcgal | 3.6.2 | 3.6.2 | public | PostGIS SFCGAL functions postgis_tiger_geocoder | 3.6.2 | 3.6.2 | tiger | PostGIS tiger geocoder and reverse geocoder postgis_topology | 3.6.2 | 3.6.2 | topology | PostGIS topology spatial types and functions (9 rows)最后可以通过 PostGIS 自带的版本报告函数做一次端到端确认kubectl cnpg psql cluster-postgis -- app -c SELECT postgis_full_version()返回postgis_full_version ------------------------------------------------------------------------------------------------------------------------ POSTGIS3.6.2 08d9b9f [EXTENSION] PGSQL180 GEOS3.13.1-CAPI-1.19.2 SFCGALSFCGAL 2.0.0, CGAL 6.0, BOOST 1.83.0 PROJ9.6.0 NETWORK_ENABLEDOFF URL_ENDPOINT USER_WRITABLE_DIRECTORY/tmp/proj (compiled against PROJ 9.6.0) GDALGDAL 3.10.3, released 2025/04/01 GDAL_DATA not found LIBXML2.9.14 LIBJSON0.18 LIBPROTOBUF1.5.1 WAGYU0.5.0 (Internal) TOPOLOGY RASTER (1 row)postgis_full_version()返回了完整的编译环境信息PostGIS 3.6.2 基于 PostgreSQL 180即 18.x并链接了 GEOS、SFCGAL/CGAL/BOOST、PROJ、GDAL、LIBXML、LIBJSON、LIBPROTOBUF 与 WAGYU 等底层空间计算依赖同时确认了 TOPOLOGY 与 RASTER 组件可用。这一行输出可以让你在生产排障时快速判断 PostGIS 的编译期能力是否满足业务需求例如 PROJNETWORK_ENABLEDOFF表示离线投影计算。延伸从集群中移除 PostGIS当你需要移除 PostGIS 时建议遵循两步走的过程避免出现 library not found 错误先从数据库层面移除扩展如果使用声明式管理在Database资源中将对应扩展的ensure设为absentOperator 会执行DROP EXTENSIONspec: extensions: - name: postgis ensure: absent再从集群基础设施层面移除从.spec.postgresql.extensions列表中删除对应条目Operator 会执行滚动更新以卸载ImageVolume并更新相关 GUC 路径。如果扩展被加入了shared_preload_libraries还需先从Cluster配置中移除它。此外请留意新增、移除或更新扩展镜像都会触发 PostgreSQL Pod 的重启这是 KubernetesImageVolume机制带来的既有行为。在生产环境执行扩展更新前务必在预发环境充分测试升级路径并同步更新Database资源中对应的version字段。总结在 CloudNativePG 上启用 PostGIS 是一条清晰的声明式路径选供给方式PG 18/K8s 1.35 优先使用 Image Volume Extensions推荐配合 image catalog 集中管理镜像旧版本环境使用社区预构建的 PostGIS Operand Images。声明扩展在Cluster的postgresql.extensions中按名启用catalog 方式或显式指定镜像 reference直接方式。启用扩展通过Database资源的extensions列表声明 PostGIS 及其生态组件并指定version以获得自动升级能力。验证使用kubectl cnpg psql查询pg_available_extensions、\dx与postgis_full_version()完成三层校验。这种方式将扩展分发与数据库镜像解耦既保持了 operand 镜像的精简与安全又通过声明式 API 将 PostGIS 的空间能力纳入了 Kubernetes 原生的工作流管理。【免费下载链接】cloudnative-pgThe most popular Kubernetes Operator for PostgreSQL.项目地址: https://gitcode.com/GitHub_Trending/cl/cloudnative-pg创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

PostGIS in CloudNativePG

相关推荐

Litestar + SQLAlchemy Repository 实战：用 Controller 组装带分页的完整 CRUD 服务

Win11Debloat 使用指南：免费三步卸载预装应用、关闭遥测，给 Windows 11 瘦身

DenseUnet腹部多脏器分割实战：3D密集连接与解剖先验融合

更多资讯

从零构建桌面协同CRM：客户管理、工单系统与消息中心的技术实践

技能进化趋势与实战方法论：从AI协作到能力跃迁

基于Matlab的2DPSK调制解调系统仿真与误码率分析

InternVL Flash Attention配置详解：多模态训练的性能加速器

基于YOLOv5的实时人脸识别与异常行为检测系统解析

es-toolkit 的 methodOf：固定对象、后置路径的方法调用工厂函数实战指南

今日更新

基于MATLAB的CRI显色指数计算：从SPD光谱到Ra的完整流程

JSP+Servlet+MySQL博客系统源码部署与优化全攻略

蜂窝调度算法 MATLAB 实现：比例公平、轮询与最大 C/I 对比

本周精选

AI驱动的自动化专利分析平台技术解析

LeetCode-Go 题解：1252. Cells with Odd Values in a Matrix（奇数值单元格计数）双解法剖析

在线答疑系统Java毕设实战：Spring Boot前后端分离与状态流转

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？