注意：部分截图借用pixany项目，虽然展示项目名称不一样，但是要做的事情意思相同（这里时间关系，就不每个项目单独截图了）

ShipAny GPT Image2 本地开发与上手指南

本项目基于 ShipAny TanStack 架构（TanStack Router + Nitro + Drizzle ORM + Better-Auth）构建，针对 GPT Image 2 及前沿文生图、图像变体与视觉生成模型进行了深度集成，同时深度优化适配 Cloudflare Workers 边缘计算网络。

1. 项目初始化与本地启动

1.1 获取项目代码

方式 1：通过 GitHub 模板创建私有仓库（推荐）

1. 在 GitHub 模板仓库页面，点击右上角 Use this template -> Create a new repository：

2. 填写你的仓库名称（Repository name），建议选择 Private（私有仓库），然后点击 Create repository：

3. 仓库创建成功后，页面会自动跳转到你自己的私有仓库主页：

4. 将新仓库克隆到本地开发环境：

git clone git@github.com:<你的GitHub用户名>/<你的仓库名>.git
cd <你的仓库名>

方式 2：基于源码克隆并重建自己的 Git 仓库

# 1. 克隆源码
git clone git@github.com:template-code-team/shipany-template-gpt-image2 my-gpt-image2-app
cd my-gpt-image2-app

# 2. 移除上游模板 remote，并关联你自己的私有仓库
git remote remove origin
gh repo create your-project-name --private --source=. --remote=origin

# 3. 推送到你的仓库并锁定 main 分支
git push -u origin main

1.2 安装依赖

项目使用 pnpm 进行单体依赖管理：

pnpm install

2. 配置说明（双层配置体系）

ShipAny 采用 “基础设施冷启动变量 + 运行时动态数据库配置” 的两层配置体系：

┌─────────────────────────────────────────────────────────────┐
│ 运行时读取：数据库 `config` 表（管理后台 /admin/settings 动态维护） │  <-- 优先级最高，支持热更新与敏感数据 AES 加密
└──────────────────────────────┬──────────────────────────────┘
                               │ 兜底
┌──────────────────────────────▼──────────────────────────────┐
│ 基础设施冷启动配置：.env.development / wrangler.toml [vars]   │  <-- 仅保留冷启动必需项：DATABASE_URL、AUTH_SECRET 等
└─────────────────────────────────────────────────────────────┘

1. 环境变量文件（.env.development / wrangler.toml）：仅用于系统构建与冷启动必需的底层基础设施项（如应用地址、数据库方言及连接串、Better-Auth 加密秘钥）。
2. 管理后台设置（/admin/settings）：所有业务级凭据（Google/GitHub OAuth、Stripe/Creem/PayPal 支付密钥、AI 供应商 API Key、Resend 邮件密钥、积分策略等）均在管理后台配置并持久化于 config 表中。
3. 加载机制与安全性：
   • 环境变量按优先级加载：.env.{NODE_ENV}.local > .env.{NODE_ENV} > .env.local > .env。
   • 运行时如数据库中存在同名配置项，数据库配置优先覆盖环境变量。
   • 若设置了 CONFIG_ENCRYPTION_KEY，存入 config 表的敏感密钥会自动进行 AES-256-GCM 高强度加密。

2.1 初始化本地环境变量

复制模板配置文件：

cp .env.example .env.development

编辑 .env.development（本地开发推荐使用 SQLite，免安装外部数据库，极速启动）：

# 1. 应用基础信息（VITE_* 会在构建时暴露给前端代码 import.meta.env）
VITE_APP_URL=http://localhost:3000
VITE_APP_NAME="GPT Image2"

# 2. 数据库连接（本地默认使用 sqlite）
DATABASE_PROVIDER=sqlite
DATABASE_URL=file:data/local.db

# 3. Better-Auth 鉴权密钥（仅服务端可见，可执行 openssl rand -base64 32 生成）
AUTH_SECRET=your_generated_auth_secret_here

# 4. （可选）配置表敏感凭据加密密钥（AES-256-GCM，生产环境建议配置，一旦生成请勿随意更改）
# CONFIG_ENCRYPTION_KEY=

3. 数据库（Drizzle ORM 多方言适配）

项目使用 Drizzle ORM，支持在 postgresql、sqlite、mysql 以及 Cloudflare d1 间灵活切换。

3.1 数据库模式与连接说明

3.2 数据库核心管理命令

• 快速同步表结构（开发阶段推荐）：

  pnpm db:push
  

  直接将当前 schema 结构同步到本地或测试数据库中，无需手动编写 SQL。

• 版本化迁移（生产上线规范）：

  pnpm db:generate  # 在 src/config/db/migrations 目录生成版本化 .sql 迁移文件
  pnpm db:migrate   # 将生成的迁移文件按序应用到目标数据库
  

• 可视化数据看板：

  pnpm db:studio    # 启动本地 Drizzle Studio，在浏览器直观增删改查表数据
  

3.3 核心数据表架构

• 用户与鉴权：user（用户信息）、session（安全 Session 凭据）、account（第三方 OAuth 关联）、verification（校验码记录）。
• 权限管理（RBAC）：role（角色表）、permission（原子权限表）、user_role（用户与角色关联）。
• 全站动态设置：config（存储所有第三方 API Key、开关与运行时参数）。
• 商业化与订单：order（订单流记录）、subscription（循环订阅）、credit（积分交易流水与不可篡改明细账本）。
• AI 创作资产：prompt（预置及用户提示词库）、showcase（精选案例展示）等核心业务资产。

