Busabase

应用用户

让顾客用邮箱验证码登录你在 Busabase 上做的应用,只看到自己的订单和记录;你来管理这些账号,不占任何席位。

商店的买家下周还想再看看自己的订单;会员专属页面需要知道是谁在看。应用用户让使用你应用的人有一个自己的账号:用发到邮箱的验证码登录,只看到属于自己的数据行,永远看不到 Busabase,也不占席位。

应用用户功能在 Busabase 云端版提供,适用于发布成网站的应用。

应用用户、成员和访客

谁是什么人能做什么
成员你的团队在 Busabase 里打开空间,占一个席位,按权限使用数据表、文档和应用
应用用户你的应用服务的人,比如商店买家只能登录你的应用。不占席位,看不到 Busabase 的任何界面,也没有密码。他们看到的是你的应用给他们看的内容,并且只有自己的数据行
访客不登录就使用你应用的人应用公开提供的功能,比如浏览商品、免登录下单

每个空间只有一个应用用户池。 同一个邮箱登录了你的两个应用,就是同一个应用用户,只是用过两个应用。应用用户永远不是成员,成为应用用户也不会让任何人获得访问你工作区的权限。

为应用打开用户登录

你需要对这个应用有管理权限。在 Busabase Cloud 上,空间还需要是 Plus 及以上套餐(试用期也算)。免费版的开关是锁定的,并显示升级按钮。如果空间在开启用户登录后降回免费版,不会再发送新的验证码,已登录的人在会话到期前保持登录,你仍然可以关闭用户登录。

  1. 打开应用,进入设置 → 用户登录。
  2. 打开允许用户登录这个应用。
  3. 填写邮件中显示的名称。买家会在验证码邮件的发件人和标题里看到这个名称。不填就用应用本身的名称。
  4. 点保存。

要设置的就这些。用户账号由 Busabase 保存,你不需要建用户表。

每一行数据归谁

哪些行属于哪位买家,由应用自己决定,而不是靠一项设置。应用把买家的 id 存在一个应用用户列(或普通的文本列)里,比如订单表里的 customer-account:登录的买家下单时,应用的服务器把他的应用用户 id 写进这一列。买家打开「我的订单」时,应用向 Busabase 要 customer-account 等于当前登录买家的那些行,而买家的 id 由 Busabase 从已验证的登录里填进去,谁也没法冒充别人的 id。

  • 归属列为空的行不属于任何人,免登录下的订单就保持这样。
  • 应用用户列会把每个 id 显示成买家的邮箱,标出已停用的买家,已删除的账号显示为已删除的应用用户。点击邮箱可以看到买家的状态、最近登录和登录过的应用,并有管理应用用户的入口。编辑数据行时,空间所有者和管理员可以按邮箱选择买家;其他成员只能保留或清除当前值。
  • 已经有一列存 id 的文本列?在列设置里把类型改成应用用户即可,所有值都会保留。
  • 导出模板时不会带上应用用户列的值:这些 id 属于本空间的买家,在别的空间没有意义。列本身会保留。

关闭用户登录会让所有人退出

关闭允许用户登录这个应用后,这个应用的所有登录会话立刻失效。只要应用按下文的方式处理过(见给开发者),访客功能会照常可用。

买家看到的是什么

  1. 在你的应用里输入邮箱。
  2. 收到一个 6 位验证码,不用设置密码,也不会忘记密码。
  3. 输入验证码就登录了,在这个浏览器上保持登录 30 天。

验证码 10 分钟内有效,最多可以试 5 次。重新获取验证码后,之前的验证码就失效了。

邮件里写的是你应用的名字(邮件中显示的名称,没填就用应用名称),从不提 Busabase。邮件语言跟随应用的请求:英语、简体中文、繁体中文、日语、韩语、德语、法语、西班牙语、葡萄牙语或越南语,其他语言一律用英语。

登录频率限制

为了防止你的应用被拿来发垃圾邮件,Busabase 会限制发送验证码的频率。触发限制时,应用会收到 RATE_LIMITED,附带原因 reason 和需要等待的秒数 retryAfterSeconds。按下面的顺序检查:

reason限制应用该怎么告诉买家
cooldown同一个邮箱 60 秒内只能发一次「验证码刚发出,N 秒后可以重新获取。」
ip_hourly_limit同一个网络每小时最多 5 个,按应用计「这个网络尝试次数太多,请稍后再试。」
ip_daily_limit同一个网络每天最多 20 个,按应用计同上
email_daily_limit同一个邮箱每天最多 10 个「这个邮箱今天获取验证码次数太多,请明天再试。」
space_daily_limit每个空间每天最多 1000 个,只计算还不是应用用户的邮箱「登录有点忙,请稍后再试。」

space_daily_limit 永远不会把老顾客挡在门外:只有新邮箱才计入这个额度,所以就算有人往随机邮箱狂发验证码,你现有的买家照样能登录。

只有应用在请求里带上买家的 IP 地址时,按网络的限制才生效。Busabase 只保存这个地址加密钥后的哈希值,从不保存地址本身。

管理应用用户

打开空间设置 → 应用用户,可以看到所有登录过你应用的人。

  • 用按邮箱搜索和按应用筛选找人。列表里有每个人的状态、最近登录时间、用过哪些应用、账号创建时间。点加载更多查看更早的账号。
  • 停用:不让这个人再登录,并让 TA 立刻从所有应用退出。启用:让 TA 可以重新登录。
  • 删除:删除账号、验证码和登录会话。TA 的订单和其他记录都会保留。之后如果 TA 再次登录,会得到一个新账号。

谁能做什么:

角色可以
空间所有者或管理员查看全部应用用户,停用、启用、删除
对某个应用有管理权限的成员在这个应用的设置 → 用户登录 → 管理应用用户里,只读查看登录过这个应用的人;修改这个应用的登录设置
其他成员查看应用的登录设置

