Docker 部署 pgVector 笔记

1. 最终 docker-compose.yml（项目根目录）

▼
yaml
复制代码
version: '3.8'

services:
  pgvector:
    image: pgvector/pgvector:pg16        # 官方镜像，已内置 vector 扩展
    container_name: pgvector
    restart: always
    environment:
      POSTGRES_USER: yuan                # 超级用户
      POSTGRES_PASSWORD: 123456          # 可 ALTER USER 随时修改
      POSTGRES_DB: yuan_ai_agent         # 默认库
    ports:
      - "5432:5432"                      # 宿主机端口
    volumes:
      - ./pgvector_data:/var/lib/postgresql/data   # 与 yml 同目录持久化
    networks:
      - pgvector_network

networks:
  pgvector_network:
    driver: bridge

目录结构

▼
text
复制代码
your-project/
├─ docker-compose.yml
└─ pgvector_data/          # 自动创建，无需手动管理

2. 一键启动 / 关闭

▼
bash
复制代码
# 启动（首次会自动拉取镜像）
docker-compose up -d

# 查看日志
docker-compose logs -f

# 停止并删除容器
docker-compose down

# 同时删除数据卷（谨慎）
docker-compose down -v

3. 连接方式汇总

场景	命令 / URL
宿主机 CLI	psql -h localhost -p 5432 -U yuan -d yuan_ai_agent -W
容器内 CLI	docker exec -it pgvector psql -U yuan -d yuan_ai_agent
JDBC	jdbc:postgresql://localhost:5432/yuan_ai_agent?user=yuan&password=123456&ssl=false
Python	psycopg2.connect(host='localhost', port=5432, user='yuan', password='123456', dbname='yuan_ai_agent')

4. 启用向量扩展（仅需一次）

▼
sql
复制代码
-- 连库后执行
CREATE EXTENSION IF NOT EXISTS vector;
SELECT extname FROM pg_extension WHERE extname = 'vector';  -- 验证

5. 快速体验：建表 + 相似度查询

▼
sql
复制代码
-- 建表
CREATE TABLE items (
    id   SERIAL PRIMARY KEY,
    emb  vector(3)
);

-- 插入
INSERT INTO items (emb) VALUES
  ('[1,2,3]'),
  ('[4,5,6]');

-- 欧氏距离近邻查询
SELECT id, emb, emb <-> '[1,2,3]' AS distance
FROM items
ORDER BY emb <-> '[1,2,3]'
LIMIT 5;

6. 修改用户密码

▼
bash
复制代码
# 连库后
ALTER USER yuan WITH PASSWORD '新密码';

7. 允许远程访问（可选）

容器内执行

▼
bash
复制代码
echo "host all yuan 0.0.0.0/0 md5" >> /var/lib/postgresql/data/pg_hba.conf
docker restart pgvector

8. 日常排错速查

现象	可能原因	快速处理
password authentication failed	密码错 / 远程未放行	改密码 + 加 hba 记录
invalid length of startup packet	非 Postgres 协议连 5432	确认客户端为 psql/JDBC
端口冲突	宿主机 5432 被占用	改宿主机端口 5433:5432
数据丢失	误删卷	仅备份 ./pgvector_data 目录即可

9. 备份与恢复

▼
bash
复制代码
# 备份（宿主机执行）
docker exec pgvector pg_dump -U yuan -Fd yuan_ai_agent -f /tmp/db.dump
docker cp pgvector:/tmp/db.dump ./db.dump

# 恢复
docker cp ./db.dump pgvector:/tmp/db.dump
docker exec pgvector pg_restore -U yuan -d yuan_ai_agent -Fd /tmp/db.dump

10. 常用命令备忘录

▼
bash
复制代码
docker-compose ps                 # 容器状态
docker exec -it pgvector bash     # 进容器
docker logs pgvector --tail 50    # 实时日志
docker-compose pull               # 更新镜像
docker-compose up -d --force-recreate  # 重建容器

至此，pgVector 已可稳定运行于 Docker 环境，支持本地开发与远程服务。

---

各个系统安装docker 参见 https://zhuanlan.zhihu.com/p/1924864194345431337