AUN

主题

存储 — RPC Manual ​

方法索引 ​

控制面方法 ​

方法说明
storage.put_objectInline 写入小对象
storage.get_objectInline 读取小对象
storage.head_object查询元数据
storage.delete_object删除对象
storage.list_objects列举对象
storage.list_prefixes列举子目录
storage.get_quota查询配额
storage.get_limits查询上传限制
storage.check_upload上传预检（秒传检测 + 超限检测）

目录树方法 ​

方法说明
storage.create_folder创建目录
storage.get_folder查询目录
storage.list_children列出目录子节点
storage.rename_folder重命名目录
storage.move_folder移动目录
storage.delete_folder删除目录
storage.resolve_path按路径解析节点

对象管理方法 ​

方法说明
storage.move_object移动或重命名对象
storage.copy_object复制对象
storage.batch_delete批量删除对象/目录
storage.batch_head_object批量查询对象元数据
storage.set_object_meta更新对象元数据
storage.get_object_url获取稳定对象 URL
storage.append_object追加写对象

数据面协调方法 ​

方法说明
storage.create_upload_session申请上传 URL
storage.complete_upload确认上传完成
storage.create_download_ticket申请下载 URL

分享方法 ​

方法说明
storage.create_share_link创建分享链接
storage.list_share_links列举分享链接
storage.revoke_share_link撤销分享链接
storage.get_by_share通过分享短码读取对象

POSIX VFS 方法 ​

在对象存储之上提供 Linux 文件系统语义（ls/find/df/stat/mkdir/rm/mv/cp/mount）。节点类型：file / dir / symlink / mount。

方法说明
storage.fs.list列目录（ls）
storage.fs.find递归查找（find，支持 name/type/size/mtime 过滤）
storage.fs.df配额/用量报告（df）
storage.fs.stat查节点（stat，跟随末级软链）
storage.fs.lstat查节点（lstat，不跟随软链）
storage.fs.mkdir建目录（mkdir）
storage.fs.remove删除文件/目录/软链（rm）
storage.fs.rename同 owner 内移动/改名（mv）
storage.fs.copy复制对象或软链（cp）
storage.fs.mount挂载卷或他人子树
storage.fs.approve源 owner 批准待审挂载
storage.fs.reject拒绝待审挂载
storage.fs.unmount卸载挂载点
storage.fs.invalidate_membership群成员变更时失效群挂载

软链方法 ​

方法说明
storage.create_symlink创建软链
storage.readlink读软链 target
storage.atomic_repoint原子重指 target（CAS 乐观锁）
storage.rename_symlink改软链 key（target 不变）
storage.delete_symlink删软链记录（不动 target）

ACL / 权限方法 ​

统一权限求值顺序（硬顺序）：公开位 → token → ACL（最近祖先前缀）→ 角色 → owner → 拒绝。

方法说明
storage.set_acl授予路径前缀 ACL
storage.remove_acl移除 ACL 授权
storage.list_acl列出路径 ACL
storage.set_visibility切换公开/私有
storage.check_access非抛错的访问探测
storage.issue_token签发路径访问 token
storage.revoke_token吊销 token
storage.list_tokens列出 token

卷方法 ​

方法说明
storage.volume.create创建/upsert 配额卷
storage.volume.renew续期卷
storage.volume.expire_due过期到期卷并失效其挂载

object_key 当前仅支持 ASCII 安全字符集合 [A-Za-z0-9._/-]，且不允许空路径段、..、反斜杠转义后的非法段。

SDK 封装状态 ​

Python / Go / TypeScript / JavaScript SDK 均提供 storage low-level 与 VFS 门面。普通应用优先使用 SDK VFS：write_bytes / upload_file 会先 check_upload，小对象走 put_object，大对象走 create_upload_session → HTTP PUT → complete_upload，秒传路径用 complete_upload(skip_blob=true)；read_bytes / download_file 优先尝试 inline get_object，超限时回退 create_download_ticket。需要精确控制 ACL、token、软链、卷、批量操作或 URL 字段时，再直接调用本手册中的 storage.* RPC。

storage.put_object ​

上传小对象（内容 base64 编码通过 RPC 传输）。

参数 ​

参数类型必填说明
object_keystring是对象路径
contentstring是base64 编码内容
content_typestring否MIME 类型，默认 "application/octet-stream"
bucketstring否存储桶，默认 "default"
owner_aidstring否所有者 AID，默认当前用户
is_privateboolean否是否私有，默认 true
overwriteboolean否是否覆盖已有对象，默认 true
expected_versioninteger否乐观并发控制版本号
expire_in_secondsinteger否过期时间（秒），0 表示不过期
metadataobject否自定义元数据

响应 ​

