InsForge SDK 技能

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

快速设置

bash
npm install @insforge/sdk@latest

javascript
import { createClient } from @insforge/sdk

const insforge = createClient({
baseUrl: https://your-project.region.insforge.app,
anonKey: your-anon-key
})

模块参考

模块	SDK 集成
数据库	database/sdk-integration.md
认证

auth/sdk-integration.md | | 存储 | storage/sdk-integration.md | | 函数 | functions/sdk-integration.md | | AI | ai/sdk-integration.md | | 实时 | realtime/sdk-integration.md |

各模块涵盖内容

模块	内容
数据库	CRUD 操作、过滤器、分页、RPC 调用
认证

注册/登录、OAuth、会话、个人资料、密码重置 | | 存储 | 上传、下载、删除文件 | | 函数 | 调用边缘函数 | | AI | 聊天补全、图像生成、嵌入 | | 实时 | 连接、订阅、发布事件 |

指南

指南	使用场景
database/postgres-rls.md	编写或审查 RLS 策略 — 涵盖无限递归预防、SECURITY DEFINER 模式、性能提示和常见 InsForge RLS 模式

实时配置

对于实时通道和数据库触发器，请使用 insforge db query 配合 SQL 创建触发器以发布到通道。实时 SDK 用于前端事件处理和消息传递，而非后端配置。

创建数据库触发器

当数据库记录发生变化时自动发布事件。

sql
-- 创建触发器函数
CREATE OR REPLACE FUNCTION notifyorderchanges()
RETURNS TRIGGER AS $$
BEGIN
PERFORM realtime.publish(
order: || NEW.id::text, -- 通道
TGOP || order, -- 事件：INSERTorder, UPDATEorder
jsonbbuildobject(
id, NEW.id,
status, NEW.status,
total, NEW.total
)
);
RETURN NEW;
END;
$$ LANGUAGE plpgsql SECURITY DEFINER;

-- 附加到表
CREATE TRIGGER order_realtime
AFTER INSERT OR UPDATE ON orders
FOR EACH ROW
EXECUTE FUNCTION notifyorderchanges();

条件触发器（仅状态变更）

sql
CREATE OR REPLACE FUNCTION notifyorderstatus()
RETURNS TRIGGER AS $$
BEGIN
PERFORM realtime.publish(
order: || NEW.id::text,
status_changed,
jsonbbuildobject(id, NEW.id, status, NEW.status)
);
RETURN NEW;
END;
$$ LANGUAGE plpgsql SECURITY DEFINER;

CREATE TRIGGER orderstatustrigger
AFTER UPDATE ON orders
FOR EACH ROW
WHEN (OLD.status IS DISTINCT FROM NEW.status)
EXECUTE FUNCTION notifyorderstatus();

访问控制（RLS）

RLS 默认禁用。要限制通道访问：

• - 启用 RLS

sql
ALTER TABLE realtime.channels ENABLE ROW LEVEL SECURITY;
ALTER TABLE realtime.messages ENABLE ROW LEVEL SECURITY;

• - 限制订阅（对 channels 的 SELECT）

sql
CREATE POLICY userssubscribeown_orders
ON realtime.channels FOR SELECT
TO authenticated
USING (
pattern = order:%
AND EXISTS (
SELECT 1 FROM orders
WHERE id = NULLIF(splitpart(realtime.channelname(), :, 2), )::uuid
AND user_id = auth.uid()
)
);

• - 限制发布（对 messages 的 INSERT）

sql
CREATE POLICY memberspublishchat
ON realtime.messages FOR INSERT
TO authenticated
WITH CHECK (
channel_name LIKE chat:%
AND EXISTS (
SELECT 1 FROM chat_members
WHERE roomid = NULLIF(splitpart(channel_name, :, 2), )::uuid
AND user_id = auth.uid()
)
);

• - 快速参考

任务	SQL
创建通道	INSERT INTO realtime.channels (pattern, description, enabled) VALUES (...)
创建触发器

CREATE TRIGGER ... EXECUTE FUNCTION ... | | 从 SQL 发布 | PERFORM realtime.publish(channel, event, payload) | | 启用 RLS | ALTER TABLE realtime.channels ENABLE ROW LEVEL SECURITY |

最佳实践

1. 1. 先创建通道模式，再从前端订阅

- 将通道模式插入 realtime.channels 表 - 确保 enabled 设置为 true

1. 2. 使用特定的通道模式

- 对动态通道使用通配符 % 模式（例如，order:% 对应 order:123） - 对全局通道使用精确模式（例如，notifications）

常见错误

错误	解决方案
订阅未定义的通道模式	先在 realtime.channels 中创建通道模式
通道未接收消息

确保通道 enabled 为 true | | 无触发器发布 | 创建数据库触发器以在变更时自动发布 |

推荐工作流程

text

1. 1. 创建通道模式 → INSERT INTO realtime.channels
2. 确保 enabled = true → 将 enabled 设置为 true
3. 按需创建触发器 → 在数据库变更时自动发布
4. 继续 SDK 订阅 → 使用匹配模式的通道名称

后端配置（CLI 尚不支持）

这些模块仍需 HTTP API 调用，因为 CLI 尚不支持：

模块	后端配置
认证	auth/backend-configuration.md
AI

ai/backend-configuration.md |

SDK 快速参考

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

模块	方法
insforge.database	.from().select(), .insert(), .update(), .delete(), .rpc()
insforge.auth

.signUp(), .signInWithPassword(), .signInWithOAuth(), .signOut(), .getCurrentSession() |
| 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() |

重要说明

• - 数据库插入需要数组格式：insert([{...}]) 而非 insert({...})
• 存储：将 url 和 key 都保存到数据库，用于下载/删除操作
• 函数调用 URL：/functions/{slug}（不带 /api 前缀）
• 使用 Tailwind CSS v3.4（不要升级到 v4）
• 部署前始终本地构建：避免浪费构建资源并加快调试速度