权限字符串文法
本文定义 Agentbase 权限字符串的文法,以及它在表/行、集合/文档、桶/文件等资源上的语义。权限字符串出现在:行/文档/文件的 $permissions 与 permissions 参数、表/集合/桶的 $permissions 与 permissions 参数中。本文不定义端点——它约束的是各文档中 permissions 字段的取值。
文法
一条权限字符串 = 动作("角色"):
read("any")
write("user:george")
create("label:admin")
update("team:dev")
delete("team:dev/owner")动作集合(SDK 由 Permission 类生成):
| 动作 | 含义 |
|---|---|
read | 读取资源(列表与单个) |
write | 写的聚合别名 = update + delete(含 create 语境的资源),不要与 update/delete/create 同时对同一角色使用 |
create | 在父资源下创建子资源(如表下建行) |
update | 修改资源 |
delete | 删除资源 |
角色集合(SDK 由 Role 类生成):
| 角色字符串 | 含义 |
|---|---|
any | 任何人(含已登录与匿名) |
user:<userId> | 指定用户 |
user:<userId>/<status> | 指定用户且限定状态(verified / unverified) |
users | 任意已登录用户(含匿名 Session) |
users/<status> | 任意已登录用户且限定状态 |
guests | 仅匿名访客(无 Session 的请求;已登录用户不含在内) |
team:<teamId> | 指定团队全部成员 |
team:<teamId>/<role> | 指定团队中拥有指定角色的成员 |
member:<membershipId> | 指定成员(按 membership 记录) |
label:<name> | 拥有指定标签的用户(标签经 users 的 updateLabels 维护) |
规则与限制:
- 角色部分整体作为引号内字符串传入;
<userId>、<teamId>等为资源 ID,最大 36 字符(与资源 ID 约束一致)。 - 同一资源可同时携带多条权限字符串(数组),同类动作多角色为并集。
write与update/delete/create混用属配置错误:write只是别名,混用会导致语义重复。- 权限字符串在创建/更新资源时以
permissions数组传入;读取时以$permissions字段返回。
服务端访问与资源级权限的关系
- 携带项目 API Key(
X-Appwrite-Key)的请求以服务端角色执行:只做 scope 检查,不做资源级权限检查。即 Key 只要有对应 scope(如rows.read),可读取该表下所有行,无论行上的$permissions如何。资源级权限约束的是用户身份(Session/JWT)访问的语境。 - 因此本目录(项目 API Key 认证)下调用时,
permissions参数的意义在于为最终用户设置资源级访问策略,而不是限制 Key 自身。
在各资源上的语义
行级与表级(TablesDB)
- 表资源携带
$permissions与rowSecurity开关;行资源携带自身$permissions。 rowSecurity=false:行的访问完全由表级$permissions决定,行级权限被忽略。rowSecurity=true:读/改/删行时先检查表级权限,再检查行级权限;写入时可携带permissions参数设置行级权限(缺省时新行不继承任何角色,仅服务端角色可访问)。create("role")控制谁可在表下建行;read/update/delete控制行的读改删。- 错误形态:用户无权读取的行在列表/单查中表现为不可见(返回 404 语义)而非 403;服务端 Key 不受影响。详见 databases。
集合与文档(旧版 Databases / DocumentsDB)
- 旧版集合(
/databases/*)与 DocumentsDB 集合(/documentsdb/*)使用同构语义:集合$permissions+documentSecurity开关,文档$permissions。 documentSecurity之于文档 =rowSecurity之于行,行为完全一致。- 增量/减量端点(
increment/decrement)按update权限检查。
桶与文件(Storage)
- 桶携带
$permissions与fileSecurity开关;文件携带$permissions。 fileSecurity=false:文件的读取/预览/下载仅由桶级权限决定。fileSecurity=true:桶级权限放行后还要通过文件级权限;写入文件时可携带permissions设置文件级策略。- 关键行为:文件权限不匹配时,预览/下载端点返回
404(storage_file_not_found)而非 403,以避免泄露文件存在性。详见 storage 与skills/ob-agentbase/references/storage-permissions.md。
团队角色与成员
teams的 membership 携带roles数组;team:<teamId>/<role>中的<role>即取自该数组中的角色名(如owner)。- 成员加入/退出团队、角色变更即时影响所有引用该团队的权限字符串判定。
取值示例(curl body 写法)
以下示例展示常见组合在真实端点请求体中的写法。示例均携带服务端两头认证(见 通用约定);permissions 参数的意义是为最终用户设置资源级策略(Key 自身不受其约束)。
创建桶:任意登录用户可读,dev 团队 owner 角色可管理,admin 标签用户可建文件(权限字符串在 JSON 数组内含双引号,需按 JSON 转义写法保持原样):
curl -X POST "https://<your-endpoint>/v1/storage/buckets" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"bucketId": "app-assets",
"name": "App Assets",
"fileSecurity": true,
"permissions": [
"read(\"users\")",
"update(\"team:dev/owner\")",
"delete(\"team:dev/owner\")",
"create(\"label:admin\")"
]
}'上传文件(multipart/form-data,数组字段用 permissions[] 形式;仅 vip 标签用户与文件属主可读,属主可改可删):
curl -X POST "https://<your-endpoint>/v1/storage/buckets/app-assets/files" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-F "fileId=unique()" \
-F 'permissions[]=read("label:vip")' \
-F 'permissions[]=read("user:66a9d8ef00f21")' \
-F 'permissions[]=update("user:66a9d8ef00f21")' \
-F 'permissions[]=delete("user:66a9d8ef00f21")' \
-F "file=@./pink.png"建表(rowSecurity=true 时行级权限才参与判定;公开可读、仅创建者可写自己的行):
curl -X POST "https://<your-endpoint>/v1/tablesdb/<DATABASE_ID>/tables" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"tableId": "comments",
"name": "Comments",
"rowSecurity": true,
"permissions": [
"read(\"any\")",
"create(\"users\")",
"update(\"user:66a9d8ef00f21/verified\")",
"delete(\"user:66a9d8ef00f21/verified\")"
]
}'组合语义速查:
| 组合 | 效果 |
|---|---|
read("any") 单独使用 | 全公开(含匿名访客);匿名场景常见于素材桶 |
read("users") | 仅登录用户可读,匿名不可见(列表中表现为 404 语义) |
read("guests") | 仅匿名访客可读,登录用户反而不含在内 |
read("user:u1") + read("label:vip") | 多角色并集:u1 与 vip 标签用户都可读 |
update("team:dev/owner") | 仅 dev 团队中拥有 owner 角色的成员可改 |
user:<id>/verified | 限定该用户邮箱/手机验证通过后的会话才生效 |
write("role-x") 与 update/delete 并存 | 配置错误:write 已含 update+delete,去掉细粒度的两条 |
注意:create 动作只约束「在父资源下创建子资源」,对资源本身的读改删无效;标签来自用户资料(users.updateLabels),团队角色来自 membership 的 roles 数组,二者变更即时反映到权限判定。
与 Server SDK 的对应
权限字符串由各语言 SDK 的 Permission / Role 构造器生成,作为各文档中 permissions 参数的取值:
| 资源 | 参数位置 | 文档 |
|---|---|---|
| 表 / 行 | tables 与 rows 各创建/更新端点的 permissions | databases |
| 集合 / 文档 | collections 与 documents 各创建/更新端点的 permissions | databases |
| 桶 / 文件 | buckets 与 files 各创建/更新端点的 permissions | storage |
事实源
- Server API spec:
agentbase-sdksv2.6.0specs/open-api3-latest-server.json(permissions参数、rowSecurity/documentSecurity/fileSecurity字段)。 - Server SDK 生成物:
server-nodejs/server-javav2.6.0(Permission/Role构造器文法)。 - 语义深度参考:
skills/ob-agentbase/references/database-permissions.md、skills/ob-agentbase/references/storage-permissions.md、skills/ob-agentbase/references/client-sdk-complex-permissions.md。