Backend Cloud SDK v4.1（免登录匿名会话 + 请求签名 + CLI 云端部署试跑）

平台官方 SDK：凭接入应用凭证触发「属主自己部署的云函数」，并附带 bc 命令行工具，支持在本地编写云函数、上传部署到平台云端沙箱试跑。

云函数模型（v4.1 起）：平台已关闭云数据库与内置云函数的开放直连接口。 云数据库（ctx.db）、关系型库（ctx.sql）、系统内置函数（ctx.call）、文件保存（ctx.fs）只能在属主云函数沙箱内经 ctx 访问； 接入应用的外部客户端（浏览器 / 服务端）只能调用 client.fnCall('函数名', args) 触发这些自有云函数。

安全模型（v4.0 双模认证，替代早期 L0/L1/L2 三模）：

• 匿名会话（浏览器免登录首选）：仅凭 appId，SDK 自动向 POST /v1/auth/session 换取短期会话令牌（X-BC-Session-Token）——零登录、无需自建后端换发票据。令牌仅存内存、短期有效（默认 1h）、可随时吊销；临期自动静默续签，失效自动重签重放。
• 请求签名（可信服务端）：配置 appSecret，SDK 自动构造 canonical 规范串并携带 X-BC-Timestamp / X-BC-Nonce / X-BC-Signature。仅限服务端环境（浏览器禁止配置，会暴露凭证）。
• 早期 L0 裸 appid 直连与 L2 STS（X-BC-Temp-Token）通道已移除，携带旧头一律 401。
• 所有模式仍受接入应用的来源 Origin 白名单 + 函数白名单 + 读写 scope 强校验（会话签发与使用均强制 Origin）。

一、快速开始：CLI 云端部署试跑（推荐）

# 1) 安装 SDK（自带 bc 命令）
npm install backend-cloud-sdk

# 2) 一行命令创建云开发配置目录（.env + functions/ 云函数模板）
npx bc init . --appid 你的appid --baseUrl http://localhost:3000
#    生成：
#      .env                BC_APP_ID / BC_BASE_URL / BC_TOKEN（部署需控制台令牌）
#      functions/hello.js  云函数编写模板（ctx.args / ctx.db / ctx.call / ctx.fs）

# 3) 本地写好云函数，上传部署到平台云端沙箱并试跑一次
npx bc run functions/hello.js --args '{"name":"world"}'

appid 在平台控制台「我的应用」页创建接入应用后获得；部署令牌 BC_TOKEN 在控制台「云函数」页获取（bc run 需属主令牌在云端部署执行，平台已无开放直连环境）。切勿把令牌提交公共仓库。

云函数模板（functions/hello.js）

module.exports = async (ctx) => {
  const doc = await ctx.db.insert('orders', { title: '示例订单', qty: 1 }) // 云数据库写入
  const { total, list } = await ctx.db.find('orders', { page: 1, pageSize: 10 }) // 查询
  await ctx.call('util_date_format', { value: 1788060000 }) // 调用系统内置函数
  return { total, first: list[0], insertedId: doc._id }
}

.mjs 文件使用 export default async (ctx) => { ... }。

ctx 能力（只在属主云函数沙箱内可用）

| 能力 | 说明 | |---|---| | ctx.args | 调用入参（对象） | | ctx.db.insert/insertMany/find/get/update/remove/removeMany | 云数据库（文档库）CRUD | | ctx.sql.* | 关系型数据库（RDB）操作（需存在对应表） | | ctx.call(name, args?) | 调用系统内置函数 或 属主自己的其他云函数 | | ctx.fs.save(...) 等文件能力 | 二进制文件保存 | | ctx.http / ctx.kv / ctx.crypto | 出网 / KV 存储 / 加密原语 |

平台已关闭云数据库/内置函数的开放直连接口：函数会上传部署到平台云端沙箱执行，ctx 的云资源访问只能在函数内发生，外部 SDK 客户端没有 data* / uploadFile 直连方法。

二、SDK 接入方式

| 方式 | 适用场景 | 引入 | |---|---|---| | npm / CLI | Vue / React / 现代打包器 / Node / 本地云开发 | npm i backend-cloud-sdk | | CDN | 快速体验、静态页 | https://unpkg.com/[email protected]/dist/umd/backend-cloud-sdk.js | | <script> | 平台同域静态托管 | <script src="/sdk/backend-cloud-sdk.js"></script> | | 原生 HTML/JS | 零构建、传统页面 | 同上（UMD 全局变量 BackendCloudClient） |

1. npm

npm install backend-cloud-sdk

浏览器（匿名会话，免登录首选）：

import { BackendCloudClient } from 'backend-cloud-sdk'

// 只需 appId：首个请求自动签发匿名会话（需页面 Origin 命中应用白名单），临期自动续签
const client = BackendCloudClient.create({ baseUrl: 'http://localhost:3000', appId: 'xxx' })
const r = await client.fnCall('orders_stat', { page: 1, pageSize: 10 }) // 触发属主云函数

// 可选：手动管理会话（如由开发者后端代发后注入）
// client.withSessionToken('服务端下发的sessionToken')
// const cred = await client.issueSession({ ttl: 1800, endUserId: 'u_123' })

服务端（Node，请求签名）：

import { BackendCloudClient } from 'backend-cloud-sdk'