字段类型说明
urlstringAID 风格 URL（默认/推荐）：https://{owner_aid}/{object_key}，经 NameService fallback 302 跳转到 storage 服务
logical_urlstring直链 URL：https://storage.{issuer}/{user}/{object_key}，直达 storage 服务，无跳转
owner_aidstring所有者 AID
bucketstring存储桶
object_keystring对象路径
size_bytesinteger对象大小（字节）
content_typestringMIME 类型
sha256stringSHA-256 哈希
versioninteger版本号
etagstring实体标签
updated_atinteger更新时间戳

示例 ​

python
import base64

content = base64.b64encode(b"Hello World").decode()
result = await client.call("storage.put_object", {
    "object_key": "notes/hello.txt",
    "content": content,
    "content_type": "text/plain",
})

storage.get_object ​

读取小对象，返回 base64 编码内容。

参数 ​

参数类型必填说明
object_keystring是对象路径
bucketstring否存储桶，默认 "default"
owner_aidstring否所有者 AID，默认当前用户

响应 ​

字段类型说明
owner_aidstring所有者 AID
bucketstring存储桶
object_keystring对象路径
contentstringbase64 编码内容
content_typestringMIME 类型
size_bytesinteger对象大小（字节）
sha256stringSHA-256 哈希
versioninteger版本号
updated_atinteger更新时间戳

注意：实现不返回 etag（与 put_object/head_object 不同）。

示例 ​

python
result = await client.call("storage.get_object", {
    "object_key": "notes/hello.txt",
})
content = base64.b64decode(result["content"])

storage.head_object ​

查询对象元数据，不返回内容。

参数 ​

参数类型必填说明
object_keystring是对象路径
bucketstring否存储桶，默认 "default"
owner_aidstring否所有者 AID，默认当前用户

响应 ​

字段类型说明
owner_aidstring所有者 AID
bucketstring存储桶
object_keystring对象路径
content_typestringMIME 类型
size_bytesinteger对象大小（字节）
sha256stringSHA-256 哈希
versioninteger版本号
etagstring实体标签
is_privateboolean是否私有
expire_atinteger过期时间戳（0 表示不过期）
created_atinteger创建时间戳
updated_atinteger更新时间戳

storage.delete_object ​

删除对象。

参数 ​

参数类型必填说明
object_keystring是对象路径
bucketstring否存储桶，默认 "default"
owner_aidstring否所有者 AID，默认当前用户

响应 ​

字段类型说明
deletedboolean是否成功删除（false 表示对象不存在）
owner_aidstring所有者 AID
object_keystring对象路径

storage.list_objects ​

列出对象。

权限：仅允许查询自己的对象（owner_aid 默认为当前用户，不可指定他人的 AID）

参数 ​

参数类型必填说明
prefixstring否路径前缀过滤
bucketstring否存储桶，默认 "default"
owner_aidstring否所有者 AID，默认当前用户
pageinteger否页码，默认 1
sizeinteger否每页条数，默认 50（最大 200）
markerstring否深度分页游标；传入时优先按游标分页

响应 ​

字段类型说明
itemsarray对象元数据列表
totalinteger总条数
pageinteger当前页码
sizeinteger每页条数
markerstring当前游标标记
next_markerstring下一页游标标记（为空表示无更多数据）

每个 item 包含：

字段类型说明
object_keystring对象路径
size_bytesinteger对象大小（字节）
content_typestringMIME 类型
sha256stringSHA-256 哈希
versioninteger版本号
is_privateboolean是否私有
updated_atinteger更新时间戳

示例 ​

python
result = await client.call("storage.list_objects", {
    "prefix": "notes/",
    "size": 20,
})
for obj in result["items"]:
    print(f"{obj['object_key']} ({obj['size_bytes']} bytes)")

storage.list_prefixes ​

列出直接子目录（前缀）。

权限：仅允许查询自己的对象（owner_aid 默认为当前用户，不可指定他人的 AID）

参数 ​

参数类型必填说明
prefixstring否路径前缀过滤
bucketstring否存储桶，默认 "default"
owner_aidstring否所有者 AID，默认当前用户
sizeinteger否每页条数上限

响应 ​

字段类型说明
prefixesstring[]直接子目录列表
countinteger子目录数量
sizeinteger实际生效的每页上限

storage.get_quota ​

查询存储配额。

参数 ​

参数类型必填说明
owner_aidstring否查询指定 AID 的配额（默认为当前用户，仅允许查询自己的配额）

响应 ​

字段类型说明
owner_aidstring所有者 AID
used_bytesinteger已使用空间（字节）
object_countinteger对象数量
quota_bytesinteger配额上限（字节），0 表示无限制

storage.create_folder ​

创建目录节点。目录和对象共用同一个 bucket，默认 bucket 为 "default"。

参数：

参数类型必填说明
pathstring否完整目录路径；提供时优先使用
namestring否目录名；未提供 path 时必填
parent_folder_idstring否父目录 ID
parent_pathstring否父目录路径，默认根目录
bucketstring否存储桶，默认 "default"
owner_aidstring否所有者 AID，默认当前用户
mkdirsboolean否是否递归创建父目录
metadataobject否目录元数据
conflict_policystring否"reject" / "return_existing"

