nickblah/pgrouting

PostgreSQL-pgRouting Docker 镜像文档

1. 镜像概述和主要用途

本镜像为 PostgreSQL 数据库与 pgRouting 扩展的预集成 Docker 镜像，旨在提供自动化构建、版本同步且即开即用的地理空间路由分析环境。镜像基于官方 PostgreSQL 镜像构建，预安装并配置 pgRouting 扩展，支持所有当前受支持的 PostgreSQL 主版本（如 12、13、14、15、16），适用于需要快速部署地理空间路由功能的开发、测试及生产环境。

2. 核心功能和特性

2.1 自动化与版本同步

• 自动化构建：通过 CI/CD 流水线与 PostgreSQL 官方版本同步，确保镜像与上游主版本（12+）及 pgRouting 最新稳定版（3.0+）保持一致。
• 多版本支持：提供标签化镜像（如 16-pgrouting-3.5、15-pgrouting-3.4），满足不同版本兼容性需求。

2.2 功能集成与可用性

• 预配置 pgRouting：默认集成 pgRouting 核心扩展（pgrouting、postgis 依赖），容器启动时自动在指定数据库中启用扩展。
• 轻量级基础：基于官方 postgres:<version>-alpine 镜像构建，减小镜像体积（约 200-300MB）。
• 数据持久化：支持 PostgreSQL 标准数据卷挂载，确保容器重启后数据不丢失。

2.3 安全性与维护

• 定期更新：每月自动拉取基础镜像安全补丁，降低漏洞风险。
• 多架构支持：提供 amd64/arm64 架构镜像，适配 x86 服务器与 ARM 开发设备（如 M1/M2 Mac）。

3. 使用场景和适用范围

3.1 典型应用场景

• GIS 应用开发：地理信息系统（GIS）后端服务，需嵌入路由计算功能（如物流配送路径规划、公共交通导航）。
• 路由规划服务：构建骑行/步行/驾车路线 API（依赖 pgRouting 最短路径、等时线分析算法）。
• 空间数据分析：地理空间数据集（如 OSM 数据）的路由效率评估、网络拓扑分析。
• 教学与测试：快速搭建 pgRouting 学习环境，无需手动配置 PostgreSQL 与扩展依赖。

3.2 适用用户

• 地理信息系统（GIS）开发者
• 后端工程师（需集成路由功能的服务）
• 数据分析师（空间数据路由特性挖掘）
• 教育机构（PostgreSQL+pgRouting 教学实验环境）

4. 使用方法和配置说明

4.1 镜像拉取

从 Docker Hub 拉取指定版本镜像（推荐指定版本标签以确保稳定性）：

bash
# 格式：docker pull <镜像名>:<postgres版本>-pgrouting-<pgrouting版本>
docker pull postgres-pgrouting:16-pgrouting-3.5

4.2 基本运行命令

启动一个单节点容器，默认启用 pgRouting 扩展：

bash
docker run -d \
  --name pgroute-demo \
  -p 5432:5432 \
  -e POSTGRES_PASSWORD=mysecretpassword \
  -e POSTGRES_DB=gisdb \
  postgres-pgrouting:16-pgrouting-3.5

4.3 数据持久化

通过挂载数据卷实现 PostgreSQL 数据持久化（推荐生产环境使用）：

bash
# 创建本地数据目录
mkdir -p /data/pgroute

# 运行容器并挂载数据卷
docker run -d \
  --name pgroute-prod \
  -p 5432:5432 \
  -e POSTGRES_PASSWORD=securepass \
  -v /data/pgroute:/var/lib/postgresql/data \
  postgres-pgrouting:16-pgrouting-3.5

4.4 环境变量配置

支持通过环境变量自定义数据库初始化参数，常用变量如下：

示例：指定自定义用户、数据库及扩展：

bash
docker run -d \
  -e POSTGRES_USER=gisadmin \
  -e POSTGRES_PASSWORD=gis@2024 \
  -e POSTGRES_DB=city_routing \
  -e PGROUTING_EXTENSIONS="pgrouting,postgis,postgis_topology" \
  postgres-pgrouting:16-pgrouting-3.5

4.5 自定义配置文件

如需修改 PostgreSQL 或 pgRouting 配置（如内存参数、连接池），可通过挂载配置文件覆盖默认配置：

bash
# 准备自定义 postgresql.conf（从容器中复制默认配置修改）
docker cp pgroute-demo:/var/lib/postgresql/data/postgresql.conf ./my-postgres.conf

# 挂载自定义配置文件运行
docker run -d \
  --name pgroute-custom \
  -v ./my-postgres.conf:/var/lib/postgresql/data/postgresql.conf \
  -v /data/pgroute:/var/lib/postgresql/data \
  postgres-pgrouting:16-pgrouting-3.5

4.6 Docker Compose 部署

使用 docker-compose.yml 简化多服务集成（如搭配 GIS 应用后端）：

yaml
version: '3.8'
services:
  pgroute:
    image: postgres-pgrouting:16-pgrouting-3.5
    container_name: pgroute-service
    restart: always
    environment:
      POSTGRES_USER: gisuser
      POSTGRES_PASSWORD: gis@pass123
      POSTGRES_DB: routing_db
      PGROUTING_EXTENSIONS: "pgrouting,postgis,postgis_raster"
    ports:
      - "5432:5432"
    volumes:
      - pgdata:/var/lib/postgresql/data
      - ./init-scripts:/docker-entrypoint-initdb.d  # 挂载初始化 SQL 脚本
    networks:
      - gis-network

networks:
  gis-network:
    driver: bridge

volumes:
  pgdata:  # 命名卷自动管理数据持久化

启动服务：docker-compose up -d

5. 验证安装

容器启动后，可通过 psql 客户端验证 pgRouting 是否正常加载：

bash
# 进入容器
docker exec -it pgroute-demo psql -U postgres -d gisdb

# 在 psql 终端执行
gisdb=# SELECT pgr_version();
               pgr_version               
----------------------------------------
 (3.5.0,1.7.0,3.5.0,bfd9c8c,master,1.7.0)
(1 row)

若返回版本信息，说明 pgRouting 已成功集成。

6. 注意事项

• 版本兼容性：确保应用依赖的 PostgreSQL 版本与镜像标签版本一致（如应用需 PostgreSQL 14，则使用 14-pgrouting-* 标签）。
• 数据备份：生产环境需定期备份 /var/lib/postgresql/data 目录数据，避免容器删除导致数据丢失。
• 性能调优：高并发场景下，建议通过 postgresql.conf 调整 shared_buffers、work_mem 等参数优化性能。

7. 镜像更新与维护

• 镜像每周自动构建，同步上游 PostgreSQL 安全更新及 pgRouting 补丁版本。
• 版本升级时，建议先备份数据，再通过新镜像启动并挂载原数据卷（需确保主版本兼容，如 15→16 需执行 pg_upgrade）。