每一次停用、启用、删除,以及每一次修改应用的登录设置,都会记进云端的审计日志,写明是哪位成员、用哪把 API 密钥做的。

用 CLI 或智能体管理

同样的管理操作也可以用 CLI 完成:

busabase-cli app-users list --email buyer@example.com            # 或 --app-id <应用 id>
busabase-cli app-users disable --id <应用用户 id>
busabase-cli app-users enable --id <应用用户 id>
busabase-cli app-users delete --id <应用用户 id>
busabase-cli app-users get-settings --app-id <应用 id>
busabase-cli app-users put-settings --app-id <应用 id> --enabled --app-name "Kelly 的小店"
busabase-cli app-users put-settings --app-id <应用 id> --no-enabled   # 关闭用户登录(所有人会被登出)

通过 MCP,智能体可以使用 app_users_list、app_users_disable、app_users_enable、app_users_delete、app_users_get_settings 和 app_users_put_settings 这几个工具。智能体不能发送登录验证码,也不能以应用用户的身份操作:这些步骤只属于你应用的服务器。

隐私

  • 删除应用用户会删掉账号、验证码和登录会话,订单等业务数据行都会保留。这些行的归属列里还是旧 id,以后任何新账号都不可能匹配上。
  • Busabase 对验证码、登录令牌和 IP 地址只保存哈希值。
  • 旧的验证码记录 48 小时后会自动清理。

给开发者

应用对应用用户做的一切,都发生在应用自己的服务器上(网站就是它的 Worker),用的是网站已经有的 API 密钥。浏览器只和你应用自己的路由打交道,比如 /account/send-code,永远拿不到 API 密钥。

用 SDK 实现登录流程

import {
  Busabase,
  appUserSessionCookie,
  clearAppUserSessionCookie,
  getAppUserSessionToken,
} from "busabase-sdk";

const bb = new Busabase({
  baseUrl: env.BUSABASE_BASE_URL,
  apiKey: env.BUSABASE_API_KEY,
  spaceId: env.BUSABASE_SPACE_ID,
});
const appId = "<应用节点 id>";

// 1. POST /account/send-code:按商店的语言给买家发验证码。
await bb.appUsers.sendCode({
  appId,
  email,
  locale: "zh-CN",
  ip: request.headers.get("CF-Connecting-IP") ?? undefined,
});

// 2. POST /account/verify:用验证码换登录会话,存进 HttpOnly Cookie。
const { sessionToken } = await bb.appUsers.verify({ appId, email, code });
return new Response(null, {
  status: 303,
  headers: { Location: "/account", "Set-Cookie": appUserSessionCookie(sessionToken) },
});

// 3. GET /account:谁登录了,以及 TA 自己的订单。
const token = getAppUserSessionToken(request);
const user = await bb.appUsers.getUser({ appId, sessionToken: token }); // 未登录时为 null
if (user) {
  const { records, nextCursor } = await bb.appUsers.queryRecords({
    appId,
    sessionToken: token,
    baseId: "orders",
    ownerField: "customer-account", // 存买家应用用户 id 的应用用户列(或文本列)
    limit: 20,
  });
}

// 4. POST /account/sign-out
await bb.appUsers.signOut({ appId, sessionToken: token });
return new Response(null, {
  status: 303,
  headers: { Location: "/", "Set-Cookie": clearAppUserSessionCookie() },
});
  • 传 locale,让邮件和网站语言一致;传 ip(买家的地址,取 CF-Connecting-IP,没有就取 X-Forwarded-For 的第一个),让按网络的限制保护你。
  • 登录的买家新建一行(比如下单)时,在服务器上从会话里取 user.id 写进归属列,绝不用浏览器传来的值。买家已验证的 user.email 也照样写进单独的邮箱列。
  • queryRecords 要传 ownerField,也就是存应用用户 id 的那个应用用户列(或文本列)的 slug。用哪一列由你的服务器决定;值由 Busabase 从已验证的会话里填入,并强制 ownerField = 当前登录用户 id:别人的数据行根本不会出现。

不要自己筛选用户的数据行

不要用网站的密钥读整张数据表,再在代码里筛出「这个买家的订单」。网站密钥能读到所有行,一个 bug 就会让一位顾客看到另一位顾客的订单。一定要用 bb.appUsers.queryRecords(POST /api/v1/app-users/records/query)并传 ownerField,由 Busabase 用当前登录用户的 id 加归属筛选。

需要处理的错误

错误带有 code,额外信息在 data 里:

code什么时候怎么处理
APP_LOGIN_DISABLED这个应用没开用户登录隐藏账号相关界面
INVALID_EMAIL邮箱格式不对请买家检查邮箱
RATE_LIMITED触发频率限制;data.reason、data.retryAfterSeconds按上面表格里的提示显示
INVALID_CODE验证码不对;data.attemptsLeft请 TA 再试一次
CODE_EXPIRED验证码过期、次数用完或从没发过提供重新发送
APP_USER_DISABLED账号已被停用告诉 TA 这个账号无法登录
APP_USER_SESSION_INVALID会话不存在、过期、被撤销或属于别的应用清掉 Cookie,显示登录表单(getUser 会直接返回 null)
INVALID_OWNER_FIELDownerField 不是这张数据表的应用用户列或文本列改正应用代码里的列 slug

让访客流程照常可用

用户登录是可选的,没有它应用也必须能用。用 bb.appUsers.getSettings({ appId }) 读一次设置:如果返回 enabled: false,或者请求返回 404(还没有应用用户功能的旧版服务器),就隐藏所有账号入口,免登录下单等公开功能保持原样。

On this page