响应：返回 folder，同时在顶层展开 folder_id、path、name、parent_folder_id、version 等字段。

storage.get_folder ​

查询目录节点。

参数：folder_id 或 path 至少提供一个；可选 bucket、owner_aid。

响应：同 storage.create_folder 的 folder 视图。

storage.list_children ​

列出目录下的直接子目录和对象。

参数：

参数类型必填说明
folder_id / pathstring否目标目录；都不传表示根目录
typestring否"all" / "folder" / "object"，默认 "all"
bucketstring否存储桶，默认 "default"
owner_aidstring否所有者 AID，默认当前用户
pageinteger否页码，默认 1
sizeinteger否每页数量，最大受服务配置限制
order_bystring否"name" / "updated_at" / "size_bytes"
orderstring否"asc" / "desc"
include_metadataboolean否是否返回元数据，默认 true
include_urlsboolean否是否返回 URL 字段，默认 true

响应：folder、items、total、page、size、next_marker。items[].node_type 区分 folder / object。

storage.rename_folder ​

重命名目录。根目录不可改名。

参数：folder_id 或 path，new_name 必填；可选 bucket、owner_aid、expected_version。

响应：更新后的 folder 视图。

storage.move_folder ​

移动目录。不能移动到自身或自身子目录。

参数：folder_id 或 path，目标目录通过 dst_parent_folder_id 或 dst_parent_path 指定；可选 new_name、bucket、owner_aid、expected_version。

响应：更新后的 folder 视图。

storage.delete_folder ​

删除目录。

参数：

参数类型必填说明
folder_id / pathstring是待删除目录
recursiveboolean否非空目录必须传 true
dry_runboolean否只预览将删除的目录/对象
bucketstring否存储桶，默认 "default"
owner_aidstring否所有者 AID，默认当前用户

响应：deleted_folders、deleted_objects、deleted_object_items、errors；dry_run=true 时返回预览列表。

storage.resolve_path ​

按路径解析目录或对象。

参数：path 必填；可选 expected_type（"any" / "object" / "folder"）、bucket、owner_aid。

响应：type、folder_id 或 object_id、path、status。

storage.move_object ​

移动或重命名对象。

参数：对象选择器（object_id / object_key / path），目标目录 dst_parent_folder_id 或 dst_parent_path；可选 new_name、conflict_policy（"reject" / "replace" / "keep_both"）、expected_version。

响应：返回 object，同时在顶层展开对象视图字段。

storage.copy_object ​

复制对象，底层内容按 CAS 引用计数复用。

参数：源对象选择器（object_id / object_key / path，也接受 src_object_key / src_path），目标 dst_object_key / dst_path 或目标父目录 + new_name；可选 conflict_policy、copy_metadata。

响应：新对象视图。

storage.batch_delete ​

批量删除对象或目录。

参数：

参数类型必填说明
itemsarray否每项含 type、object_id / object_key / path / folder_id
object_keysstring[]否兼容简写，转为对象删除
recursiveboolean否删除目录时是否递归
dry_runboolean否只预览

响应：deleted、errors、deleted_count、summary。

storage.batch_head_object ​

批量查询对象元数据。

参数：object_ids、paths 至少提供一类；可选 owner_aid、bucket、include_missing、include_metadata、include_urls。

响应：items 和 errors。

storage.set_object_meta ​

更新对象元数据和可选 MIME 类型。

参数：对象选择器，metadata；可选 merge（默认 true）、content_type、expected_version。

响应：更新后的对象视图。

storage.get_object_url ​

获取稳定对象 URL。

参数：对象选择器；可选 include_path_url。

响应：object_id、object_url、path_url、stable。

storage.append_object ​

向对象尾部追加 base64 内容；对象不存在时创建。

参数：与 storage.put_object 类似，content 必填；可选 object_key / path / name、bucket、owner_aid、content_type、metadata、expected_version、is_private。

响应：对象视图。

storage.create_upload_session ​

获取上传用 presigned URL。

参数 ​

参数类型必填说明
object_keystring是对象路径
size_bytesinteger否声明的文件大小（字节）。当前实现允许省略，但建议传入用于客户端追踪与最终校验
content_typestring否MIME 类型，默认 "application/octet-stream"
bucketstring否存储桶，默认 "default"
owner_aidstring否所有者 AID，默认当前用户
expected_versioninteger否乐观并发控制版本号
expire_in_secondsinteger否URL 有效期（秒），默认 3600

响应 ​

字段类型说明
upload_urlstring上传用 presigned URL
blob_keystringBlob 存储 key
expire_atintegerURL 过期时间戳
owner_aidstring所有者 AID
bucketstring存储桶
object_keystring对象路径
content_typestringMIME 类型
size_bytesinteger声明的文件大小

客户端获得 upload_url 后，通过 HTTP PUT 上传文件数据。

