oorabona/postgres

PostgreSQL数据库容器


生产就绪的PostgreSQL容器，提供多种针对不同工作负载优化的版本：AI/RAG、分析或通用用途。基于Alpine Linux构建，包含预编译扩展。

快速开始

bash
# 基础PostgreSQL（最小镜像）
docker pull ghcr.io/oorabona/postgres:17-alpine

# 带pgvector的AI/RAG应用版本
docker pull ghcr.io/oorabona/postgres:17-vector-alpine

# 带分析扩展的版本
docker pull ghcr.io/oorabona/postgres:17-analytics-alpine

# 带TimescaleDB的时序数据版本
docker pull ghcr.io/oorabona/postgres:17-timeseries-alpine

# 带PostGIS的地理空间数据版本
docker pull ghcr.io/oorabona/postgres:17-spatial-alpine

# 带Citus的分布式PostgreSQL版本
docker pull ghcr.io/oorabona/postgres:17-distributed-alpine

# 包含所有扩展的完整版本
docker pull ghcr.io/oorabona/postgres:17-full-alpine

可用版本

版本详情

基础版 (*-alpine)

标准PostgreSQL，包含内置扩展：

• pg_stat_statements - 查询统计
• pgcrypto - 加密函数
• uuid-ossp - UUID生成
• btree_gin、btree_gist - 额外索引类型
• pg_trgm - 用于模糊搜索的三元组匹配

向量版 (*-vector-alpine)

包含基础版 + pgvector，适用于AI/ML工作负载：

sql
-- 存储来自OpenAI、Anthropic等的嵌入向量
CREATE TABLE documents (
    id SERIAL PRIMARY KEY,
    content TEXT,
    embedding vector(1536)  -- OpenAI ada-002维度
);

-- 创建HNSW索引以实现快速相似度搜索
CREATE INDEX ON documents USING hnsw (embedding vector_cosine_ops);

-- 查找相似文档
SELECT * FROM documents
ORDER BY embedding <=> '[0.1, 0.2, ...]'::vector
LIMIT 10;

分析版 (*-analytics-alpine)

包含基础版 + 数据仓库扩展：

• pg_partman - 时序数据自动分区管理
• hypopg - 用于查询规划的假设索引
• pg_qualstats - 用于索引建议的谓词统计
• pg_buffercache - 缓冲缓存检查
• pg_prewarm - 数据预加载

sql
-- 为时序表自动分区
SELECT partman.create_parent(
    p_parent_table := 'public.events',
    p_control := 'created_at',
    p_interval := 'daily'
);

-- 检查假设索引的收益
SELECT hypopg_create_index('CREATE INDEX ON users(email)');
EXPLAIN SELECT * FROM users WHERE email = 'test@example.com';

时序版 (*-timeseries-alpine)

包含基础版 + 时序工作负载扩展：

• TimescaleDB - 高性能时序数据库
• pg_partman - 自动分区管理

sql
-- 创建时序数据超表
CREATE TABLE metrics (
    time TIMESTAMPTZ NOT NULL,
    device_id TEXT,
    temperature DOUBLE PRECISION
);

SELECT create_hypertable('metrics', by_range('time'));

-- 使用time_bucket进行聚合
SELECT time_bucket('1 hour', time) AS bucket,
       device_id,
       AVG(temperature) AS avg_temp
FROM metrics
WHERE time > NOW() - INTERVAL '1 day'
GROUP BY bucket, device_id
ORDER BY bucket DESC;

地理空间版 (*-spatial-alpine)

包含基础版 + PostGIS地理空间扩展：

• PostGIS - 地理空间类型、索引和函数
• pg_cron - 定时任务
• pg_ivm - 增量物化视图

sql
CREATE EXTENSION postgis;

CREATE TABLE places (
    id SERIAL PRIMARY KEY,
    name TEXT,
    location GEOGRAPHY(POINT, 4326)
);

-- 查找10公里范围内的地点
SELECT name, ST_Distance(location, ST_MakePoint(-73.99, 40.73)::geography) AS dist
FROM places
WHERE ST_DWithin(location, ST_MakePoint(-73.99, 40.73)::geography, 10000)
ORDER BY dist;

分布式版 (*-distributed-alpine)

包含基础版 + Citus水平扩展：

• Citus - 用于多节点集群的分布式PostgreSQL

sql
-- 创建分布式表
SELECT citus_set_coordinator_host('coordinator', 5432);
SELECT create_distributed_table('events', 'tenant_id');

-- 或创建引用表（跨节点复制）
SELECT create_reference_table('config');

-- 查询自动分布式执行
SELECT tenant_id, COUNT(*)
FROM events
GROUP BY tenant_id;

完整版 (*-full-alpine)

包含所有扩展，适用于开发和测试。集成了其他所有版本（向量、分析、时序、地理空间、分布式）的功能。

支持版本

镜像标签格式

ghcr.io/oorabona/postgres:{version}-{flavor}-alpine

示例：

• 17-alpine 或 17-base-alpine - PG17基础版
• 17-vector-alpine - PG17向量版
• 16-analytics-alpine - PG16分析版
• 17-full-alpine - PG17完整版

使用方法

Docker Compose

yaml
services:
  postgres:
    image: ghcr.io/oorabona/postgres:17-vector-alpine
    environment:
      POSTGRES_DB: myapp
      POSTGRES_USER: myuser
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U myuser -d myapp"]
      interval: 30s
      timeout: 10s
      retries: 3

volumes:
  postgres_data:

Docker Run

