PostgreSQL 安装手册：从 Docker 到 pgvector 的完整实践
PostgreSQL 安装手册
本文面向本项目的向量数据库学习场景，也适合作为普通后端开发机的 PostgreSQL 安装参考。建议优先使用 Docker 安装，因为它最容易复现、最不污染本机环境；如果要长期在本机开发，再考虑 Homebrew、apt 或系统包管理器安装。
1. 安装方案选择
| 场景 | 推荐方案 | 说明 |
| --- | --- | --- |
| 学习本项目、快速实验 pgvector | Docker Compose | 最省心，和项目配置一致 |
| macOS 本机长期开发 | Homebrew | 方便启动、停止、升级 |
| Ubuntu/Debian 服务器 | apt 或 PGDG APT 仓库 | 系统服务化管理方便 |
| 只需要命令行客户端 | PostgreSQL client / libpq | 只安装 psql、pg_dump 等工具 |
| 生产环境 | 云数据库或系统包部署 | 不建议直接照本地 Docker 简化配置上线 |
版本建议：
- 学习和本地开发：选择固定主版本，例如 PostgreSQL 16、17 或 18。
- 本项目已有 Docker 配置：当前使用
pgvector/pgvector:pg16。 - 生产环境不要使用
latest标签，避免自动升级导致不可控变化。
2. Docker 安装 PostgreSQL + pgvector
这是本项目最推荐的方式。
2.1 前置条件
docker --version
docker compose version
2.2 使用本项目 Docker Compose
cd /Users/yangshuangjun/learn/book
docker compose up -d postgres
docker compose ps
预期看到 postgres 服务处于 running 状态。
2.3 连接数据库
本项目默认连接信息：
host: localhost
port: 5432
user: postgres
password: postgres
database: vectordb
本机有 psql 时：
psql "postgresql://postgres:postgres@localhost:5432/vectordb"
本机没有 psql 时，进入容器执行：
docker exec -it vector-db-course-postgres psql -U postgres -d vectordb
2.4 初始化 pgvector schema
psql "postgresql://postgres:postgres@localhost:5432/vectordb" -f sql/schema_pgvector.sql
如果你只想先验证扩展：
CREATE EXTENSION IF NOT EXISTS vector;
SELECT extname, extversion
FROM pg_extension
WHERE extname = 'vector';
2.5 停止和删除
停止容器：
docker compose stop postgres
停止并删除容器：
docker compose down
删除数据卷并清空数据库：
docker compose down -v
注意：-v 会删除数据库数据。
3. macOS 使用 Homebrew 安装
适合长期在 Mac 上做本机开发。
3.1 安装 PostgreSQL
安装指定版本，例如 PostgreSQL 17：
brew install postgresql@17
或安装 Homebrew 默认版本：
brew install postgresql
3.2 配置 PATH
Apple Silicon Mac 常见路径：
echo 'export PATH="/opt/homebrew/opt/postgresql@17/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
Intel Mac 常见路径：
echo 'export PATH="/usr/local/opt/postgresql@17/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
检查：
psql --version
postgres --version
3.3 启动服务
brew services start postgresql@17
brew services info postgresql@17
停止：
brew services stop postgresql@17
重启：
brew services restart postgresql@17
3.4 创建数据库
createdb vectordb
psql vectordb
进入 psql 后查看当前连接：
\conninfo
退出：
\q
3.5 只安装 psql 客户端
如果你只想连接 Docker 或远程 PostgreSQL，不想安装完整服务：
brew install libpq
Apple Silicon Mac：
echo 'export PATH="/opt/homebrew/opt/libpq/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
4. Ubuntu / Debian 安装
4.1 使用系统默认仓库
sudo apt update
sudo apt install -y postgresql postgresql-contrib
检查服务：
sudo systemctl status postgresql
启动并设置开机自启：
sudo systemctl start postgresql
sudo systemctl enable postgresql
4.2 创建数据库和用户
sudo -iu postgres
psql
CREATE DATABASE vectordb;
CREATE USER vector_user WITH PASSWORD 'change_me';
GRANT ALL PRIVILEGES ON DATABASE vectordb TO vector_user;
\q
4.3 使用 PostgreSQL 官方 PGDG APT 仓库
如果你需要安装特定主版本，可以使用 PostgreSQL Global Development Group 维护的 APT 仓库。具体命令建议以官方页面为准：
- Ubuntu: https://www.postgresql.org/download/linux/ubuntu/
- Debian: https://www.postgresql.org/download/linux/debian/
安装指定版本示例：
sudo apt install -y postgresql-17 postgresql-client-17
5. 安装 pgvector
5.1 Docker 方式
本项目已经使用带 pgvector 的镜像：
image: pgvector/pgvector:pg16
因此容器启动后只需要在数据库里启用扩展：
CREATE EXTENSION IF NOT EXISTS vector;
5.2 Ubuntu / Debian 包方式
如果使用 PGDG 仓库，通常可以安装对应版本的 pgvector 包：
sudo apt install -y postgresql-17-pgvector
进入数据库后启用扩展：
CREATE EXTENSION IF NOT EXISTS vector;
5.3 macOS Homebrew
brew install pgvector
然后进入数据库执行：
CREATE EXTENSION IF NOT EXISTS vector;
如果 PostgreSQL 有多个版本，注意 pgvector 是否安装到了你正在运行的 PostgreSQL 版本对应目录。
6. 常用 psql 命令
连接数据库：
psql "postgresql://USER:PASSWORD@HOST:PORT/DBNAME"
常用元命令：
\l -- 列出数据库
\c vectordb -- 切换数据库
\dt -- 列出表
\d table_name -- 查看表结构
\dx -- 查看扩展
\conninfo -- 查看当前连接
\q -- 退出
执行 SQL 文件：
psql "postgresql://postgres:postgres@localhost:5432/vectordb" -f sql/schema_pgvector.sql
7. 配置文件位置
Docker 数据目录由 volume 管理：
volumes:
- pgvector-data:/var/lib/postgresql/data
查看 Docker volume：
docker volume ls
macOS Homebrew：
brew services info postgresql@17
brew --prefix postgresql@17
Ubuntu / Debian 常见配置文件：
/etc/postgresql/<version>/main/postgresql.conf
/etc/postgresql/<version>/main/pg_hba.conf
重载配置：
sudo systemctl reload postgresql
重启服务：
sudo systemctl restart postgresql
8. 连接与权限配置
本机开发通常只监听 localhost：
listen_addresses = 'localhost'
如果需要远程连接，才考虑：
listen_addresses = '*'
远程连接必须配合防火墙、强密码和 pg_hba.conf，不要直接暴露到公网。
pg_hba.conf 示例：
host all all 127.0.0.1/32 scram-sha-256
host all all 192.168.1.0/24 scram-sha-256
9. 备份与恢复
导出单库：
pg_dump "postgresql://postgres:postgres@localhost:5432/vectordb" > vectordb.sql
恢复：
psql "postgresql://postgres:postgres@localhost:5432/vectordb" < vectordb.sql
自定义格式备份：
pg_dump -Fc "postgresql://postgres:postgres@localhost:5432/vectordb" -f vectordb.dump
恢复自定义格式：
pg_restore -d "postgresql://postgres:postgres@localhost:5432/vectordb" vectordb.dump
10. 本项目验证步骤
启动数据库：
cd /Users/yangshuangjun/learn/book
docker compose up -d postgres
初始化 schema：
psql "postgresql://postgres:postgres@localhost:5432/vectordb" -f sql/schema_pgvector.sql
验证扩展：
psql "postgresql://postgres:postgres@localhost:5432/vectordb" -c "SELECT extname, extversion FROM pg_extension WHERE extname = 'vector';"
验证表：
psql "postgresql://postgres:postgres@localhost:5432/vectordb" -c "\dt"
预期能看到：
documents
chunks
embeddings
11. 常见问题
11.1 端口 5432 被占用
lsof -i :5432
解决方式：
- 停掉本机 PostgreSQL。
- 或修改 Docker Compose 端口，例如
"5433:5432"。
连接时对应改成：
psql "postgresql://postgres:postgres@localhost:5433/vectordb"
11.2 psql: command not found
macOS：
brew install libpq
Ubuntu/Debian：
sudo apt install -y postgresql-client
11.3 password authentication failed
检查：
- 用户名是否正确。
- 密码是否正确。
- 连接端口是否是你期望的 PostgreSQL 实例。
- Docker volume 是否复用了旧密码初始化的数据。
学习环境可删除 volume 重建：
docker compose down -v
docker compose up -d postgres
11.4 extension "vector" is not available
说明当前 PostgreSQL 没有安装 pgvector 扩展文件。
解决：
- Docker：确认镜像是
pgvector/pgvector:<version>，不是普通postgres:<version>。 - Ubuntu/Debian：安装
postgresql-<version>-pgvector。 - macOS：安装
brew install pgvector，并确认 PostgreSQL 版本匹配。
11.5 数据库启动但连接不上
docker compose logs postgres
docker compose ps
psql "postgresql://postgres:postgres@localhost:5432/vectordb"
12. 安全提醒
学习环境可以使用简单密码：
postgres / postgres
生产环境不要这样做。至少需要：
- 使用强密码。
- 不暴露公网 5432。
- 使用最小权限用户。
- 定期备份。
- 配置监控和告警。
- 使用云数据库安全组或内网访问。
- 对重要数据启用审计和加密策略。
13. 参考资料
- PostgreSQL macOS 下载：https://www.postgresql.org/download/macosx/
- PostgreSQL Ubuntu 安装：https://www.postgresql.org/download/linux/ubuntu/
- PostgreSQL Debian 安装：https://www.postgresql.org/download/linux/debian/
- PostgreSQL PGDG APT 仓库：https://apt.postgresql.org/
- Postgres Docker 官方镜像：https://hub.docker.com/_/postgres
- Docker Postgres 文档：https://github.com/docker-library/docs/blob/master/postgres/README.md
- pgvector Docker 镜像：https://hub.docker.com/r/pgvector/pgvector
- pgvector 项目文档：https://github.com/pgvector/pgvector