使用 Databricks 资产捆绑管理 Databricks 应用

Databricks Apps 允许你在 Databricks 平台上创建安全数据和 AI 应用程序，以便与用户轻松共享。可以使用 Databricks 资产捆绑包管理应用的部署。有关应用和捆绑包的详细信息，请参阅 Databricks 应用和什么是 Databricks 资产捆绑包？。

本文指导你在本地开发 Databricks 应用，然后使用 Databricks 资产捆绑包配置捆绑包来管理应用到 Databricks 工作区的部署。

小窍门

若要用 Streamlit 应用初始化一个示例捆绑包，请使用带有 bundle init 命令的 streamlit-app 捆绑模板：

databricks bundle init https://github.com/databricks/bundle-examples --template-dir contrib/templates/streamlit-app

要求

Databricks 工作区和本地开发环境必须满足 Databricks Apps 的要求。请参阅设置 Databricks Apps 工作区和开发环境。
Databricks CLI 版本 0.250.0 或更高版本。若要检查安装的 Databricks CLI 版本，请运行命令 databricks -v。要安装 Databricks CLI，请参阅《安装或更新 Databricks CLI》。

在本地创建应用

首先，创建 Databricks 应用。应用是使用常用框架（如 Dash 或 Gradio）在 Python 中开发的。可以从头开始在本地生成 Databricks 应用，在 Databricks 工作区中创建一个，然后将文件同步到本地计算机，或者从 GitHub 获取 Databricks 示例应用。

若要从头开始生成应用，请执行以下作：
1. 请按照框架的快速入门教程进行操作。
  - 破折号
  - Flask
  - Gradio
  - 闪亮
  - Streamlit
2. 将文件 app.yaml 添加到项目的根目录，以定义如何运行主 Python 应用。例如：
  
  对于 Streamlit 应用：
```
command: ['streamlit', 'run', 'app.py']
```
  或者对于 Dash 应用：
```
command: ['python', 'app.py']
```
若要在工作区中创建应用并将其同步到本地：
1. 按照 Databricks 应用入门中的步骤在 UI 中创建应用。
2. 为应用创建本地目录并将其 cd 放入其中：
```
mkdir hello-world-app
cd hello-world-app
```
3. 在本地同步应用文件。可以从工作区 UI 中的应用安装页面复制 databricks workspace export-dir 命令，并在命令行中运行该命令。例如：
```
databricks workspace export-dir /Workspace/Users/someone@example.com/databricks_apps/hello-world_2025_05_09-17_43/hello-world-app .
```
  这会将工作区目录中的应用文件下载到 hello-world-app 本地计算机上的目录。
从 GitHub 获取 Databricks 示例应用：
1. 克隆 Databricks 应用模板 GitHub 存储库：
```
git clone https://github.com/databricks/app-templates
```
2. 选择一个示例应用作为简单的应用项目。

将现有应用添加到现有捆绑包

如果您的工作区中有一个 Databricks 应用，并且已有一个想要将应用添加到其中的捆绑包，那么您可以使用 databricks bundle generate app 命令。此命令为应用生成配置文件，并下载应用的所有源代码文件，并将其添加到捆绑包。例如：

databricks bundle generate app --existing-app-name hello-world-app

在捆绑包中生成应用配置后，使用 databricks bundle bind 命令将应用保留在工作区中并同步捆绑包。

有关databricks bundle generate和databricks bundle bind的更多信息，请参阅bundle 命令组。

在本地开发和调试应用

接下来，继续在本地开发应用。使用 databricks apps run-local 命令启动和调试应用。此命令启动一个应用代理，用于将请求代理到应用本身，并注入必要的 Databricks 应用相关标头。

若要安装所有依赖项，请准备虚拟环境，并启动应用和调试器，请使用run-local命令和--prepare-environment--debug选项：
```
databricks apps run-local --prepare-environment --debug
```
此命令用于 uv 准备虚拟环境，调试器基于 debugpy。
导航到 http://localhost:8001 查看应用。
设置断点以调试应用。在 Visual Studio Code 中，安装 Python 调试器，然后选择“ 运行>开始调试 ”，然后选择 “远程附加”。

代理在端口 5678 上启动，但可以使用此选项 --port 对其进行配置。

将应用部署到工作区

准备好将应用部署到工作区时，添加创建应用的捆绑包配置，然后部署捆绑包。

在应用项目的根目录中创建文件 databricks.yml 。 Databricks CLI 将根目录中有 databricks.yml 文件的文件夹识别为捆绑包，从而启用 databricks 捆绑命令。

将以下 YAML 复制并粘贴到 databricks.yml 文件中，并用您自己的值替换占位符的工作区和用户名：

bundle:
  name: hello_world_bundle

resources:
  apps:
    hello_world_app:
      name: 'hello-world-app'
      source_code_path: . # This assumes the app source code is at the root of the project.
      description: 'A Databricks app'

