PostgreSQL 16 + pgvector 安装（Debian）

环境要求

项目	要求
操作系统	Debian 12 / Debian 11 (x86_64)
内存	≥ 2 GB
磁盘	≥ 10 GB 可用空间
权限	root 或 sudo

---

一、更新系统并安装基础依赖

sudo apt update
sudo apt install -y curl wget gnupg lsb-release ca-certificates \
    build-essential git libreadline-dev zlib1g-dev libssl-dev \
    libxml2-dev libxslt1-dev pkg-config

---

二、添加 PostgreSQL 官方 APT 源

Debian 自带仓库中的 PostgreSQL 版本通常较旧，建议使用 PGDG 官方仓库安装 PostgreSQL 16。

2.1 导入 PGDG 仓库签名密钥

curl -fsSL https://www.postgresql.org/media/keys/ACCC4CF8.asc | \
sudo gpg --dearmor -o /usr/share/keyrings/postgresql.gpg

2.2 写入 PGDG 软件源

echo "deb [signed-by=/usr/share/keyrings/postgresql.gpg] http://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" | \
sudo tee /etc/apt/sources.list.d/pgdg.list

2.3 刷新软件包索引

sudo apt update

---

三、安装 PostgreSQL 16

sudo apt install -y postgresql-16 postgresql-client-16 \
    postgresql-server-dev-16 postgresql-contrib

安装完成后，Debian 会自动初始化默认集群。

3.1 启动并设置开机自启

sudo systemctl enable postgresql
sudo systemctl start postgresql
sudo systemctl status postgresql

输出中看到 active (running) 即表示启动成功。

3.2 查看集群状态

pg_lsclusters

期望看到类似：

Ver Cluster Port Status Owner    Data directory               Log file
16  main    5432 online postgres /var/lib/postgresql/16/main ...

---

四、安装 pgvector

4.1 方式一：APT 安装（推荐）

sudo apt install -y postgresql-16-pgvector

若提示找不到该包，使用方式二从源码编译。

4.2 方式二：源码编译安装

cd /tmp
git clone --branch v0.8.0 https://github.com/pgvector/pgvector.git
cd pgvector

make PG_CONFIG=/usr/lib/postgresql/16/bin/pg_config
sudo make install PG_CONFIG=/usr/lib/postgresql/16/bin/pg_config

---

五、配置 PostgreSQL

5.1 确认认证方式（pg_hba.conf）

Debian 下 PostgreSQL 16 的默认配置文件通常位于：

/etc/postgresql/16/main/pg_hba.conf

默认常见配置如下：

# Unix socket（系统用户 postgres 免密登录）
local   all             postgres                                peer
local   all             all                                     peer

# 本机 TCP 连接（需要密码）
host    all             all             127.0.0.1/32            scram-sha-256
host    all             all             ::1/128                 scram-sha-256

若需允许远程连接，在文件末尾追加一行：

echo "host    all             all             0.0.0.0/0               scram-sha-256" | \
sudo tee -a /etc/postgresql/16/main/pg_hba.conf

5.2 配置监听地址（仅远程访问需要）

编辑配置文件：

sudo nano /etc/postgresql/16/main/postgresql.conf

找到并修改：

listen_addresses = '*'
port = 5432

也可用命令直接修改：

sudo sed -i "s/^#listen_addresses = 'localhost'/listen_addresses = '*'/" /etc/postgresql/16/main/postgresql.conf

5.3 重启服务使配置生效

sudo systemctl restart postgresql

5.4 开放防火墙端口（如需远程访问）

如果系统启用了 ufw：

sudo ufw allow 5432/tcp
sudo ufw reload

如果未启用防火墙，可跳过此步骤。

---

六、初始化数据库用户与扩展

6.1 设置 postgres 用户密码

sudo -u postgres psql -c "ALTER USER postgres PASSWORD 'your_password';"

6.2 创建业务用户与数据库

sudo -u postgres psql << 'EOF'
CREATE USER authine WITH PASSWORD 'Authine@123456';

CREATE DATABASE cloudpivot_launcher OWNER authine;
CREATE DATABASE cloudpivot_user     OWNER authine;
CREATE DATABASE cloudpivot_report   OWNER authine;
CREATE DATABASE cloudpivot_ai       OWNER authine;
CREATE DATABASE cloudpivot_tenant   OWNER authine;

GRANT ALL PRIVILEGES ON DATABASE cloudpivot_launcher TO authine;
GRANT ALL PRIVILEGES ON DATABASE cloudpivot_user     TO authine;
GRANT ALL PRIVILEGES ON DATABASE cloudpivot_report   TO authine;
GRANT ALL PRIVILEGES ON DATABASE cloudpivot_ai       TO authine;
GRANT ALL PRIVILEGES ON DATABASE cloudpivot_tenant   TO authine;
EOF

6.3 启用 pgvector 扩展

仅 cloudpivot_ai 库需要向量能力：

sudo -u postgres psql -d cloudpivot_ai -c "CREATE EXTENSION IF NOT EXISTS vector;"

---

七、验证安装

7.1 验证 PostgreSQL 版本

sudo -u postgres psql -c "SELECT version();"

期望输出包含：PostgreSQL 16.x

7.2 验证 pgvector

sudo -u postgres psql -d cloudpivot_ai << 'EOF'
SELECT extname, extversion FROM pg_extension WHERE extname = 'vector';

CREATE TABLE test_vector (
    id SERIAL PRIMARY KEY,
    embedding vector(3)
);

INSERT INTO test_vector (embedding)
VALUES ('[1,2,3]'), ('[4,5,6]'), ('[1,1,1]');

SELECT id, embedding, embedding <=> '[1,2,3]' AS distance
FROM test_vector
ORDER BY distance
LIMIT 3;

DROP TABLE test_vector;
EOF

期望输出：查询返回按距离排序的结果，且 [1,2,3] 自身距离为 0。

7.3 创建向量索引（可选，生产环境推荐）

sudo -u postgres psql -d cloudpivot_ai << 'EOF'
CREATE TABLE documents (
    id SERIAL PRIMARY KEY,
    content TEXT,
    embedding vector(1536)
);

CREATE INDEX ON documents USING ivfflat (embedding vector_cosine_ops) WITH (lists = 100);

-- CREATE INDEX ON documents USING hnsw (embedding vector_cosine_ops);
EOF

---

八、常用管理命令

# 启动 / 停止 / 重启 / 状态
sudo systemctl start postgresql
sudo systemctl stop postgresql
sudo systemctl restart postgresql
sudo systemctl status postgresql

# 查看集群
pg_lsclusters

# 进入 psql 交互终端
sudo -u postgres psql
sudo -u postgres psql -d cloudpivot_ai

# 查看 pg_config
/usr/lib/postgresql/16/bin/pg_config

# 查看日志
sudo journalctl -u postgresql -f
sudo tail -f /var/log/postgresql/postgresql-16-main.log

---

九、常见问题排查

问题	原因	解决方法
apt update 提示 PGDG 源签名错误	密钥未正确导入	重新执行第二节
postgresql-16-pgvector 找不到	当前仓库未提供该包	使用第四节方式二源码编译
无法远程连接	监听或访问控制未配置	检查 listen_addresses 和 pg_hba.conf
CREATE EXTENSION vector 失败	pgvector 未安装成功	重新执行第四节并确认 pg_config 路径
make 编译 pgvector 失败	缺少开发头文件	安装 postgresql-server-dev-16
服务未启动	集群未正常初始化或端口冲突	用 pg_lsclusters 和 journalctl -u postgresql 排查