const client = BackendCloudClient.create({
  baseUrl: 'http://localhost:3000',
  appId: '你的appid',
  appSecret: process.env.BC_APP_SECRET, // 仅服务端；配置后自动走 HMAC 请求签名
})

2. CDN / <script> / 原生 HTML

<script src="/sdk/backend-cloud-sdk.js"></script>
<script>
  const client = BackendCloudClient.createBrowser({ appId: '你的appid' })
  client.fnCall('orders_stat', { page: 1 })
    .then((r) => console.log(r.total, r.list))
</script>

三、Vue 3 接入

方式 A：插件

// main.js
import { createApp } from 'vue'
import { BackendCloudPlugin } from 'backend-cloud-sdk/vue'

createApp(App).use(BackendCloudPlugin, { baseUrl: '', appId: 'xxx' }).mount('#app')

方式 B：组合式 API

<script setup>
import { onMounted } from 'vue'
import { createBackendCloud, useBackendCloud } from 'backend-cloud-sdk/vue'

createBackendCloud({ baseUrl: '', appId: 'xxx' }) // 应用启动时初始化一次
const { client } = useBackendCloud()

onMounted(async () => {
  const r = await client.fnCall('orders_stat', { page: 1 }) // 数据读取封装为属主云函数
})
</script>

四、React 接入

import { useEffect, useState } from 'react'
import { createBackendCloud, useBackendCloud } from 'backend-cloud-sdk/react'

createBackendCloud({ baseUrl: '', appId: 'xxx' }) // 应用入口初始化一次

function Orders() {
  const { client } = useBackendCloud()
  const [list, setList] = useState([])

  useEffect(() => {
    client.fnCall('orders_stat', { page: 1 }).then((r) => setList(r.list)) // 数据读取封装为属主云函数
  }, [])

  return <div>{list.length} 条记录</div>
}

五、核心 API

初始化与认证模式

| 方法 / 属性 | 说明 | |---|---| | BackendCloudClient.create({ baseUrl, appId, appSecret? }) | 通用入口（Node / 浏览器）；配置 appSecret 走请求签名，否则浏览器走匿名会话 | | BackendCloudClient.createBrowser(opts) | 浏览器入口（自动携带页面 Origin，需命中应用来源白名单）；兼容旧名，等价 create | | client.issueSession({ ttl?, endUserId? }) | 主动签发匿名会话（免登录：appId + Origin 白名单即可）；成功自动写入本实例，越界报 2916 | | client.withSessionToken(token) | 切换 / 清除会话令牌（传 null 后首个请求自动重签） | | client.sessionTokenValue | 当前缓存的会话令牌 | | client.id | 当前使用中的 appid |

自动行为：浏览器模式首个请求前自动签发会话；剩余寿命 < 20% 时自动续签；收到 2915（令牌失效）自动重签一次后重放原请求。

云函数（唯一开放入口）

| 方法 | 对应接口 | |---|---| | fnCall(name, args?) | POST /v1/fn/:name（body 即 ctx.args） |

const result = await client.fnCall('orders_stat', { page: 1, pageSize: 20, where: { status: 'paid' } })
console.log(result.total, result.list)

平台已移除 dataList / dataGet / dataCreate / dataUpdate / dataDelete / uploadFile 等开放直连方法： 云数据库 / 关系型库 / 系统内置函数 / 文件保存均只能在属主云函数内经 ctx 访问（见第一节）。把业务逻辑写成一个或多个云函数，客户端以 fnCall 触发即可。

六、安全说明

• 双模认证：浏览器免登录（appId + Origin 自动签发短期匿名会话，默认 1h，可吊销）；可信服务端配 appSecret 走请求签名。L0 裸 appid 与 L2 STS 通道已移除。
• appSecret 只在服务端：浏览器配置会直接抛错（防凭证泄漏）。
• 来源白名单强制：会话的签发与每一次使用都必须携带 Origin 且命中应用白名单（2904；签发缺失 Origin 报 2918）——令牌被摘走也无法在非浏览器环境使用。
• 开放面只调属主函数：fnCall 仅解析「接入应用属主自己部署的云函数」（isBuiltin=0 且属主本人），函数级白名单（配置为空 = 属主全部自有函数，非空则仅白名单内函数可调，403/2906）。
• 请求签名防护：时间窗（默认 ±300s）+ 一次性 nonce，篡改/超窗/重放返回 2913。
• 端用户标识：issueSession({ endUserId }) 或请求签名模式携带 X-BC-End-User 头，平台调用日志据此区分端用户（仅统计维度，不做权限隔离）。
• 应用停用 / 删除 / 切换为强制签名 / 属主封禁 → 该 appid 的会话即时全部失效。
• 错误：非 2xx 或业务码非 0 时，SDK 抛出携带 status 与平台业务码（2901/2902/2904/2910/2913/2915/2916/2918 等）的 SDKError。

七、从源码构建

pnpm --filter backend-cloud-sdk build   # 或 cd apps/sdk && pnpm build
# 产物：dist/esm（ESM+类型）、dist/cjs（CJS+类型）、dist/umd/backend-cloud-sdk.js（UMD）、dist/vue.mjs、dist/react.mjs、
# bin/bc.mjs（CLI），并同步拷贝 UMD 到 apps/web/public/sdk/