03_数据库配置指南：PostgreSQL 17 + pgvector 向量存储

第一阶段：启动 PostgreSQL 17 容器

我们将使用 Docker Desktop 来管理数据库。在 2026 年的开发流中，这是 Windows 环境的标准配置。

1.1 创建配置文件

在你的项目根目录 KnoSphere/ 下，新建一个文件叫 docker-compose.yml。填入以下内容：

yaml 复制代码

services:
  db:
    image: pgvector/pgvector:pg17 # 使用内置向量支持的 PostgreSQL 17 镜像
    ports:
      - "5432:5432"
    environment:
      POSTGRES_USER: admin
      POSTGRES_PASSWORD: knosphere_password
      POSTGRES_DB: knosphere
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:

1.2 启动数据库

在终端根目录下运行：

powershell 复制代码

docker-compose up -d

提示：看到 Container knosphere-db-1 Started 就表示数据库已经在后台跑起来了。

第二阶段：后端连接配置 (Python + SQLModel)

我们将回到 apps/api 目录，告诉我们的 Python 程序如何找到数据库。

2.1 添加数据库依赖

进入后端目录，利用 uv 极速安装数据库驱动和 SQLModel（这是 2026 年最流行的 ORM 框架，完美兼容 FastAPI）：

powershell 复制代码

cd apps/api
uv add psycopg2-binary

2.2 配置环境变量

在 apps/api 下新建一个 .env 文件，存放敏感信息：

plaintext 复制代码

DATABASE_URL=postgresql://admin:knosphere_password@localhost:5432/knosphere

可选优化 ：如果你计划使用 Pydantic 进行更严格的配置验证，可以安装 python-dotenv 和 pydantic：
powershell 复制代码
uv add python-dotenv pydantic

2.3 编写连接代码

在 apps/api 下新建 database.py：

python 复制代码

from sqlmodel import create_engine, SQLModel, Session
import os
from dotenv import load_dotenv

load_dotenv()
database_url = os.getenv("DATABASE_URL")
engine = create_engine(database_url)

def init_db():
    # 自动创建所有定义的表格
    SQLModel.metadata.create_all(engine)

def get_session():
    with Session(engine) as session:
        yield session

第三阶段：开启 AI 向量"外挂"

为了让知识库支持语义搜索，我们需要激活 pgvector 扩展。

3.1 创建主应用文件 (main.py)

在 apps/api 目录下，创建 main.py，内容如下：

python 复制代码

from fastapi import FastAPI
from contextlib import asynccontextmanager
from database import init_db, engine
from sqlmodel import text

@asynccontextmanager
async def lifespan(app: FastAPI):
    # 启动时执行
    with engine.connect() as conn:
        # 激活向量扩展，这是 2026 年 RAG 系统的核心
        conn.execute(text("CREATE EXTENSION IF NOT EXISTS vector;"))
        conn.commit()
    init_db()
    yield
    # 关闭时执行（如果需要清理资源）

app = FastAPI(lifespan=lifespan)

@app.get("/")
async def root():
    return {"message": "Hello from KnoSphere API!"}

@app.get("/health")
async def health():
    return {"status": "healthy"}

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)

可选步骤：如果你想要单独运行 API 服务器进行测试，可以安装 uvicorn：
powershell 复制代码
uv add uvicorn[standard]

为什么这样设计？

PostgreSQL 17: 相比旧版本，它在 JSON 性能和并发扫描上有了大幅提升，非常适合存储复杂的 AI 元数据。
pgvector 0.8+: 让你可以在同一个数据库里既查订单、又查语义相似的文档，无需在多个数据库间同步数据。
HNSW 索引: 虽然我们现在还没写，但 PostgreSQL 17 支持 HNSW 索引，能让你的千万级数据检索在毫秒内完成。

检查点：你的数据工厂已开工

数据库容器：正在后台静默运行。
向量扩展：已准备好接收 Embedding 向量。
连接链路：Python 程序已具备读写数据库的能力。