帮你快速理解、总结文档立即下载
文档中心>大数据智能体工作台 DataBuddy>数据工程>CI/CD>实践教程>教程：使用 Bundle 开发

教程：使用 Bundle 开发

最近更新时间：2026-09-11 20:57:31
我的收藏

本页目录：

提示
预计用时 15 分钟。学习目标：完成从 Bundle 初始化到工作流部署运行的端到端流程。

场景介绍

Bundle 是 DataBuddy CI/CD 的核心载体，允许您将工作流配置和代码文件组织为一个可版本化、可部署的项目包。本教程演示如何从零开始使用 Bundle 完成一次完整的开发部署流程。
在本教程中，您将：
1. 安装 databuddy CLI 并完成身份认证
2. 初始化一个 Bundle 项目
3. 验证并部署 Bundle 到开发环境
4. 在开发环境运行工作流

前提条件

已开通 DataBuddy 服务并完成空间初始化。
当前账号在目标 Workspace 中拥有 管理 权限。
本地已安装 curl 命令（macOS / Linux 默认自带）。

步骤 1：安装 databuddy CLI

根据您的操作系统选择对应的安装命令：
macOS / Linux：
curl https://wedata3-platform-bundle-cq-1257305158.cos.ap-chongqing.myqcloud.com/bundle_sh/install.sh | sudo sh
Windows：
curl.exe -fsSL https://wedata3-platform-bundle-cq-1257305158.cos.ap-chongqing.myqcloud.com/bundle_sh/install.bat -o install.bat && install.bat
安装成功后，验证安装：
databuddy -v
预期输出：DataBuddy CLI <版本号>

步骤 2：登录认证

登录前请先获取 Workspace 地址：登录 DataBuddy 控制台并进入目标 Workspace，直接复制浏览器地址栏的完整 URL，形如 https://databuddy.cloud.tencent.com/workbench?o=<workspace_id>&r=<region_id>。其中 o 为 Workspace ID，r 为地域 ID，均由控制台自动生成，无需手动拼接。
注意：
Workspace 地址必须包含 o= 参数（Workspace ID），否则登录失败并提示 workspace id is empty, 'o' param not found in URL。
执行登录命令：
databuddy auth login
终端会依次提示：
1. 显示当前 Profile（默认为 DEFAULT）。
2. 输入新的配置名称，直接回车表示沿用当前配置。
3. 输入上面获取的 DataBuddy Workspace 地址。
完成登录后，终端显示：
Verification Success
登录信息保存在本地配置文件 ~/.databuddycfg 中，其中的配置名称即后续命令 -p 参数要用的 Profile 名称。
说明：
登录状态保留 7 天。也可以在登录时直接指定 Workspace 地址：databuddy auth login --host "<workspace-url>"。地址必须用双引号包裹——使用单引号会导致 URL 解析失败，不加引号会导致身份验证失败。

步骤 3：初始化 Bundle 项目

在本地创建 Bundle 项目：
databuddy bundle init -p <profile>
其中 -p <profile> 指定步骤 2 中登录使用的 Profile 名称，后续所有命令均需携带此参数。
注意：
Profile 名称须与 ~/.databuddycfg 中的配置名称完全一致（区分大小写），默认配置名为 DEFAULT。名称不匹配会提示 profile <name> not found in file。
系统会引导您完成交互式配置：
1. 选择模板 ：根据开发场景选择模板：
SQL：适用于 SQL 数据开发任务。
NoteBook：适用于交互式数据分析与探索。
Minimal：空项目骨架，适合自定义场景。
1. 输入项目名称 ：例如 yiwu_etl。
2. 选择计算资源 ：输入任务使用的计算资源组名称。
完成后，系统在当前目录创建项目文件夹。以 SQL 模板为例，生成结构如下：
yiwu_etl/
├── databuddy.yml           # Bundle 主配置文件
├── src/                    # 代码文件
│   └── sql_example.sql
├── resources/              # 资源定义 YAML
│   └── workflow/
│       └── sql_example.yml
└── README.md               # 项目说明
说明：
不同模板生成的初始目录结构不同：
SQL ：src/ 下包含 .sql 示例文件，resources/workflow/ 下包含对应的任务定义 .yml 文件。
NoteBook ：src/ 下包含 .ipynb 示例文件，resources/workflow/ 下包含对应的任务定义 .yml 文件。
Minimal ：仅包含空的 src/、resources/ 目录和 databuddy.yml，不预置任何示例代码。

步骤 4：验证 Bundle 配置

进入项目目录并验证配置：
cd yiwu_etl
databuddy bundle validate -t dev -p <profile>
验证成功输出：
Name: yiwu_etl
Target: dev
Workspace:
  url: <项目链接>
  User: your_name@example.com
  Path: /Workspace/Users/your_name@example.com/.bundle/yiwu_etl/dev

Validation OK!
注意：
如果验证失败，系统会列出错误详情（资源类型、资源名、错误原因）。请根据提示修改 YAML 配置后重新验证。

步骤 5：部署到开发环境

databuddy bundle deploy -t dev -p <profile>
部署成功输出：
Uploading bundle files to /Workspace/Users/your_name@example.com/.bundle/yiwu_etl/dev/files...
Deploying resources...
Updating deployment state...
Deployment complete!
部署完成后，您可以在 DataBuddy 控制台的 Workflow 中看到已部署的工作流。

步骤 6：运行工作流

databuddy bundle run workflow example_workflow -t dev -p <profile>
运行结果会展示各任务的执行状态：
task name         | status  | time consuming
extract_data      | success | 12s
transform_data    | success | 8s

Run Summary:
  Number of running tasks: 2
  Number of successes: 2
  Number of failures: 0

验证结果

完成所有步骤后：
1. 在 DataBuddy 控制台 数据工程 > Workflow 列表中可以看到已部署的工作流，名称带有 dev_<用户名>_ 前缀。
2. 在工作流详情页可查看运行记录和任务执行日志。
3. 本地 Bundle 项目中的代码文件已同步到 DataBuddy Studio 的 .bundle/<项目名>/dev/files/ 目录下。

总结

在本教程中，您完成了：
安装 databuddy CLI 并完成身份认证
初始化 Bundle 项目并理解其目录结构
验证、部署 Bundle 到开发环境
在开发环境运行工作流并查看结果

下一步

进阶：Git 联动开发
参考：Bundle 包定义
参考：Bundle 命令
中国站