当前实现会对 BlobStore 返回的 loopback URL 做对外地址规范化：优先使用 KITE_STORAGE_EXTERNAL_URL，否则按 storage.{issuer} 形式改写。对外地址不可使用 127.0.0.1 或 localhost。

当前实现不会在 create_upload_session 阶段强校验配额或最终文件大小；这些检查会在 storage.complete_upload 阶段执行。

storage.complete_upload ​

完成上传，提交校验信息。

参数 ​

参数类型必填说明
object_keystring是对象路径
sha256string否文件 SHA-256 哈希；提供则校验完整性，skip_blob=true 时必填
bucketstring否存储桶，默认 "default"
owner_aidstring否所有者 AID，默认当前用户
content_typestring否MIME 类型，默认 "application/octet-stream"
is_privateboolean否是否私有，默认 true
size_bytesinteger否预期文件大小（用于校验）
skip_blobboolean否秒传模式，默认 false；为 true 时跳过 blob 上传，必须提供 sha256，且当前 owner 已拥有相同内容
expected_versioninteger否乐观并发控制版本号
expire_in_secondsinteger否过期时间（秒）
metadataobject否自定义元数据

响应 ​

字段类型说明
urlstringAID 风格 URL（默认/推荐）：https://{owner_aid}/{object_key}，经 NameService fallback 302 跳转
logical_urlstring直链 URL：https://storage.{issuer}/{user}/{object_key}，无跳转
owner_aidstring所有者 AID
bucketstring存储桶
object_keystring对象路径
size_bytesinteger对象大小（字节）
content_typestringMIME 类型
sha256stringSHA-256 哈希
versioninteger版本号
etagstring实体标签
updated_atinteger更新时间戳

storage.create_download_ticket ​

获取下载 URL。

参数 ​

参数类型必填说明
object_keystring是对象路径
bucketstring否存储桶，默认 "default"
owner_aidstring否所有者 AID，默认当前用户（公开对象可指定其他 AID）
expire_in_secondsinteger否URL 有效期（秒），默认 3600

响应 ​

字段类型说明
urlstringAID 风格 URL（默认/推荐）：public 文件为 https://{owner_aid}/{object_key}，private 文件为 https://{owner_aid}/{object_key}?t={token}。经 NameService fallback 302 跳转到 storage 服务，storage 实时鉴权后出文件（302 到 blob 后端，对客户端透明）
logical_urlstring直链 URL：https://storage.{issuer}/{user}/{object_key}，直达 storage 服务，无 NameService 跳转
download_urlstring同 url（兼容旧客户端，格式已统一）
expire_atintegertoken 过期时间戳（Unix 秒），public 文件此字段无实际约束
tokenstringprivate 文件的不透明访问 token（10 位 Base62），public 文件无此字段
file_namestring文件名（从 object_key 提取）
size_bytesinteger文件大小（字节）
content_typestringMIME 类型
sha256stringSHA-256 哈希
versioninteger版本号
etagstring实体标签

url 是推荐使用的干净链接。访问时 storage 服务实时鉴权：public 文件直接通过，private 文件需 ?t= token 或 Authorization: Bearer <AID JWT> 头证明 owner 身份。鉴权通过后 storage 302 到 blob 后端完成实际下载，这一步对客户端完全透明。

事件 ​

event/storage.object_changed ​

对象变更时推送。

Payload：

json
{
    "module_id": "storage",
    "action": "put",
    "owner_aid": "alice.agentid.pub",
    "object_key": "notes/hello.txt"
}
字段类型说明
module_idstring当前模块 ID，通常为 "storage"
actionstring"put" 或 "delete"
owner_aidstring对象所有者 AID
object_keystring对象路径

当前实现在 storage.put_object 成功后推送 action="put"，storage.delete_object 返回 deleted=true 时推送 action="delete"，storage.complete_upload 成功后也会推送 action="put" 事件。

storage.get_limits ​

查询当前用户的上传限制和配额使用情况。客户端可在上传前调用此方法，避免超限后浪费流量。

参数 ​

参数类型必填说明
owner_aidstring否查询指定用户的配额，默认当前用户

响应 ​

字段类型说明
max_inline_bytesintegerput_object 内联上限（当前 64KB）
max_file_size_bytesinteger单文件大小上限（当前 10MB）
quota_total_bytesinteger用户总配额（0 表示无限制）
quota_used_bytesinteger已用配额

示例 ​

python
limits = await client.call("storage.get_limits", {})
print(f"单文件上限: {limits['max_file_size_bytes']} bytes")
print(f"配额: {limits['quota_used_bytes']}/{limits['quota_total_bytes']}")

storage.check_upload ​

上传预检：一次调用同时回答"文件是否超限"和"当前 owner 是否可秒传"。客户端应在计算完文件 SHA-256 后、实际上传前调用。

