insforge

InsForge 应用集成技能

本技能涵盖使用 @insforge/sdk 的客户端 SDK 集成。对于后端基础设施操作（创建表、检查模式、部署函数、密钥、管理存储桶、配置支付提供商密钥/目录、网站部署、定时任务和计划、日志等），请使用 insforge-cli 技能。

快速设置

1. 安装 SDK

npm install @insforge/sdk@latest

2. 设置环境变量

在使用 SDK 之前，在项目根目录创建一个 .env 文件（对于 Next.js 使用 .env.local），其中包含你的 InsForge URL 和匿名密钥。

如何获取 URL 和匿名密钥

1. 确保项目已链接。 检查项目根目录是否存在 .insforge/project.json。

   • 对于现有项目，使用 npx @insforge/cli link 生成；对于新项目，使用 npx @insforge/cli create。

2. 通过 CLI 获取匿名密钥：

   npx @insforge/cli secrets get ANON_KEY
   

3. 从 .insforge/project.json 的 oss_host 字段获取 URL（例如 https://myapp.us-east.insforge.app）。

4. 将两个值写入 .env 文件，使用正确的框架前缀（见下表）。

重要： 对于用户范围的 SDK 客户端（包括 SSR），请使用匿名密钥。对于需要管理员/服务访问权限的特权服务器端代码，请使用 createAdminClient({ apiKey })；API 密钥是完整访问权限的管理员密钥，相当于其他平台上的服务角色密钥。

根据你的框架使用正确的环境变量前缀和访问模式：

框架	.env 文件	变量	访问模式
Next.js	.env.local	NEXT_PUBLIC_INSFORGE_URL, NEXT_PUBLIC_INSFORGE_ANON_KEY	process.env.NEXT_PUBLIC_*
Vite (React, Vue, Svelte)	.env	VITE_INSFORGE_URL, VITE_INSFORGE_ANON_KEY	import.meta.env.VITE_*
Astro	.env	PUBLIC_INSFORGE_URL, PUBLIC_INSFORGE_ANON_KEY	import.meta.env.PUBLIC_*
SvelteKit	.env	PUBLIC_INSFORGE_URL, PUBLIC_INSFORGE_ANON_KEY	import { env } from '$env/dynamic/public'
Create React App	.env	REACT_APP_INSFORGE_URL, REACT_APP_INSFORGE_ANON_KEY	process.env.REACT_APP_*
Node.js / Server	.env	INSFORGE_URL, INSFORGE_ANON_KEY	process.env.*

Next.js 的 .env.local 示例：

NEXT_PUBLIC_INSFORGE_URL=https://your-appkey.us-east.insforge.app
NEXT_PUBLIC_INSFORGE_ANON_KEY=eyJhbGciOiJIUzI1NiIs...

重要： 保持 .env 文件本地化。将 .env、.env.local 和 .env*.local 添加到 .gitignore，并保留 .env.example 用于记录所需变量。

3. 初始化客户端

Next.js：

import { createClient } from '@insforge/sdk'

const insforge = createClient({
  baseUrl: process.env.NEXT_PUBLIC_INSFORGE_URL,
  anonKey: process.env.NEXT_PUBLIC_INSFORGE_ANON_KEY
})

Vite：

import { createClient } from '@insforge/sdk'

const insforge = createClient({
  baseUrl: import.meta.env.VITE_INSFORGE_URL,
  anonKey: import.meta.env.VITE_INSFORGE_ANON_KEY
})

Astro：

import { createClient } from '@insforge/sdk'

const insforge = createClient({
  baseUrl: import.meta.env.PUBLIC_INSFORGE_URL,
  anonKey: import.meta.env.PUBLIC_INSFORGE_ANON_KEY
})

对于需要项目管理员访问权限的可信服务器端代码：

import { createAdminClient } from "@insforge/sdk";

const admin = createAdminClient({
  baseUrl: process.env.INSFORGE_URL,
  apiKey: process.env.INSFORGE_API_KEY,
});

模块参考

模块	集成指南
数据库	database/sdk-integration.md
认证	auth/sdk-integration.md
存储	storage/sdk-integration.md
函数	functions/sdk-integration.md
AI	ai/overview.md
实时	realtime/sdk-integration.md
邮件	email/sdk-integration.md
支付：Stripe	payments/stripe.md
支付：Razorpay	payments/razorpay.md

