为 Azure Databricks Git 文件夹 (Repos) 设置专用 Git 连接

了解并配置适用于 Databricks Git 文件夹的 Git 服务器代理，这是一种可配置的服务，可用于将 Databricks 工作区 Git 文件夹中的 Git 命令代理到 GitHub Enterprise Server、Azure DevOps Server、Bitbucket Server 和 GitLab 自管理服务的本地存储库。

什么是适用于 Databricks Git 文件夹的 Git 服务器代理？

适用于 Databricks Git 文件夹的 Git 服务器代理是一项功能，可用于将 Git 命令从 Azure Databricks 工作区代理到你管理的本地 Git 存储库。

Databricks Git 文件夹（旧称 Repos）将连接的 Git 存储库表示为文件夹。 这些文件夹的内容通过将它们同步到连接的 Git 存储库进行版本控制。 默认情况下，Git 文件夹只能与公共 Git 提供程序（如公共 GitHub、GitLab、Azure DevOps 等）同步。 但是，如果你托管自己的本地 Git 服务器（如 GitHub Enterprise Server、Bitbucket Server 或 GitLab 自管理），则必须将 Git 服务器代理与 Git 文件夹配合使用，才能提供对 Git 服务器的 Databricks 访问权限。 必须可以从 Azure Databricks 数据平面（驱动程序节点）访问你的 Git 服务器。

适用于 Databricks Git 文件夹的 Git 服务器代理如何工作？

适用于 Databricks Git 文件夹的 Git 服务器代理会从 Databricks 控制平面将 Git 命令代理到在 Databricks 工作区计算平面中运行的“代理群集”。 在此上下文中，代理群集是一个群集，配置为从 Databricks Git 文件夹到自承载 Git 存储库的 Git 命令运行代理服务。 此代理服务从 Databricks 控制平面接收 Git 命令，并将其转发到 Git 服务器实例。

下图演示了整个系统体系结构：

目前，Git 服务器代理不再需要所有用户具备 CAN_ATTACH_TO 权限。 具有现有代理群集的管理员现在可修改群集 ACL 权限来启用此功能。 若要启用：

1. 从边栏中选择“计算”，然后单击正在运行的 Git 服务器代理的计算条目旁边的 kebab 菜单：

   

2. 在对话框中，删除“所有用户”的“可附加到”条目：

   

如何设置适用于 Databricks Git 文件夹的 Git 服务器代理？

本部分介绍了如何为适用于 Databricks Git 文件夹的 Git 服务器代理准备 Git 服务器实例、创建代理并验证配置。

开始之前

在启用代理之前，请考虑以下先决条件和规划任务：

• 工作区已启用 Databricks Git 文件夹功能。
• 可从 Azure Databricks 工作区的计算平面 VPC 访问 Git 服务器实例，且实例已启用 HTTPS 和个人访问令牌 (PAT)。

步骤 1：准备 Git 服务器实例

要配置 Git 服务器实例，请执行以下操作：

1. 为代理群集的驱动程序节点授予 Git 服务器访问权限。

   你的企业 Git 服务器可以拥有 allowlist IP 地址，可通过这些地址进行访问。

   1. 为源自代理群集的流量关联静态出站 IP 地址。 为此，可以使用 Azure 防火墙或出口设备。
   2. 将上一步中的 IP 地址添加到 Git 服务器的允许列表。

2. 设置 Git 服务器实例以允许 HTTPS 传输。

   • 对于 GitHub Enterprise，请参阅 GitHub Enterprise 帮助中的应使用哪个远程 URL。
   • 对于 Bitbucket，请转到 Bitbucket 服务器管理页并选择服务器设置。 在“HTTP(S) SCM 托管”部分中，启用已启用 HTTP(S) 复选框。

步骤 2：运行启用笔记本

要启用代理，请执行以下命令：

1. 以工作区管理员（有权创建群集）身份登录到 Azure Databricks 工作区。

2. 导入此笔记本，它会选择云提供商提供的最小实例类型来运行 Git 代理：

   笔记本：启用适用于 Databricks Git 文件夹的 Git 服务器代理以在 Git 文件夹中建立专用 Git 服务器连接。

