> ## Documentation Index > Fetch the complete documentation index at: https://docs.devinenterprise.com/llms.txt > Use this file to discover all available pages before exploring further. # 将 Devin 连接到 Databricks > 通过 service principal、OAuth 客户端密钥或 OIDC 令牌联合、Databricks CLI 以及 Unity Catalog 授权，将 Devin 连接到 Databricks。 Devin 可以像一位异步协作的同事一样在你的 Databricks workspace 中工作：浏览 catalog、调试失败的 job、调优 SQL、编写并测试笔记本，以及通过你日常的 Git 工作流程交付变更。本指南将介绍如何通过一个专用的 Databricks service principal 完成这项配置——Devin 以该身份进行身份验证，并受 Unity Catalog 治理。 该集成由三个完全由你掌控的部分构成：一个 Databricks service principal、通过[环境蓝图](/zh/onboard-devin/environment/blueprints)安装的 Databricks CLI，以及 (可选的) Databricks 技能 plugin。Databricks、其 workspace 及所有权限始终保留在你的账户中。
## 选择 Devin 的身份验证方式
Devin 以 service principal 身份向 Databricks 进行身份验证，有两种方式。两者使用相同的 service principal、由蓝图安装的 CLI 以及 Unity Catalog 授权，区别仅在于所用的凭据。 | 方式 | 适用场景 | 设置 | | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------- | | [**方案 A：OAuth 客户端密钥**](#option-a-oauth-client-secret) | 快速上手。只需三个 Devin Secrets 和一份简短的蓝图。 | 在 service principal 上生成 OAuth secret，并将其存储到 Devin Secrets 中。 | | [**方案 B：OIDC 令牌联合**](#option-b-oidc-token-federation) | 扩展集成规模，或者不愿管理 Databricks secret 的团队。Databricks [强烈建议](https://docs.databricks.com/aws/en/dev-tools/auth/oauth-federation)自动化 workloads 采用令牌联合，因为没有任何需要轮换的内容。 | 通过联合策略信任 Devin 的 OIDC 签发方；每个会话用短期有效的 Devin 身份令牌换取 Databricks OAuth 令牌。 | 如果你希望今天就让 Devin 跑通 Databricks，请从方案 A 开始。后续可随时改用方案 B，无需改动 service principal 及其授权。
## 为什么要将 Devin 连接到 Databricks？
* **Devin 直接在你的数据平台上干活。** Databricks 上的工作大多不只是在代码仓库里编辑笔记本，还包括排查 job 为什么失败、查看表的 schema、对数据仓库执行 query，或检查流水线。把 CLI 交给 Devin，这些原本要找人解答的问题，就变成了 Devin 自己就能搞定的事。 * **单一可审计身份。** Devin 以你创建的 service principal 身份执行操作，因此每一次 API call、query 和 job 运行都会以该身份记录在 Databricks 的 audit logs 和 Unity Catalog 血缘中，而不是挂在某位工程师的个人令牌名下。 * **Devin 能碰什么由 Unity Catalog 说了算。** OAuth 决定 Devin 能否通过身份验证；Unity Catalog 的授权和 workspace 权限则决定它能读取或更改什么。你可以先在生产环境中以 read-only 起步，给 Devin 一个 sandbox catalog 用于构建，等看清它的行为表现后再放宽作用域。 * **通向零存储 secrets 的路径。** 采用 OIDC 令牌联合 (方案 B) 时，Devin 完全不存储 Databricks 令牌或客户端密钥。每个会话都会用一个有效期 60 秒的 Devin 身份令牌换取一个 short-lived 的 Databricks OAuth 令牌。
## 概述
``` Devin 会话 │ Databricks CLI 以 service principal 身份进行身份验证 │ 方式 A：来自 Devin Secrets 的 client ID + 客户端密钥 │ 方式 B：短期有效的 Devin OIDC 令牌，通过联合策略进行匹配 ▼ Databricks 为该 service principal 颁发短期有效的 OAuth access token │ ▼ Workspace API、SQL 仓库、job、Unity Catalog （受 workspace 权限和 Unity Catalog 授权的限制） ``` 配置分为四个部分： | 部分 | 所在位置 | 作用 | | --------------------- | ------------------------------------ | ------------------------------------------------------------------------------ | | **service principal** | Databricks 账户 | Devin 所使用的身份。需分配到 Devin 所需的 workspace。 | | **身份验证** | Databricks 账户 + Devin | **选项 A：** OAuth M2M，客户端密钥存储在 Devin Secrets 中。**选项 B：** OIDC 令牌联合，无需存储 secrets。 | | **Databricks CLI** | Devin 蓝图 | 安装到快照中，并配置为以 service principal 身份进行身份验证。 | | **权限** | Databricks workspace + Unity Catalog | workspace 权限、SQL 仓库与 job 权限，以及 catalog/schema 授权。 | [Databricks 技能 plugin](#step-4-install-the-databricks-skills-plugin-optional) 是第五层，可选：它在 CLI 之上，让 Devin 掌握 Databricks 特有的工作流程 (Asset Bundles、jobs、SQL、Unity Catalog) 。
## 前置条件
**Databricks** * 一个位于 AWS、Azure 或 GCP 上的 Databricks 账户，且执行配置的人员拥有 **account admin** 访问权限。创建 service principal、OAuth secrets 和联合策略都在账户级别完成。 * 一个或多个启用了 **Unity Catalog** 的 workspace。本指南假设 Devin 需要访问的数据由 Unity Catalog 管控。 * 在 admin 自己的 machine 上安装 [Databricks CLI](https://docs.databricks.com/aws/en/dev-tools/cli/)，用于执行下文的账户级别命令，任意较新版本均可。Devin 所用的副本会在步骤 2 中单独安装。 **Devin** * 编辑你的组织的[环境蓝图](/zh/onboard-devin/environment/blueprints) (**Settings > Environment > Blueprints**) 的权限。 * 若采用方案 A，需要添加 [Devin Secrets](/zh/product-guides/secrets) 的权限。 * 若采用方案 B，需要你的 Devin **OIDC 签发方 URL** 和 **organization ID**。步骤 2 将说明如何从 Devin 会话内的令牌中读取这两项。相关背景请参阅 [Cloud Authentication with OIDC](/zh/product-guides/oidc)。 **网络** * Devin 会话必须能通过 HTTPS 访问你的 workspace 主机 (例如 `https://dbc-xxxx.cloud.databricks.com`、`https://adb-xxxx.azuredatabricks.net` 或 `https://xxxx.gcp.databricks.com`) 。如果你的组织启用了 Devin [网络策略](/zh/product-guides/security-profiles)，请将该 workspace 主机加入放行范围；若要执行账户级别命令，还需加入账户主机 (`accounts.cloud.databricks.com`、`accounts.azuredatabricks.net` 或 `accounts.gcp.databricks.com`) 。 * 若采用方案 B，Databricks 必须能通过公共互联网访问 `https:///.well-known/jwks.json` 获取 Devin 的 JWKS，以验证令牌签名。
## 步骤 1：创建 service principal
请为 Devin 单独创建一个 service principal，不要复用其他自动化所依赖的主体。专用主体能让审计日志和权限审查保持清晰。 在一台已登录 Databricks **账户** (而非 workspace) 的机器上执行： ```bash theme={null} databricks account service-principals create --display-name devin-sessions ``` 记录输出中的两个值： | 字段 | 用途 | | --------------- | ------------------------------------------------------------------------------------------------ | | `applicationId` | OAuth **client ID**。用于 `DATABRICKS_CLIENT_ID` secret (方案 A) 或 CLI profile (方案 B) ，以及 `GRANT` 语句。 | | `id` | service principal 的数字 ID。创建 OAuth secret (方案 A) 或附加联合策略 (方案 B) 时需要用到。 | 然后，将该 service principal 分配给 Devin 需要使用的每个 workspace。你可以在 account console 的 **User management → Service principals** 中操作，也可以使用 CLI： ```bash theme={null} databricks account workspace-assignment update \ --json '{"permissions": ["USER"]}' ``` 使用 `USER`，而非 `ADMIN`。Devin 不需要 workspace admin 权限。
## 步骤 2：将 Devin 连接到 service principal
请按下面两个选项中的**其中一个**操作。每个选项都可单独完成：它会通过 **Settings > Environment > Blueprints** 下的[蓝图](/zh/onboard-devin/environment/blueprints)安装 Databricks CLI，并将该 CLI 配置为以步骤 1 中创建的 service principal 身份进行身份验证。 * [**选项 A：OAuth 客户端密钥**](#option-a-oauth-client-secret)。标准的 [OAuth M2M](https://docs.databricks.com/aws/en/dev-tools/auth/oauth-m2m) 方式：为 service principal 生成一个客户端密钥，并将其存储在 Devin Secrets 中。这是最快的上手方式。 * [**选项 B：OIDC 令牌联合**](#option-b-oidc-token-federation)。每个 Devin 会话都可以签发一个由 Devin 签名的短期 OpenID Connect 令牌。借助 Databricks [令牌联合](https://docs.databricks.com/aws/en/dev-tools/auth/oauth-federation)，service principal 可以信任该签发方，Devin 便能用自己的身份令牌换取 Databricks OAuth 令牌。全程不会创建或存储任何 Databricks secrets，因此 Databricks 强烈建议在自动化 workloads 中采用这种方式。 无论选择哪个选项，都不建议使用与人工用户绑定的个人访问令牌 (PAT) 。它们会绕过 service principal，过期时间难以预测，还会把 Devin 的操作归到某个人名下。
### 方案 A：OAuth 客户端密钥
不想管理 Databricks secrets？可直接跳至 [方案 B：OIDC 令牌联合](#option-b-oidc-token-federation)。你也可以先按本方案配置，之后再切换：换用方案 B 的蓝图，创建联合策略，然后删除 OAuth secrets 及 `DATABRICKS_CLIENT_SECRET` 这个 Devin Secret。
#### 1. 生成 OAuth secret
在账户 console 中，打开步骤 1 中创建的 service principal，生成 **OAuth secret**。有效期请设置为轮换流程所能支持的最短时长 (最长 730 天) ，并将该 secret 限制在 Devin 所需的 API 作用域内，例如 `sql`、`jobs` 和 `unity-catalog`，不要选择全部作用域。
#### 2. 添加 Devin secrets
在 Devin 中，将以下内容作为 [Devin secrets](/zh/product-guides/secrets) 添加到你接下来要编辑的蓝图 (组织级或代码仓库级) 的 **Secrets** 选项卡中： | Secret | 值 | | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | `DATABRICKS_HOST` | Devin 要操作的 **workspace** URL，例如 `https://dbc-xxxx.cloud.databricks.com` 或 `https://adb-xxxx.azuredatabricks.net`，不带 `/api` 后缀。不要使用 `accounts.*` 主机。 | | `DATABRICKS_CLIENT_ID` | 步骤 1 中该 service principal 的 `applicationId` (一个 UUID) ，而不是数字型的 `id` | | `DATABRICKS_CLIENT_SECRET` | 你生成的 OAuth secret | 当同时存在 client ID 和客户端密钥时，CLI 会自动选择 OAuth M2M，因此无需设置 `DATABRICKS_AUTH_TYPE`。只有当你想明确排除其他所有认证方式时，才将其设为 `oauth-m2m`。 Secrets 会在每个新会话开始时以环境变量的形式注入，因此 CLI 不需要 Profile 文件。轮换后的 secret 无需重建即可在下一个新会话中生效。
#### 3. 添加蓝图
仅安装 CLI。身份验证完全依赖上述三个 secrets。 ```yaml theme={null} initialize: - name: Install Databricks CLI run: | sudo rm -f /usr/local/bin/databricks curl -fsSL https://raw.githubusercontent.com/databricks/setup-cli/main/install.sh | sudo sh databricks --version knowledge: - name: databricks-auth contents: | The `databricks` CLI authenticates as a service principal using the DATABRICKS_HOST, DATABRICKS_CLIENT_ID, and DATABRICKS_CLIENT_SECRET environment variables, which are provided as Devin Secrets. Do not run `databricks auth login`, do not set DATABRICKS_TOKEN, and do not ask for a personal access token. Check auth with `databricks current-user me`. Write only to the devin_dev catalog; production catalogs are read-only. Ship notebook and job changes through a pull request. ``` 不要在 `initialize` 阶段将 secrets 写入文件；写入其中的任何内容都会被固化到快照中。 另外，请勿设置 `DATABRICKS_TOKEN`，也不要在快照中保留 `~/.databrickscfg` Profile。凭据冲突是导致 M2M 身份验证失败最常见的原因。
#### 4. 构建快照
保存蓝图，等待构建状态显示为 **Success**，然后启动新会话。已有会话仍使用旧快照。接下来请继续[步骤 3](#step-3-grant-permissions)。
### 方案 B：OIDC 令牌联合
Devin 会话会签发短期身份令牌 (`iss`、`sub`、`aud`) ，而 service principal 上的联合策略会让 Databricks 信任这些令牌。蓝图会安装 `devin-oidc` CLI，并对 `databricks` 进行封装，使每次调用都携带一个全新的令牌，同时写入一个指向你的 service principal 的 profile。之后，你从会话中读取令牌的 claims，并创建与之匹配的 policy。 想先走最短路径？可以从[方案 A](#option-a-oauth-client-secret) 开始，等你准备好不再依赖存储的 secrets 时再回到这里。
#### 1. 添加蓝图
Profile 中有两个占位符必须替换为你自己的值： | 占位符 | 替换为 | | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `` | Devin 需要在其中工作的 **workspace** URL，例如 `https://dbc-xxxx.cloud.databricks.com` 或 `https://adb-xxxx.azuredatabricks.net`，不带 `/api` 后缀。不要使用 `accounts.*` 主机。该值与选项 A 中的 `DATABRICKS_HOST` 相同。 | | `` | 步骤 1 中 `databricks account service-principals create` 输出里 service principal 的 `applicationId` (一个 UUID) 。不是数字形式的 `id`，后者仅用于附加联合策略。 | ```yaml theme={null} initialize: - uses: github.com/CognitionAI/actions/setup-devin-oidc@main - name: Install Databricks CLI run: | sudo rm -f /usr/local/bin/databricks curl -fsSL https://raw.githubusercontent.com/databricks/setup-cli/main/install.sh | sudo sh sudo mv /usr/local/bin/databricks /usr/local/bin/databricks-bin - name: Wrap the CLI so each call carries a fresh Devin OIDC token run: | sudo tee /usr/local/bin/databricks > /dev/null <<'EOF' #!/usr/bin/env bash set -euo pipefail DATABRICKS_OIDC_TOKEN="$(devin-oidc token --audience "${DATABRICKS_DEVIN_AUDIENCE:-databricks}")" export DATABRICKS_OIDC_TOKEN exec /usr/local/bin/databricks-bin "$@" EOF sudo chmod +x /usr/local/bin/databricks - name: Write Databricks CLI profile run: | cat > ~/.databrickscfg <<'EOF' [DEFAULT] host = auth_type = env-oidc client_id = audience = databricks EOF chmod 600 ~/.databrickscfg knowledge: - name: databricks-auth contents: | The `databricks` CLI is preconfigured to authenticate as a service principal through Devin OIDC token federation. Do not run `databricks auth login`, do not set DATABRICKS_TOKEN, and do not ask for a personal access token. Check auth with `databricks current-user me`. Write only to the devin_dev catalog; production catalogs are read-only. Ship notebook and job changes through a pull request. ``` | 组成部分 | 目的 | | ---------------------- | --------------------------------------------------------------------- | | `setup-devin-oidc` | 安装 `devin-oidc` CLI，用于签发 Devin 身份令牌 ([详情](/zh/product-guides/oidc)) 。 | | 包装脚本 | Devin 身份令牌 60 秒后即过期，因此每次 CLI 调用都会各自签发新令牌。 | | `auth_type = env-oidc` | 将 CLI 固定为令牌联合方式，使其绝不会回退到 PAT 或交互式登录。 | | `host` / `client_id` | 上表中的 workspace URL 和 service principal 的 `applicationId`。 | | `audience` | 包装脚本请求的 audience，也是你稍后要填入下方联合策略的值。 | | `knowledge` | 告知 Devin 该 CLI 已完成身份验证，使其不会尝试执行 `databricks auth login`。 | 该 Profile 不含任何 secrets，因此可以安全地在 `initialize` 阶段写入。如果你是从方案 A 切换过来的，请在下方策略配置就绪后删除 `DATABRICKS_CLIENT_SECRET` 这一 Devin Secret，以免 CLI 同时看到两份凭据。
#### 2. 构建快照
保存蓝图，等待构建状态变为 **Success**。蓝图中没有任何内容依赖于你接下来创建的联合策略，因此之后无需重建。
#### 3. 创建联合策略
蓝图构建完成后，Devin 会话即可签发身份令牌。先用一个令牌读取 Databricks 需要信任的确切 claims，然后在 service principal 上创建与之匹配的联合策略。 启动一个新的 Devin 会话，让它运行以下命令。该命令只会打印令牌的身份 claims，不会打印令牌本身。 ```bash theme={null} devin-oidc token --audience databricks | python3 -c ' import sys, json, base64 p = sys.stdin.read().strip().split(".")[1] c = json.loads(base64.urlsafe_b64decode(p + "==")) print(json.dumps({k: c[k] for k in ("iss", "sub", "aud")}, indent=2))' ``` 预期输出格式： ```json theme={null} { "iss": "https://app.devin.ai", "sub": "org_id:", "aud": "databricks" } ``` 在企业部署中，`iss` 是你的自定义 Devin URL (例如 `https://yourcompany.devinenterprise.com`) 。请严格按打印结果复制 `iss` 和 `sub`。不要把原始令牌粘贴到工单或文档中；在接下来的 60 秒内，它就是一份 bearer 凭据。 将以下内容保存为 `devin-federation-policy.json`，并替换为上一步获得的值： ```json theme={null} { "description": "Allow Devin sessions to authenticate as the devin-sessions service principal", "oidc_policy": { "issuer": "https://", "audiences": ["databricks"], "subject": "org_id:" } } ``` 这三个字段都要精确匹配： * `issuer` 必须与令牌的 `iss` 完全一致，包含协议前缀，且结尾不带斜杠。 * `audiences` 必须包含 Devin 请求的 audience (本指南中为 `databricks`) 。 * `subject` 必须与令牌的 `sub` 完全一致。默认的 subject 是你的组织 ID，因此该组织中的每个会话都能以此主体进行身份验证。对 Databricks 来说这是合适的粒度，因为联合策略是按字面字符串匹配 subject 的。像 `devin_id` 这类会话级 claims 每个会话都不同，静态策略无法匹配。 请不要设置 `subject_claim`、`jwks_uri` 和 `jwks_json`。Databricks 默认使用 `sub` claim，并从签发方的 `/.well-known/openid-configuration` 发现 JWKS。 ```bash theme={null} databricks account service-principal-federation-policy create \ --policy-id devin-sessions \ --json @devin-federation-policy.json ``` 确认策略已存在： ```bash theme={null} databricks account service-principal-federation-policy list ``` 蓝图写入的 profile 已指向该 service principal，因此无需重建。继续进行[步骤 3](#step-3-grant-permissions)。
### 重建与版本固定
Databricks 安装脚本和 `setup-devin-oidc@main` 都跟随各自上游的 `main` 分支，因此完整构建会拉取到新版本；而[差分构建](/zh/onboard-devin/environment/differential-builds)会跳过 `initialize`，在蓝图发生变更之前一直沿用快照中已有的版本。如果你需要可复现的构建，请从发布标签而非 `main` 获取安装程序 (例如 `.../databricks/setup-cli/v1.17.0/install.sh`) ，这样安装的就是指定的那个 CLI 版本；同时将 action 固定到某个提交 SHA (`setup-devin-oidc@`) 。
## 步骤 3：授予权限
身份验证只能证明 Devin 的身份。Devin 能查看或更改哪些内容，则由 workspace 权限和 Unity Catalog 授权决定；你可以随时调整这些设置，无需改动蓝图。建议从满足当前工作所需的最小 Profile 起步，再有针对性地逐步扩大。
### 权限 Profile
| Profile | 典型工作 | Unity Catalog 授权 | workspace 权限 | | --------------------- | --------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | | **Explore** (建议从这里开始) | 回答数据相关问题、编写 schema 文档、排查失败的 job、在 PR 中提出 query 修复方案 | 在生产 catalog 上授予 `USE CATALOG`、`USE SCHEMA`、`SELECT`、`BROWSE`；在 Devin 需要读取文件的位置授予 `READ VOLUME` | 在一个 SQL 仓库上授予 `CAN USE`；在 Devin 需要排查的 job 和流水线上授予 `CAN VIEW` | | **Build** | 在沙盒中对表、函数和笔记本进行原型开发；针对真实的只读数据运行测试 | Explore 在生产环境的授权，外加对专用 `devin_dev` catalog 或 schema 的所有权 (或 `ALL PRIVILEGES`) | Explore 的权限，外加沙盒 job 上的 `CAN MANAGE RUN`；如果允许 Devin 启动计算资源，还需一条限制性的集群策略 | | **Operate** | 在 Explore 和 Build 得到验证后，重新运行或修复特定生产 job | Explore 的授权，外加对该 job 写入的特定表的 `MODIFY` | 在特定 job 上授予 `CAN MANAGE RUN`，按 job 逐个授予，而非在整个 workspace 范围授予 | 授权 statement 通过应用程序 ID 指定 service principal： ```sql theme={null} -- Explore：对生产环境 analytics catalog 的只读权限 GRANT USE CATALOG, BROWSE ON CATALOG analytics TO ``; GRANT USE SCHEMA, SELECT ON SCHEMA analytics.gold TO ``; GRANT READ VOLUME ON VOLUME analytics.gold.landing TO ``; -- Build：由 Devin 拥有的沙盒 catalog，与生产环境隔离 CREATE CATALOG IF NOT EXISTS devin_dev; ALTER CATALOG devin_dev OWNER TO ``; ``` 如果你更倾向于基于组的管理方式，可以将 service principal 添加到某个组 (例如 `devin-agents`) ，然后改为向该组授权。 代码修改仍应通过拉取请求进行。Devin 可以读取生产数据来了解问题，并在沙盒中验证修复，但笔记本、job 定义或 Asset Bundle 的变更仍需经由你常规的评审流程合入，而不是直接改动生产环境。
## 步骤 4：安装 Databricks 技能 plugin (可选)
Databricks 发布了 [Agent Skills](https://github.com/databricks/databricks-agent-skills)，可以让代码 Agent 掌握 Databricks 的各类工作流程：Asset Bundles、jobs、SQL、Unity Catalog 和 Spark。将它们安装为 Devin 的 [plugin](/zh/product-guides/plugins) 后，Devin 就能在 CLI 的基础上具备这些专业知识。 1. 打开 **Customize → Plugins**，选择 **Add plugin → From repository**。 2. 输入代码仓库 `databricks/databricks-agent-skills` 和子目录 `plugins/databricks/claude`。plugin 清单位于该子目录中，因此从 repository root 安装会提示 **No plugin manifest found**。 3. 如果你在步骤 2 中使用了 organization blueprint，请在 **Organization** 作用域下安装；如果使用的是 repository blueprint，则改为在该代码仓库的 `.devin/config.json` 中声明该 plugin (参见[继承与级别](/zh/cli/extensibility/plugins/overview#inheritance-and-levels)) ，这样只有装有 CLI 的会话才会获得这些技能。 4. 确认 plugin 正常工作后，[将 plugin 固定到某个 commit](/zh/product-guides/plugins#pinning-a-plugin)，以免上游变更未经审查就进入你的会话。 该 plugin 的核心技能建议运行 `databricks auth login` 来设置 profile。这一交互式浏览器流程无法在无人值守的 Devin 会话中完成，这里也不需要执行；步骤 2 中的 `knowledge` 条目已告知 Devin，CLI 已完成身份验证。
## 步骤 5：验证
待蓝图构建成功后，启动一个新会话，让 Devin 运行： ```bash theme={null} databricks --version databricks current-user me ``` `current-user me` 应返回该服务主体 (service principal) ，且其 `userName` 等于该应用程序 ID。要确认 CLI 使用了哪种身份验证方式： ```bash theme={null} databricks auth describe ``` 选项 A 会报告 `oauth-m2m`，选项 B 则报告 `env-oidc`。 身份验证成功并不代表 Devin 就能访问你的数据。请确认步骤 3 中的授权已生效： ```bash theme={null} databricks catalogs list databricks warehouses list databricks grants get catalog ``` 将 `` 替换为你在步骤 3 中授权的 catalog (那里的示例使用 `analytics`) 。然后让 Devin 对它拥有 `CAN USE` 权限的仓库运行一个小型只读 query；如果你配置了 Build profile，还可以让它在 `devin_dev` 中创建并删除一张表。而对 Devin 没有 `SELECT` 权限的生产表执行 query 应当失败——这次失败恰恰说明权限边界正在生效。
## 故障排查
| 症状 | 适用于 | 原因与修复 | | ---------------------------------- | ---- | --------------------------------------------------------------------------------------------------------------------------------- | | 出现凭据冲突或存在多种身份验证方式的报错 | 方案 A | 移除 `DATABRICKS_TOKEN`、`DATABRICKS_USERNAME` 以及所有 `~/.databrickscfg` Profile。当配置了多种身份验证方式时，CLI 不会自行猜测该用哪一种。 | | `DATABRICKS_OIDC_TOKEN` 未设置或为空 | 方案 B | 包装脚本被绕过或未安装。确认 `which databricks` 解析到该包装脚本，并且单独执行 `devin-oidc token --audience databricks` 能够成功。 | | `invalid_grant` 或提及 subject 的报错 | 方案 B | 策略中的 `subject` 与令牌的 `sub` 不完全一致。重新运行步骤 2 中的 claims 脚本，逐字符比对。 | | 提及 audience 的报错 | 方案 B | 策略中的 `audiences` 未包含包装脚本请求的 audience。两者默认均为 `databricks`；请保持一致。 | | 提及签发方、JWKS 或签名的报错 | 方案 B | `issuer` 有拼写错误 (尾部斜杠、`http`、主机名有误) ，或 Databricks 无法访问 `https:///.well-known/jwks.json`。请从你的网络外部加载该 URL，确认它可公开访问。 | | 令牌已过期 | 方案 B | Devin 身份令牌的有效期为 60 秒。请使用包装脚本，不要手动签发令牌。 | | CLI 无法识别 `env-oidc` | 方案 B | 快照中的 CLI 版本过旧 (或装有旧版 Python `databricks-cli` package) 。请从蓝图中移除旧 package 并重建。 | | 已通过身份验证，但 `catalogs list` 为空或查询被拒绝 | 两者 | 主体已通过身份验证，但未获授权。使用 `databricks grants get catalog ` 检查 workspace 分配 (步骤 1) 和 Unity Catalog 授权 (步骤 3) 。 | | 连接超时或 DNS 故障 | 两者 | Devin 无法访问该 workspace 主机。请将其 (以及必要时的 account 主机) 添加到你的 Devin [网络策略](/zh/product-guides/security-profiles)中。 |
## 支持
Databricks 侧的设置 (service principal、OAuth secrets、联合策略、Unity Catalog) 请参阅 [Databricks 身份验证文档](https://docs.databricks.com/aws/en/dev-tools/auth/) (可按需切换到 Azure 或 GCP 版本) 。Devin 侧的设置 (蓝图、OIDC、plugin、网络策略) 请联系 [support@cognition.ai](mailto:support@cognition.ai) 或你的账户团队。