应用用户
让顾客用邮箱验证码登录你在 Busabase 上做的应用,只看到自己的订单和记录;你来管理这些账号,不占任何席位。
商店的买家下周还想再看看自己的订单;会员专属页面需要知道是谁在看。应用用户让使用你应用的人有一个自己的账号:用发到邮箱的验证码登录,只看到属于自己的数据行,永远看不到 Busabase,也不占席位。
应用用户功能在 Busabase 云端版提供,适用于发布成网站的应用。
应用用户、成员和访客
| 谁 | 是什么人 | 能做什么 |
|---|---|---|
| 成员 | 你的团队 | 在 Busabase 里打开空间,占一个席位,按权限使用数据表、文档和应用 |
| 应用用户 | 你的应用服务的人,比如商店买家 | 只能登录你的应用。不占席位,看不到 Busabase 的任何界面,也没有密码。他们看到的是你的应用给他们看的内容,并且只有自己的数据行 |
| 访客 | 不登录就使用你应用的人 | 应用公开提供的功能,比如浏览商品、免登录下单 |
每个空间只有一个应用用户池。 同一个邮箱登录了你的两个应用,就是同一个应用用户,只是用过两个应用。应用用户永远不是成员,成为应用用户也不会让任何人获得访问你工作区的权限。
为应用打开用户登录
你需要对这个应用有管理权限。在 Busabase Cloud 上,空间还需要是 Plus 及以上套餐(试用期也算)。免费版的开关是锁定的,并显示升级按钮。如果空间在开启用户登录后降回免费版,不会再发送新的验证码,已登录的人在会话到期前保持登录,你仍然可以关闭用户登录。
- 打开应用,进入设置 → 用户登录。
- 打开允许用户登录这个应用。
- 填写邮件中显示的名称。买家会在验证码邮件的发件人和标题里看到这个名称。不填就用应用本身的名称。
- 点保存。
要设置的就这些。用户账号由 Busabase 保存,你不需要建用户表。
每一行数据归谁
哪些行属于哪位买家,由应用自己决定,而不是靠一项设置。应用把买家的 id 存在一个应用用户列(或普通的文本列)里,比如订单表里的 customer-account:登录的买家下单时,应用的服务器把他的应用用户 id 写进这一列。买家打开「我的订单」时,应用向 Busabase 要 customer-account 等于当前登录买家的那些行,而买家的 id 由 Busabase 从已验证的登录里填进去,谁也没法冒充别人的 id。
- 归属列为空的行不属于任何人,免登录下的订单就保持这样。
- 应用用户列会把每个 id 显示成买家的邮箱,标出已停用的买家,已删除的账号显示为已删除的应用用户。点击邮箱可以看到买家的状态、最近登录和登录过的应用,并有管理应用用户的入口。编辑数据行时,空间所有者和管理员可以按邮箱选择买家;其他成员只能保留或清除当前值。
- 已经有一列存 id 的文本列?在列设置里把类型改成应用用户即可,所有值都会保留。
- 导出模板时不会带上应用用户列的值:这些 id 属于本空间的买家,在别的空间没有意义。列本身会保留。
关闭用户登录会让所有人退出
关闭允许用户登录这个应用后,这个应用的所有登录会话立刻失效。只要应用按下文的方式处理过(见给开发者),访客功能会照常可用。
买家看到的是什么
- 在你的应用里输入邮箱。
- 收到一个 6 位验证码,不用设置密码,也不会忘记密码。
- 输入验证码就登录了,在这个浏览器上保持登录 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_FIELD | ownerField 不是这张数据表的应用用户列或文本列 | 改正应用代码里的列 slug |
让访客流程照常可用
用户登录是可选的,没有它应用也必须能用。用 bb.appUsers.getSettings({ appId }) 读一次设置:如果返回 enabled: false,或者请求返回 404(还没有应用用户功能的旧版服务器),就隐藏所有账号入口,免登录下单等公开功能保持原样。