3. 单击“全部运行”以运行笔记本，该笔记本执行以下任务：

   • 创建名为“Repos Git 代理”的单节点计算资源，该资源不会自动终止。 这是要处理 Git 命令并将其从 Azure Databricks 工作区转发到本地 Git 服务器的“Git 代理服务”。
   • 启用功能标记，该标记控制 Databricks Git 文件夹中的 Git 请求是否通过计算实例进行代理。

   作为最佳做法，请考虑创建一个简单的作业来运行 Git 代理计算资源。 这可以是对状态（例如“Git 代理服务正在运行”）进行打印或记录的一个简单笔记本。请将作业设置为定期运行，以确保 Git 代理服务始终可供用户使用。

步骤 3：验证 Git 服务器配置

要验证 Git 服务器配置，请尝试通过代理群集克隆托管在专用 Git 服务器上的存储库。 克隆成功意味着你已成功为你的工作区启用 Git 服务器代理。

步骤 4：创建启用了代理的存储库

用户配置其 Git 凭据后，无需执行进一步的步骤来创建或同步存储库。 要在 Databricks Git 文件夹中配置凭据和创建存储库，请参阅配置 Git 凭据并将远程存储库连接到 Azure Databricks。

删除全局 CAN_ATTACH_TO 权限

具有现有代理群集的管理员现在可以修改群集 ACL 权限，以利用正式发布版 Git 服务器代理行为。

如果以前使用 CAN_ATTACH_TO 权限配置了 Databricks Git 服务器代理，请使用以下步骤删除这些权限：

1. 从边栏中选择“计算”，然后单击正在运行的 Git 服务器代理的计算条目旁边的 kebab 菜单：

   

2. 在对话框中，删除“所有用户”的“可附加到”条目：

   

故障排除

是否在配置适用于 Databricks Git 文件夹的 Git 服务器代理时遇到错误？ 下面是一些常见问题和更有效地诊断它们的方法。

常见问题清单

在开始诊断错误之前，请确认已完成以下步骤：

• 确认代理群集正在运行。
• 确认你是工作区管理员。
• 再次运行支持笔记本并捕获结果（如果尚未）。 如果无法调试问题，Databricks 支持部门可以审查结果。 你可以将启用笔记本导出并作为 DBC 存档发送。

更改 Git 代理配置

如果 Git 代理服务无法使用默认配置，则你可以设置特定的环境变量来更改默认配置，以便更好地支持网络基础结构。

使用下列环境变量更新 Git 代理服务的配置：

环境变量	格式	说明
GIT_PROXY_ENABLE_SSL_VERIFICATION	true/false	如果将自签名证书用于专用 Git 服务器，请将此设置为 false。
GIT_PROXY_CA_CERT_PATH	文件路径（字符串）	将此设置为 SSL 验证所用 CA 证书文件的路径。 示例： /FileStore/myCA.pem
GIT_PROXY_HTTP_PROXY	https://<hostname>:<port #>	将此项设置为 HTTP 流量的网络防火墙代理的 HTTPS URL。
GIT_PROXY_CUSTOM_HTTP_PORT	端口号（整数）	将此设置为分配给 Git 服务器的 HTTP 端口的端口号。

若要设置这些环境变量，请前往 Azure Databricks 工作区中的“计算”选项卡，然后选择 Git 代理服务的计算配置。 在“配置”窗格底部，展开“高级选项”，然后选择“Spark”选项卡。 将一个或多个环境变量添加到“环境变量”文本区域即可设置这些环境变量。

检查代理群集上的日志

代理群集上/databricks/git-proxy/git-proxy.log的文件包含可用于调试的日志。

日志文件应以行“Data-plane proxy server binding to ('', 8000)…”开头，否则，这意味着代理服务器未正确启动。 请尝试重启群集，或删除已创建的群集，然后再次运行启用笔记本。

如果日志文件不以此行开头，请查看 Databricks Git 文件夹中 Git 操作启动的每个 Git 请求之后的日志语句。

