权限字符串文法
运行示例前,将 <APPBASE_ENDPOINT_WITH_V1> 替换为目标环境的 API 地址,并核对项目及凭据属于同一环境。
本文定义 Agentbase 资源级访问控制(ACL)权限字符串的完整文法,以及它在结构化表/行(TablesDB)、文档集合/文档(DocumentsDB)、存储桶/文件(Storage)、知识库(KnowledgeBases)与词库(Lexicons)等资源上的判定语义。
服务与资源边界
权限字符串是 Agentbase 平台实现多租户、多角色细粒度数据隔离的核心声明式机制:
声明位置:出现在表/集合/存储桶的容器级
$permissions与permissions参数中,以及行/文档/文件/知识库/词库的资源级$permissions与permissions参数中。双重门禁模型(容器级 + 资源级):当容器开启细粒度安全开关(表的
rowSecurity=true、集合的documentSecurity=true、存储桶的fileSecurity=true)时,终端用户(Session / JWT)的访问采用「容器级权限 OR 资源级权限」判定——容器级放行则对容器内全部子资源生效;容器级未放行时,逐条检查子资源自身的$permissions。防枚举隐私保护边界:对于终端用户无权读取(缺
read权限)的行、文档、文件或词库,平台统一返回404 Not Found(或在列表查询中静默过滤),绝不返回403 Forbidden,防止攻击者通过状态码差异探测敏感业务记录是否存在。
资源与基础路径
Base URL:
https://appbuild-sit.oceanbase.com/v1(或https://<your-endpoint>/v1)。承载路径范围:权限字符串不对应单一独立端点,而是作为数组字段
permissions: string[]贯穿于/v1/tablesdb/*、/v1/documentsdb/*、/v1/databases/*、/v1/storage/*、/v1/knowledgebases/*与/v1/lexicons/*的创建与更新请求体中。核心字段模型:
| 字段名 | 方向 | 类型 | 约束 | 说明 |
|---|---|---|---|---|
permissions | 请求体 / 表单 | string[] | 单资源最多 100 条(部分容器支持更高上限) | 传入的资源级或容器级权限字符串数组;省略时保留默认或原权限 |
$permissions | 响应体 | string[] | 只读系统属性 | 服务端归一化校验后持久化的权限字符串数组 |
rowSecurity | 表配置 | boolean | 默认 false | 为 true 时启用行级 $permissions 独立授权 |
documentSecurity | 集合配置 | boolean | 默认 false | 为 true 时启用文档级 $permissions 独立授权 |
fileSecurity | 存储桶配置 | boolean | 默认 false | 为 true 时启用文件级 $permissions 独立授权 |
认证与权限
服务端访问与资源级权限的关系
服务端 API Key 角色(Bypass ACL):携带项目 API Key(
X-Appwrite-Key)的请求以服务端特权角色执行,只做 API Key Scope 检查(如rows.read、files.write),不做资源级$permissions检查。只要 Key 拥有对应 Scope,即可读写该项目下的所有行或文件。终端用户身份(Enforce ACL):携带用户 Session Cookie、
X-Appwrite-Session或X-Appwrite-JWT的请求,严格按当前登录用户的角色集合(any、users、user:<id>、team:<id>、team:<id>/<role>、member:<id>、label:<name>)与目标资源的$permissions求交集,交集非空方可通过。越权授予防护(Grant Validation):当非服务端特权身份(例如普通用户通过客户端创建行或词库)尝试显式传入
permissions数组时,服务端会校验调用方自身是否持有被授予的角色(例如普通用户不能在自己创建的行上凭空授予自己不所属的team:other权限)。
文法
一条合法的权限字符串由 动作("角色") 构成(角色标识必须包裹在英文双引号内):
read("any")
write("user:user_zhangwei_001")
create("label:admin")
update("team:team_tier2_support")
delete("team:team_tier2_support/owner")动作集合(在各语言 SDK 中由 Permission 工具类生成):
| 动作 | 适用层级 | 语义说明 |
|---|---|---|
read | 容器级 & 资源级 | 允许读取单个资源详情或在列表中检索到该资源 |
create | 仅容器级(表/集合/桶) | 允许在父容器下创建新行、新文档或上传新文件;对单条子资源本身无意义 |
update | 容器级 & 资源级 | 允许修改既有资源的业务字段或元数据(含原子递增/递减操作) |
delete | 容器级 & 资源级 | 允许删除既有资源 |
write | 容器级 & 资源级 | 写入聚合别名(在容器级等价于 create + update + delete,在资源级等价于 update + delete);切勿对同一角色同时混用 write 与细粒度写动作 |
角色集合(在各语言 SDK 中由 Role 工具类生成):
| 角色字符串语法 | 匹配对象与语义说明 |
|---|---|
any | 任何请求方(同时涵盖已登录用户与未登录匿名访客) |
guests | 仅限未登录的匿名访客(无 Session 的请求;注意:已登录用户不匹配 guests) |
users | 任意已登录用户(包括普通账号登录与匿名会话登录) |
users/verified | 任意已完成邮箱或手机号验证(emailVerification=true 或 phoneVerification=true)的已登录用户 |
users/unverified | 任意尚未完成验证的已登录用户 |
user:<userId> | 指定用户 ID(如 user:user_zhangwei_001) |
user:<userId>/verified | 指定用户 ID 且该账号必须处于已验证状态 |
user:<userId>/unverified | 指定用户 ID 且该账号处于未验证状态 |
team:<teamId> | 指定团队(如 team:team_tier2_support)下的全部正式成员 |
team:<teamId>/<role> | 指定团队中拥有特定角色(如 team:team_tier2_support/owner)的成员 |
member:<membershipId> | 指定团队成员关系记录 ID(即使该成员角色变更,只要 membership 存在即有效) |
label:<name> | 拥有指定用户标签(如 label:vip、label:support_agent)的全部用户;标签通过 Users API 的 PUT /v1/users/{userId}/labels 维护 |
在各资源上的语义
行级与表级(TablesDB)
表资源携带
$permissions与rowSecurity开关;行资源携带自身$permissions。rowSecurity=false:行的访问完全由表级$permissions决定,行上的$permissions被忽略。rowSecurity=true:读/改/删行时先检查表级权限,若表级未放行,再检查行级$permissions;写入时可通过permissions参数设置行级权限(若服务端 API Key 建行时未传permissions,则新行$permissions为空数组[],仅服务端 API Key 可访问)。
集合与文档(DocumentsDB / 旧版 Databases)
集合(
/documentsdb/*与/databases/*)使用同构语义:集合$permissions+documentSecurity开关,文档$permissions。documentSecurity之于文档完全等价于rowSecurity之于行;原子增减端点(increment/decrement)按update权限检查。
桶与文件(Storage)
存储桶携带
$permissions与fileSecurity开关;文件携带$permissions。fileSecurity=true时,文件预览(/preview)、查看(/view)与下载(/download)必须在桶级或文件级匹配read权限,或者在 URL 查询串中附带有效的 文件短时访问令牌(?token=<secret>)。
知识库与词库(KnowledgeBases & Lexicons)
词库(
/v1/lexicons)仅支持read、update、delete三种动作(不支持create动作),用于在项目内控制不同团队对同义词库(如lex_enterprise_synonyms)与停用词库(如lex_support_stopwords)的维护权限。
端点总览
以下汇总接受 permissions 数组配置的核心 REST API 端点分组:
| 模块 | 容器级权限配置端点 | 子资源级权限配置端点 | 细粒度安全开关字段 |
|---|---|---|---|
| TablesDB | POST/PUT /v1/tablesdb/{databaseId}/tables* | POST/PATCH/PUT /v1/tablesdb/{databaseId}/tables/{tableId}/rows* | rowSecurity |
| DocumentsDB | POST/PUT /v1/documentsdb/{databaseId}/collections* | POST/PATCH /v1/documentsdb/{databaseId}/collections/{collectionId}/documents* | documentSecurity |
| Storage | POST/PUT /v1/storage/buckets* | POST/PUT /v1/storage/buckets/{bucketId}/files* | fileSecurity |
| Lexicons | — | POST/PATCH /v1/lexicons* | 默认启用资源级权限 |
端点清单
| 方法 + 路径 | 权限字段位置 | 支持的动作集合 | 用途 |
|---|---|---|---|
POST /v1/tablesdb/{databaseId}/tables | body permissions[] | read, create, update, delete, write | 创建业务表并设置表级权限与 rowSecurity |
POST /v1/tablesdb/{databaseId}/tables/{tableId}/rows | body permissions[] | read, update, delete, write | 创建行记录并设置行级归属权限 |
POST /v1/storage/buckets | body permissions[] | read, create, update, delete, write | 创建存储桶并设置桶级权限与 fileSecurity |
POST /v1/storage/buckets/{bucketId}/files | formData permissions[] | read, update, delete, write | 上传文件并设置文件级访问策略 |
POST /v1/lexicons | body permissions[] | read, update, delete | 创建项目词库并设置读写删策略 |
端点详解
JSON 请求体与 Multipart 表单中的序列化差异
JSON 请求体(
application/json):permissions为标准 JSON 字符串数组。由于每条权限字符串内部包含双引号(如read("any")),在 JSON 字符串中必须对内部双引号进行反斜杠转义:"read(\"any\")"。Multipart 表单(
multipart/form-data):在调用POST /v1/storage/buckets/{bucketId}/files上传文件时,数组参数通过重复同名permissions[]表单项传递,此时无需 JSON 外层引号转义,直接写-F 'permissions[]=read("user:user_zhangwei_001")'即可。
请求与响应
取值示例(curl body 写法)
以下示例基于展示项目 enterprise-ai-hub-210 演示常见权限组合在真实端点中的完整写法。
场景 1:创建客服业务表 customer_tickets(允许登录用户提单,二线团队与工单创建人可读写)
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -X POST "<APPBASE_ENDPOINT_WITH_V1>/tablesdb/enterprise_biz_db/tables" \
-H "X-Appwrite-Project: <APPBASE_PROJECT_ID>" \
--header @- \
-H "Content-Type: application/json" \
-d '{
"tableId": "customer_tickets",
"name": "企业智能客服工单表",
"rowSecurity": true,
"permissions": [
"create(\"users/verified\")",
"read(\"team:team_tier2_support\")",
"update(\"team:team_tier2_support/specialist\")",
"delete(\"team:team_tier2_support/owner\")"
]
}'
)响应示例(201 Created):
{
"$id": "customer_tickets",
"$createdAt": "2026-10-22T02:00:00.000+00:00",
"$updatedAt": "2026-10-22T02:00:00.000+00:00",
"$permissions": [
"create(\"users/verified\")",
"read(\"team:team_tier2_support\")",
"update(\"team:team_tier2_support/specialist\")",
"delete(\"team:team_tier2_support/owner\")"
],
"databaseId": "enterprise_biz_db",
"name": "企业智能客服工单表",
"enabled": true,
"rowSecurity": true,
"columns": [],
"indexes": []
}场景 2:创建工单行记录并授予客户 user_zhangwei_001 行级查看与补充权限
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -X POST "<APPBASE_ENDPOINT_WITH_V1>/tablesdb/enterprise_biz_db/tables/customer_tickets/rows" \
-H "X-Appwrite-Project: <APPBASE_PROJECT_ID>" \
--header @- \
-H "Content-Type: application/json" \
-d '{
"rowId": "TK-20261022-001",
"data": {
"title": "OceanBase 向量索引 HNSW 构建参数咨询",
"priority": "high",
"status": "open",
"customerId": "user_zhangwei_001"
},
"permissions": [
"read(\"user:user_zhangwei_001\")",
"update(\"user:user_zhangwei_001/verified\")",
"read(\"label:support_agent\")"
]
}'
)场景 3:向 agent_multimedia_bucket 上传工单截图并设置 multipart/form-data 文件级权限
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -X POST "<APPBASE_ENDPOINT_WITH_V1>/storage/buckets/agent_multimedia_bucket/files" \
-H "X-Appwrite-Project: <APPBASE_PROJECT_ID>" \
--header @- \
-F "fileId=unique()" \
-F 'permissions[]=read("user:user_zhangwei_001")' \
-F 'permissions[]=read("team:team_tier2_support")' \
-F 'permissions[]=delete("team:team_tier2_support/owner")' \
-F "file=@./ticket-attachment.png"
)组合语义速查表
| 权限组合表达式 | 实际生效边界 |
|---|---|
read("any") | 全公开可读(含匿名访客与已登录用户);常用于公开帮助文档或静态素材桶 |
read("users") | 仅限已登录会话可读;未登录请求返回 404 |
read("guests") | 仅限未登录匿名访客可读;用户一旦登录反而不再匹配该规则 |
read("user:u1") + read("label:vip") | 多角色并集:用户 u1 或任何带有 vip 标签的用户均可读取 |
update("team:dev/owner") | 仅 dev 团队中 membership roles 包含 owner 的成员可修改 |
user:<id>/verified | 仅当该用户完成邮箱或手机验证后才放行 |
错误与边界
| HTTP 状态码 | 错误类型 (type) | 触发原因 | 修复与排障建议 |
|---|---|---|---|
400 Bad Request | general_argument_invalid | 权限字符串缺少内部双引号(如誤写为 read(any))、使用了未知动作或角色 ID 超过 36 字符 | 使用 SDK 的 Permission.read(Role.any()) 构造器,或严格写成 "read(\"any\")" |
400 Bad Request | general_argument_invalid | 在词库(/v1/lexicons)上传递了不支持的 create(...) 权限动作 | 词库仅支持 read、update、delete 三种权限动作 |
401 Unauthorized | general_access_forbidden | 客户端尝试授予自身未持有的角色(如非团队成员授予 team:other) | 由服务端 API Key 代为设置跨团队权限,或仅授予当前用户自身角色 |
404 Not Found | row_not_found / storage_file_not_found | 开启了 rowSecurity=true 或 fileSecurity=true,但新创建的资源 $permissions 为空且使用客户端身份读取 | 检查表/桶的细粒度安全开关,确认创建资源时已传入目标用户的 read(...) 权限 |
与 Server SDK 的对应
各语言 Server SDK(agentbase-node-sdk@2.10.0、agentbase-python-sdk==2.10.0 等)内置了强类型的 Permission 与 Role 构造器,避免手工拼接转义引号出错:
| 权限字符串字面量 | Node.js / TypeScript 写法 | Python 写法 | 关联 API 文档 |
|---|---|---|---|
"read(\"any\")" | Permission.read(Role.any()) | Permission.read(Role.any()) | databases/overview.md |
"create(\"users/verified\")" | Permission.create(Role.users('verified')) | Permission.create(Role.users('verified')) | databases/overview.md |
"update(\"user:user_zhangwei_001\")" | Permission.update(Role.user('user_zhangwei_001')) | Permission.update(Role.user('user_zhangwei_001')) | auth/users.md |
"delete(\"team:dev/owner\")" | Permission.delete(Role.team('dev', 'owner')) | Permission.delete(Role.team('dev', 'owner')) | auth/teams.md |
"read(\"label:vip\")" | Permission.read(Role.label('vip')) | Permission.read(Role.label('vip')) | storage.md |