InsForge 常见问题：数据库、Edge Function 与 SDK

读写数据库算 Edge Function 吗？数据库、Edge Function、Custom Compute 有什么区别？

不算。你平时对数据表做增删改查的时候，其实没有跑任何函数，当然也就不是 Edge Function。在 InsForge 里，你的代码有三种方式跟后端打交道，很容易搞混：

	怎么触发	会不会一直运行	用来做什么
读写数据库（自动生成的 REST API）	客户端发一个 SDK 或 REST 请求	不用你管，后端托管	增删改查数据表
Edge Function	HTTP 请求、定时（cron），或数据库触发器	跑一次就结束	自定义接口、webhook、触发逻辑、调外部服务
Custom Compute	你自己起一个常驻进程	一直开着	队列 worker、AI 推理循环、websocket、需要一直保持状态的活

读写数据库。 你建好一张表，InsForge 自动就给你一套 REST 接口（比如 GET /api/database/records/{table}）和一个带类型的 SDK。你调 select、insert 这些，就是直接在读写数据库，不用部署也不用跑任何东西。日常的增删改查用这个就够了，参见数据库。Edge Function。 当自动接口满足不了、你想写自己的服务端逻辑时才用它，比如接支付回调（webhook）、登录钩子、在某行数据发生 INSERT/UPDATE/DELETE 时触发一段代码，或者定时任务。它的特点是跑完一次请求就结束，不会一直待着。参见 Edge Functions。Custom Compute。 当你需要一个一直开着的进程时才用它，比如队列 worker 或者 AI 推理循环。这种活 Edge Function 干不了，因为它不常驻。参见 Custom Compute。一句话判断：只是读写数据，就走数据库（自动 REST）；要写一段跑完就结束的逻辑，用 Edge Function；要一直运行，用 Custom Compute。

怎么查询 public 以外 schema 里的表？

默认你所有的表都在 public 里。只有当你自己用 CREATE SCHEMA 建过别的 schema，才会有非 public 的 schema（InsForge 自己的内部 schema，比如 auth、storage，不对数据 API 开放，.schema() 和 ?schema= 查不到；但作为 project admin，你仍可以用原始 SQL 读它们，比如 insforge db query 或 dashboard 的 SQL 编辑器）。一旦有了，dashboard、REST API、CLI、SDK 都能读写它。下面的例子用一个你自己建的、名叫 my_schema 的 schema。Dashboard。 打开 Database，用侧边栏顶部的 schema 选择器。你建的任何 schema 都会和 public 并列出现，选中它就能浏览该 schema 下的表。REST API。 records 接口既接受 query 参数，也接受 PostgREST 的 profile header。读用 Accept-Profile，写和 RPC 用 Content-Profile：

# 读：?schema= 参数，或 Accept-Profile header
curl "$PROJECT_URL/api/database/records/mytable?schema=my_schema" \
  -H "Authorization: Bearer $TOKEN"

# 写：带上 Content-Profile
curl -X POST "$PROJECT_URL/api/database/records/mytable" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Profile: my_schema" \
  -H "Content-Type: application/json" \
  -d '{"name": "hello"}'

CLI。 CLI 用 db query 就能读写任意 schema，把表名加上 schema 前缀即可：

insforge db query "SELECT * FROM my_schema.mytable"

SDK。 在查询构造器前链式调用 .schema()（@insforge/sdk 支持）。它底层映射到同样的 Accept-Profile / Content-Profile header，读、写、RPC 都会路由到你指定的 schema：

// 读
const { data } = await client.database
  .schema('my_schema')
  .from('mytable')
  .select('*')

// 写
await client.database
  .schema('my_schema')
  .from('mytable')
  .insert([{ name: 'hello' }])

// RPC
await client.database.schema('my_schema').rpc('my_function', { day: '2026-01-01' })

不管走哪条路，访问 API 都还有一步：自建 schema 只是「可路由」，不等于「可读」。在你显式授权之前，anon 和 authenticated 角色对它没有任何权限，跟表的 owner 是谁无关，所以授权前调用只会返回空结果或权限不足。给你要开放的每个角色授权，再加 RLS：

GRANT USAGE ON SCHEMA my_schema TO anon, authenticated;
GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA my_schema TO anon, authenticated;