check_upload / complete_upload(skip_blob=true) 只允许复用当前 owner 已拥有的内容，避免跨 owner 暴露全局 CAS 存在性或跳过上传克隆他人私有内容。不同 owner 上传相同内容时，仍会在完成上传后归一到同一个 CAS blob，由服务端引用计数管理物理去重。

参数 ​

参数类型必填说明
sha256string是文件内容的 SHA-256 hex（64 字符）
size_bytesinteger是文件大小（字节）
owner_aidstring否检查指定 owner 是否可秒传，默认当前用户；必须等于当前登录 AID

响应 ​

字段类型说明
within_limitboolean文件大小是否在限制内
existsboolean当前 owner 是否已拥有相同内容且 CAS blob 可用
skip_uploadboolean是否可跳过上传（秒传）

使用场景 ​

python
import hashlib

data = open("large_file.bin", "rb").read()
sha256 = hashlib.sha256(data).hexdigest()

check = await client.call("storage.check_upload", {
    "sha256": sha256,
    "size_bytes": len(data),
})

if not check["within_limit"]:
    print("文件超限，无法上传")
elif check["skip_upload"]:
    # 秒传：当前 owner 已拥有相同内容，跳过上传直接 complete
    await client.call("storage.complete_upload", {
        "object_key": "my/file.bin",
        "sha256": sha256,
        "size_bytes": len(data),
        "skip_blob": True,
    })
else:
    # 正常上传流程
    session = await client.call("storage.create_upload_session", {
        "object_key": "my/file.bin",
        "size_bytes": len(data),
    })
    # HTTP PUT ...
    await client.call("storage.complete_upload", {
        "object_key": "my/file.bin",
        "sha256": sha256,
        "size_bytes": len(data),
    })

创建分享链接。生成一个短码（share_id），通过短码可访问对象，支持授权 AID 白名单、有效期、使用次数限制。

参数 ​

参数类型必填说明
object_keystring是被分享对象的路径
bucketstring否存储桶，默认 "default"
owner_aidstring否对象所有者 AID，默认当前用户（仅可分享自己的对象）
allowed_aidsstring[]否授权访问的 AID 列表，默认 ["*"]（任意 AID 可访问）；含 "*" 即视为公开
expire_in_secondsinteger否有效期（秒），默认 86400（1 天），0 表示永不过期
max_usesinteger否最大使用次数，默认 0（无限制）

响应 ​

字段类型说明
share_idstring10 位 Base62 分享短码
urlstring默认分享 URL（隐藏路径）：https://{owner_aid}/s/{share_id}，最短直链
path_urlstring可选分享 URL（暴露路径）：https://{owner_aid}/{object_key}?t={share_id}，可读性强
aid_share_urlstring同 url（兼容旧字段）
share_urlstringstorage 直链：https://storage.{issuer}/s/{share_id}，兼容字段
expire_atinteger过期时间戳（Unix 秒），0 表示永不过期
max_usesinteger最大使用次数，0 表示无限制
allowed_aidsstring[]授权 AID 列表，["*"] 表示公开

两种格式都通过 share_id 定位到 share_links 记录鉴权。url 隐藏文件结构，path_url 暴露文件名便于识别，调用者按需选择。 访问 url 时经 NameService 302 跳转到 storage.{issuer}/s/{share_id}；访问 path_url 时经 NameService fallback 到 storage，由 ?t= token 鉴权。 share_id 指向 (owner_aid, bucket, object_key) 逻辑引用，非内容快照：对象改名/移动后原 share_id 失效，内容覆盖后下载到新内容。

示例 ​

python
result = await client.call("storage.create_share_link", {
    "object_key": "docs/report.pdf",
    "allowed_aids": ["alice.agentid.pub"],
    "expire_in_seconds": 3600,
    "max_uses": 5,
})
share_url = result["url"]  # https://alice.agentid.pub/s/Ab3xK9mZ2q

列举分享链接，可按 bucket / object_key 过滤。仅返回当前用户自己创建的链接。

参数 ​

参数类型必填说明
bucketstring否按存储桶过滤
object_keystring否按对象路径过滤

响应 ​

字段类型说明
linksarray分享链接列表

每个 link 包含：

字段类型说明
share_idstring分享短码
urlstring默认分享 URL（隐藏路径）：https://{owner_aid}/s/{share_id}
path_urlstring可选分享 URL（暴露路径）：https://{owner_aid}/{object_key}?t={share_id}
aid_share_urlstring同 url（兼容旧字段）
share_urlstringstorage 直链（兼容）
object_keystring被分享对象路径
bucketstring存储桶
allowed_aidsstring[]授权 AID 列表，["*"] 表示公开
expire_atinteger过期时间戳（秒），0 表示永不过期
max_usesinteger最大使用次数，0 表示无限制
used_countinteger已使用次数
created_atinteger创建时间戳（毫秒）

撤销分享链接。

参数 ​

参数类型必填说明
share_idstring是待撤销的分享短码

响应 ​

字段类型说明
revokedboolean是否成功撤销
share_idstring被撤销的分享短码

