Docs
文档目录

权限(行级 / 表级 / 存储与复杂授权)

这是什么 / 何时用

Agentbase 的授权模型:权限动作 × 角色 → $permissions 字符串,分别配置在表(Table)、行(Row)与存储桶 / 文件上,配合 rowSecurity / fileSecurity 开关生效。何时用:实现「用户只能访问自己的数据」「团队共享」「管理员可见」等访问控制;以及 Client SDK 约束下需要给别人授权的复杂场景。

前置

权限模型

动作与挂载点

动作表 $permissions行 $permissions效果
read可以可以读整表所有行 / 读指定行
create可以(建行必经)无意义谁能在该表建行
update / delete可以可以改 / 删任意行 / 指定行
write可以可以create+update+delete(不含 read)的快捷方式

判定模型(rowSecurity)

操作rowSecurity: false(默认)rowSecurity: true
创建行必须有表级 create仍必须有表级 create
读 / 改 / 删行仅表级权限表级 或 该行权限(canRead(row) = table.read OR row.read)

表级权限是「放行」不是「限制」:配置了表级 read(Role.users()) 后所有会话用户可读全部行,行级 $permissions 不再构成约束。enabled: false 对普通用户停用整表,API Key 仍可管理。

Role 常量速查

角色含义典型用途
Role.any()任意请求(含无会话访客)公开读取;写入慎用
Role.guests()无会话访客登录前专属内容
Role.users()任意有会话用户(含匿名会话)登录后可用资源
Role.user(userId)指定用户行拥有者
Role.team(teamId[, role])团队(可限成员角色)团队共享
Role.member(membershipId)指定成员关系精细团队授权
Role.label(labelId)带标签用户管理员 / 审核员

权限之间是允许的并集,没有「显式拒绝」规则。

使用骨架(推荐模式:创建者独占)

  1. 建表只授 create:createTable({ permissions: [Permission.create(Role.users())], rowSecurity: true, enabled: true });不要再加普通用户的表级 read/update/delete/write,否则绕过行级隔离。

  2. 客户端建行省略 permissions:服务端自动写入创建者的 read/update/delete;ownerId 之类业务字段可以加,但它不是权限边界。

  3. 需要显式表达时:permissions: [Permission.read(Role.user(自己)), Permission.update(Role.user(自己)), Permission.delete(Role.user(自己))];不要从页面参数接受任意 ownerId 套 Role.user()。

  4. 服务端代用户建行:API Key 请求没有「当前最终用户」,省略 permissions 会得到空行权限——必须先从可信会话 / JWT 取得用户 ID,再显式授予该用户。

  5. 团队协作:文件 / 行的 update/delete 用 Role.team(teamId) 而不是上传者个人,避免「只有上传者能删」的 403。

关键边界:Client SDK 的 hasRole 约束

Client SDK 创建 / 更新行时,permissions 里每个 Role 都必须通过 authorization.hasRole(role):

因此 Client SDK 无法在行级给别人授权;需要时走 Function 代理:

  1. 前端建行只含自己。

  2. 需要共享时调 Function,Function 内用 Server SDK 读行 $permissions、校验调用者确为行 owner(x-appwrite-user-id),合并目标用户 / 标签权限后 updateRow 全量提交,并留审计。

  3. 可配一张授权记录表(resourceId / granteeId / accessLevel / grantedBy),前端直接查询「我被授权了什么」,变更仍由 Function 完成。

关键边界:updateRow 全量替换

updateRow 传 permissions 时是全量替换,不是增量追加:只传新权限会丢掉原有全部权限。正确做法是先 getRow 读 $permissions,在副本上增删后整组提交。不传 permissions 则保留原权限。

存储权限(bucket / file)

错误与边界

SDK 类别差异

示例指引

各语言调用示例

以下按使用骨架逐项给出各语言调用示例;每个卡片可切换语言(全页同步)。

建表基线:只授 create(服务端)

rowSecurity: true 下人人可建行,但只能看到(或改、删)自己的行;不要再加普通用户的表级 read/update/delete/write。无 Web 页签:建表属服务端动作(Console 在 UI 配置基线)。

import { Client, TablesDB, Permission, Role } from 'agentbase-node-sdk';

const client = new Client()
    .setEndpoint(process.env.APPBASE_ENDPOINT!)   // 必须包含 /v1
    .setProject(process.env.APPBASE_PROJECT_ID!)
    .setKey(process.env.APPBASE_API_KEY!);
const tablesDB = new TablesDB(client);

await tablesDB.createTable({
    databaseId: 'main',
    tableId: 'private_notes',
    name: 'Private notes',
    permissions: [Permission.create(Role.users())],
    rowSecurity: true,
    enabled: true,
});
// 不要再加表级 read/update/delete/write(Role.users())——会绕过行级隔离

客户端建行:创建者默认独占

Client SDK 省略 permissions 时服务端自动写入创建者的 read/update/delete;Server SDK(API Key)没有「当前最终用户」,必须显式授予。

import { ID, Permission, Role } from 'agentbase-node-sdk';

// API Key 请求省略 permissions 会得到空行权限:
// 先从可信会话 / JWT 取得用户 ID,再显式授予该用户
const userId = '<从已验证会话 / JWT 取得>';
await tablesDB.createRow({
    databaseId: 'main',
    tableId: 'private_notes',
    rowId: ID.unique(),
    data: { title: 'My note' },
    permissions: [
        Permission.read(Role.user(userId)),
        Permission.update(Role.user(userId)),
        Permission.delete(Role.user(userId)),
    ],
});

团队协作共享与全量替换(updateRow / Role.team)

updateRow 传 permissions 是全量替换:先 getRow 读 $permissions,在副本上增删后整组提交;不传则保留原权限。Client SDK 无法在行级给别人授权(hasRole 约束),共享走 Function 代理(见上文)。

import { Permission, Role } from 'agentbase-node-sdk';

const row = await tablesDB.getRow({ databaseId: 'main', tableId: 'private_notes', rowId: '<rowId>' });
const next = [...row.$permissions, Permission.read(Role.team('dev'))];
await tablesDB.updateRow({
    databaseId: 'main',
    tableId: 'private_notes',
    rowId: '<rowId>',
    permissions: next,          // 只传新权限会丢掉原有全部权限
});