insforge

InsForge 应用集成技能

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

快速设置

1. 安装 SDK

npm install @insforge/sdk@latest

2. 设置环境变量

使用 SDK 前，请在项目根目录中创建 .env 文件（Next.js 项目使用 .env.local），并写入 InsForge URL 和 anon key。

如何获取 URL 和 anon key

1. 确保项目已关联。 检查项目根目录中是否有 .insforge/project.json。

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

2. 通过 CLI 获取 anon key：

   npx -y @insforge/cli secrets get ANON_KEY
   

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

4. 将这两个值写入 .env 文件，并使用适用于对应框架的前缀（见下表）。

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

请为所用框架使用正确的环境变量前缀和访问方式：

框架	.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	database/sdk-integration.md
Auth	auth/sdk-integration.md
Storage	storage/sdk-integration.md
Functions	functions/sdk-integration.md
AI	ai/overview.md
Real-time	realtime/sdk-integration.md
Email	email/sdk-integration.md
Payments: Stripe	payments/stripe.md
Payments: Razorpay	payments/razorpay.md

各模块涵盖内容

模块	内容
Database	CRUD 操作、筛选、分页、RPC 调用
Auth	注册/登录、OAuth、会话、个人资料、密码重置
Storage	上传、下载、删除文件；用于 CI / 备份工具的 S3 兼容网关；为存储桶编写 RLS 策略
Functions	调用边缘函数
AI	使用 OpenRouter AI 进行聊天、图像、视频、音频、嵌入和模型发现调用
Email	发送自定义事务型 HTML 邮件（欢迎邮件、新闻简报、通知）
Payments: Stripe	Stripe Checkout Sessions、订阅和 Billing Portal 重定向
Payments: Razorpay	Razorpay Orders、Subscriptions、Checkout.js 和订阅管理
Real-time	连接、订阅、发布事件，并跟踪在线状态快照及加入/离开变化

指南

指南	适用场景
../insforge-cli/references/database/access-control.md	为应用表访问控制配置后端 — 涵盖 RLS、防止无限递归、SECURITY DEFINER 模式、性能提示和常见的 InsForge 模式
storage/s3-gateway.md	当使用方已有 S3 工具（aws CLI、AWS SDKs、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 Storage
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、订阅和 Billing Portal，请加载 payments/stripe.md。
• 对于 Razorpay Orders、Subscriptions、Checkout.js 以及取消／暂停／恢复流程，请加载 payments/razorpay.md。

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

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

如果所选提供商尚未配置，请让开发者／管理员先配置该提供商。

实时后端设置

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

后端配置

受支持的项目配置项通过 CLI 管理——使用 npx -y @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 -y @insforge/cli branch create feat-x --mode schema-only
# ... apply migrations / change auth config / update RLS on the branch ...
# ... test the SDK against the branch backend ...
npx -y @insforge/cli branch merge feat-x --dry-run     # review SQL
npx -y @insforge/cli branch merge feat-x               # apply to parent

⚠ 执行 branch create 或 branch switch 后，请更新应用的 InsForge URL 和 anon-key 环境变量，然后重启开发服务器（或重新加载 .env），以便 SDK 连接到所选分支的后端。

SDK 快速参考

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

模块	方法
insforge.database	.from().select()、.insert()、.update()、.delete()、.rpc()
insforge.auth	.signUp()、.signInWithPassword()、.signInWithOtp() / .verifyOtp()、.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([{...}])
• 高效读取，节省带宽：列出列名并对列表读取使用 .limit()；切勿定时轮询无界的 select()——应使用 realtime 订阅（并配合 realtime.publish 触发器），或轮询开销低且有序的探测查询。低效的查询形式是项目耗尽每月出站流量额度的首要原因。探测代码片段和完整规则：database/sdk-integration.md。
• Next.js / SSR 身份验证：使用 @insforge/sdk/ssr 辅助函数（createBrowserClient、createServerClient、createAuthActions、createRefreshAuthRouter），并在 Proxy/Middleware 中从 @insforge/sdk/ssr/middleware 导入 updateSession。将刷新令牌设为 httpOnly，在服务器上通过 createAuthActions() 执行身份验证变更，Server Actions 仅返回安全的应用数据，并让浏览器读取短期访问令牌以供 Storage/Realtime 使用。请参阅 auth/ssr-integration.md
• Storage：将 url 和 key 都保存到数据库，以便执行下载/删除操作
• Functions 调用 URL：优先使用 insforge.functions.invoke(slug)——SDK 会负责构造路由。对于原始 HTTP：项目基础 URL 提供兼容路径 /functions/{slug}，而函数部署主机（例如 *.function2.insforge.app）在根路径 /{slug} 提供该 slug
• 电子邮件投递：身份验证邮件（注册验证、密码重置、魔法链接、邀请）在所有套餐中均可发送。通过 insforge.emails.send() 发送自定义邮件在所有付费套餐中均可使用。使用平台管理的投递路径；自定义发件人域名在控制面板中配置。请参阅 email/sdk-integration.md。
• 支付：先使用 npx -y @insforge/cli payments <provider> ... 配置提供商密钥/目录；前端代码使用特定于提供商的 SDK 模块。
• 支付 RLS：添加支付界面之前，先为提供商运行时表添加特定于应用的 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 -y @insforge/cli branch create 创建分支——请参阅 insforge-cli 技能中的 branch 参考。执行 branch create / branch switch 后，更新应用的 InsForge URL 和 anon-key 环境变量，然后重启开发服务器。
• 遇到 InsForge 端的问题？ 如果 SDK、后端、文档或技能出现异常——本应正常工作的 API 却报错（--type bug）、需要的功能不受支持（--type feature-request）、文档与实际行为矛盾（使用 --type bug --component docs，并附上 --doc/--expected）——请提交反馈并继续采用变通方案：npx -y @insforge/cli feedback --json --type <bug|feature-request|friction> --component <backend|sdk|cli|skills|docs> --title "..." --detail "..."；SDK 问题可添加 --language <lang>（无需登录；PII 会在本地脱敏）。完整标志集及情形→类型映射请参阅 insforge-cli 技能中的 Feedback 部分。切勿针对你编写的应用代码中的问题提交反馈。