Docker 中安装 PostgreSQL 16 并配置 pgvector一、环境准备 1. 确认 Docker 版本

一、环境准备

1. 确认 Docker 版本

docker --version
# Docker version 28.3.3, build 980b856
# 如版本低于27.0，请先升级

2. 创建专用网络（生产环境必备）

docker network create pg-network

作用：

隔离数据库流量
避免端口冲突
方便后续扩展（如连接应用容器）

二、PostgreSQL 16 容器化部署

1. 搜索镜像

docker search postgres

2. 拉取官方镜像（指定版本）

docker pull postgres:16

3. 创建持久化数据卷

docker volume create pgdata

生产环境重要性：

容器重启/删除时数据不丢失
独立于容器生命周期管理
方便备份迁移

4. 启动 PostgreSQL 容器（生产优化版）

docker run -d \
  --name postgres \
  --network pg-network \
  -p 5432:5432 \
  -e POSTGRES_PASSWORD=123456 \
  -e POSTGRES_USER=ahjmkj \
  -e POSTGRES_DB=openAgent \
  -e TZ=Asia/Shanghai \
  -e POSTGRES_INITDB_ARGS="--data-checksums" \
  -v pgdata:/var/lib/postgresql/data \
  -v /etc/localtime:/etc/localtime:ro \
  --restart=unless-stopped \
  --memory=4g \
  --cpus=2 \
  --health-cmd="pg_isready -U ahjmkj" \
  --health-interval=30s \
  --health-timeout=5s \
  --health-retries=3 \
  postgres:16 \
  -c max_connections=200 \
  -c shared_buffers=1GB

参数详解：

参数说明生产环境重要性 --network pg-network 加入专用网络 ⭐⭐⭐⭐⭐ 网络安全隔离

-e POSTGRES_PASSWORD 管理员密码 ⭐⭐⭐⭐⭐ 必须使用强密码

-e TZ=Asia/Shanghai 设置时区 ⭐⭐⭐⭐ 避免时间相关错误

-v pgdata:/var/... 挂载数据卷 ⭐⭐⭐⭐⭐ 数据持久化

--restart=unless-stopped 自动重启策略 ⭐⭐⭐⭐ 高可用保障

--memory=4g --cpus=2 资源限制 ⭐⭐⭐⭐ 防止单容器耗尽资源

--health-cmd 健康检查 ⭐⭐⭐ 自动故障检测

-c max_connections=200 最大连接数 ⭐⭐⭐ 根据业务需求调整

-c shared_buffers=1GB 共享内存大小 ⭐⭐⭐ 性能优化关键参数

三、验证与连接

1. 检查容器状态

docker ps --format "table {{.ID}}\t{{.Names}}\t{{.Status}}\t{{.Ports}}"

输出：
CONTAINER ID  NAMES          STATUS                    PORTS
a1b2c3d4e5f6  prod-postgres  Up 2 minutes (healthy)   0.0.0.0:5432->5432/tcp

2. 查看实时日志

docker logs -f postgres

输出：
PostgreSQL init process complete; ready for start up
database system is ready to accept connections

3. 命令行连接测试

docker exec -it postgres \
  psql -U ahjmkj -d openAgent -c "SELECT version();"

输出：
PostgreSQL 16.3 on x86_64-pc-linux-gnu, compiled by gcc...

4. 客户端工具连接

使用 DBeaver/pgAdmin 连接：

Host: 服务器IP
Port: 5432
Database: openAgent
Username: ahjmkj
Password: 123456

四、生产环境高级配置

1. 配置文件自定义

# 创建配置目录
mkdir -p /docker/pg-config

# 生成默认配置
docker run --rm postgres:16 \
  cat /usr/share/postgresql/postgresql.conf.sample > /docker/pg-config/postgresql.conf

# 编辑配置文件（优化关键参数）
nano /docker/pg-config/postgresql.conf

关键参数建议：

listen_addresses = '*'  # 允许所有网络接口
max_connections = 250   # 根据实际负载调整
shared_buffers = 1GB    # 建议分配内存的25%
work_mem = 16MB         # 每个操作的内存
maintenance_work_mem = 512MB  # 维护操作内存
synchronous_commit = off  # 异步提交提升性能

重新启动容器：

docker run ... \
  -v /docker/pg-config/postgresql.conf:/etc/postgresql/postgresql.conf \
  postgres:16 -c 'config_file=/etc/postgresql/postgresql.conf'

2. 定期备份方案

创建备份脚本 (pg-backup.sh):

#!/bin/bash
BACKUP_DIR=/backups/pg
DATE=$(date +%Y%m%d_%H%M%S)

docker exec prod-postgres \
  pg_dump -U ahjmkj -Fc openAgent > $BACKUP_DIR/prod_db_$DATE.dump

