大数据智能体工作台 DataBuddy 教程：Git 联动开发

提示
预计用时 20 分钟。学习目标：将 Bundle 项目接入 Git 仓库，配置 CI/CD 流水线实现自动化部署。
场景介绍
在团队协作开发中，通常需要通过代码审查（Code Review）和自动化流水线来保证部署质量。本教程演示如何将 Bundle 项目与 Git 仓库联动，实现 Push 到不同分支时自动部署到对应环境。
在本教程中，您将：
1. 将 Bundle 项目初始化为 Git 仓库并配置 .gitignore
2. 配置多分支策略（dev → prod）
3. 在 CI/CD 平台配置密钥认证
4. 编写流水线配置文件（以 GitLab CI 和 GitHub Actions 为例）
5. 验证自动化部署流程
前提条件
已完成 使用 Bundle 开发 教程，具备 Bundle 基础操作能力。
已有 Git 仓库（GitHub / GitLab / 其他 Git 平台）。
已获取腾讯云 API 密钥（SecretId + SecretKey），用于 CI/CD 流水线中的非交互式认证。
已开通 DataBuddy Studio 功能。
提示
如需获取 API 密钥，请登录 腾讯云 CAM 控制台 创建或查看。
使用限制
CI/CD 流水线中使用密钥认证方式（非交互式），不支持浏览器登录方式。
流水线 Runner 环境需为 Linux（macOS / Windows 下安装命令不同，本教程以 Linux 为例）。
databuddy bundle deploy -s 会将变更直接提交到调度（生产环境），请确保已在流水线中配置审批保护。
步骤 1：规划分支策略
本教程以 dev 和 prod 两个分支为例进行演示，分别对应开发环境和生产环境的 Target：
分支
对应 Target
用途
dev
dev
开发集成，日常开发合入点
prod
prod
生产环境，只接受 MR/PR 合入
说明：
以上分支策略仅为演示目的。实际使用中，团队可根据自身情况灵活设计。例如：每位开发者使用自己的个人分支进行开发，通过 MR/PR 合入 dev 或 prod 分支触发对应环境的部署。
步骤 2：初始化 Git 仓库
1. 进入 Bundle 项目目录，初始化 Git 仓库：
cd my_bundle
git init
2. 创建 .gitignore 文件，排除本地状态目录：
# DataBuddy CLI 状态目录（自动生成，包含绑定关系和本地状态，不应提交）
.bundle/
3. 完成首次提交：
git add .
git commit -m "chore: init bundle project"
git remote add origin <你的仓库地址>
git push -u origin dev
注意：
.bundle/ 目录包含本地绑定状态和认证缓存，必须 加入 .gitignore，不应提交到 Git 仓库。
步骤 3：配置密钥认证
CI/CD 流水线中无法使用浏览器交互式登录，需要通过密钥方式认证。DataBuddy CLI 通过读取 ~/.databuddycfg 配置文件获取认证信息。
GitLab CI
在 GitLab 项目中配置 CI/CD 变量：Settings → CI/CD → Variables ，添加以下 4 个变量：
变量名
说明
选项
WEDATA_HOST
DataBuddy Workspace 地址（完整 URL）
Masked
WEDATA_SECRET_ID
腾讯云 API 密钥 ID
Masked
WEDATA_SECRET_KEY
腾讯云 API 密钥 Key
Masked
WEDATA_REGION
地域，如 ap-beijing-fsi
—
GitHub Actions
在 GitHub 仓库中配置 Secrets：Settings → Secrets and variables → Actions ，添加以下 4 个 Secret：
Secret 名称
说明
WEDATA_HOST
DataBuddy Workspace 地址（完整 URL）
WEDATA_SECRET_ID
腾讯云 API 密钥 ID
WEDATA_SECRET_KEY
腾讯云 API 密钥 Key
WEDATA_REGION
地域，如 ap-guangzhou
警告：
密钥绝不能明文写入配置文件或提交到 Git 仓库。务必通过 CI/CD Variables 或 Secrets 注入。
步骤 4：编写 CI/CD 流水线配置
GitLab CI
在仓库根目录创建 .gitlab-ci.yml：
stages:
  - validate
  - deploy