之后行级可见性照常由 RLS 控制。project_admin 拥有表，只是让它能管理并直接查询这些表（比如在 dashboard 的 SQL 编辑器里），并不会给 API 角色访问权限。

怎么给一张表开启或关闭行级安全（RLS）？

新建的表默认开启 RLS。创建表时（在 dashboard、POST /api/database/tables，或用 SDK），除非你显式传 rlsEnabled: false，否则都会启用 RLS。update-table-schema 端点（PATCH /api/database/tables/{table}/schema）没有切换 RLS 的字段——它只处理列、外键和重命名。要改已存在表的 RLS，执行一条 SQL 即可：

-- 关闭 RLS
ALTER TABLE public.mytable DISABLE ROW LEVEL SECURITY;

-- 重新开启 RLS
ALTER TABLE public.mytable ENABLE ROW LEVEL SECURITY;

用任何你运行管理员 SQL 的方式都可以执行它，这些方式都需要 project owner / admin 权限：

# 一次性执行，通过 CLI
insforge db query "ALTER TABLE public.mytable DISABLE ROW LEVEL SECURITY"

# 或者作为 migration 跟踪
npx @insforge/cli db migrations new disable-rls-on-mytable
# 把 ALTER TABLE 语句写进生成的 .sql 文件里，然后：
npx @insforge/cli db migrations up --all

也可以在 dashboard 的 SQL 编辑器、MCP 的 run-raw-sql 工具，或原始 SQL 的 REST 端点（POST /api/database/advance/rawsql/unrestricted）里执行。

关闭 RLS 会移除所有行级过滤：任何拥有表权限的角色（比如 authenticated，以及被授权的 anon）都能通过数据 API 读写每一行。相比关闭 RLS，更推荐编写 RLS 策略。用 API Key（ik_...）发起的管理员请求本来就会绕过 RLS。给一张没有任何策略的表开启 RLS 会触发 PostgreSQL 的默认拒绝：在你至少加一条策略之前，anon 和 authenticated 通过数据 API 对它的所有访问都会被拒绝（每个 SELECT/INSERT/UPDATE/DELETE 都被拦下）。请在开启 RLS 之前，或紧接着，补上需要的策略。

InsForge 有 `service_role` key / `INSFORGE_SERVICE_ROLE_KEY` 吗？

没有叫这个名字的。InsForge 里的等价物是你项目的 API Key（以 ik_ 开头），也就是全权限的管理员 key。每个项目有两个 key：

Anon Key：公开的，给浏览器用。请求以 anon 角色运行，受 RLS 管，permission denied for schema storage 就是它撞出来的。
API Key：全权限管理员 key，只在服务端用，绕过 RLS。

在 dashboard 的 Project Settings → General 里找 API Key（标着 API Key 的那一行，写明「对项目有完全控制权限，不要暴露在前端」），或者运行 npx @insforge/cli secrets get API_KEY。在可信的服务端代码里通过 createAdminClient 使用，绝不要放到浏览器：

import { createAdminClient } from '@insforge/sdk'

const admin = createAdminClient({
  baseUrl: process.env.INSFORGE_URL,
  apiKey: process.env.INSFORGE_API_KEY, // ik_... 管理员 key，绕过 RLS
})

const { data, error } = await admin.storage
  .from('post-images')
  .upload('posts/post-123/cover.jpg', fileObject)

把它放在只有服务端能读的环境变量里，绝不要用会暴露给浏览器的变量（不要带 NEXT_PUBLIC_、VITE_ 或 PUBLIC_ 前缀）。

怎么把项目分享给另一个管理员，或者邀请队友？

访问权限是按 organization（组织） 共享的，不是按单个 project。你是把人邀请进拥有这些 project 的组织，他就能访问组织下的所有 project，没有「只分享某一个 project」的入口。邀请步骤：

在 dashboard 里，用左上角的组织切换器打开拥有该 project 的组织。
点左侧栏的 Members。
点 Invite Member，填对方邮箱，选一个角色：
- Administrator（管理员）：完全控制，既能管理 project，也能邀请、移除成员、修改成员角色。
- Developer（开发者）：能正常访问组织的 project，但不能管理成员。
对方会收到一封邀请邮件（7 天内有效）。他用「收到邀请的那个邮箱」登录 InsForge 并接受后，就以你选的角色加入组织。

