本地 PostgreSQL 配置指南

📋 概述

本指南帮助您配置本地 PostgreSQL 数据库用于 MBE 开发环境。

🔧 前置要求

• 已安装 PostgreSQL（推荐版本 12+）
• 已安装 pgAdmin 4 或 psql 命令行工具
• 管理员权限（用于创建数据库和用户）
• 重要: pgvector 扩展（用于向量搜索）

⚠️ pgvector 扩展安装

MBE 需要 pgvector 扩展用于向量相似性搜索。有两种方式：

方式 1: 使用 Docker PostgreSQL（推荐，最简单）

使用 Docker 的 pgvector/pgvector 镜像，已包含 pgvector：

# 启动包含 pgvector 的 PostgreSQL
docker run -d \
  --name mbe-postgres-local \
  -e POSTGRES_USER=mbe \
  -e POSTGRES_PASSWORD=mbe_dev_password \
  -e POSTGRES_DB=mbe_dev \
  -p 5432:5432 \
  pgvector/pgvector:pg16

方式 2: 在本地 PostgreSQL 安装 pgvector（需要编译）

Windows 安装步骤：

1. 安装编译工具：

   • Visual Studio 2019+ (包含 C++ 构建工具)
   • Git for Windows

2. 下载并编译 pgvector：

   git clone https://github.com/pgvector/pgvector.git
   cd pgvector
   
   # 确保 pg_config 在 PATH 中
   # 通常位于: C:\Program Files\PostgreSQL\16\bin\pg_config.exe
   
   make
   make install
   

3. 配置 PostgreSQL：

   • 编辑 postgresql.conf（通常在 C:\Program Files\PostgreSQL\16\data\postgresql.conf）
   • 添加：shared_preload_libraries = 'pgvector'
   • 重启 PostgreSQL 服务

4. 创建扩展：

   CREATE EXTENSION vector;
   

注意: Windows 上编译 pgvector 可能比较复杂，建议使用 Docker 方式。

📝 配置步骤

1. 创建数据库和用户

使用 pgAdmin 4 或 psql 命令行工具执行以下 SQL：

-- 创建数据库
CREATE DATABASE mbe_dev;

-- 创建用户（如果不存在）
CREATE USER mbe WITH PASSWORD 'mbe_dev_password';

-- 授予权限
GRANT ALL PRIVILEGES ON DATABASE mbe_dev TO mbe;

-- 连接到 mbe_dev 数据库
\c mbe_dev

-- 授予 schema 权限
GRANT ALL ON SCHEMA public TO mbe;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON TABLES TO mbe;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON SEQUENCES TO mbe;

2. 使用 pgAdmin 4 创建数据库

1. 打开 pgAdmin 4
2. 连接到 PostgreSQL 服务器（默认：localhost:5432）
3. 右键点击 "Databases" → "Create" → "Database"
4. 设置数据库名称：mbe_dev
5. 点击 "Save"

3. 配置环境变量

编辑 .env.development 文件，设置 DATABASE_URL：

# 使用本地 PostgreSQL（默认端口 5432）
DATABASE_URL=postgresql+asyncpg://postgres:your_password@localhost:5432/mbe_dev

# 或者使用专用用户
DATABASE_URL=postgresql+asyncpg://mbe:mbe_dev_password@localhost:5432/mbe_dev

注意：

• 将 your_password 替换为您的 PostgreSQL 用户密码
• 如果使用默认的 postgres 用户，用户名是 postgres
• 如果创建了专用用户 mbe，使用该用户和密码

4. 初始化数据库表结构

运行初始化脚本：

# 如果项目有数据库迁移脚本
python scripts/init_database.py

# 或者使用 Alembic（如果配置了）
alembic upgrade head

5. 验证连接

测试数据库连接：

# 使用 Python 测试
python -c "
import asyncio
from sqlalchemy.ext.asyncio import create_async_engine

async def test():
    engine = create_async_engine('postgresql+asyncpg://postgres:your_password@localhost:5432/mbe_dev')
    async with engine.begin() as conn:
        result = await conn.execute('SELECT version()')
        print(result.fetchone())

asyncio.run(test())
"

🔍 常见问题

问题 1: 连接被拒绝

错误信息：

could not connect to server: Connection refused

解决方案：

1. 确认 PostgreSQL 服务正在运行
2. 检查端口是否正确（默认 5432）
3. 检查 pg_hba.conf 配置，确保允许本地连接

问题 2: 认证失败

错误信息：

password authentication failed for user "postgres"

解决方案：

1. 确认用户名和密码正确
2. 如果忘记密码，可以重置：

   ALTER USER postgres WITH PASSWORD 'new_password';
   

问题 3: 数据库不存在

错误信息：

database "mbe_dev" does not exist

解决方案： 按照步骤 1 创建数据库

问题 4: 权限不足

错误信息：

permission denied for schema public

解决方案： 执行以下 SQL 授予权限：

GRANT ALL ON SCHEMA public TO mbe;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON TABLES TO mbe;

📊 端口说明

🔄 切换数据库

从 Docker PostgreSQL 切换到本地 PostgreSQL

1. 停止 Docker 容器：

   docker-compose -f docker-compose.dev.yml stop postgres-dev
   

2. 更新 .env.development：

   DATABASE_URL=postgresql+asyncpg://postgres:your_password@localhost:5432/mbe_dev
   

3. 重启应用服务

从本地 PostgreSQL 切换到 Docker PostgreSQL

1. 更新 .env.development：

   DATABASE_URL=postgresql+asyncpg://mbe:mbe_dev_password@postgres-dev:5432/mbe_dev
   

2. 启动 Docker 容器：

   docker-compose -f docker-compose.dev.yml up -d postgres-dev
   

📚 相关文档

• PostgreSQL 官方文档
• pgAdmin 4 文档
• SQLAlchemy 异步引擎文档