故障排查

Webhook 未触发

症状：支付成功但积分未发放。

1. 检查 Stripe Dashboard → Webhooks 的投递日志
2. 验证 STRIPE_WEBHOOK_SECRET 与 Stripe 设置匹配
3. 确保 webhook 端点可公开访问
4. 检查服务器日志中的签名验证错误

年付积分未自动发放

症状：年付计划用户未收到月度积分。

1. 验证定时任务是否正常运行（检查 /api/cron/subscription-grants）
2. 查看 subscriptionCreditSchedule / subscription_credit_schedule 中的 nextGrantAt / next_grant_at 时间
3. 确保 CRON_SECRET 配置正确

过期积分未更新

症状：每日登录积分过期后仍然可用。

1. 验证 /api/cron/credit-expiry 定时任务是否正常运行
2. 查看 creditBalanceBucket / credit_balance_bucket 中 expiresAt / expires_at 已过期且 remainingAmount / remaining_amount 大于 0 的记录
3. 确保 CRON_SECRET 或 cron basic auth 凭据配置正确

AI 工具生成失败

1. 验证 VOLCENGINE_API_KEY、VOLCENGINE_BASE_URL 和 VOLCENGINE_MODEL
2. 确认服务端运行环境可以访问火山引擎 endpoint
3. 查看 aiGeneration / ai_generation 中失败的生成记录和错误信息
4. 确认用户生成前有足够积分

用户无法访问管理后台

1. 确认数据库中 user.role = 'admin'
2. 检查 modules/auth/admin.ts 中的 requireAdmin()
3. 确保用户会话有效（尝试退出重新登录）

邮件发送失败

1. 验证 RESEND_API_KEY 和 RESEND_FROM_EMAIL
2. 如果使用 onboarding@resend.dev，只能发送到 Resend 账号注册邮箱
3. 生产环境需确认 Resend 发送域名已验证
4. 查看 Resend 邮件日志中的投递失败信息

数据库连接问题

1. 验证 DATABASE_URL 连接字符串
2. 确保云数据库包含 ?sslmode=require
3. 检查 IP 是否在白名单中（如有 IP 限制）
4. 尝试直接连接：psql $DATABASE_URL

升级后构建报错

如果升级依赖后遇到 TypeScript 错误：

# 清除 Next.js 缓存
rm -rf .next

# 重新安装依赖
pnpm install

# 重新构建
pnpm build