bash
docker run -d \
  --name postgres \
  -e POSTGRES_DB=myapp \
  -e POSTGRES_USER=myuser \
  -e POSTGRES_PASSWORD=secret \
  -p 5432:5432 \
  -v postgres_data:/var/lib/postgresql/data \
  ghcr.io/oorabona/postgres:17-vector-alpine

本地构建

bash
# 构建基础版
docker build --build-arg VERSION=17-alpine --build-arg FLAVOR=base -t postgres:17 .

# 构建向量版
docker build --build-arg VERSION=17-alpine --build-arg FLAVOR=vector -t postgres:17-vector .

# 构建包含所有扩展的版本
docker build --build-arg VERSION=17-alpine --build-arg FLAVOR=full -t postgres:17-full .

配置

环境变量

初始化脚本

将.sql或.sh文件放在挂载到/docker-entrypoint-initdb.d/的卷中：

yaml
volumes:
  - ./init:/docker-entrypoint-initdb.d

脚本在容器首次启动时按字母顺序执行：

init/
├── 01-schema.sql
├── 02-seed-data.sql
└── 03-setup.sh

性能调优

对于生产工作负载，考虑在postgresql.conf中设置以下参数：

ini
# 内存
shared_buffers = 256MB
effective_cache_size = 1GB
work_mem = 16MB
maintenance_work_mem = 128MB

# 预写日志
wal_buffers = 16MB
checkpoint_completion_target = 0.9
max_wal_size = 2GB

# 查询规划器
random_page_cost = 1.1
effective_io_concurrency = 200
default_statistics_target = 100

扩展参考

已编译扩展

内置扩展

所有版本均包含以下PostgreSQL contrib扩展：

• pg_stat_statements - 查询性能统计
• pgcrypto - 加密函数
• uuid-ossp - UUID生成
• btree_gin / btree_gist - 额外索引类型
• pg_trgm - 模糊字符串匹配

分析版和完整版还包含：

• pg_buffercache - 共享缓冲区检查
• pg_prewarm - 缓冲区缓存预加载
• file_fdw / postgres_fdw - 外部数据包装器（仅完整版）

安全

凭证管理

切勿硬编码密码：

yaml
# 不推荐
environment:
  POSTGRES_PASSWORD: mysecretpassword

# 推荐 - 使用环境变量
environment:
  POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}

# 更推荐 - 使用Docker secrets
secrets:
  postgres_password:
    file: ./secrets/postgres_password.txt

运行时强化

yaml
services:
  postgres:
    image: ghcr.io/oorabona/postgres:17-alpine
    read_only: true
    tmpfs:
      - /tmp
      - /run/postgresql
    cap_drop:
      - ALL
    cap_add:
      - CHOWN
      - SETGID
      - SETUID
      - DAC_OVERRIDE
    security_opt:
      - no-new-privileges:true
    ports:
      - "127.0.0.1:5432:5432"  # 仅本地访问

网络安全

• 绑定到127.0.0.1以仅允许本地访问
• 使用Docker网络进行服务通信
• 远程连接时启用SSL

监控

健康检查

bash
# 检查PostgreSQL是否就绪
docker exec postgres pg_isready -U myuser -d myapp

# 连接测试
docker exec postgres psql -U myuser -d myapp -c "SELECT 1"

查询统计

sql
-- 启用pg_stat_statements（所有版本已默认启用）
-- 前10条最慢查询
SELECT query, calls, mean_exec_time, total_exec_time
FROM pg_stat_statements
ORDER BY mean_exec_time DESC
LIMIT 10;

缓冲缓存分析（分析版/完整版）

sql
-- 按表的缓冲缓存使用情况
SELECT c.relname,
       count(*) AS buffers,
       pg_size_pretty(count(*) * 8192) AS size
FROM pg_buffercache b
JOIN pg_class c ON b.relfilenode = c.relfilenode
GROUP BY c.relname
ORDER BY buffers DESC
LIMIT 10;

备份与恢复

创建备份

bash
# SQL转储
docker exec postgres pg_dump -U myuser myapp > backup.sql

# 二进制备份（大型数据库更快）
docker exec postgres pg_basebackup -U myuser -D /backup -Ft -z

恢复

bash
# 从SQL转储恢复
docker exec -i postgres psql -U myuser -d myapp < backup.sql

# 从备份创建新数据库
docker exec postgres createdb -U myuser myapp_restored
docker exec -i postgres psql -U myuser -d myapp_restored < backup.sql

版本管理

bash
# 检查当前版本
./version.sh

# 检查最新上游版本
./version.sh latest

# 输出格式（JSON用于CI集成）
./version.sh --json

架构

postgres/
├── Dockerfile              # 多版本构建
├── variants.yaml           # 版本/类型矩阵
├── extensions/
│   ├── config.yaml         # 扩展定义
│   ├── build/              # 扩展构建脚本
│   └── artifacts/          # 已编译扩展tar包
├── flavors/
│   ├── base.yaml           # 基础版配置
│   ├── vector.yaml         # 向量版配置
│   ├── analytics.yaml      # 分析版配置
│   ├── timeseries.yaml     # 时序版配置
│   ├── spatial.yaml        # 地理空间版配置
│   ├── distributed.yaml    # 分布式版配置
│   └── full.yaml           # 完整版配置
└── custom-init/            # 自定义初始化脚本

创建自定义版本

您可以通过组合扩展创建自己的版本，以满足特定需求。

步骤1：创建版本定义

在flavors/中创建新文件：

yaml
# flavors/myapp.yaml
name: myapp
description: "我的应用的自定义版本"
extends: base

# 选择要包含的已编译扩展
extensions:
  - pgvector      # 用于AI功能