数据库配置指南

本文档介绍如何配置项目的 PostgreSQL 数据库。

重大更新通知：本项目当前默认推荐使用本地 PostgreSQL（或其他自托管数据库）作为数据库后端，配合 VPS + PM2 部署。

默认配置：标准 PostgreSQL

当前项目数据库与任务处理逻辑以 Node.js runtime 为主（postgres.js + Drizzle + 服务端事务逻辑），因此更推荐使用标准的 PostgreSQL。

1. 环境变量配置

在 .env.local 文件中添加你的 PostgreSQL 连接字符串：

# PostgreSQL 数据库连接URL
DATABASE_URL=postgres://user:password@host/database

2. 使用 Docker 运行本地 PostgreSQL

# 启动 PostgreSQL 容器
docker run -d \
  --name vibany-postgres \
  -e POSTGRES_USER=vibany \
  -e POSTGRES_PASSWORD=yourpassword \
  -e POSTGRES_DB=vibany \
  -p 5432:5432 \
  postgres:15-alpine

# 对应的连接字符串
DATABASE_URL=postgresql://vibany:yourpassword@localhost:5432/vibany

选项 B：使用 Neon 数据库 (Serverless)

如果您希望继续使用 Neon 作为数据库（Serverless PostgreSQL），由于 Neon 的驱动要求（如 @neondatabase/serverless），请切换到专门的稳定标签版本：

git checkout neon-stable-2026-02-24

为什么有单独的 Neon 版本？

Neon 是一个 Serverless PostgreSQL 服务，具有连接池、自动休眠、分支等特性。由于 Neon 的连接方式和驱动配置与标准 PostgreSQL 略有差异（例如需要使用 @neondatabase/serverless 驱动或特定的连接池配置），项目在 neon-stable-2026-02-24 标签处保留了一套经过验证的 Neon 集成配置。

Neon 配置步骤

登录 Neon Console 创建项目
复制包含 sslmode=require 的连接字符串
在 .env.local 中配置：

# Neon PostgreSQL 连接 URL
DATABASE_URL=postgresql://username:password@host:5432/database?sslmode=require

运行迁移并启动应用：

npm install
npm run db:migrate
npm run dev

数据库管理命令 (Drizzle ORM)

无论使用哪种数据库，项目都统一使用 Drizzle ORM 进行管理。

# 生成迁移文件
npm run db:generate

# 推送 schema 到数据库（开发环境）
npm run db:push

# 应用迁移（生产环境）
npm run db:migrate

# 一键更新（生成 + 推送）
npm run db:update

# 打开 Drizzle Studio（数据库 GUI，访问 http://localhost:4983）
npm run db:studio

数据库 Schema 概览

核心表结构位于 lib/db/schema.ts：

users：用户信息及 Clerk ID
wallets：用户积分钱包
orders：充值与购买订单
histories：图像生成历史
videos：视频处理及缩略图记录
invitations：邀请码管理

故障排除

1. 连接被拒绝 (ECONNREFUSED)

检查数据库服务是否已启动 (Docker 或本地服务)
检查 DATABASE_URL 端口和主机名是否正确

2. Neon 连接错误

确保使用的是 neon-stable-2026-02-24 分支代码
确保连接字符串中包含了 sslmode=require 参数

3. 迁移表冲突 (relation already exists)

不要在包含数据的生产库中直接使用 db:push，请使用 db:migrate
如果是在开发环境，可使用 npm run db:studio 检查并清理冲突的表