sodafountain/postgis_pgvector

PostgreSQL with pgvector and PostGIS 镜像文档

镜像概述

本镜像基于官方PostgreSQL镜像构建，预集成了pgvector和PostGIS两个扩展。pgvector是PostgreSQL的向量数据库扩展，支持向量存储与相似度搜索；PostGIS是地理空间数据库扩展，提供空间数据类型、索引及分析功能。该镜像旨在为需要同时处理地理空间数据和向量检索的应用提供开箱即用的数据库环境。

核心功能与特性

基础功能

• 完整继承官方PostgreSQL数据库功能，包括ACID事务、SQL标准支持、多种索引类型等
• 基于最新稳定版PostgreSQL构建，确保兼容性与安全性

pgvector扩展特性

• 支持向量数据类型（vector），可存储高维向量（最高***维）
• 提供多种相似度计算函数：欧氏距离（<->）、余弦相似度（<=>）、内积（<#>）
• 支持向量索引（IVFFlat、HNSW索引类型），优化大规模向量检索性能
• 兼容常见机器学习框架输出向量（如OpenAI嵌入、BERT嵌入等）

PostGIS扩展特性

• 支持标准地理空间数据类型：点（Point）、线（LineString）、面（Polygon）等
• 提供丰富的空间分析函数：距离计算、缓冲区分析、空间关系判断（包含、相交等）
• 支持空间索引（GiST、SP-GiST），加速地理数据查询
• 兼容OGC标准，可与GIS工具（如QGIS、GeoServer）无缝集成

其他特性

• 预配置扩展，无需手动编译安装
• 支持多平台架构（amd64、arm64）
• 与官方PostgreSQL镜像环境变量及数据目录兼容

适用场景

地理空间数据处理

• 地图服务与位置分析应用（如配送路线优化、区域划分）
• 地理信息系统（GIS）数据存储与查询
• 基于位置的服务（LBS）后端数据库

向量检索应用

• 推荐系统（用户/物品向量相似度匹配）
• 语义搜索（文本嵌入向量检索）
• AI应用（图像、音频等多媒体向量存储与相似性查询）

复合场景

• 基于地理位置的推荐系统（结合用户位置向量与偏好向量）
• 空间语义分析（地理数据与文本向量融合检索）

使用方法与配置说明

基本使用

直接运行容器

bash
docker run -d \
  --name postgres-vector-gis \
  -e POSTGRES_USER=myuser \
  -e POSTGRES_PASSWORD=mypassword \
  -e POSTGRES_DB=mydb \
  -p 5432:5432 \
  -v postgres-data:/var/lib/postgresql/data \
  [镜像名称]

docker-compose配置示例

yaml
version: '3.8'
services:
  postgres:
    image: docker.xuanyuan.run/[镜像名称]
    container_name: postgres-vector-gis
    environment:
      POSTGRES_USER: myuser
      POSTGRES_PASSWORD: mypassword
      POSTGRES_DB: mydb
    ports:
      - "5432:5432"
    volumes:
      - postgres-data:/var/lib/postgresql/data
    restart: unless-stopped

volumes:
  postgres-data:

环境变量说明

启用扩展

镜像已预安装扩展，使用时需在数据库中创建扩展：

1. 进入容器：

bash
docker exec -it postgres-vector-gis psql -U myuser -d mydb

2. 创建扩展：

sql
-- 启用pgvector
CREATE EXTENSION vector;

-- 启用PostGIS
CREATE EXTENSION postgis;
-- 可选：启用PostGIS额外功能
CREATE EXTENSION postgis_topology;
CREATE EXTENSION fuzzystrmatch;
CREATE EXTENSION postgis_tiger_geocoder;

数据持久化

通过挂载卷（如上述示例中的postgres-data卷）实现数据持久化，避免容器删除后数据丢失。建议生产环境使用命名卷或绑定主机目录。

扩展使用示例

pgvector使用示例

sql
-- 创建含向量字段的表
CREATE TABLE items (
  id SERIAL PRIMARY KEY,
  embedding vector(3)  -- 3维向量
);

-- 插入向量数据
INSERT INTO items (embedding) VALUES ('[1,2,3]'), ('[4,5,6]');

-- 计算向量相似度（欧氏距离）
SELECT id, embedding <-> '[3,2,1]' AS distance 
FROM docker.xuanyuan.run/items 
ORDER BY distance;

PostGIS使用示例

sql
-- 创建含地理字段的表
CREATE TABLE locations (
  id SERIAL PRIMARY KEY,
  name VARCHAR(100),
  geom GEOMETRY(Point, 4326)  -- WGS84坐标系点类型
);

-- 插入地理数据
INSERT INTO locations (name, geom) 
VALUES ('北京', ST_SetSRID(ST_MakePoint(116.4042, 39.9153), 4326));

-- 空间查询（查找距离给定点100公里内的位置）
SELECT name, ST_Distance(geom, ST_SetSRID(ST_MakePoint(116.3, 39.9), 4326))/1000 AS distance_km
FROM docker.xuanyuan.run/locations
WHERE ST_DWithin(
  geom, 
  ST_SetSRID(ST_MakePoint(116.3, 39.9), 4326), 
  100000  -- 100000米 = 100公里
);

注意事项

• 生产环境需合理配置资源限制（内存、CPU），尤其是向量和空间数据量较大时
• 向量索引（如IVFFlat）需根据数据量和查询模式调整参数（如lists数量）
• PostGIS空间索引建议针对常用查询字段创建，提升查询性能
• 定期备份持久化卷数据，避免数据丢失