# 保留最近7天备份
find $BACKUP_DIR -mtime +7 -delete

设置定时任务： crontab -e

每天凌晨2点备份

0 2 * * * /path/to/pg-backup.sh

3. 监控配置

使用内置统计收集器：

ALTER SYSTEM SET track_activities = on;
ALTER SYSTEM SET track_counts = on;
ALTER SYSTEM SET track_io_timing = on;
SELECT pg_reload_conf();

推荐监控工具：

Prometheus + Grafana（配合 postgres_exporter）
pgAdmin 4 监控面板
Datadog / New Relic

五、故障排查与维护

1. 常见问题解决

问题1：端口冲突

# 检查占用5432端口的进程
sudo lsof -i :5432

# 解决方案：改用其他端口
docker run ... -p 5433:5432 ...

问题2：忘记管理员密码

# 进入容器bash
docker exec -it postgres bash

# 以postgres用户连接
psql -U postgres

# 重置密码
ALTER USER ahjmkj WITH PASSWORD '123456';

问题3：磁盘空间不足

# 查看容器磁盘使用
docker system df

# 清理无用容器/镜像
docker system prune -f

# 扩展数据卷
docker volume inspect pgdata # 找到实际路径
# 然后扩展对应磁盘分区

2. 关键维护命令

查看资源使用：

docker stats postgres

进入维护模式：

docker exec -it postgres bash
psql -U ahjmkj -d openAgent

日志分析：

docker logs --tail 100 postgres | grep -i error

六、安全加固建议

网络层安全

# 限制访问IP（仅允许应用服务器）
docker network create --subnet=10.1.0.0/16 pg-secure-network

2. SSL加密连接

# 启动容器时添加SSL参数
-e POSTGRES_SSL=on \
-e POSTGRES_SSL_CERT_FILE=/etc/ssl/certs/server.crt \
-e POSTGRES_SSL_KEY_FILE=/etc/ssl/private/server.key

3. 定期轮换凭证

# 每月更新密码
ALTER USER ahjmkj WITH PASSWORD 'NewP@ssw0rd_$(date +%Y%m)';

4. 审计日志

ALTER SYSTEM SET log_statement = 'all';
SELECT pg_reload_conf();

七、安装pgvector 扩展

进入容器

docker exec -it postgre bash

2. 容器内安装依赖

apt update
apt install -y git build-essential postgresql-server-dev-16

3. 容器内编译并安装 pgvector

cd /tmp
git clone https://github.com/pgvector/pgvector.git
cd pgvector
make
make install

【容器环境无法连接github 网络的解决方案】：这里，我们的容器环境无法连接 github 网络，所以我们先本地PC环境手动下载 github 上的 pgvector 文件，再手动上传至服务器环境中，再通过 docker cp 命令将服务器上的文件拷贝至容器内。注意：如果需要数据持久化，一定要使用Volume卷挂载的方式！！！

注意：如果需要数据持久化，一定要使用Volume卷挂载的方式！！！

docker cp 不会持久化数据，如果容器被删除（docker rm），复制的文件会丢失。
如果需要持久化存储，应该使用 Docker Volume（卷）或 Bind Mount（绑定挂载）：

# 命令语法
docker cp /源文件夹 容器名或ID:/容器内/目标路径/

# 这里，我们使用的命令为：
docker cp /Users/dashanshushu/soft/pgvector  5e2d98d35927:/tmp

其中 010f4d6fa849 为容器ID。

拷贝成功后，再进入容器内的 /tmp/pgvector 目录，依次运行：

docker exec -it postgres
cd /tmp/pgvector
make
make install

4. 检查扩展文件是否安装成功

ls -l /usr/share/postgresql/15/extension/vector*

启用pgvector扩展

psql -U ahjmkj -d openAgent

psql：PostgreSQL 的交互式终端程序
-U postgres：指定使用 postgres 用户身份连接
-d postgres：指定连接到名为 postgres 的默认数据库

连接成功后出现如下界面：

然后，使用PostgreSQL 数据库中的 SQL 命令，安装名为 vector 的扩展(extension)：

# -- 在psql中执行
CREATE EXTENSION vector;
# 或
CREATE EXTENSION IF NOT EXISTS vector;  # 仅在扩展未安装时执行

出现如下界面说明创建成功：

关于vector 扩展：

这是 PostgreSQL 的一个扩展，用于支持向量(vector)数据类型和向量相似性搜索；
常用于机器学习、AI应用，特别是需要存储和查询嵌入向量(embeddings)的场景；
提供向量运算、相似度计算(如余弦相似度、欧氏距离等)功能。

验证安装是否成功

基于 PostgreSQL 的查询语句，检查数据库中是否已安装名为 vector 的扩展(extension)：

SELECT * FROM pg_extension WHERE extname = 'vector';

出现如下界面：