targets:
  dev:
    mode: development
    default: true
    workspace:
      host: https://myworkspace.cloud.databricks.com
  prod:
    mode: production
    workspace:
      host: https://myworkspace.cloud.databricks.com
      root_path: /Workspace/Users/someone@example.com/.bundle/${bundle.name}/${bundle.target}
    permissions:
      - user_name: someone@example.com
        level: CAN_MANAGE

验证，然后部署捆绑包。默认情况下，这会在工作区的目标中创建 dev 应用和捆绑包。
```
databricks bundle validate
databricks bundle deploy
```
部署捆绑包不会自动将应用部署到计算资源。若要部署应用，请使用应用在 Databricks 工作区页面的 UI 或使用 Databricks CLI （databricks apps deploy）。请参阅部署 Databricks 应用。

bundle summary使用命令检索有关已部署应用的信息：

databricks bundle summary

Name: hello_world_bundle
Target: dev
Workspace:
  Host: https://myworkspace.cloud.databricks.com
  User: someone@example.com
  Path: /Workspace/Users/someone@example.com/.bundle/hello_world_bundle/dev
Resources:
  Apps:
    hello_world_app:
      Name: hello-world-app
      URL:  https://myworkspace.cloud.databricks.com/apps/hello-world-app?o=8498204313176880

开发、测试、迭代

继续在本地更改应用，然后重新部署捆绑包以更新工作区中的应用。在测试期间，可能需要为 Azure Databricks 工作区中的其他用户配置应用的使用情况权限，可以通过指定权限来执行此作：

resources:
  apps:
    hello_world_app:
      name: 'hello-world-app'
      source_code_path: . # This assumes the app source code is at the root of the project.
      description: 'A Databricks app'
      permissions:
        - level: CAN_USE
          group_name: users

若要在工作区中启动应用，请在捆绑包中运行应用，方法是在命令中为应用指定资源密钥：

databricks bundle run hello_world_app

部署到生产

Databricks 建议使用服务主体在生产环境中进行身份验证。准备好使应用在生产环境中可用时，请将捆绑包配置更新为使用服务主体，然后将捆绑包部署到目标生产工作区。有关服务主体的信息，请参阅 CI/CD 的服务主体。

修改捆绑包以使用服务主体

在部署到生产环境之前，请在捆绑包中配置授予对服务主体的权限。可以在创建应用或运行捆绑包时配置授权。

若要在捆绑部署时授予服务主体权限，请修改捆绑包 databricks.yml 以定义应用的授权。使用捆绑包替换来分配服务主体：

bundle:
  name: hello_world_bundle

resources:
  apps:
    hello_world_app:
      name: 'hello-world-app'
      source_code_path: . # This assumes the app source code is at the root of the project.
      description: 'A Databricks app'

  schemas:
    my_schema:
      name: my_schema
      grants:
        # highlight-next-line
        - principal: '${resources.apps.hello_world_app.service_principal_client_id}'
          privileges:
            - CREATE_TABLE
      catalog_name: main

targets:
  dev:
    mode: development
    default: true
    workspace:
      host: https://myworkspace.cloud.databricks.com
  prod:
    mode: production
    workspace:
      host: https://myworkspace.cloud.databricks.com
      root_path: /Workspace/Users/someone@example.com/.bundle/${bundle.name}/${bundle.target}
    permissions:
      - user_name: someone@example.com
        level: CAN_MANAGE

或者，在捆绑包中定义一个作业，该作业在运行捆绑包时配置授权：

在单元格中添加包含以下内容的笔记本 grant_notebook.ipynb 。将 <schema-name> 替换为管理员用户名。

app_service_principal = dbutils.widgets.get("app_service_principal")
spark.sql(f"GRANT ALL PRIVILEGES ON SCHEMA <schema-name> TO `{app_service_principal}`")

定义捆绑包 databricks.yml 中的作业以运行向服务主体授予权限的笔记本。使用捆绑包替换来分配服务主体值：

bundle:
  name: hello_world_bundle

resources:
  apps:
    hello_world_app:
      name: 'hello-world-app'
      source_code_path: . # This assumes the app source code is at the root of the project.
      description: 'A Databricks app'

  jobs:
    grant_job:
      name: 'grant-job'
      parameters:
        - name: app_service_principal
          # highlight-next-line
          default: '${resources.apps.hello_world_app.service_principal_client_id}'
      tasks:
        - task_key: setup_grants
          notebook_task:
            notebook_path: ./grant_notebook.ipynb

targets:
  dev:
    mode: development
    default: true
    workspace:
      host: https://myworkspace.cloud.databricks.com
  prod:
    mode: production
    workspace:
      host: https://myworkspace.cloud.databricks.com
      root_path: /Workspace/Users/someone@example.com/.bundle/${bundle.name}/${bundle.target}
    permissions:
      - user_name: someone@example.com
        level: CAN_MANAGE

部署更新的捆绑包

现在，将捆绑包部署到生产工作区并运行应用：

databricks bundle deploy -t prod
databricks bundle run grant_job -t prod # (Optional) Run this if the grant is configured with a job
databricks bundle run hello_world_app -t prod

其他资源

反馈

此页面是否有帮助？

Last updated on 2026-02-06