一、概述
这篇说说如何创建 Volume 类 Catalog、在其下创建 Volume，并完成文件上传、浏览与预览。
二、前提条件
·已开通 DataBuddy 服务并完成空间初始化。
·当前账号在目标工作空间中拥有创建 Catalog 的权限。
·已了解 三级命名空间 的基本概念。
三、使用限制
| 限制项 | 说明 |
| 支持地域 | 全部支持 DataBuddy 的地域 |
| 存储类型 | 当前仅支持腾讯云 COS；托管 Volume 由平台直接管理底层存储；外部 Volume 需基于 External Location 创建 |
| 支持的预览类型 | CSV、Text、PDF（其他文件类型仅支持下载） |
| Volume 搜索 | 全局数据搜索支持搜索 Volume 名称、描述、标签，以及 Volume 下的文件夹和文件名称 |
| 文件夹创建 | 在 Volume 内可创建文件夹，重复文件名上传时自动覆盖 |
五、步骤 1：进入数据目录
1. 登录 DataBuddy 控制台，切换到目标工作空间。
2. 在左侧导航栏选择 数据目录 。
六、步骤 2：新建 Volume 类 Catalog
1. 在左侧目录树顶部点击 + 创建数据目录 。
2. 在 创建数据目录 弹窗中配置参数：
·目录名称 ：必填。
·目录来源 ：必填，选择 TCCatalog
·目录类型 ：必填，选择原生目录
·目录用途 ：必填，选择文件卷目录
·描述 ：可选，最多 500 字符。
3. 点击 确认 完成创建。
创建成功后，你会进入 Catalog 详情页，与 结构化数据目录相同，包含default Schema
七、创建 Volume
Volume 是非结构化文件的容器，挂载在 Schema 之下。
八、步骤 1：进入 Schema 详情页
1. 在 Catalog 详情页点击目标 Schema 名称，进入 Schema 详情页。
2. 在右上角点击 创建数据对象 。
九、步骤 2：填写 Volume 信息
在弹窗中选择 Volume 类型：
| Volume 类型 | 说明 |
| 托管 Volume （Managed Volume） | 由平台分配存储路径，你只需填写 Volume 名称与描述 |
| 外部 Volume （External Volume） | 基于已注册的 External Location 创建，复用外部 COS 路径 |
填写以下信息：
·Volume 名称 ：必填，在当前 Schema 内唯一。
·Volume 存储类型 ：云托管、外部。
·External Location ：仅外部 Volume 需要，下拉选择已注册的 External Location。
·描述 ：可选。
点击 确定 完成创建。创建成功后，你会进入 Volume 详情页。
十、在 Volume 中管理文件
Volume 详情页 概览 Tab 提供文件与文件夹管理能力。
十一、上传文件
在 Volume 详情页右上角点击 上传数据 ，跳转到非结构化数据上传页面。详细操作请参考 本地文件上传到卷。
注意：说明：
注意：文件上传由前端直接调用 COS API，无需选择计算资源。重名文件会自动覆盖原文件。
十二、创建文件夹
1. 在 Volume 详情页 概览 Tab 点击 创建文件夹 。
2. 在弹窗中填写文件夹名称。
3. 点击 确定 完成创建。
文件夹支持嵌套，路径以 /Volumes/<catalog>/<schema>/<volume>/<directory>/… 形式呈现，列表上方面包屑可复制完整路径。
十三、删除文件、文件夹
·在文件列表中勾选目标文件或文件夹，列表内点击删除 ，支持在顶部更多 下拉选择批量删除操作。
·在文件夹中删除非空文件夹会同时删除其下所有内容。
注意：警告：
注意：文件与文件夹删除不可恢复。请在删除前确认无依赖任务或下游引用。
十四、文件搜索
在文件列表上方搜索框输入文件名或文件夹名称，进行实时模糊搜索。
十五、文件预览
在文件列表操作中点击预览图标，进入文件预览页：
·支持类型：CSV、Text、PDF。
·操作：下载、预览、删除
·不支持预览的文件类型仅展示元信息，可下载到本地查看。
十六、文件路径格式
Volume 中的文件遵循统一路径格式：
/Volumes/<catalog>/<schema>/<volume>/<directory>/<file>
例如：
/Volumes/ops_catalog/raw_logs/access_log/2026-06-06/access.log
该路径可直接被 SQL、Python 代码、Notebook 引用：
with open("/Volumes/ops_catalog/raw_logs/access_log/2026-06-06/access.log") as f: data = f.read()
十七、Volume 详情页信息
展示：存储路径、创建时间、创建人、数据变更时间、变更人
十八、权限管理
Volume 的权限模型与表、模型保持一致，可在 Catalog / Schema / Volume 任意层级单独授权。
十九、Volume 层级权限点
| 权限点 | 含义 |
| read | 读取 Volume 中的文件（含下载、预览） |
| write | 写入 / 更新 Volume 中的文件（含上传、覆盖） |
| delete | 删除 Volume 中的文件 |
| create volumes | 在所属 Schema 下创建 Volume |
| all | 授予以上所有权限 |
| grant | 可二次授权（管理以上所有权限） |
注意：说明：
注意：Volume 的权限点同样存在依赖关系：授予 read / write / delete 时，请确保用户已具备所属 Catalog 的 use catalog 与所属 Schema 的 use schema 权限，否则用户无法定位到该 Volume。
20、配置 Volume 权限
1. 进入 Volume 详情页 权限 Tab。
2. 点击 新增授权 ，选择授权主体（用户/用户组）。
3. 选择预设权限（读取、编辑）或勾选具体 Volume 权限点。
4. 点击 确定 完成授权。
仅主账号、Volume 的 owner 和具有 grant 权限的用户可执行授权；其他用户授权按钮置灰。
21、转交 Volume owner
1. 在 Volume 详情页右侧 业务信息 > 资产负责人 旁点击笔形图标。
2. 选择新的 owner。
3. 在弹窗中确认提示文案：「若你非当前 Volume 创建人，转交后你不再拥有该 Volume 的管理权限」。
更多权限规则请参考 成员与权限管理。
22、业务标签
在 Volume 详情页右侧 业务信息 > 标签 旁点击笔形图标，可为 Volume 添加多个治理标签（key:value 形式）。详细规则请参考 治理标签。
23、常见问题
Q：托管 Volume 与外部 Volume 有什么区别？
A：
·托管 Volume ：底层存储由平台分配（默认 default 存储空间），无需你预先准备 COS 路径。适合新建项目、测试场景。
·外部 Volume ：基于已注册的 External Location 创建，复用外部 COS 桶路径，便于跨工作空间共享或对接已有数据。详见 外部数据管理。
Q：上传文件时为什么不需要选择计算资源？
A：Volume 文件上传由前端直接调用 COS API 完成，不经过计算引擎。因此上传过程不消耗计算资源。
Q：删除 Volume 会删除底层 COS 文件吗？
A：
·托管 Volume：删除 Volume 后，平台会同时清理对应 COS 路径下的文件。
·外部 Volume：删除 Volume 仅解除 DataBuddy 中的元数据注册，不会删除 External Location 对应的 COS 文件。
Q：Volume 中的文件能不能被 SQL 直接读取？
A：可以。Volume 路径（/Volumes/<catalog>/<schema>/<volume>/…）可在 Spark SQL、Python、Notebook 中直接读取，例如使用 Spark 读取 Volume 中的 Parquet：spark.read.parquet("/Volumes/ops_catalog/raw_logs/event/")。
24、相关文档
·三级命名空间
·外部数据管理
·本地文件上传到卷
·成员与权限管理