imresamu/docker-postgis-test

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

postgis/postgis

https://github.com/postgis/docker-postgis/workflows/Docker%20PostGIS%20CI/badge.svg](https://github.com/postgis/docker-postgis/actions) https://badges.gitter.im/Join%20Chat.svg](https://gitter.im/postgis/docker-postgis?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)

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

postgis/postgis镜像提供用于运行已安装http://postgis.net/%E6%89%A9%E5%B1%95%E7%9A%84Postgres%E7%9A%84%E6%A0%87%E7%AD%BE%E3%80%82%E8%AF%A5%E9%95%9C%E5%83%8F%E5%9F%BA%E4%BA%8E%E5%AE%98%E6%96%B9https://registry.hub.docker.com/_/postgres/%E9%95%9C%E5%83%8F%EF%BC%8C%E6%8F%90%E4%BE%9B%E9%80%82%E7%94%A8%E4%BA%8EPostgreSQL 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

• 基础操作系统为https://alpinelinux.org/%EF%BC%8C%E8%AE%BE%E8%AE%A1%E5%B0%8F%E5%B7%A7%E3%80%81%E7%AE%80%E5%8D%95%E4%B8%94%E5%AE%89%E5%85%A8%EF%BC%8C%E5%9F%BA%E4%BA%8Ehttps://musl.libc.org/%E3%80%82
• 在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容器的详细说明，请参阅https://registry.hub.docker.com/_/postgres/%E3%80%82

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

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

更多连接方式详见https://registry.hub.docker.com/_/postgres/%E5%92%8Chttps://docs.docker.com/network/%E3%80%82

创建和使用空间数据库的更多选项，请参阅http://postgis.net/docs/postgis_installation.html#create_new_db_extensions%E3%80%82

支持的环境变量

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

• POSTGRES_PASSWORD
• POSTGRES_USER
• POSTGRES_DB
• POSTGRES_INITDB_ARGS
• POSTGRES_INITDB_WALDIR
• POSTGRES_HOST_AUTH_METHOD
• PGDATA https://github.com/docker-library/docs/blob/master/postgres/README.md#pgdata

详情请阅读https://github.com/docker-library/docs/blob/master/postgres/README.md

⚠️ PGDATA卷路径变更

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

卷路径摘要：

请为18+镜像调整卷挂载。更多详情见https://github.com/docker-library/postgres/pull/1259%E3%80%82

仅在空数据目录初始化

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

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

libpq环境变量

请注意，Docker环境变量与https://www.postgresql.org/docs/current/libpq-envars.html%E4%BD%BF%E7%94%A8%E7%9A%84%E5%8F%98%E9%87%8F**%E4%B8%8D%E5%90%8C**%E3%80%82%E5%90%8E%E8%80%85%E5%8C%85%E6%8B%AC%60PGDATABASE%60%E3%80%81%60PGUSER%60%E3%80%81%60PGPASSWORD%60%E7%AD%89%E5%AE%A2%E6%88%B7%E7%AB%AF%E5%B7%A5%E5%85%B7%E4%BD%BF%E7%94%A8%E7%9A%84%E5%8F%98%E9%87%8F%E3%80%82

故障排除提示

故障排除可能具有挑战性。需注意docker-postgis是官方Docker PostgreSQL仓库的扩展，因此遇到问题时，建议先测试是否可使用https://hub.docker.com/_/postgres%E5%A4%8D%E7%8E%B0%E3%80%82%E8%8B%A5%E5%8F%AF%E5%A4%8D%E7%8E%B0%EF%BC%8C%E5%BB%BA%E8%AE%AE%E5%9F%BA%E4%BA%8E%E6%AD%A4%E6%90%9C%E7%B4%A2%E8%A7%A3%E5%86%B3%E6%96%B9%E6%A1%88%E3%80%82%E6%8E%A8%E8%8D%90%E4%BB%A5%E4%B8%8B%E8%B5%84%E6%BA%90%EF%BC%9A

• 上游docker postgres仓库：https://github.com/docker-library/postgres
  • 搜索开放或已关闭的issue！
• Docker社区论坛：https://forums.docker.com
• Docker社区Slack：https://dockr.ly/slack
• Stack Overflow：https://stackoverflow.com/questions/tagged/docker+postgresql

若问题与PostGIS相关：

• Stack Overflow：docker + postgis https://stackoverflow.com/questions/tagged/docker+postgis
• PostGIS issue跟踪器：https://trac.osgeo.org/postgis/report

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

• https://www.docker.com/blog/how-to-use-the-postgres-docker-official-image/%EF%BC%88%E8%8B%B1%E6%96%87%EF%BC%89

安全

在云环境中，默认设置下这些镜像可能存在风险，若端口开放，极易遭受加密货币挖矿程序感染（https://github.com/docker-library/postgres/issues/770#issuecomment-704460980%EF%BC%89%E3%80%82

• 注意：未绑定到主机的端口（即-p 5432:5432而非-p 127.0.0.1:5432:5432）将可从外部访问。即使配置UFW阻止该端口，Docker也会管理自己的iptables规则（https://docs.docker.com/network/iptables/%EF%BC%89%E3%80%82

io_uring

每个postgis/postgis:18-*镜像都包含io_uring异步I/O功能。但部分容器运行时（如https://github.com/containerd/containerd/issues/9048%EF%BC%89%E5%9B%A0**%E5%AE%89%E5%85%A8%E8%80%83%E8%99%91**%E6%9B%BE**%E7%A6%81%E7%94%A8io_uring%E6%94%AF%E6%8C%81**%E3%80%82%E5%A6%82%E9%9C%80%E8%AF%95%E7%94%A8%E6%AD%A4%E5%8A%9F%E8%83%BD%EF%BC%8C%E8%AF%B7**%E8%87%AA%E8%A1%8C%E6%89%BF%E6%8B%85%E9%A3%8E%E9%99%A9**%EF%BC%8C%E5%B9%B6%E7%A1%AE%E4%BF%9D%E5%9C%A8https://docs.docker.com/engine/security/seccomp/%E4%B8%AD%E6%98%BE%E5%BC%8F%E5%90%AF%E7%94%A8io_uring%E3%80%82

建议

• 可添加SSL选项（https://github.com/docker-library/postgres/issues/989#issuecomment-***%EF%BC%89
  • -c ssl=on -c ssl_cert_file=/var/lib/postgresql/server.crt -c ssl_key_file=/var/lib/postgresql/server.key
• 或使用https://www.postgresql.org/docs/15/ssh-tunnels.html%EF%BC%8C%E9%85%8D%E5%90%88%60-p 127.0.0.1:5432:5432`

安全扫描信息

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