想专门加一个管理员，邀请时选 Administrator 即可，之后也能在 Members 列表里改角色。只有 Administrator 能邀请和管理成员。把整个组织「移交给新 Owner」是另一个独立操作，跟邀请成员不是一回事。要移交的话，打开 Organization Settings，用里面的 Transfer Ownership（只有当前 Owner 能发起，且对方必须是已验证的 InsForge 用户并接受邮件里的请求）。

为什么我的项目被暂停了？怎么避免被暂停？

只有 Free 计划会出现暂停，原因有两种：

闲置：free 项目连续 7 天没有任何请求后会被暂停。我们会先发邮件提醒，任意一次请求都会重置这 7 天的计时。
超出用量：如果你的 organization 超过了 Free 的用量额度，它下面的项目会一直保持暂停，直到你升级。

无论哪种情况，你的数据都完好无损。想彻底不再被暂停，把 organization 升级到 Pro。参见 Pricing。

我的项目被暂停了，怎么重新启动？

在 dashboard 里打开这个项目，点 Restore Project，几分钟后就会带着完整数据恢复。有几种情况要注意：

free 项目在暂停后的 30 天内都可以在 dashboard 直接恢复。超过之后项目会被归档，你只能下载数据库备份和 Storage 文件（数据仍然不会丢失）。
如果是因为 organization 超出用量而暂停，需要 Upgrade to Pro 才能恢复。

还是卡住？到我们的 Discord 提问，响应最快。

不打开浏览器，怎么给 CLI 登录鉴权？

npx @insforge/cli login 会打开浏览器登录。在无界面机器、远程服务器或 CI 上，改用 user API key，不需要浏览器。最快的方式是用 dashboard 里的 setup prompt，它会帮你登录并关联好项目：

打开 Install 页

在 dashboard 里打开你的项目，进入 Install 页。

选择你的 coding agent

在 Install in Agent 下点你在用的 agent，然后切到 CLI 标签。

复制 prompt

复制 setup prompt 粘贴给你的 agent，它会一步搞定登录和项目关联。

这个 prompt 会填好一条限定到你账号的登录命令，后面跟着关联命令：

npx @insforge/cli login --user-api-key <your-user-api-key>
npx @insforge/cli link --project-id <your-project-id>

如果你只需要那把 key（比如在 CI 里跑 CLI），打开账号菜单，进入 Profile → API Keys，创建一把 key（设个有效期，或选 Never）。把它存成 CI secret，再用它跑 login --user-api-key。加上 --json 可以得到机器可读的输出。这把 key 拥有你账号的完整权限，所以要保密，一旦泄露就轮换掉。

FLY_API_TOKEN 是什么？

只有当你自托管 InsForge 并且想使用 Custom Compute 时才需要设置这个环境变量。Custom Compute 把你的长驻容器跑在 Fly.io 上，所以自托管实例需要你自己的 Fly 账号：在 .env 里设置 FLY_API_TOKEN（用 fly tokens create org 生成的 Fly API token）和 FLY_ORG（用 fly orgs list 查到的 Fly org slug），然后重启。两者都必填，在设置之前 compute 接口会返回 503 COMPUTE_NOT_CONFIGURED。在 InsForge Cloud 上你完全不用碰这个。Compute 由平台托管，平台其余部分（数据库、认证、Storage、Edge Functions）都不需要任何 Fly token。

这个助手能帮我解决我自己项目里的具体问题吗？

基本不行。这个助手是基于 InsForge 的公开文档来回答的，看不到你的项目：既没法调试报错，也读不到你的数据，更查不了你的配置。凡是跟你自己项目相关的，交给你的编码 agent 来处理。你的 agent 通过 CLI 或 MCP 连着 InsForge，能读到你的实时后端、结构、数据和日志，直接帮你调试，用大白话描述问题就行。想自己拿一份后端健康和报错报告，跑 npx @insforge/cli diagnose。参见 Diagnostics & advisor。

怎么拿到数据库的 Postgres 连接串（connection string）？

每个 cloud 项目都有一个直连的 Postgres connection string，方便用 psql、数据库 GUI、ORM（Prisma、Drizzle），或者像 Better Auth 这类需要自带 Postgres 的外部服务。用 CLI 打印出来：

