PostgreSQL Docker 部署指南

Posted on Thu 09 October 2025 in 数据库

本指南详细介绍如何使用 Docker 部署一个包含 PostGIS、pgvector 和 TimescaleDB 扩展的 PostgreSQL 15 数据库。该方案解决了扩展兼容性问题，特别是 pgvector 的段错误问题。

项目结构

PgSQL/
├── .env                          # 环境变量配置
├── Dockerfile                    # PostgreSQL 镜像构建文件
├── docker-compose.yml            # Docker Compose 配置
├── README.md                     # 项目说明
├── config/                       # 配置文件目录
│   ├── pg_hba.conf              # 客户端认证配置
│   └── postgresql.conf          # PostgreSQL 主配置
├── data/                        # 数据持久化目录
│   └── pgdata/                  # PostgreSQL 数据目录
├── init-scripts/                # 初始化脚本
│   └── 01-install-extensions.sql # 扩展安装脚本
├── logs/                        # 日志目录
└── test-examples.sql            # 测试示例

快速开始

1. 环境准备

确保系统已安装： - Docker - Docker Compose

2. 克隆或创建项目目录

mkdir -p ~/Server/PgSQL
cd ~/Server/PgSQL

3. 配置环境变量

创建 .env 文件：

# PostgreSQL 数据库配置
POSTGRES_DB=devdb
POSTGRES_USER=postgres
POSTGRES_PASSWORD=your_secure_password
POSTGRES_PORT=5432

# 注意：请修改 POSTGRES_PASSWORD 为您的实际密码
# 建议使用强密码，包含大小写字母、数字和特殊字符

4. 构建镜像

docker build -t postgres-all-extensions:latest .

5. 启动服务

docker-compose up -d

6. 验证安装

# 检查容器状态
docker ps

# 连接数据库验证扩展
docker exec postgres-all-extensions psql -U postgres -d devdb -c "SELECT extname, extversion FROM pg_extension WHERE extname IN ('timescaledb', 'postgis', 'vector') ORDER BY extname;"

详细配置说明

Dockerfile 解析

FROM postgres:15

# 安装系统依赖
RUN apt-get update && apt-get install -y \
    build-essential \
    postgresql-server-dev-15 \
    cmake \
    git \
    wget \
    ca-certificates \
    postgresql-15-postgis-3 \
    postgresql-15-postgis-3-scripts \
    libkrb5-dev \
    libgssapi-krb5-2 \
    && rm -rf /var/lib/apt/lists/*

# 安装 pgvector (预编译版本，避免段错误)
RUN cd /tmp && \
    wget https://github.com/pgvector/pgvector/archive/v0.5.1.tar.gz && \
    tar -xzf v0.5.1.tar.gz && \
    cd pgvector-0.5.1 && \
    make && \
    make install

# 安装 TimescaleDB (从源码编译)
RUN cd /tmp && \
    git clone https://github.com/timescale/timescaledb.git && \
    cd timescaledb && \
    git checkout 2.13.0 && \
    ./bootstrap && \
    cd build && \
    make && \
    make install

# 配置 PostgreSQL
RUN echo "shared_preload_libraries = 'timescaledb'" >> /usr/share/postgresql/postgresql.conf.sample

# 复制初始化脚本
COPY init-scripts/ /docker-entrypoint-initdb.d/

EXPOSE 5432

Docker Compose 配置

version: '3.8'

services:
  postgres-all-extensions:
    image: postgres-all-extensions:latest
    container_name: postgres-all-extensions
    environment:
      POSTGRES_DB: ${POSTGRES_DB}
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    ports:
      - "5432:5432"
    volumes:
      - ./data/pgdata:/var/lib/postgresql/data
      - ./config/postgresql.conf:/etc/postgresql/postgresql.conf
      - ./config/pg_hba.conf:/etc/postgresql/pg_hba.conf
      - ./logs:/var/log/postgresql
    networks:
      - postgres-network
    restart: unless-stopped
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 30s
      timeout: 10s
      retries: 3

networks:
  postgres-network:
    driver: bridge

扩展功能测试

PostGIS 测试

-- 创建几何数据
SELECT ST_AsText(ST_MakePoint(-71.064544, 42.28787));

-- 空间查询示例
CREATE TABLE locations (
    id SERIAL PRIMARY KEY,
    name VARCHAR(100),
    geom GEOMETRY(POINT, 4326)
);

INSERT INTO locations (name, geom) VALUES 
('Boston', ST_SetSRID(ST_MakePoint(-71.0589, 42.3601), 4326));

pgvector 测试

-- 创建向量表
CREATE TABLE items (
    id SERIAL PRIMARY KEY,
    embedding VECTOR(3)
);

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

-- 向量相似度查询
SELECT * FROM items ORDER BY embedding <-> '[3,1,2]' LIMIT 5;

TimescaleDB 测试

-- 创建时序表
CREATE TABLE sensor_data (
    time TIMESTAMPTZ NOT NULL,
    sensor_id INTEGER,
    temperature DOUBLE PRECISION,
    humidity DOUBLE PRECISION
);

-- 转换为超表
SELECT create_hypertable('sensor_data', 'time');

-- 插入时序数据
INSERT INTO sensor_data VALUES 
(NOW(), 1, 23.5, 65.2),
(NOW() - INTERVAL '1 hour', 1, 22.8, 64.1);

连接配置

IDE 连接参数

Host: localhost
Port: 5432
Database: devdb (或 postgres)
Username: postgres
Password: [您在.env中设置的密码]

命令行连接

# 使用 Docker 容器内的 psql
docker exec -it postgres-all-extensions psql -U postgres -d devdb

# 使用外部 psql (需要安装 PostgreSQL 客户端)
PGPASSWORD=your_password psql -h localhost -p 5432 -U postgres -d devdb

管理命令

启动/停止服务

# 启动服务
docker-compose up -d

# 停止服务
docker-compose down

# 重启服务
docker-compose restart

# 查看日志
docker-compose logs -f

数据备份与恢复

# 备份数据库
docker exec postgres-all-extensions pg_dump -U postgres devdb > backup.sql

# 恢复数据库
docker exec -i postgres-all-extensions psql -U postgres devdb < backup.sql

性能监控

# 查看容器资源使用
docker stats postgres-all-extensions

# 查看数据库连接
docker exec postgres-all-extensions psql -U postgres -c "SELECT * FROM pg_stat_activity;"

安全建议

修改默认密码：确保在 .env 文件中设置强密码
网络安全：生产环境中限制 pg_hba.conf 的访问范围
数据加密：考虑启用 SSL/TLS 连接
定期备份：建立自动化备份策略
更新维护：定期更新 PostgreSQL 和扩展版本

版本信息

PostgreSQL: 15.14
PostGIS: 3.6.0
pgvector: 0.5.1
TimescaleDB: 2.13.0

许可证

本项目遵循 MIT 许可证。各个扩展遵循其各自的许可证条款。

Previous Post Next Post