4. 初始化 RBAC 与管理员账号

在本地数据库 Schema 同步完成后，执行脚本初始化权限控制体系（RBAC）并创建超级管理员：

# 请将邮箱和密码替换为你自己的超管账号信息
pnpm rbac:init --admin-email=admin@example.com --admin-password=your_secure_password

启动本地开发服务器：

pnpm dev

• 前台访问：http://localhost:3000
• 管理后台：http://localhost:3000/admin（使用上方初始化的超管邮箱与密码登录）

登录后台后即可进入仪表盘：

5. 登录鉴权配置（Better-Auth）

鉴权核心驱动为 src/core/auth/index.ts，路由由 src/server/api/auth 统一承载。

5.1 邮箱密码登录与邮箱验证

进入管理后台 Settings > Auth：

• 邮箱密码登录：系统默认开启（email_auth_enabled），用户注册后立即生成安全会话。
• 邮箱验证：如需防刷防恶意注册，可开启 email_verification_enabled。
  • 需要在 Settings > Email 中配置 Resend 服务凭据（resend_api_key 与 resend_sender_email）。
  • 邮箱验证链接有效期为 24 小时，且具备 60 秒防重发冷却防护。

5.2 Google OAuth 快捷登录

1. 打开 Google Cloud Console Credentials。
2. 创建 OAuth 2.0 客户端 ID（应用类型选择 Web application）：

3. 依据要求填写应用名称、支持邮箱，并将用户类型设置为 External（外部）：

4. 添加已获授权的重定向 URI（Authorized redirect URIs）：
   • 本地开发环境：
     • http://localhost:3000
     • http://localhost:3000/api/auth/callback/google
   • 线上生产环境（部署时添加）：
     • https://你的线上域名
     • https://你的线上域名/api/auth/callback/google

5. 复制生成的 Client ID 与 Client Secret，进入管理后台 http://localhost:3000/zh/admin/settings 的 Auth 栏目：
   • 填入 google_client_id 与 google_client_secret。
   • （可选）开启 google_one_tap_enabled 支持 Google One Tap 浮窗一键快捷登录。

5.3 GitHub OAuth 登录

1. 前往 GitHub 账户 Settings > Developer settings > OAuth Apps，点击 New OAuth App。
2. 配置 Authorization callback URL：http://localhost:3000/api/auth/callback/github（生产环境为 https://你的域名/api/auth/callback/github）。
3. 将生成的 Client ID 与 Client Secret 填入管理后台的 github_client_id 与 github_client_secret 并保存即可。

6. 支付模块（Stripe / Creem / PayPal）

ShipAny 采用统一的支付管理器抽象（位于 src/extensions/payment/），支持国际信用卡、PayPal、微信/支付宝等多币种结算：

6.1 支付闭环交互流程

1. 创建收银台会话：前端调用 POST /api/payment/checkout，传入 { product_id, payment_provider, redirect }。
2. 服务端验签与建单：服务端校验商品有效性并生成本地 order 待支付记录，返回第三方收银台 URL。
3. 用户支付并跳转：用户完成支付后跳回 /api/payment/callback?order_no=...。
4. 异步 Webhook 履约：第三方支付网关发送 Webhook，服务端验签后将订单置为 PAID，并向用户积分账本增发额度。

7. 积分系统（FIFO 消耗算法）

积分模块基于不可篡改的流水账本设计，驱动生图与 AI 生成消费。

7.1 积分发放体系

• 新手注册赠送：在后台 Settings > Credits 设置：
  • initial_credits_enabled（开启赠送开关）
  • initial_credits_amount（赠送额度，如 50 积分）
  • initial_credits_valid_days（有效天数，填 0 代表永久有效）
• 充值购买与订阅：支付回调成功后，自动向 credit 表注入额度；订阅到期后自动随订阅周期轮转。
• 管理员手动派发：在后台直接向指定用户派发积分，流水标记为 GIFT 或 REWARD。

7.2 先进先出消耗机制（FIFO）

AI 生图扣费时，严格按照 “最先过期的积分批次最先扣减” 原则，优先扣除即将过期的积分，最大化保障用户权益与账本精准。

8. AI 供应商配置与商业毛利模型

8.1 配置 AI 服务密钥

系统在 src/extensions/ai/ 模块已集成 KIE.AI、Replicate、fal.ai、Gemini 以及 Custom（兼容 APIMart 等全模态服务商）：

1. 注册并获取对应平台的 API Key（例如 KIE AI 控制台 或 APIMart 控制台）。
2. 进入管理后台 http://localhost:3000/zh/admin/settings 的 AI 配置页面。
3. 填入对应的 API Key 并保存。
4. 访问前台即可立即体验 GPT Image 2 极速生图与视觉创作。

8.2 商业毛利率与计费安全性参考

• 积分单价模型：按一次性标准套餐折算，用户购买每 1 积分的单价约为 $0.0165 ～ $0.0225 美元。
• GPT Image 2 生图模型（综合毛利 80%～90%）：
  • 标准生图：每次扣除 6～10 积分（约收入 $0.11～$0.18 美元），上游接口成本约 $0.015～$0.035 美元，商业毛利率保持在 80% 以上。
  • 高分辨率及多图生成：支持前端按尺寸与画幅阶梯计费，避免穿底风险。

9. 生产环境部署实战

部署在Cloudflare Worker