诊断和修复 LookML 项目中的 Git 问题

Looker 项目依赖于稳定的 Git 配置（例如远程仓库连接、有效的部署密钥、完整的代码库结构和正确的文件系统权限）。如果出现 Git 问题，开发者和管理员可以使用诊断和修复工具来测试代码库的健康状况、确定根本原因并运行自动修复。

诊断和修复工具可在您的个人开发环境或共享生产环境中，通过八项诊断测试检查来评估您的 LookML 项目代码库。发现问题后，Looker 可以自动执行精细修复（例如移除过时的锁定文件、修复文件权限或修复损坏的对象索引），或者在专用恢复分支上保护未提交的更改，同时重建损坏的代码库。

前提条件和权限

如需使用 Git 诊断和修复工具，您必须满足以下权限要求：

  • 开发者环境：需要拥有项目中至少一个模型的 develop 权限。
  • 生产环境：需要拥有项目中至少一个模型的 deploy 权限。

运行 Git 诊断

如需诊断 LookML 项目，请按以下步骤操作：

  1. 启用开发模式。
  2. 在导航面板中选择开发以打开开发面板。
  3. 在开发面板中，选择项目以显示 LookML 项目页面。
  4. 打开要诊断的项目。
  5. 从 Looker IDE 图标菜单中选择设置图标。
  6. 在 Git 诊断和修复部分中，点击诊断和修复。

  7. 在诊断和修复对话框中，选择要测试的环境：

    “诊断和修复”对话框，其中“开发环境”处于选中状态。

    • 开发：测试 Git 代码库的个人开发者副本。
    • 生产：测试 Git 代码库的生产版本。

  8. 点击诊断。

Looker 会启动诊断测试套件，并在对话框中实时显示每项测试检查的进度。

显示运行的测试和测试结果的 Git 诊断报告。

了解诊断结果

诊断测试套件运行时，每项检查都会报告以下状态之一：

状态徽章 含义 需采取行动
未检测到 诊断检查已通过，未发现任何问题。 您无需执行任何操作。
检测到 系统在代码库或连接中发现了问题或不一致之处。 运行自动修复（如果可用），或按照手动解决步骤操作。
已修复 自动化修复流程已成功解决问题。 无需采取进一步行动。
失败 自动修复尝试无法解决问题，或者检查需要人工干预。 查看问题详情，然后按照手动修复程序操作。

运行自动修复

如果任何诊断检查返回“检测到”状态，且支持自动修复，您可以直接从对话框中开始修复：

  1. 在诊断和修复对话框中，点击开始修复按钮。
  2. Looker 会针对所有可修复的问题应用自动修复。
  3. 修复过程完成后，状态标记会更新为已修复（对于已解决的检查）或失败（如果需要人工干预）。

诊断检查和修复参考

诊断测试套件会评估八类 Git 问题。下表介绍了每项检查、诊断结果以及执行的补救措施：

诊断检查 说明 维修类型 补救措施
Git 设置 验证项目是否具备初始化其代码库所需的先决条件（已配置的远程 Git 源网址和有效的数据库配置记录）。 手动 如果缺少必需的值，请在项目设置中完成初始 Git 配置（设置 > 配置 > 配置 Git）。如需了解详情，请参阅解决 Git 设置问题部分。
Git 连接测试 针对远程源代码库运行 Looker 的标准 Git 连接测试套件，验证凭据、网络可达性和远程访问权限。 手动 连接失败是由外部因素（例如 SSH 部署密钥过期、OAuth 或个人访问令牌被撤消、防火墙限制或提供商中断）造成的。直接与 Git 提供商解决凭据或网络问题。如需了解详情，请参阅解决 Git 连接测试问题部分。
文件系统访问权限 检测到文件系统 I/O 或存储错误，导致 Looker 无法读取项目代码库中的目录列表或文件名。 自动 从头开始重建项目代码库的干净副本。将旧目录归档到安全备份中，并将未提交的工作保存到远程恢复分支中。
代码库运行状态 检查内部 .git 结构是否存在且完整，并验证 Git 是否将该目录识别为正常的工作树。 自动 从头开始重建项目代码库，恢复正常的 Git 目录结构，同时归档之前的内容以防止数据丢失。
Git 锁定文件 扫描因中断或终止的 Git 操作而遗留的过时 .lock 文件（例如索引或配置锁定），这些文件会阻止后续 Git 命令。 自动 立即安全地移除过时的锁定文件，解除对 Git 操作的阻塞，而不会更改代码库历史记录或工作文件。
对象权限 扫描项目文件和目录，查找偏离建议的安全和运营标准的文件系统权限（例如，确保目录和脚本具有读取和执行访问权限，而标准文件保持不可执行状态）。 自动 自动规范化整个项目中的文件和目录权限，恢复安全标准权限，而不会修改文件内容。
Git 配置设置 检查代码库的内部 Git 配置是否与 Looker 的必需默认设置相符（具体来说，验证文件模式跟踪 core.filemode 是否已停用，以避免文件系统之间的权限差异生成虚假更改）。 自动 更新了代码库配置以匹配 Looker 默认设置，并保存了更新后的配置。
代码库一致性 FSCK 运行 Git 文件系统检查 (git fsck)，以检查代码库的内部对象数据库是否存在结构性损坏（包括索引文件损坏、提交签名错误、对象指针无效、对象损坏或引用损坏）。 自动 初始修复：重建索引、剪除过时的引用日志、移除损坏的引用，并运行 git fetch --refetch 以检索丢失的对象。
回退重建：如果初始修复无法解决所有错误，则安全地重建代码库，并在远程恢复分支上保留未提交的工作。

解决手动 Git 问题

如果 Git 设置或 Git 连接测试检查到问题，则无法进行自动修复，因为问题源于本地代码库之外。请按照以下准则解决手动问题：

  • 解决 Git 设置问题：

    1. 在 Looker IDE 中打开项目。
    2. 从图标菜单中选择设置图标。
    3. 在配置标签页中，选择重置 Git 连接或配置 Git 以完成代码库设置。如需详细说明，请参阅设置并测试 Git 连接。

  • 解决 Git 连接测试问题：

    • SSH 部署密钥：验证 Looker 中的部署密钥是否与向 Git 托管服务提供商注册的公钥一致，并确保该密钥已启用写入访问权限。如有需要，请在项目设置中生成新的部署密钥，并更新 Git 提供商。
    • HTTPS 凭据和个人访问令牌：检查您的个人访问令牌或服务账号密码是否已过期或被撤消。在 Git 提供商处生成新令牌，并在 Looker 中更新您的凭据。
    • IP 许可名单和防火墙：确保您的 Git 托管服务提供商允许来自 Looker 实例 IP 地址的入站流量。