Vibany Next - Image AI Render
运行应用程序
git clone https://github.com/vibany-shipping/vibany-next
cd vibany-next
npm install
要在本地运行应用程序,您需要:
- 在 https://clerk.com 注册一个 Clerk 账户。
- 前往 Clerk 控制面板 并创建一个应用程序。
- 按照 示例
.env
文件 中所示设置所需的环境变量。 - 如果需要,在侧边栏中进入"Organization Settings"并启用组织功能。
- 使用
npm install
安装所需依赖项。 - 使用
npm run dev
启动开发服务器。
环境变量配置
在根目录中创建一个 .env.local
文件,包含以下变量:
基本配置
# 调试模式
NEXT_PUBLIC_DEBUG=
# 应用URL
NEXT_PUBLIC_APP_URL=https://yourdomain.com
Vercel Cron 配置
# Vercel Cron 任务密钥(用于保护定时任务API)
CRON_SECRET=your_cron_secret_key
# Cron 任务超时时间(秒)
TIMEOUT_SECONDS=790
数据库配置
# Neon PostgreSQL 数据库连接URL
DATABASE_URL=postgres://user:password@host/database
Clerk 身份验证
# Clerk 公钥和密钥
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_your_publishable_key
CLERK_SECRET_KEY=sk_your_secret_key
# 登录和注册后的重定向URL
CLERK_SIGN_IN_FALLBACK_REDIRECT_URL=/draw
CLERK_SIGN_UP_FALLBACK_REDIRECT_URL=/draw
支付系统配置
- 支付宝/微信支付服务注册:https://s.zhaikr.com/epay
- Stripe 支付注册:https://stripe.com
# 支付宝/微信支付API配置
PAY_API_URL=https://epayapi.wxda.net
PAY_PID=your_payment_id
PAY_PUBLIC_KEY=your_payment_public_key
PAY_MERCHANT_PRIVATE_KEY=your_merchant_private_key
# Stripe支付配置
STRIPE_SECRET_KEY=sk_test_your_stripe_secret_key # 测试环境使用sk_test_,生产环境使用sk_live_
STRIPE_WEBHOOK_SECRET=whsec_your_stripe_webhook_secret # Stripe webhook签名密钥
AI 模型配置
AI 模型的配置包括 Tuzi、XAI 和 OpenAI 的 API 配置。
- TUZI 注册地址:https://s.zhaikr.com/tuzi
- XAI 注册地址:https://xai.com
- OpenAI 注册地址:https://openai.com
# Tuzi API配置
TUZI_API_URL=https://api.tu-zi.com/v1
TUZI_API_KEY=sk_your_tuzi_api_key
TUZI_MODEL_IMAGE=gpt-4o-image-vip
TUZI_MODEL_IMAGE_VIP=gpt-4o-image-vip
TUZI_MODEL_IMAGE_SMALL=gpt-4o-image
# XAI API配置
XAI_API_URL=https://api.xai.com/v1
XAI_API_KEY=xai-your_xai_api_key
XAI_API_MODEL_IMAGE=grok-2-image-latest
# OpenAI API配置
OPENAI_API_URL=https://api.openai.com/v1
OPENAI_API_KEY=sk_your_openai_api_key
OPENAI_MODEL_IMAGE=gpt-image-1
OPENAI_MODEL_IMAGE_SMALL=dall-e-3
Cloudflare R2 存储配置
Cloudflare R2 存储注册
- 地址:https://dash.cloudflare.com
- 路径:R2 对象存储
# Cloudflare R2 存储配置
R2_ACCOUNT_ID=your_account_id
R2_ACCESS_KEY_ID=your_access_key_id
R2_SECRET_ACCESS_KEY=your_secret_access_key
R2_BUCKET_NAME=your_bucket_name
R2_PUBLIC_URL_PREFIX=https://your-bucket-name.r2.dev
Vercel 配置
Vercel 注册地址:https://vercel.com
本项目使用 Vercel 进行部署,需要特别注意以下配置:
- Vercel Pro 计划:由于项目使用了 Vercel 的高级功能(如长时间运行的函数和 Cron Jobs),需要升级到 Vercel Pro 计划
- 环境变量设置:在 Vercel 项目设置中的 "Environment Variables" 部分添加所有
.env.local
中的环境变量
vercel.json 配置说明
项目根目录下的 vercel.json
文件包含以下重要配置:
{
"functions": {
"app/api/**/*": {
"maxDuration": 800
}
},
"crons": [
{
"path": "/api/public/clear",
"schedule": "*/5 * * * *"
},
{
"path": "/api/public/backup?type=hourly",
"schedule": "0 * * * *"
},
{
"path": "/api/public/backup/fix",
"schedule": "15,45 * * * *"
}
]
}
函数执行时间
maxDuration: 800
:设置 API 路由的最大执行时间为 800 秒(约 13 分钟)- 注意:此配置需要 Vercel Pro 或 Enterprise 计划才能生效,免费计划的函数执行时间上限为 60 秒
定时任务 (Cron Jobs)
项目配置了以下定时任务:
- 每 5 分钟执行一次清理任务 (
/api/public/clear
) - 每小时执行一次小时级备份 (
/api/public/backup?type=hourly
) - 每小时的第 15 分钟和第 45 分钟执行修复任务 (
/api/public/backup/fix
)
重要提示:Vercel 的 Cron Jobs 功能需要 Pro 或 Enterprise 计划才能使用。
Vercel 手动配置事项
在 Vercel 部署时,需要手动配置以下内容:
-
环境变量设置:
- 在 Vercel 项目设置中的 "Environment Variables" 部分添加所有
.env.local
中的环境变量 - 确保敏感信息(如 API 密钥、数据库连接字符串)正确设置且受到保护
- 在 Vercel 项目设置中的 "Environment Variables" 部分添加所有
-
项目设置:
- 构建命令:确保使用
npm run build
作为构建命令 - 输出目录:默认为
.next
,通常不需要修改 - Node.js 版本:建议使用 Node.js 18.x 或更高版本
- 构建命令:确保使用
-
域名配置:
- 在 Vercel 项目的 "Domains" 部分添加您的自定义域名
- 按照 Vercel 提供的说明配置 DNS 记录
-
付费计划升级:
- 由于项目使用了 Vercel 的高级功能(如长时间运行的函数和 Cron Jobs),需要升级到 Vercel Pro 计划
- 当前 Vercel Pro 计划价格为 $20/月(可能会变动,请查看 Vercel 官方定价)
支付系统配置
本项目集成了支付系统,需要特别注意以下配置:
支付接口配置
-
申请支付接口:
- 联系支付服务提供商申请商户账号
- 获取
PAY_PID
、PAY_PUBLIC_KEY
和PAY_MERCHANT_PRIVATE_KEY
-
支付宝/微信支付回调配置:
- 在支付服务提供商后台设置支付回调 URL:
https://yourdomain.com/api/public/epay/notify
- 确保回调 URL 可以被支付服务提供商的服务器访问
- 在支付服务提供商后台设置支付回调 URL:
-
Stripe 支付配置:
- 在 Stripe Dashboard 创建账户
- 获取 API 密钥 (
STRIPE_SECRET_KEY
) - 配置 Webhook 端点:
https://yourdomain.com/api/public/stripe/notify
- 选择事件类型:
checkout.session.completed
和payment_intent.succeeded
- 获取 Webhook 签名密钥 (
STRIPE_WEBHOOK_SECRET
)
-
支付安全:
- 妥善保管所有支付相关的密钥,不要泄露给第三方
- 定期检查支付记录,确保系统安全
- 使用 HTTPS 确保支付过程的安全性
费用说明
-
Vercel 相关费用:
- Vercel Pro 计划:$20/月(套餐影响)
- 超出免费额度的带宽和构建分钟数将产生额外费用
- 可以使用 opennext 方案部署到其他平台或 VPS 上(Next Deployment 文档),节省成本(但会增加服务器维护的工作)
-
数据库费用:
- Neon PostgreSQL 数据库:根据使用情况收费,基本计划约 $4/月起,早期可以直接使用免费套餐完全够用
-
存储费用:
- Cloudflare R2 存储:前 10GB 免费,超出部分 $0.015/GB/月
- 出站流量:前 100GB 免费,超出部分 $0.09/GB
-
API 调用费用:
- 各 AI 模型 API 根据调用次数和使用量收费
- 建议设置使用限额,避免意外超支
-
Clerk 费用:
- 早期使用免费套餐即可
-
支付系统费用:
- 支付宝/微信支付:https://s.zhaikr.com/epay
- Stripe 支付:根据使用情况收费,大概 4% 上下
部署流程
本地开发到生产部署
-
本地开发:
npm run dev
-
构建项目:
npm run build
-
部署到 Vercel:
- 使用 Vercel CLI 部署:
npm i -g vercel vercel
- 或通过 GitHub 集成自动部署(推荐)
- 使用 Vercel CLI 部署:
数据库迁移
项目使用 Drizzle ORM 进行数据库管理(以下操作在生产构建时会自动完成):
-
生成迁移文件:
npm run db:generate
-
应用迁移:
npm run db:migrate
注意:不要手动创建 @drizzle/migrations/
目录下的 SQL 文件,这些文件由 Drizzle ORM 自动生成。
常见问题与故障排除
Vercel 部署问题
-
函数执行超时:
- 检查是否已升级到 Vercel Pro 计划
- 确认
vercel.json
中的maxDuration
设置正确 - 优化代码减少执行时间
-
环境变量问题:
- 确保所有必需的环境变量都已在 Vercel 项目设置中配置
- 检查环境变量名称是否正确(注意大小写)
- 重新部署项目以应用环境变量更改
-
Cron 任务未执行:
- 确认已升级到 Vercel Pro 计划
- 检查 Cron 表达式是否正确
- 在 Vercel 控制台中查看 Functions 日志以排查问题
支付系统问题
-
支付宝/微信支付回调失败:
- 确认回调 URL 配置正确
- 检查支付服务提供商的 IP 是否被允许访问
- 查看服务器日志以获取详细错误信息
-
Stripe Webhook 通知失败:
- 确认 Webhook 端点配置正确
- 检查
STRIPE_WEBHOOK_SECRET
是否正确配置 - 查看 Stripe Dashboard 中的 Webhook 日志
- 使用 Stripe CLI 进行本地测试:
stripe listen --forward-to localhost:3000/api/public/stripe/notify
-
订单状态不同步:
- 检查数据库连接是否稳定
- 确认支付回调处理逻辑正确
- 使用管理员工具手动同步订单状态
- 对于 Stripe 支付,可以在 Stripe Dashboard 中查看支付状态
API 集成问题
-
AI 模型调用失败:
- 验证 API 密钥是否有效
- 检查 API 调用参数是否正确
- 确认 API 服务提供商的服务状态
-
存储问题:
- 验证 Cloudflare R2 配置是否正确
- 检查存储桶权限设置
- 确认文件上传路径和访问 URL 格式正确