链接不存在或已撤销时返回通用错误（-32000）。

storage.get_by_share ​

通过分享短码读取对象。公开分享无需额外授权；私有白名单分享需要请求者 AID 在 allowed_aids 内。

参数：

参数类型必填说明
share_idstring是分享短码

响应：小对象返回 content；大对象返回 download_url。同时返回 object_id、object_key、path、size_bytes、content_type、sha256。

storage.fs.list ​

列目录（POSIX ls）。混合返回子目录/对象/软链/可用挂载点，排序 dir < file < symlink < mount。群 owner 路径回退到 Group FS 子节点。

参数 ​

参数类型必填默认说明
pathstring否""目录路径（空=根）
owner_aidstring否当前用户所有者 AID
bucketstring否"default"存储桶
pageinteger否1页码
sizeinteger否100每页条数（受 list_max_limit 上限约束）
markerstring否—分页游标
tokenstring否—访问 token

响应 ​

字段类型说明
nodesarray节点列表，每项 {type, node_type, name, path, mode, size, mtime, owner_principal}
itemsarray同 nodes（兼容别名）
totalinteger总数
page / sizeinteger分页
next_markerstring下一页游标

type 取值：file / dir / symlink / mount。

storage.fs.find ​

递归查找（POSIX find），支持 name/type/size/mtime 过滤与分页。Group FS 与 .collab 注册表有回退。

参数 ​

参数类型必填默认说明
pathstring是—起始目录
owner_aidstring否当前用户所有者 AID
bucketstring否"default"存储桶
namestring否—名称 glob（如 *.md）
typestring否—节点类型过滤：f/d/l（SDK 形参 node_type）
sizestring否—大小表达式（如 +1M）
mtimestring否—修改时间表达式
pageinteger否1页码
page_sizeinteger否1000每页条数
tokenstring否—访问 token

响应 ​

同 storage.fs.list：{nodes, items, total, page, size, next_marker}。

storage.fs.df ​

配额/用量报告（POSIX df），含每 owner 卷（过期卷重新计算）。

参数 ​

参数类型必填默认说明
owner_aidstring否当前用户所有者 AID
bucketstring否"default"存储桶

响应 ​

字段类型说明
owner_aid / bucketstring所有者 / 桶
used_bytesinteger已用字节
object_countinteger对象数
quota_bytesinteger配额上限
avail_bytesinteger剩余可用
volumesarray每卷用量明细

storage.fs.stat ​

查节点元数据（POSIX stat）。follow_final=true，解析末级软链 target。

参数 ​

参数类型必填默认说明
pathstring是—节点路径
owner_aidstring否当前用户所有者 AID
bucketstring否"default"存储桶
tokenstring否—访问 token

响应 ​

fs 节点视图：{type, node_type, name, path, mode, size, mtime, owner_principal, ...}。

storage.fs.lstat ​

查节点（POSIX lstat），不跟随末级软链——返回软链本身（携带 dangling 悬空标志），不返回 target。

参数 ​

同 storage.fs.stat。

响应 ​

fs 节点视图；若为软链，返回软链节点本身（含 dangling 标志）。

storage.fs.mkdir ​

建目录（POSIX mkdir）。委托 create_folder。

参数 ​

参数类型必填默认说明
pathstring是—目录路径
owner_aidstring否当前用户所有者 AID
bucketstring否"default"存储桶
parentsboolean否false递归创建父目录（类 mkdir -p）

响应 ​

fs 目录节点视图。

storage.fs.remove ​

删除文件/目录/软链（POSIX rm，目录用 recursive）。拒绝删除挂载点（须先 unmount）。

参数 ​

参数类型必填默认说明
pathstring是—节点路径
owner_aidstring否当前用户所有者 AID
bucketstring否"default"存储桶
recursiveboolean否false递归删除目录

响应 ​

字段类型说明
owner_aid / bucket / pathstring目标
removed_countinteger删除节点数
deletedboolean是否删除成功

storage.fs.rename ​

同 owner/bucket 内移动或改名（POSIX mv）。跨 owner/bucket 被拒；按节点类型分派到 move_folder / rename_symlink / move_object。

参数 ​

参数类型必填默认说明
srcstring是—源路径
dststring是—目标路径
owner_aidstring否当前用户所有者 AID
bucketstring否"default"存储桶
overwriteboolean否false覆盖已存在目标
expected_versioninteger否—乐观锁版本号

响应 ​

被重命名节点的 fs 节点视图。

storage.fs.copy ​

复制对象或软链（POSIX cp，目录复制暂不支持）。CAS blob 引用计数复用，支持跨 owner 对象复制。

参数 ​

参数类型必填默认说明
srcstring是—源路径
dststring是—目标路径
owner_aidstring否当前用户源所有者 AID
bucketstring否"default"源存储桶
overwriteboolean否false覆盖已存在目标
follow_symlinksboolean否false复制软链 target 而非软链本身
dst_owner_aidstring否同源目标所有者（SDK 形参 dst_owner）
dst_bucketstring否同源目标存储桶

