权限(行级 / 表级 / 存储与复杂授权)
这是什么 / 何时用
Agentbase 的授权模型:权限动作 × 角色 → $permissions 字符串,分别配置在表(Table)、行(Row)与存储桶 / 文件上,配合 rowSecurity / fileSecurity 开关生效。何时用:实现「用户只能访问自己的数据」「团队共享」「管理员可见」等访问控制;以及 Client SDK 约束下需要给别人授权的复杂场景。
前置
表结构与桶配置由服务端(API Key)或 Console 下发;API Key 不交给浏览器 / 移动端。
SDK 的
Permission/Role辅助类(JS 为Permission.read(Role.user(id))形态;Java / Python 同构)。
权限模型
动作与挂载点
| 动作 | 表 $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) | 带标签用户 | 管理员 / 审核员 |
权限之间是允许的并集,没有「显式拒绝」规则。
使用骨架(推荐模式:创建者独占)
建表只授
create:createTable({ permissions: [Permission.create(Role.users())], rowSecurity: true, enabled: true });不要再加普通用户的表级read/update/delete/write,否则绕过行级隔离。客户端建行省略
permissions:服务端自动写入创建者的read/update/delete;ownerId之类业务字段可以加,但它不是权限边界。需要显式表达时:
permissions: [Permission.read(Role.user(自己)), Permission.update(Role.user(自己)), Permission.delete(Role.user(自己))];不要从页面参数接受任意ownerId套Role.user()。服务端代用户建行:API Key 请求没有「当前最终用户」,省略
permissions会得到空行权限——必须先从可信会话 / JWT 取得用户 ID,再显式授予该用户。团队协作:文件 / 行的
update/delete用Role.team(teamId)而不是上传者个人,避免「只有上传者能删」的 403。
关键边界:Client SDK 的 hasRole 约束
Client SDK 创建 / 更新行时,permissions 里每个 Role 都必须通过 authorization.hasRole(role):
✅
Role.user(自己的 ID)、已加入的Role.team(...)、Role.any()/Role.users();❌
Role.user(别人的 ID)、未加入的团队 → 401;Role.label('admin')仅当自己真有该标签;Server SDK(API Key)跳过整组检查,可自由授权。
因此 Client SDK 无法在行级给别人授权;需要时走 Function 代理:
前端建行只含自己。
需要共享时调 Function,Function 内用 Server SDK 读行
$permissions、校验调用者确为行 owner(x-appwrite-user-id),合并目标用户 / 标签权限后updateRow全量提交,并留审计。可配一张授权记录表(
resourceId/granteeId/accessLevel/grantedBy),前端直接查询「我被授权了什么」,变更仍由 Function 完成。
关键边界:updateRow 全量替换
updateRow 传 permissions 时是全量替换,不是增量追加:只传新权限会丢掉原有全部权限。正确做法是先 getRow 读 $permissions,在副本上增删后整组提交。不传 permissions 则保留原权限。
存储权限(bucket / file)
双层模型:桶级是「大门」,
fileSecurity: true时文件级是「房门」;有桶级权限直接放行,没有则按文件级$permissions判定。权限不足返回 404(
file_not_found),不是 403——隐藏文件存在性的安全设计;排障先查权限。fileSecurity: false:仅按桶级判定,不匹配即 401。跨域
<img>场景 Cookie 丢失导致「看起来 404」的处理(Blob URL / File Token)见 storage.md。Function 代理同样适用于把桶文件授权给其他用户 / 团队。
错误与边界
401
Permissions must be one of: (any, users, user:xxx, user:xxx/unverified, users/unverified):Client SDK 行级用了不属于自己或不受支持的角色。表级
write(Role.users())会意外放开所有人 update/delete;不要用write当「读写都开」。匿名会话计入
Role.users();完全匿名可写要用Role.any()并自行防护滥用。权限变更即时生效;已在客户端缓存的行列表不会自动失效。
SDK 类别差异
Client SDK:受
hasRole约束(见上);行 / 文件的日常读写、查询自己可见的数据。Server SDK:跳过
hasRole;配置表 / 桶基线权限、代用户授权、批量治理。Console SDK:不承担业务授权;仅在 Console UI 配置基线。
差异入口:client-sdk/web.md、
server-sdk/nodejs.md。
示例指引
各语言写法集中在语言树
examples/;Function 代理完整代码、权限表 schema 与多场景(部分用户可读、按角色授权、撤销)见skills/ob-agentbase/references/client-sdk-complex-permissions.md与skills/ob-agentbase/references/database-permissions.md。
各语言调用示例
以下按使用骨架逐项给出各语言调用示例;每个卡片可切换语言(全页同步)。
建表基线:只授 create(服务端)
rowSecurity: true 下人人可建行,但只能看到(或改、删)自己的行;不要再加普通用户的表级 read/update/delete/write。无 Web 页签:建表属服务端动作(Console 在 UI 配置基线)。
- Node.js(Server)
- Java
- Python
- Go
- REST(curl)
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())——会绕过行级隔离import io.agentbase.Permission;
import io.agentbase.Role;
import io.agentbase.services.TablesDB;
TablesDB tablesDB = new TablesDB(client); // client 初始化见 server-sdk/java.md
tablesDB.createTable("main", "private_notes", "Private notes",
List.of(Permission.create(Role.users())), // 权限串 create("users")
true, // rowSecurity
true, // enabled
null, null, null);
// 不要再加表级 read/update/delete/write(Role.users())——会绕过行级隔离from agentbase.permission import Permission
from agentbase.role import Role
from agentbase.services.tables_db import TablesDB
tables_db = TablesDB(client) # client 初始化见 examples/python.md
tables_db.create_table(
database_id='main', table_id='private_notes', name='Private notes',
permissions=[Permission.create(Role.users())], # 或直接传语法字符串 'create("users")'(权限串文法同 REST)
row_security=True,
enabled=True,
)
# 不要再加表级 read/update/delete/write(Role.users())——会绕过行级隔离tables := agentbase.NewTablesDB(cl) // facade 构造器;cl 为已装载 API Key 的 Client
_, err := tables.CreateTable("main", "private_notes", "Private notes",
tables.WithCreateTablePermissions([]string{"create(\"users\")"}), // 权限字符串数组,语义同 REST
tables.WithCreateTableRowSecurity(true),
tables.WithCreateTableEnabled(true))
// 不要再加表级 read/update/delete/write(Role.users())——会绕过行级隔离curl -sS -X POST "$APPBASE_ENDPOINT/tablesdb/main/tables" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{
"tableId": "private_notes",
"name": "Private notes",
"rowSecurity": true,
"permissions": ["create(\"users\")"]
}'
# 表级权限是「放行」不是「限制」:配置 read("users") 后所有人可读全部行客户端建行:创建者默认独占
Client SDK 省略 permissions 时服务端自动写入创建者的 read/update/delete;Server SDK(API Key)没有「当前最终用户」,必须显式授予。
- Node.js(Server)
- Web(用户 Session)
- Java
- Python
- Go
- REST(curl)
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)),
],
});import { Account, ID, Permission, Role } from 'agentbase-web-sdk'; // 用户已登录
// 推荐:省略 permissions,服务端自动写入创建者 read/update/delete
await tablesDB.createRow({
databaseId: 'main',
tableId: 'private_notes',
rowId: ID.unique(),
data: { title: 'My note' },
});
// 显式等价写法(每个 Role 都须通过 hasRole,否则 401):
const user = await new Account(client).get();
await tablesDB.createRow({
databaseId: 'main',
tableId: 'private_notes',
rowId: ID.unique(),
data: { title: 'My note' },
permissions: [
Permission.read(Role.user(user.$id)),
Permission.update(Role.user(user.$id)),
Permission.delete(Role.user(user.$id)),
],
});import io.agentbase.ID;
// Server SDK(API Key)跳过客户端的 hasRole 检查;省略 permissions 会得到空行权限,
// 先从可信会话 / JWT 取得用户 ID,再显式授予该用户
String userId = "<从已验证会话 / JWT 取得>";
tablesDB.createRow("main", "private_notes", ID.unique(),
Map.of("title", "My note"),
List.of(Permission.read(Role.user(userId)),
Permission.update(Role.user(userId)),
Permission.delete(Role.user(userId))),
null);from agentbase.id import ID
from agentbase.permission import Permission
from agentbase.role import Role
# Server SDK(API Key)省略 permissions 会得到空行权限:先从可信会话 / JWT 取得用户 ID,再显式授予该用户
user_id = '<从已验证会话 / JWT 取得>'
tables_db.create_row(
database_id='main', table_id='private_notes', row_id=ID.unique(),
data={'title': 'My note'},
permissions=[Permission.read(Role.user(user_id)),
Permission.update(Role.user(user_id)),
Permission.delete(Role.user(user_id))],
)// API Key 请求省略 permissions 会得到空行权限:先从可信会话 / JWT 取得用户 ID,再显式授予该用户
userId := "<从已验证会话 / JWT 取得>"
_, err = tables.CreateRow("main", "private_notes", id.Unique(), map[string]interface{}{"title": "My note"},
tables.WithCreateRowPermissions([]string{
"read(\"user:" + userId + "\")", "update(\"user:" + userId + "\")", "delete(\"user:" + userId + "\")",
})) // data 为第 4 个位置参数;permissions 取权限字符串数组,语义同 RESTcurl -sS -X POST "$APPBASE_ENDPOINT/tablesdb/main/tables/private_notes/rows" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{
"rowId": "note-001",
"data": {"title": "My note"},
"permissions": [
"read(\"user:66a9d8ef00f21\")",
"update(\"user:66a9d8ef00f21\")",
"delete(\"user:66a9d8ef00f21\")"
]
}'团队协作共享与全量替换(updateRow / Role.team)
updateRow 传 permissions 是全量替换:先 getRow 读 $permissions,在副本上增删后整组提交;不传则保留原权限。Client SDK 无法在行级给别人授权(hasRole 约束),共享走 Function 代理(见上文)。
- Node.js(Server)
- Web(用户 Session)
- Java
- Python
- Go
- REST(curl)
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, // 只传新权限会丢掉原有全部权限
});// Client SDK 不能给别人授权(hasRole 约束):需要共享时调 Function——
// Function 内用 Server SDK 校验调用者确为行 owner 后,合并权限 updateRow 全量提交并留审计var row = tablesDB.getRow("main", "private_notes", "<rowId>", null, null); // 先读 $permissions
var next = new java.util.ArrayList<Object>(row.getPermissions()); // 在副本上追加,整组提交
next.add(Permission.read(Role.team("dev")));
tablesDB.updateRow("main", "private_notes", "<rowId>", null, next, null); // 只传新权限会丢掉原有全部权限row = tables_db.get_row(database_id='main', table_id='private_notes', row_id='<rowId>') # 先读 $permissions(Row 模型属性 .permissions)
# 在副本上追加 read("team:dev") 后整组提交;update_row 传 permissions 为全量替换
next_permissions = list(row.permissions) + ['read("team:dev")']
tables_db.update_row(database_id='main', table_id='private_notes', row_id='<rowId>',
permissions=next_permissions)row, err := tables.GetRow("main", "private_notes", "<rowId>") // 先读 $permissions(row.Decode 取原始 JSON)
// 在副本上追加 read("team:dev") 后整组提交;UpdateRow 传 permissions 为全量替换,只传新权限会丢掉原有全部权限
_, err = tables.UpdateRow("main", "private_notes", "<rowId>",
tables.WithUpdateRowPermissions([]string{
"read(\"user:66a9d8ef00f21\")", // 原有权限(来自 $permissions 副本)
"read(\"team:dev\")", // 新增:团队共享
}))# 先 GET 行读 $permissions,合并后整组提交(PATCH 的 permissions 语义同 SDK updateRow)
curl -sS -X PATCH "$APPBASE_ENDPOINT/tablesdb/main/tables/private_notes/rows/note-001" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{"permissions": ["read(\"user:66a9d8ef00f21\")", "read(\"team:dev\")"]}'