例如：

  do_GET: https://server-address/path/to/repo/info/refs?service=git-upload-pack 10.139.0.25 - - [09/Jun/2021 06:53:02] /
  "GET /server-address/path/to/repo/info/refs?service=git-upload-pack HTTP/1.1" 200`

写入此文件的错误日志可帮助你或 Databricks 支持团队调试问题。

常见错误消息及其解决方法

• 由于 SSL 问题，无法建立安全连接

  你可能会看到以下错误：

    https://git.consult-prodigy.com/Prodigy/databricks_test: Secure connection to https://git.consult-prodigy.com/Prodigy/databricks_test could not be established because of SLL problems
  

  这通常意味着你使用的是需要特殊 SSL 证书的存储库。 检查代理群集上“/databricks/git-proxy/git-proxy.log”文件的内容。 如果它告知证书验证失败，则必须将证书颁发机构添加到系统证书链。 首先，提取根证书（使用浏览器或其他选项），并将其上传到 DBFS。 然后，编辑“Git 文件夹 Git 代理”群集，以使用 GIT_PROXY_CA_CERT_PATH 环境变量指向根证书文件。 关于编辑群集环境变量的详细信息，请参阅环境变量。

  完成此步骤后，重启群集。

• 未能克隆存储库并收到错误“缺少/无效 Git 凭据”

  首先，检查是否已在“用户设置”中配置 Git 凭据。

  在以下情况下，你可能会遇到此错误：

    Error: Invalid Git credentials. Go to User Settings -> Git Integration and check that your personal access token or app password has the correct repo access.
  

  如果组织使用了 SAML SSO，请确保令牌已获得授权（可通过 Git 服务器的个人访问令牌 (PAT) 管理页授权）。

常见问题解答

Git 服务器代理的安全影响是什么?

要了解的最重要事项包括：

• 代理不会影响 Databricks 控制平面的安全体系结构。
• 每个工作区只能有一个 Git 代理服务器群集。

所有与 Databricks Git 文件夹相关的 Git 流量是否都通过代理群集路由，即使是针对公共 Git 存储库?

是的。 在当前版本中，Azure Databricks 工作区不区分代理存储库和非代理存储库。

Git 代理功能是否适用于其他 Git 企业服务器提供程序?

Databricks Git 文件夹支持 GitHub Enterprise、Bitbucket Server、Azure Repos Server 和 GitLab 自主管理。 如果其他企业 Git 服务器提供程序符合常见的 Git 规范，则它们应该也可以正常工作。

Databricks Git 文件夹是否支持提交 GPG 签名？

否。

Databricks Git 文件夹是否支持将 SSH 传输用于 Git 操作?

否。 仅支持 HTTPS。

是否支持在 Git 服务器上使用非默认 HTTPS 端口?

目前，启用笔记本假定 Git 服务器使用默认 HTTPS 端口 443。 可以设置环境变量 GIT_PROXY_CUSTOM_HTTP_PORT 以使用首选值覆盖端口值。

多个工作区是否可以共享一个代理，或者每个工作区都需要一个代理群集?

每个 Azure Databricks 工作区都需要一个代理群集。

代理是否适用于旧版单笔记本版本控制?

否，该代理不适用于旧版单笔记本版本控制。 用户必须迁移到 Databricks Git 文件夹版本控制。

Databricks 是否可以隐藏代理的 Git 服务器 URL? 用户是否可以输入原始 Git 服务器 URL 而不是代理 URL?

两个问题的答案都是“是”。 用户不需要针对代理调整自己的行为。 使用当前代理实现时，Databricks Git 文件夹的所有 Git 流量都通过代理进行路由。 用户输入正常的 Git 存储库 URL，例如 https://git.company.com/org/repo-name.git。

用户使用 Git URL 的频率如何?

通常，用户仅在创建新的存储库时，或在签出尚未签出的现有存储库时，添加 Git URL。

该功能是否以透明方式将身份验证数据代理到 Git 服务器?

是的，该代理使用用户帐户的 Git 服务器令牌向 Git 服务器进行身份验证。

是否有 Databricks 访问 Git 服务器代码?

Azure Databricks 代理服务使用用户提供的凭据访问 Git 服务器上的 Git 存储库，并将存储库中的任何代码文件与存储库同步。 访问权限受用户提供的个人访问令牌 (PAT) 中指定的权限限制。