﻿
# ---- 全局配置 ----
variables:
  BUNDLE_DIR: my_bundle   # 修改为实际的 bundle 目录名
﻿
before_script:
  # 安装 DataBuddy CLI（Go 二进制版本）
  - curl 'https://wedata3-platform-bundle-cq-1257305158.cos.ap-chongqing.myqcloud.com/bundle_sh/install.sh' | sudo sh || true
  - databuddy --version
  # 写入认证配置文件（密钥从 CI/CD Variables 注入）
  - |
    cat << EOF > "$HOME/.databuddycfg"
    host = ${WEDATA_HOST}
    secret_id = ${WEDATA_SECRET_ID}
    secret_key = ${WEDATA_SECRET_KEY}
    region = ${WEDATA_REGION}
    EOF
  - cd ${BUNDLE_DIR}
﻿
# ========== dev 分支：部署到开发环境 ==========
﻿
validate-dev:
  stage: validate
  script:
    - databuddy bundle validate -t dev
  rules:
    - if: '$CI_COMMIT_BRANCH == "dev"'
﻿
deploy-dev:
  stage: deploy
  script:
    - databuddy bundle deploy -t dev
  rules:
    - if: '$CI_COMMIT_BRANCH == "dev"'
  environment:
    name: development
﻿
# ========== prod 分支：部署到生产环境 ==========
﻿
validate-prod:
  stage: validate
  script:
    - databuddy bundle validate -t prod
  rules:
    - if: '$CI_COMMIT_BRANCH == "prod"'
﻿
deploy-prod:
  stage: deploy
  script:
    - databuddy bundle deploy -t prod -s
  rules:
    - if: '$CI_COMMIT_BRANCH == "prod"'
  environment:
    name: production
GitHub Actions
在仓库中创建 .github/workflows/deploy.yml：
name: DataBuddy Bundle CI/CD
﻿
on:
  push:
    branches: [dev, prod]
  pull_request:
    branches: [prod]
﻿
env:
  BUNDLE_DIR: my_bundle   # 修改为实际的 bundle 目录名
﻿
jobs:
  # ========== dev 分支：部署到开发环境 ==========
  deploy-dev:
    if: github.ref == 'refs/heads/dev'
    runs-on: ubuntu-latest
    environment: development
    steps:
      - uses: actions/checkout@v4
﻿
      - name: Install DataBuddy CLI
        run: |
          curl 'https://wedata3-platform-bundle-cq-1257305158.cos.ap-chongqing.myqcloud.com/bundle_sh/install.sh' | sudo sh || true
          databuddy --version
﻿
      - name: Configure credentials
        run: |
          cat << EOF > "$HOME/.databuddycfg"
          host = ${{ secrets.WEDATA_HOST }}
          secret_id = ${{ secrets.WEDATA_SECRET_ID }}
          secret_key = ${{ secrets.WEDATA_SECRET_KEY }}
          region = ${{ secrets.WEDATA_REGION }}
          EOF
﻿
      - name: Validate
        run: |
          cd ${{ env.BUNDLE_DIR }}
          databuddy bundle validate -t dev
﻿
      - name: Deploy
        run: |
          cd ${{ env.BUNDLE_DIR }}
          databuddy bundle deploy -t dev
﻿
  # ========== prod 分支：部署到生产环境 ==========
  deploy-prod:
    if: github.ref == 'refs/heads/prod'
    runs-on: ubuntu-latest
    environment: production
    steps:
      - uses: actions/checkout@v4
﻿
      - name: Install DataBuddy CLI
        run: |
          curl 'https://wedata3-platform-bundle-cq-1257305158.cos.ap-chongqing.myqcloud.com/bundle_sh/install.sh' | sudo sh || true
          databuddy --version
﻿
      - name: Configure credentials
        run: |
          cat << EOF > "$HOME/.databuddycfg"
          host = ${{ secrets.WEDATA_HOST }}
          secret_id = ${{ secrets.WEDATA_SECRET_ID }}
          secret_key = ${{ secrets.WEDATA_SECRET_KEY }}
          region = ${{ secrets.WEDATA_REGION }}
          EOF
