使用 Lakehouse 访问跨云数据时，您可以诊断和解决后台元数据刷新、通过跨云互连进行专用互连路由以及 Service Directory 端点解析方面的问题。解决这些问题有助于保持联合表元数据处于最新状态，并恢复私有跨云查询执行。
数据和资源已过时或未更新
Lakehouse 联合目录会根据刷新间隔同步远程云中的元数据。如果目录包含许多资源（共享、架构、命名空间和表），则目录的后台元数据刷新可能需要更长时间。如果上一次刷新超时，则系统会跳过当前刷新，并在下一个预定时间间隔运行下一次刷新。
如果查询的数据似乎已过时，则目录的后台元数据刷新可能已超时或失败。如果您在远程云中删除某个资源，则该资源会在下次完成后台元数据刷新时从 Lakehouse 中移除。
在 Google Cloud 控制台的 Lakehouse 页面中，或使用 Google Cloud CLI 查看联合目录的后台元数据刷新状态：
gcloud biglake iceberg catalogs describe FEDERATED_CATALOG_NAME \ --project="PROJECT_ID" gcloud biglake delta-sharing catalogs describe FEDERATED_CATALOG_NAME \ --project="PROJECT_ID"
AWS Glue Data Catalog 问题排查
如果您在 Lakehouse 运行时目录中的 AWS Glue 联合目录上配置 --metadata-service-directory-name 后，后台元数据刷新失败，请检查以下内容：
- 验证 Private Catalog 端点映射：确认用于后台元数据刷新的混合连接性网络端点组 (NEG) 或 Service Directory 端点指向 AWS Glue 接口 VPC 端点 (
com.amazonaws.AWS_REGION.glue) 的私有 IP 地址（在 TCP 端口443上），而不是指向 Amazon S3 接口 VPC 端点。 - 验证 IAM 角色信任政策和权限：确认您的 Amazon Web Services (AWS) IAM 角色信任政策允许目录的Google Cloud 服务账号 (
biglake-service-account) 担任该角色 (sts:AssumeRoleWithWebIdentity)，并且该角色有权读取您的 AWS Glue 数据库和表元数据（glue:GetDatabase、glue:GetDatabases、glue:GetTable、glue:GetTables）。 - 检查 VPC 端点安全组规则：确认附加到 AWS Glue 接口 VPC 端点的 AWS 安全组允许来自Google Cloud 虚拟私有云 (VPC) 子网和仅代理子网 CIDR 范围的 TCP 端口
443上的入站 HTTPS 流量。
Databricks Unity Catalog 问题排查
在后台元数据刷新期间，表为空或未被发现
如果目录后台元数据刷新指示完成（例如 Refresh successfully completed），但联合目录中的表未显示或列出表返回 0 项，请检查以下内容：
EXTERNAL USE SCHEMA权限：验证 Databricks 服务主体是否已在 Databricks Unity Catalog 中获得对目标架构或目录的EXTERNAL USE SCHEMA权限。如果没有此权限，后台元数据刷新和查询凭据发放将会失败。- 外部数据访问设置：验证 Databricks Unity Catalog 元存储区上是否已启用外部数据访问。
- 外部位置：验证您的 Databricks Unity Catalog 和表使用的是外部存储位置（例如 Amazon S3、Microsoft Azure Data Lake Storage Gen2 或 Cloud Storage），而不是默认存储。
通过跨云互连进行的后台元数据刷新失败
如果在 Lakehouse 运行时目录中为 Databricks Unity Catalog 配置了 --metadata-service-directory-name，但后台元数据刷新失败，请验证以下内容：
- 工作区专用端点目标：确认您的元数据 Service Directory 端点或内部区域代理网络负载均衡器后端以 Databricks 工作区 AWS PrivateLink 接口端点或 Azure 专用端点的专用 IP 地址（TCP 端口
443）为目标，而不是以远程存储端点为目标，并且--unity-instance-name与您的工作区主机名匹配。 - Workspace 专用访问权限设置：如果您的 Databricks 工作区强制执行专用访问权限设置或 IP 访问权限列表，请验证是否允许通过专用端点从 Google CloudVPC 网络传入的请求。
Snowflake Horizon Catalog 问题排查
后台元数据刷新失败，并显示代码 16（未经身份验证）
如果 Snowflake Horizon Catalog 的后台元数据刷新失败，并显示状态 Code 16 (UNAUTHENTICATED)，请验证以下内容：
- Secret 载荷格式设置：确保 Secret Manager 中的 Secret 令牌包含所需的 JSON 结构 (
{"client_secret": "SNOWFLAKE_PAT_TOKEN", "scope": "session:role:SNOWFLAKE_ROLE"})，而不是原始程序化访问令牌 (PAT) 字符串。 - 令牌过期和权限：验证 Snowflake PAT 是否有效，以及关联的用户和角色是否有权读取目标目录和数据库。
- PrivateLink 或 Private Link 账号标识符：如果您将
--metadata-service-directory-name配置为使用 AWS PrivateLink 或 Azure Private Link 通过跨云互连同步元数据，请验证--snowflake-account-identifier指定的是您的 Snowflake.privatelink账号标识符（例如myorg-myaccount.privatelink），而不是您的公共账号标识符。 - 网络政策：如果后台元数据刷新通过公共互联网连接，并且 Snowflake 网络政策处于有效状态，请验证 Google 的出站流量 IP 地址范围（来自
goog.json）是否包含在网络政策的允许 IP 列表中。
通过跨云互连进行的后台元数据刷新失败
如果在 Lakehouse 运行时目录中为 Snowflake Horizon Catalog 配置了 --metadata-service-directory-name，但后台元数据刷新失败，请验证以下内容：
- Snowflake 专用端点目标：确认您的元数据 Service Directory 端点或内部区域级代理网络负载均衡器后端指向 Snowflake AWS PrivateLink 接口端点或 Azure 专用端点在 TCP 端口
443上的专用 IP 地址，而不是远程对象存储区端点。 - 私有账号标识符：确认
--snowflake-account-identifier使用您的.privatelink账号标识符（例如myorg-myaccount.privatelink）。
连接性或路由问题
如果您在通过跨云互连路由流量时遇到查询传输或后台元数据刷新失败，请验证以下内容：
- 验证路由传播：检查Google Cloud 中的 Cloud Router 路由器，验证它是否已获知您的 AWS VPC 或 Azure 虚拟网络 (VNet) 前缀。检查您的 AWS 或 Azure 路由表，验证它们是否具有返回 Google CloudVPC 网络的路由。如果您使用内部区域级代理网络负载均衡器，请验证 Cloud Router 是否通过自定义 BGP 路由通告来通告代理专用子网 CIDR 范围。
- 检查内部负载均衡器的健康状况：在 Google Cloud 控制台中，前往网络服务 > 负载均衡，验证传输和元数据后端服务的混合连接网络端点组 (NEG) 后端是否运行正常。如果后端运行状况不佳，请检查专用互连连接和远程安全规则。
- 测试连接性 Google Cloud：在与内部负载均衡器或 Service Directory 端点相同的 Google Cloud VPC 网络和子网中创建测试虚拟机实例，并测试与 TCP 端口
443上的 AWS 弹性网络接口 (ENI) 或 Azure 专用端点网络接口 (NIC) IP 地址的连接（例如，使用curl或nc）。 - 验证 Service Directory 配置和权限：确认在
--service-directory-name（用于查询传输）和--metadata-service-directory-name（用于后台元数据刷新）中配置的 Service Directory 服务与联合目录位于同一 Google Cloud 区域。如果目录刷新失败并显示Permission 'servicedirectory.services.resolve' denied错误，请验证目录的唯一服务账号 ID（biglake-service-account字段）在托管 Service Directory 服务的每个项目上是否具有roles/servicedirectory.viewer和roles/servicedirectory.pscAuthorizedService角色。 - 检查安全群组和防火墙规则：验证Google Cloud 防火墙规则、AWS 安全群组和 Azure 网络安全群组 (NSG) 是否允许在 Google Cloud VPC CIDR 范围（包括任何代理专用子网 CIDR 范围）与远程专用端点之间通过端口
443传输 TCP 流量。