診斷及修復 LookML 專案中的 Git 問題

Looker 專案需要穩定的 Git 設定 (例如遠端存放區連線、有效的部署金鑰、完整的存放區結構，以及正確的檔案系統權限)。發生 Git 問題時，開發人員和管理員可以使用「診斷與修復」工具測試存放區健康狀態、找出根本原因，並執行自動修復。

「診斷與修復」工具會在個人開發環境或共用正式環境中，透過八項診斷測試檢查評估 LookML 專案存放區。如果發現問題，Looker 可以自動執行精細的修復作業 (例如移除過時的鎖定檔案、修正檔案權限或修復損毀的物件索引)，或重建損毀的存放區，同時在專屬的復原分支上保護未提交的變更。

先決條件和權限

如要使用 Git 診斷與修復工具，必須符合下列權限規定：

  • 開發人員環境：須具備專案中至少一個模型的 develop 權限。
  • 正式環境：專案中至少須有一個模型具備 deploy 權限。

執行 Git 診斷

如要診斷 LookML 專案，請按照下列步驟操作：

  1. 啟用開發模式。
  2. 在導覽面板中選取「開發」，開啟「開發」面板。
  3. 在「開發」面板中選取「專案」，即可顯示「LookML 專案」頁面。
  4. 開啟要診斷的專案。
  5. 從 Looker IDE 圖示選單中選取「設定」圖示。
  6. 在「Git Diagnose and Repair」部分，按一下「Diagnose & Repair」。

  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 位址的連入流量。