响应 ​

被复制节点的 fs 节点视图。

storage.fs.mount ​

挂载卷或他人子树进 owner 命名空间。readonly 默认 true；require_approval=true 时进入 pending 直到源 owner 批准。群成员卷挂载场景下，storage 通过 CA aid_type=group 识别群命名空间，命中 /memberdata/ 时调 group.check_membership 实时校验成员身份。

参数 ​

参数类型必填默认说明
mount_pathstring是—挂载点路径
owner_aidstring否当前用户命名空间所有者
bucketstring否"default"存储桶
volume_idstring否—挂载实体卷（与 source_* 互斥）
source_aidstring否—虚拟卷源 AID（与 volume_id 互斥）
source_pathstring否—虚拟卷源路径
source_bucketstring否—虚拟卷源存储桶
readonlyboolean否true只读挂载
require_approvalboolean否false需源 owner 批准
expires_atinteger否—挂载过期时间

响应 ​

字段类型说明
mountobject挂载视图
statusstringactive（直接生效）/ pending（待批准）

storage.fs.approve ​

源 owner 批准 pending 挂载（重新校验源路径存在）。mount_id 或 (owner_aid, bucket, mount_path) 二选一定位。

参数 ​

参数类型必填说明
mount_idstring否挂载 ID（或用下方三元组定位）
owner_aidstring否命名空间所有者
bucketstring否存储桶
mount_pathstring否挂载点路径

响应 ​

字段类型说明
approvedbooleantrue
mountobject挂载视图

storage.fs.reject ​

源 owner 或挂载 owner 拒绝 pending 挂载。定位方式同 fs.approve。

响应 ​

{rejected: boolean, mount}。

storage.fs.unmount ​

卸载挂载点（仅 owner 可操作）。

参数 ​

参数类型必填默认说明
mount_pathstring是—挂载点路径
owner_aidstring否当前用户命名空间所有者
bucketstring否"default"存储桶

响应 ​

{unmounted: boolean, owner_aid, bucket, path, mount_path}。

storage.fs.invalidate_membership ​

群成员变更/群解散时失效群挂载（仅群 owner 或内部调用者）。SDK 形参不带 owner/bucket。

参数 ​

参数类型必填默认说明
group_idstring是—群 ID
group_owner_aidstring是—群 owner AID
member_aidstring否—成员 AID（不传=全员）
reasonstring否"membership_changed"dissolved / membership_changed
statusstring否—inactive / unavailable

响应 ​

{group_id, group_aid, group_owner_aid, member_aid, reason, status, invalidated}（invalidated=失效挂载数）。

创建软链。target 受限于 owner 命名空间；拒绝同名 file/dir；父路径不可含软链前缀。

参数 ​

参数类型必填默认说明
pathstring是—软链路径
targetstring是—指向目标路径
owner_aidstring否当前用户所有者 AID
bucketstring否"default"存储桶
overwriteboolean否false覆盖已存在软链

响应 ​

软链视图（含 dangling 悬空标志）。

读软链 target（owner 校验）。

参数 ​

参数类型必填默认说明
pathstring是—软链路径
owner_aidstring否当前用户所有者 AID
bucketstring否"default"存储桶

响应 ​

软链视图 {symlink, target, version, ...}。

storage.atomic_repoint ​

原子重指软链 target（乐观锁 CAS）。collab commit / tag 并发正确性的底层核心。

参数 ​

参数类型必填默认说明
pathstring是—软链路径
new_targetstring是—新 target
owner_aidstring否当前用户所有者 AID
bucketstring否"default"存储桶
expected_versioninteger否—CAS 期望版本（null=跳过 CAS）

响应 ​

成功：{ok: true, ...软链视图}（version+1）。 CAS 失败：{ok: false, current_version, current_target}。

改软链 key（同 owner/bucket 内移动/改名），target 不变。跨 owner 被拒。

参数 ​

参数类型必填默认说明
pathstring是—原软链路径（SDK 形参 path/服务端 src）
new_pathstring是—新软链路径（服务端 dst）
owner_aidstring否当前用户所有者 AID
bucketstring否"default"存储桶
overwriteboolean否false覆盖已存在
expected_versioninteger否—CAS 期望版本

响应 ​

成功：{ok: true, ...软链视图}。 CAS 失败：{ok: false, current_version, current_path, current_target}。

删软链记录（不动 target 对象）。

参数 ​

参数类型必填默认说明
pathstring是—软链路径
owner_aidstring否当前用户所有者 AID
bucketstring否"default"存储桶

响应 ​

{deleted: boolean, owner_aid, bucket, path, symlink_id, target}。

storage.set_acl ​

授予路径前缀 ACL grant（群内部 admin 或群代理写授权）。支持 role:<role> 形式 grantee。ACL 对目录前缀授权，子路径默认继承（最近祖先覆盖）。

