用 InsForge 与 @insforge/sdk…

在应用前端/服务端代码中集成 InsForge（@insforge/sdk）做 CRUD、登录、上传、AI、实时、邮件与 Stripe/Razorpay 支付时的标准落地流程。

适用场景

解决思路

1. 安装 SDK：`npm install @insforge/sdk@latest`。
2. 在项目根目录创建 `.env` 文件（Next.js 用 `.env.local`），写入 InsForge URL 和 anon key。
3. 获取 URL 和 anon key：(a) 确认项目已链接——检查项目根目录的 `.insforge/project.json`，没有就用 `npx -y @insforge/cli link`（已有项目）或 `npx -y @insforge/cli create`（新项目）生成；(b) 用 `npx -y @insforge/cli secrets get ANON_KEY` 取 anon key；(c) 从 `.insforge/project.json` 的 `oss_host` 字段取 URL（如 `https://myapp.us-east.insforge.app`）；(d) 按框架前缀把两个值写入 `.env`。
4. 按框架使用正确的环境变量前缀与访问方式：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.*` 访问。
5. 不要把密钥提交进仓库：把 `.env`、`.env.local`、`.env*.local` 加入 `.gitignore`，并保留 `.env.example` 记录必需变量。
6. 初始化客户端：`createClient({ baseUrl: <对应框架的环境变量>, anonKey: <对应框架的 anon key 环境变量> })`。
7. 用户范围的客户端（含 SSR）一律用 anon key；需要在受信任的服务端代码里获得项目管理员/服务权限时，改用 `createAdminClient({ baseUrl: process.env.INSFORGE_URL, apiKey: process.env.INSFORGE_API_KEY })`——该 API key 是全权限 admin key，等价于其他平台的 service role key。
8. 按功能查阅对应模块集成指南：Database（CRUD、过滤、分页、RPC）、Auth（注册/登录、OAuth、会话、profile、密码重置）、Storage（上传/下载/删除、S3 兼容网关、bucket 写入 RLS）、Functions（调用 edge functions）、AI（OpenRouter 的 chat/图像/视频/音频/embeddings/模型发现）、Real-time（连接、订阅、发布、presence 快照与 join/leave 增量）、Email（自定义事务 HTML 邮件）、Payments: Stripe、Payments: Razorpay。
9. 做支付时先选 provider（没有通用支付指南）：Stripe Checkout/订阅/Billing Portal 读 `payments/stripe.md`；Razorpay Orders/订阅/Checkout.js/取消暂停恢复读 `payments/razorpay.md`。写代码前先用 CLI 检查配置：`npx -y @insforge/cli payments stripe status`、`npx -y @insforge/cli payments razorpay status`；若 provider 未配置，先请开发者/管理员配置。
10. 实时功能：前端事件处理与消息用实时 SDK；channel 模式、数据库 trigger、channel/message RLS 用 insforge-cli 技能配置（见 realtime 参考）。
11. 后端配置项用 CLI 管理：`npx -y @insforge/cli config export/plan/apply` 处理 auth 重定向 URL、验证开关、密码策略、auth SMTP 设置、存储上传大小、realtime/schedule 保留期、云部署子域名；OAuth provider、外部应用设置、存储 bucket、functions、secrets、部署环境变量仍走各自 dashboard 或 CLI 流程。
12. 当代码改动依赖 schema 迁移、新 RLS 策略、OAuth provider 配置变更等会影响生产行为的后端变更时，先建后端分支：`npx -y @insforge/cli branch create feat-x --mode schema-only`；分支共享 `JWT_SECRET`（已有用户 JWT 继续有效）但有全新的数据库 + EC2 + `API_KEY`/`ANON_KEY`，可端到端隔离测试。
13. 分支上的典型循环：在分支上应用迁移/修改 auth 配置/更新 RLS → 让 SDK 对着分支后端测试 → `npx -y @insforge/cli branch merge feat-x --dry-run` 审阅 SQL → `npx -y @insforge/cli branch merge feat-x` 应用到父分支。
14. 在 `branch create` 或 `branch switch` 之后，更新应用的 InsForge URL 与 anon-key 环境变量值，然后重启开发服务器（或重新 source `.env`），确保 SDK 连到选中的分支后端。
15. 注意所有 SDK 方法都返回 `{ data, error }`。
16. 数据库插入必须使用数组格式：`insert([{...}])`。
17. 带宽高效读取：读取列表时显式命名列并加 `.limit()`；绝不要按固定间隔轮询无界的 `select()`——改用 realtime 订阅（配合 `realtime.publish` trigger）或轮询一个廉价的 ordered probe。浪费的查询形态是项目耗尽月度出网配额的首要原因。
18. Next.js / SSR 认证：使用 `@insforge/sdk/ssr` 辅助函数（`createBrowserClient`、`createServerClient`、`createAuthActions`、`createRefreshAuthRouter`），在 Proxy/Middleware 中从 `@insforge/sdk/ssr/middleware` 导入 `updateSession`；refresh token 保持 httpOnly，auth 变更通过服务端的 `createAuthActions()` 执行，Server Actions 只返回安全的 app 数据，浏览器只读取短期 access token 供 Storage/Realtime 使用。
19. Storage：把 `url` 和 `key` 都保存到数据库，以便后续下载/删除操作。
20. Functions 调用：优先用 `insforge.functions.invoke(slug)`，让 SDK 负责路由构造；裸 HTTP 时项目 base URL 对应兼容路径 `/functions/{slug}`，而 functions 部署主机（如 `*.function2.insforge.app`）在根路径 `/{slug}` 提供该 slug。
21. 邮件投递：认证邮件（注册验证、密码重置、magic link、邀请）在所有计划可用；通过 `insforge.emails.send()` 发送自定义邮件需要付费计划。使用平台托管的投递路径；自定义发件域在 dashboard 配置。
22. 支付：先用 `npx -y @insforge/cli payments <provider> ...` 配置 provider key 与目录（catalog），前端代码使用 provider 作用域的 SDK 模块。
23. 支付 RLS：在做支付 UI 之前，先给 provider 运行时表添加 app 专属 RLS——Stripe 用 `payments.stripe_checkout_sessions` 和 `payments.stripe_customer_portal_sessions`；Razorpay 用 `payments.razorpay_orders` 和 `payments.razorpay_subscriptions`。持久化的履约 trigger 放在 `payments.webhook_events` 上，而不是 success URL、Checkout 回调或 `payments.transactions`。
24. 样式使用 Tailwind CSS v3.4。
25. 部署前总是先在本地构建，避免浪费构建资源并加快调试。
26. 所有功能（包括认证）都直接使用 `@insforge/sdk` 包。
27. 部署 SPA 路由（React、React Router 应用）时在项目根目录放一个 `vercel.json`（`download-template` 工具会自动包含它）。
28. 遇到 SDK、后端、文档或技能本身的问题时：报告并继续用 workaround——`npx -y @insforge/cli feedback --json --type <bug|feature-request|friction> --component <backend|sdk|cli|skills|docs> --title "..." --detail "..."`，SDK 问题再加 `--language <lang>`（无需登录，PII 在本地脱敏）。类型映射：本该能用却报错用 `--type bug`；缺失能力用 `--type feature-request`；文档与实际行为矛盾用 `--type bug --component docs` 并加 `--doc`/`--expected`。
29. 当消费方是已有 S3 工具链（aws CLI、AWS SDK、rclone、Terraform、boto3）且难以采用 `@insforge/sdk` 时，走 S3 网关回退路径（`storage/s3-gateway.md`），需 InsForge 2.0.9+，配置 endpoint/region、access key 管理、path-style 寻址，并确认支持与不支持的 S3 操作；app 代码仍优先用 SDK。
30. 写 `storage.objects` 的 RLS 策略时参考 `storage/postgres-rls.md`：owner-only、public-read、path-scoped、team-shared，以及混合 REST + S3 bucket 的 `NULL uploaded_by` 注意事项。
31. 做语义搜索/推荐/RAG 时参考向量指南：启用 `vector` 扩展、schema/维度、距离操作符、HNSW/IVFFlat 索引、RPC 相似度检索。
32. 应用表访问控制的后端搭建参考 `../insforge-cli/references/database/access-control.md`：RLS、防止无限递归、`SECURITY DEFINER` 模式、性能建议与常见 InsForge 模式。
33. 配置 Stripe/Razorpay key、同步 provider 目录、设置 webhook、在应用集成前编写支付 RLS 时，参考 payments 概览文档。

适用边界 · 注意事项

• 后端基础设施操作（建表、查看 schema、部署函数、管理 secrets、管理存储 bucket、配置支付 provider key/目录、网站部署、cron 与调度、日志等）不在本技能范围，应改用 insforge-cli 技能。
• 不要为自己正在编写的应用代码中的问题提交 feedback（只报告 SDK/后端/文档/技能本身的故障）。
• 不要用固定间隔轮询无界 `select()`；也不要优先使用已废弃的 `insforge.ai` 回退接口，应走 OpenRouter 相关指南。