每个模块涵盖的内容

模块	内容
数据库	CRUD 操作、过滤器、分页、RPC 调用
认证	注册/登录、OAuth、会话、个人资料、密码重置
存储	上传、下载、删除文件；用于 CI/备份工具的 S3 兼容网关；为存储桶编写 RLS 策略
函数	调用边缘函数
AI	通过 OpenRouter 进行 AI 调用，支持聊天、图像、视频、音频、嵌入和模型发现
邮件	发送自定义事务性 HTML 邮件（欢迎、新闻通讯、通知）
支付：Stripe	Stripe Checkout 会话、订阅和计费门户重定向
支付：Razorpay	Razorpay 订单、订阅、Checkout.js 和订阅管理
实时	连接、订阅、发布事件，并跟踪存在快照以及加入/离开增量

指南

指南	使用时机
../insforge-cli/references/database/access-control.md	应用表访问控制的后端设置 — 涵盖 RLS、无限递归预防、SECURITY DEFINER 模式、性能技巧和常见 InsForge 模式
storage/s3-gateway.md	当使用者是现有 S3 工具（aws CLI、AWS SDK、rclone、Terraform、boto3）且采用 @insforge/sdk 不切实际时的回退路径 — 涵盖端点/区域设置、访问密钥管理、路径样式寻址以及支持和不支持的 S3 操作。需要 InsForge 2.0.9+。 对于应用代码，优先使用 SDK (storage/sdk-integration.md)
storage/postgres-rls.md	为 storage.objects 编写 RLS 策略 — 仅所有者、公开读取、路径范围、团队共享，以及混合 REST + S3 存储桶的 NULL uploaded_by 注意事项
../insforge-cli/references/database/vector.md	语义搜索、推荐或 RAG 的后端设置 — 涵盖 vector 扩展、模式/维度、距离运算符、HNSW/IVFFlat 索引和 RPC 相似性搜索
ai/chat-completions.md	通过 OpenRouter 进行文本生成、结构化回答和流式聊天
ai/image-generation.md	通过 OpenRouter 进行图像生成/编辑，然后持久存储到 InsForge 存储
ai/video-generation.md	异步 OpenRouter 视频任务、状态轮询和存储生成的媒体
ai/audio.md	语音转文本、文本转语音，以及使用 InsForge 存储音频资产/转录
ai/embeddings-and-rag.md	通过 OpenRouter 生成嵌入，将其存储在 pgvector 中，并连接基本的 RAG 管道
ai/models-list.md	发现 OpenRouter 模型 ID、模态、参数、定价和嵌入维度
payments	在应用集成之前配置 Stripe/Razorpay 密钥、同步提供商目录、设置 webhook 和编写支付 RLS

为新应用构建支付

首先选择提供商。没有通用的应用支付指南：

• 对于 Stripe Checkout、订阅和计费门户，加载 payments/stripe.md。
• 对于 Razorpay 订单、订阅、Checkout.js 以及取消/暂停/恢复流程，加载 payments/razorpay.md。

在编写应用代码之前，使用 insforge-cli 支付参考检查提供商设置：

npx @insforge/cli payments stripe status
npx @insforge/cli payments razorpay status

如果所选提供商未配置，请要求开发人员/管理员先配置该提供商。

实时后端设置

实时 SDK 用于前端事件处理和消息传递。使用 insforge-cli 技能配置频道模式、数据库触发器和频道/消息 RLS；请参阅 realtime。

后端配置

支持的项目配置旋钮通过 CLI 管理 — 使用
npx @insforge/cli config export/plan/apply 进行认证重定向 URL、
验证标志、密码策略、认证 SMTP 设置、存储上传大小、
实时/计划保留和云部署子域。OAuth 提供商、
外部应用设置、存储桶、函数、密钥和部署环境变量
仍使用专用仪表板或 CLI 流程。请参阅 insforge-cli
技能的配置部分。

有风险的后端更改？先使用分支

