🚨 注意：这是一个测试仓库！ 🚨

postgis/postgis

![构建状态]([] ![加入聊天]([]

⚠️ 重大变更（PostgreSQL 18+）： 默认VOLUME路径已变更为/var/lib/postgresql

postgis/postgis镜像提供用于运行已安装PostGIS扩展的Postgres的标签。该镜像基于***postgres镜像，提供适用于PostgreSQL 13、14、15、16、17和18版本的PostGIS 3.5.x和3.6.x的Debian和Alpine变体。此外，还提供基于PostgreSQL 16和17的镜像变体，使用各自主分支构建PostGIS及其依赖项，标记为16-master和17-master。

此镜像确保父postgres镜像创建的默认数据库将安装以下扩展：

除非在启动容器时传递-e POSTGRES_DB，否则此数据库将以管理员用户命名（postgres或通过-e POSTGRES_USER指定的用户）。如果希望使用旧版模板数据库机制启用PostGIS，镜像还提供名为template_postgis的PostGIS启用模板数据库。

版本信息（2025-11-16）

支持架构：amd64（x86-64）

新用户推荐版本：

• postgis/postgis:18-3.6
  • ⚠️ 使用卷路径/var/lib/postgresql（PostgreSQL 18+中变更）
• postgis/postgis:17-3.5
  • 使用旧版卷路径/var/lib/postgresql/data

基于Debian（推荐）

• 此Docker-PostGIS镜像采用谨慎的发布周期以确保高稳定性。
  • “谨慎”意味着不总是包含最新版本的geos、proj、gdal和sfcgal包。
• 使用Debian仓库中的PostGIS、geos、proj、gdal和sfcgal包。
  • 在Debian Bullseye仓库（适用于PostgreSQL 13-17）中，版本为：
    • geos=3.9
    • gdal=3.2
    • proj=7.2
    • sfcgal=1.3.9
  • 在Debian Trixie仓库（适用于PostgreSQL 18+）中，版本为：
    • geos=3.13
    • gdal=3.10
    • proj=9.6
    • sfcgal2=2.0
• 此版本易于扩展，且经过长期完善。

基于Alpine

• 基础操作系统为Alpine Linux，设计小巧、简单且安全，基于musl libc。
• 在Alpine 3.22版本中，包版本为：
  • geos=3.13.1
  • gdal=3.10.2
  • proj=9.6.0
  • sfcgal=2.0.0
• PostGIS从源码编译，扩展难度稍大。

测试镜像

• 提供alpha、beta、发布候选版（rc）和开发版（标记为~master）。
• *-master镜像的模板需手动更新，可能会有几周延迟。

使用方法

要运行一个基本的PostGIS启用数据库容器，可按以下方式启动：

sh
docker run --name some-postgis -e POSTGRES_PASSWORD=mysecretpassword -d postgis/postgis

有关启动和控制Postgres容器的详细说明，请参阅postgres镜像文档。

启动数据库容器后，可直接连接到运行中的容器：

sh
docker exec -ti some-postgis psql -U postgres

或启动新容器作为客户端，使用用户定义网络连接两个容器：

sh
docker network create some-network

# 服务端容器
docker run --name some-postgis --network some-network -e POSTGRES_PASSWORD=mysecretpassword -d postgis/postgis

# 客户端容器
docker run -it --rm --network some-network postgis/postgis psql -h some-postgis -U postgres

更多连接方式详见postgres镜像文档和Docker网络文档。

创建和使用空间数据库的更多选项，请参阅PostGIS文档。

支持的环境变量

由于docker-postgis是Docker PostgreSQL仓库的扩展，所有支持的环境变量在此同样适用：

• POSTGRES_PASSWORD
• POSTGRES_USER
• POSTGRES_DB
• POSTGRES_INITDB_ARGS
• POSTGRES_INITDB_WALDIR
• POSTGRES_HOST_AUTH_METHOD
• PGDATA ⚠️ Docker PostgreSQL >=18中变更！⚠️

详情请阅读docker-postgres README

⚠️ PGDATA卷路径变更

从PostgreSQL 18开始，默认数据目录（VOLUME）路径已变更。这影响所有**postgis/postgis:18-***及更新镜像。

卷路径摘要：

请为18+镜像调整卷挂载。更多详情见上游变更。

仅在空数据目录初始化

Docker特定环境变量（如POSTGRES_DB、POSTGRES_USER、POSTGRES_PASSWORD）仅在容器使用空数据目录启动时生效。容器启动时，任何预先存在的数据库将保持不变。

如需重新初始化或更改设置，请先删除或重新创建卷。

libpq环境变量

请注意，Docker环境变量与libpq — C库使用的变量不同。后者包括PGDATABASE、PGUSER、PGPASSWORD等客户端工具使用的变量。

故障排除提示

故障排除可能具有挑战性。需注意docker-postgis是Docker PostgreSQL仓库的扩展，因此遇到问题时，建议先测试是否可使用PostgreSQL Docker镜像复现。若可复现，建议基于此搜索解决方案。推荐以下资源：

• 上游docker postgres仓库：[***]
  • 搜索开放或已关闭的issue！
• Docker社区论坛：[***]
• Docker社区Slack：[***]
• Stack Overflow：[***]

若问题与PostGIS相关：

• Stack Overflow：docker + postgis [***]
• PostGIS issue跟踪器：[***]

若无postgres docker使用经验，建议阅读：

• [***]

安全

在云环境中，默认设置下这些镜像可能存在风险，若端口开放，极易遭受加密货币挖矿程序感染（详见）。

• 注意：未绑定到主机的端口（即-p 5432:5432而非-p 127.0.0.1:5432:5432）将可从外部访问。即使配置UFW阻止该端口，Docker也会管理自己的iptables规则（详见）。

io_uring

每个postgis/postgis:18-*镜像都包含io_uring异步I/O功能。但部分容器运行时（如containerd）因安全考虑曾禁用io_uring支持。如需试用此功能，请自行承担风险，并确保在seccomp配置文件中显式启用io_uring。

建议

• 可添加SSL选项（见postgres示例）
  • -c ssl=on -c ssl_cert_file=/var/lib/postgresql/server.crt -c ssl_key_file=/var/lib/postgresql/server.key
• 或使用SSH隧道，配合-p 127.0.0.1:5432:5432

安全扫描信息

• 请同时扫描基础postgres Docker镜像的潜在安全问题。若安全扫描器报告漏洞（CVE），请查看[Docker Library FAQ