npx @insforge/cli db connection-string

你也可以在 dashboard 里拿到：进入 Project Settings → Connect → Connection String（仅限 cloud 项目）。它返回的 URL 形如：

postgresql://postgres:<password>@<appkey>.<region>.database.insforge.app:5432/insforge?sslmode=require

加上 --json 会得到 { "connectionURL": "..." }，方便脚本使用。这个命令只对 cloud 项目有效——自托管实例的 Postgres 由你的 docker-compose 直接暴露，所以请改用本地 Postgres 凭据（.env 里的 DATABASE_URL / POSTGRES_*）。这个串以拥有完整权限的 postgres 角色连接，因此不受行级安全（RLS）限制，而且串里嵌了该角色的密码。请把它当成机密：只在服务端使用，绝不要发到浏览器。

怎么把已有的 Postgres 数据库导入（load）到 InsForge？

用项目的 Postgres connection string（就是上一个问题里的那个 URL）把已有数据库还原（restore）过去即可。标准的 PostgreSQL 客户端工具——pg_dump、pg_restore 和 psql——都能直接连它，所以导入就是一次「先 dump、再 restore」。不需要专门的 InsForge 命令。

dump 你本地（或其他）的数据库：

# 自定义格式（推荐——体积更小，且支持并行 restore）
pg_dump -Fc your_local_db > local.dump

# ……或者纯 SQL 文件
pg_dump your_local_db > local.sql

拿到 InsForge 的 connection string（仅限 cloud 项目）：

npx @insforge/cli db connection-string

restore 到 InsForge：

# 自定义格式的 dump
pg_restore --no-owner --single-transaction -d "postgresql://postgres:<password>@<appkey>.<region>.database.insforge.app:5432/insforge?sslmode=require" local.dump

# ……或者纯 SQL 文件
psql --single-transaction "postgresql://postgres:<password>@<appkey>.<region>.database.insforge.app:5432/insforge?sslmode=require" < local.sql

有几点需要注意：

加上 --no-owner，让还原出来的对象归 postgres 角色所有，而不是只存在于源库里的那些角色。
这个 connection string 以拥有完整权限的 postgres 角色连接（会绕过行级安全 RLS），请把它当成机密，只在服务端运行这些命令。
这只对 cloud 项目有效。自托管实例请改用本地 Postgres 凭据（.env 里的 DATABASE_URL / POSTGRES_*）来 restore。
restore 会写入你正在使用的数据库，并可能覆盖已有对象。请先手动做一次备份——参见数据库备份与恢复。
--single-transaction 让整个恢复在单个事务里执行：任何一句失败（对象已存在、扩展或角色缺失、约束冲突），整个导入都会回滚，而不会把数据库留在导入了一半的状态。
导入的表不会自动获得 InsForge 托管的访问设置。raw 恢复会跳过 InsForge 为表配置的 anon / authenticated 授权和行级安全（RLS），因此在你为每张表授予访问权限并添加 RLS 策略之前，这些表无法通过 REST API 或 SDK 访问，源库里的访问规则也不带 InsForge 的 RLS 保护（参见数据库）。如果你更想把 schema 变更纳入 git 版本管理，参见数据库迁移。

怎么下线或删除已部署的站点（site）？

目前没有自助下线已部署 Site 的方式——既没有 deployments delete 命令，dashboard 里也没有对应操作。已部署的站点托管在外部，所以即使删除项目（npx @insforge/cli projects delete --project <id>）也只会清掉后端资源——数据库、Storage 和后端分支——而不会移除已托管的站点。实际上这基本不影响使用。如果你确实需要下线某个已部署的站点，请到 Discord 联系 InsForge 团队。有两个相关操作，和「下线一个已上线站点」并不是一回事：

取消还在跑的构建： npx @insforge/cli deployments cancel <id> 会终止一个进行中的部署；它不会下线一个已经上线的站点。
替换当前上线的内容： 用 npx @insforge/cli deployments deploy ./frontend 在同一个站点上重新部署——最新一次 ready 的部署会接管这个 URL。

快速开始

Products

Agent-Native Initiatives

Partnership

Self-Hosting

Resources

常见问题

InsForge 常见问题：数据库、Edge Function 与 SDK