当此技能中的代码更改依赖于模式迁移、新的 RLS 策略、OAuth 提供商配置更改或任何其他影响生产行为的后端更改时，请先创建后端分支。分支共享 JWT_SECRET（现有用户 JWT 继续工作），但获得全新的数据库 + EC2 + API_KEY / ANON_KEY，因此你可以端到端地隔离测试 SDK + 后端更改。

完整的分支工作流位于 insforge-cli 技能中 — 请参阅 branch 了解决策指南和生命周期命令。典型循环：

npx @insforge/cli branch create feat-x --mode schema-only
# ... 在分支上应用迁移 / 更改认证配置 / 更新 RLS ...
# ... 针对分支后端测试 SDK ...
npx @insforge/cli branch merge feat-x --dry-run     # 审查 SQL
npx @insforge/cli branch merge feat-x               # 应用到父分支

⚠ 在 branch create 或 branch switch 之后，更新应用的 InsForge URL 和匿名密钥环境变量，然后重新启动开发服务器（或重新加载 .env），以便 SDK 与所选分支后端通信。

SDK 快速参考

所有 SDK 方法返回 { data, error }。

模块	方法
insforge.database	.from().select(), .insert(), .update(), .delete(), .rpc()
insforge.auth	.signUp(), .signInWithPassword(), .signInWithOAuth(), .signOut(), .getCurrentUser()
insforge.storage	.from().upload(), .uploadAuto(), .download(), .remove()
insforge.functions	.invoke()
insforge.ai	仅作弃用回退：.chat.completions.create(), .images.generate(), .embeddings.create()
insforge.realtime	.connect(), .subscribe(), .publish(), .on(), .disconnect()
insforge.emails	.send({ to, subject, html, cc?, bcc?, from?, replyTo? })
insforge.payments.stripe	.createCheckoutSession(), .createCustomerPortalSession()
insforge.payments.razorpay	.createOrder(), .verifyOrder(), .createSubscription(), .verifySubscription(), .cancelSubscription(), .pauseSubscription(), .resumeSubscription()

重要说明

• 数据库插入需要数组格式：insert([{...}])
• Next.js / SSR 认证：使用 @insforge/sdk/ssr 辅助函数（createBrowserClient、createServerClient、createAuthActions、createRefreshAuthRouter），并从 @insforge/sdk/ssr/middleware 导入 updateSession 用于代理/中间件。保持刷新令牌 httpOnly，在服务器上通过 createAuthActions() 运行认证变更，仅从服务器操作返回安全的应用数据，并让浏览器读取短期访问令牌用于存储/实时。请参阅 auth/ssr-integration.md
• 存储：将 url 和 key 都保存到数据库，以便进行下载/删除操作
• 函数调用 URL：/functions/{slug}
• 邮件投递：认证邮件（注册验证、密码重置、魔法链接、邀请）在所有计划上发送。通过 insforge.emails.send() 的自定义邮件在所有付费计划上发送。使用平台管理的投递路径；自定义发件人域是仪表板配置。请参阅 email/sdk-integration.md。
• 支付：首先使用 npx @insforge/cli payments <provider> ... 配置提供商密钥/目录；前端代码使用提供商范围的 SDK 模块。
• 支付 RLS：在支付 UI 之前，在提供商运行时表上添加应用特定的 RLS。Stripe 使用 payments.stripe_checkout_sessions 和 payments.stripe_customer_portal_sessions；Razorpay 使用 payments.razorpay_orders 和 payments.razorpay_subscriptions。持久履行触发器应放在 payments.webhook_events 上，而不是成功 URL、Checkout 回调或 payments.transactions 上。
• 使用 Tailwind CSS v3.4
• 部署前始终本地构建：防止浪费构建资源并加快调试速度
• SDK 包：直接使用 @insforge/sdk 实现所有功能，包括认证。
• 部署：在项目根目录包含 vercel.json 用于 SPA 路由（React、React Router 应用）。download-template 工具会自动包含此文件。
• 对有风险的后端更改使用分支：如果你的 SDK 代码依赖于新的模式、RLS 策略或认证配置更改，请先通过 npx @insforge/cli branch create 创建分支 — 请参阅 insforge-cli 技能的 branch 参考。在 branch create / branch switch 之后，更新应用的 InsForge URL 和匿名密钥环境变量，然后重新启动开发服务器。