﻿
      - name: Validate
        run: |
          cd ${{ env.BUNDLE_DIR }}
          databuddy bundle validate -t prod
﻿
      - name: Deploy
        run: |
          cd ${{ env.BUNDLE_DIR }}
          databuddy bundle deploy -t prod -s
说明：
建议在 GitHub 上为 production 环境配置 Required Reviewers，确保生产部署需要人工审批。
步骤 5：日常开发协作流程
完成流水线配置后，团队成员日常按以下流程协作：
1. 从 dev 分支创建 feature 分支进行开发：
git checkout dev
git pull origin dev
git checkout -b feature/add-report-task
2. 编辑 Bundle 配置和代码文件，本地校验通过后提交：
# 本地校验
databuddy bundle validate -t dev -p <profile>
﻿
# 提交代码
git add .
git commit -m "feat(tasks): add daily report task"
git push origin feature/add-report-task
3. 在 Git 平台创建 Merge Request / Pull Request，合入 dev 分支。流水线自动执行 validate 和 deploy 到开发环境。
4. 在开发环境验证无误后，创建 MR 从 dev 合入 prod，经 Code Review 通过后合入。流水线自动部署到生产环境。
步骤 6：验证自动化流程
完成以上配置后，执行一次端到端验证：
1. 在 feature 分支修改 Bundle 配置，推送后创建 MR 合入 dev。
2. 检查 CI/CD 流水线是否自动执行 validate + deploy-dev。
3. 在 DataBuddy 控制台的开发环境中确认工作流已更新。
4. 创建 MR 从 dev 合入 prod，确认 deploy-prod 流水线执行成功。
5. 在 DataBuddy 控制台的生产环境中确认工作流已部署且处于调度状态。
常见问题
流水线中 validate 失败
检查以下几点：
确认 BUNDLE_DIR 变量与实际 Bundle 目录名一致。
确认 ~/.databuddycfg 中的 host、secret_id、secret_key、region 四个字段均正确注入。
确认 CI Runner 网络可访问 DataBuddy API 端点。
流水线中 deploy 失败
确认目标 Target（dev / prod）已在 databuddy.yml 中正确定义。
确认 API 密钥对应的账号在目标 Workspace 中拥有足够权限。
如何回滚
如果生产部署出现问题：
1. 使用 git revert 撤回有问题的 commit。
2. 将 revert commit 合入 prod 分支。
3. 流水线自动执行 deploy，将远端资源恢复到上一状态。
相关文档
使用 Bundle 开发
Bundle 包定义
Bundle 命令
CI/CD 概述
分支	对应 Target	用途
`dev`	`dev`	开发集成，日常开发合入点
`prod`	`prod`	生产环境，只接受 MR/PR 合入
变量名	说明	选项
`WEDATA_HOST`	DataBuddy Workspace 地址（完整 URL）	Masked
`WEDATA_SECRET_ID`	腾讯云 API 密钥 ID	Masked
`WEDATA_SECRET_KEY`	腾讯云 API 密钥 Key	Masked
`WEDATA_REGION`	地域，如 `ap-beijing-fsi`	—
Secret 名称	说明
`WEDATA_HOST`	DataBuddy Workspace 地址（完整 URL）
`WEDATA_SECRET_ID`	腾讯云 API 密钥 ID
`WEDATA_SECRET_KEY`	腾讯云 API 密钥 Key
`WEDATA_REGION`	地域，如 `ap-guangzhou`
教程：Git 联动开发

本页目录：

场景介绍

前提条件

使用限制

步骤 1：规划分支策略

步骤 2：初始化 Git 仓库

步骤 3：配置密钥认证

GitLab CI

GitHub Actions

步骤 4：编写 CI/CD 流水线配置

GitLab CI

GitHub Actions

步骤 5：日常开发协作流程

步骤 6：验证自动化流程

常见问题

流水线中 validate 失败

流水线中 deploy 失败

如何回滚

相关文档