参数 ​

参数类型必填默认说明
pathstring是—授权路径前缀
grantee_aidstring是—被授权 AID（或 role:<role>）
permsstring是—权限位：r/w/rw/rwx（rwx 含删除）
owner_aidstring否当前用户所有者 AID
bucketstring否"default"存储桶
expires_atinteger否—授权过期时间
max_usesinteger否—最大使用次数

响应 ​

ACL 视图。

storage.remove_acl ​

移除路径 ACL 授权。

参数 ​

参数类型必填默认说明
pathstring是—授权路径前缀
grantee_aidstring是—被授权 AID
owner_aidstring否当前用户所有者 AID
bucketstring否"default"存储桶

响应 ​

{removed: boolean, owner_aid, bucket, path, grantee_aid}。

storage.list_acl ​

列出路径上的 ACL 授权（owner 校验）。

参数 ​

参数类型必填默认说明
pathstring是—路径
owner_aidstring否当前用户所有者 AID
bucketstring否"default"存储桶

响应 ​

{owner_aid, bucket, path, acls}。

storage.set_visibility ​

切换对象或目录的公开/私有（软链不支持）。allow_roles 替换 role: 类 ACL。

参数 ​

参数类型必填默认说明
pathstring是—路径
visibilitystring是—public / private
owner_aidstring否当前用户所有者 AID
bucketstring否"default"存储桶
allow_rolesarray否—允许的角色列表（替换 role ACL）

响应 ​

fs 节点视图（含 allow_roles）。

storage.check_access ​

非抛错的访问探测——探测某操作在某路径是否放行（内部捕获 NotFound/Dangling/Permission）。

参数 ​

参数类型必填默认说明
pathstring是—路径（服务端别名 object_key）
operationstring否"read"read / write / delete（服务端别名 op）
owner_aidstring否当前用户所有者 AID
bucketstring否"default"存储桶
tokenstring否—访问 token
follow_symlinksboolean否true跟随软链

响应 ​

{allowed: boolean, reason, message, requester_aid, owner_aid, bucket, path, operation}。

storage.issue_token ​

签发 hash 化的 bearer 访问 token，scope 到某路径。返回的明文 token 仅此一次可见。

参数 ​

参数类型必填默认说明
pathstring是—授权路径（服务端别名 object_key）
owner_aidstring否当前用户所有者 AID
bucketstring否"default"存储桶
expires_atinteger否—过期时间
max_readsinteger否—最大读取次数（服务端别名 max_uses）

响应 ​

token 视图 + 明文 token（一次性返回）。

storage.revoke_token ​

按明文 token 值吊销（内部 hash 后查找）。

参数 ​

参数类型必填默认说明
pathstring是—路径（服务端别名 object_key）
tokenstring是—要吊销的明文 token
owner_aidstring否当前用户所有者 AID
bucketstring否"default"存储桶

响应 ​

{revoked: boolean, owner_aid, bucket, path}。

storage.list_tokens ​

列出路径上的 token（owner 校验，不返回明文）。

参数 ​

参数类型必填默认说明
pathstring是—路径
owner_aidstring否当前用户所有者 AID
bucketstring否"default"存储桶

响应 ​

token 列表（hash 摘要 + 元数据）。

storage.volume.create ​

创建/upsert 配额卷（含 mount_point）。

参数 ​

参数类型必填默认说明
size_bytesinteger是—卷容量（>0）
owner_aidstring否当前用户所有者 AID
bucketstring否"default"存储桶
volume_idstring否自动卷 ID
used_bytesinteger否—已用字节
statusstring否activeactive / grace / expired
mount_pointstring否—挂载点
expires_atinteger否—过期时间

响应 ​

{volume, ...卷视图}。

storage.volume.renew ​

续期卷过期时间/状态（owner 校验，owner 不符抛 PermissionError）。

参数 ​

参数类型必填默认说明
volume_idstring是—卷 ID（服务端别名 id）
expires_atinteger是—新过期时间
owner_aidstring否当前用户所有者 AID
bucketstring否"default"存储桶
statusstring否—卷状态

响应 ​

{volume, ...卷视图}。

storage.volume.expire_due ​

过期所有到期卷并标记其挂载为 unavailable。

参数 ​

参数类型必填默认说明
owner_aidstring否当前用户所有者 AID
bucketstring否"default"存储桶
nowinteger否当前时间判定基准时间

响应 ​

{owner_aid, bucket, expired, mounts_unavailable, volumes, mounts}。

错误码 ​

code说明
-32002服务暂不可用（数据库未连接）
-32004权限拒绝（requester 不是对象 owner，或非公开对象的读权限不足）
-32008对象不存在（ErrNotFound）
-32009版本冲突（ErrVersionConflict，expected_version 与实际版本不匹配）
-32000通用错误（参数校验失败、配额不足、base64 解码失败、文件大小超限等）

AUN Protocol Documentation

Copyright © 2026