建置垃圾回收

雖然 docker builder prune 或 docker buildx prune 指令是手動執行，但垃圾回收 (GC) 是定期運作的，並遵循一系列有序的刪除策略。當快取大小過大或快取過期時，BuildKit 常駐程式會清除建置快取。

對於大多數使用者而言，預設的 GC 行為已足夠，無需任何介入。進階使用者，特別是那些進行大規模建置、使用自我管理建置器或儲存空間受限的使用者，可能透過自訂這些設定來更符合其工作流程需求，從中獲益。以下章節說明 GC 的運作方式，並提供透過自訂配置來調整其行為的指引。

垃圾回收策略

GC 策略定義了一組規則，決定如何管理與清理建置快取。這些策略包含何時刪除快取項目的標準，例如快取存留時間、已用空間大小以及要刪除的快取記錄類型。

每個 GC 策略都會按順序進行評估，從最明確的標準開始；如果先前的策略無法釋放足夠的快取，則會繼續執行更廣泛的規則。這讓 BuildKit 能夠優先處理快取項目，在確保系統維護效能與可用性的同時，保留最有價值的快取。

例如，假設您有以下 GC 策略：

1. 尋找過去 48 小時內未使用的「過時 (stale)」快取記錄，並刪除記錄直到剩下的「過時」快取不超過 5GB。
2. 如果建置快取大小超過 10GB，則刪除記錄直到總快取大小不超過 10GB 為止。

第一條規則更為明確，優先處理過時的快取記錄，並為價值較低的快取類型設定較低的上限。第二條規則則設定了一個適用於任何類型快取記錄的較高硬性限制。透過這些策略，如果您有 11GB 的建置快取，其中：

• 7GB 為「過時」快取
• 4GB 為其他更有價值的快取

GC 掃描會作為第一條策略的一部分刪除 5GB 的過時快取，剩下 6GB，這意味著第二條策略無需再清理任何快取。

預設的 GC 策略（約略為）：

1. 若來自本機目錄或遠端 Git 儲存庫的建置上下文，以及快取掛載 (cache mounts) 已超過 48 小時未使用，則予以刪除，因為這些快取易於重新產生。
2. 刪除建置中超過 60 天未使用的快取。
3. 刪除超過建置快取大小限制的非共享快取。非共享快取記錄是指未被其他資源（通常作為映像層）使用的層 Blob。
4. 刪除任何超過建置快取大小限制的建置快取。

精確的演算法以及配置策略的方法，會根據您使用的建置器類型而略有不同。詳細資訊請參閱配置。

配置

注意

如果您對預設的垃圾回收行為感到滿意，且不需要微調其設定，可以跳過本節。預設配置適用於大多數使用場景，無需額外設定。

根據您使用的建置驅動程式 (build driver)類型，您需要使用不同的設定檔來更改建置器的 GC 設定：

• 如果您使用 Docker Engine 的預設建置器（docker 驅動程式），請使用 Docker 常駐程式設定檔。
• 如果您使用自訂建置器，請使用 BuildKit 設定檔。

Docker 常駐程式 (Daemon) 設定檔

如果您使用的是預設的 docker 驅動程式，GC 是在 daemon.json 設定檔中進行配置；如果您使用 Docker Desktop，則在 設定 > Docker Engine 中進行。

以下程式碼片段顯示了 Docker Desktop 使用者的 docker 驅動程式預設建置器配置：

{
  "builder": {
    "gc": {
      "defaultKeepStorage": "20GB",
      "enabled": true
    }
  }
}

defaultKeepStorage 選項設定了建置快取的大小限制，這會影響 GC 策略。docker 驅動程式的預設策略運作方式如下：

1. 如果短暫且未使用的建置快取超過 defaultKeepStorage 的 13.8%（或至少 512MB），且該快取存留時間超過 48 小時，則予以刪除。
2. 刪除超過 60 天未使用的建置快取。
3. 刪除超過 defaultKeepStorage 限制的非共享建置快取。
4. 刪除任何超過 defaultKeepStorage 限制的建置快取。

鑑於 Docker Desktop 的 defaultKeepStorage 預設值為 20GB，預設的 GC 策略解析如下：

{
  "builder": {
    "gc": {
      "enabled": true,
      "policy": [
        {
          "keepStorage": "2.764GB",
          "filter": [
            "unused-for=48h",
            "type==source.local,type==exec.cachemount,type==source.git.checkout"
          ]
        },
        { "keepStorage": "20GB", "filter": ["unused-for=1440h"] },
        { "keepStorage": "20GB" },
        { "keepStorage": "20GB", "all": true }
      ]
    }
  }
}

調整 docker 驅動程式建置快取配置最簡單的方法是調整 defaultKeepStorage 選項：

• 如果您認為 GC 過於激進，請增加該限制。
• 如果您需要節省空間，請減少該限制。

如果您需要更多控制權，可以直接定義您自己的 GC 策略。以下範例定義了一個較為保守的 GC 配置，包含以下策略：

1. 如果建置快取超過 50GB，則刪除超過 1440 小時（即 60 天）未使用的快取記錄。
2. 如果建置快取超過 50GB，則刪除未共享的快取記錄。
3. 如果建置快取超過 100GB，則刪除任何快取記錄。

{
  "builder": {
    "gc": {
      "enabled": true,
      "defaultKeepStorage": "50GB",
      "policy": [
        { "keepStorage": "0", "filter": ["unused-for=1440h"] },
        { "keepStorage": "0" },
        { "keepStorage": "100GB", "all": true }
      ]
    }
  }
}

此處策略 1 和 2 將 keepStorage 設定為 0，這意味著它們將回退到 defaultKeepStorage 所定義的 50GB 預設限制。

BuildKit 設定檔

對於 docker 以外的建置驅動程式，GC 是使用 buildkitd.toml 設定檔進行配置。該檔案使用以下高階配置選項，您可以藉此調整 BuildKit 應使用多少磁碟空間作為快取的閾值：

您可以將這些選項設定為位元組數、單位字串（例如 512MB）或總磁碟大小的百分比。更改這些選項會影響 BuildKit 工作執行緒使用的預設 GC 策略。在預設閾值下，GC 策略解析如下：

# Global defaults
[worker.oci]
  gc = true
  reservedSpace = "10GB"
  maxUsedSpace = "100GB"
  minFreeSpace = "20%"

# Policy 1
[[worker.oci.gcpolicy]]
  filters = [ "type==source.local", "type==exec.cachemount", "type==source.git.checkout" ]
  keepDuration = "48h"
  maxUsedSpace = "512MB"

# Policy 2
[[worker.oci.gcpolicy]]
  keepDuration = "1440h" # 60 days
  reservedSpace = "10GB"
  maxUsedSpace = "100GB"

# Policy 3
[[worker.oci.gcpolicy]]
  reservedSpace = "10GB"
  maxUsedSpace = "100GB"

# Policy 4
[[worker.oci.gcpolicy]]
  all = true
  reservedSpace = "10GB"
  maxUsedSpace = "100GB"

實際而言，這意味著：

• 策略 1：如果建置快取超過 512MB，BuildKit 會刪除過去 48 小時內未使用的本機建置上下文、遠端 Git 上下文和快取掛載的快取記錄。
• 策略 2：如果磁碟使用量超過 100GB，則會刪除超過 60 天未使用的非共享建置快取，確保至少有 10GB 的磁碟空間保留給快取。
• 策略 3：如果磁碟使用量超過 100GB，則會刪除任何非共享快取，確保至少有 10GB 的磁碟空間保留給快取。
• 策略 4：如果磁碟使用量超過 100GB，則會刪除所有快取（包括共享記錄和內部記錄），確保至少有 10GB 的磁碟空間保留給快取。

reservedSpace 在定義建置快取大小的下限時具有最高優先級。如果 maxUsedSpace 或 minFreeSpace 定義的值較低，快取的最小大小永遠不會低於 reservedSpace。

如果同時設定了 reservedSpace 和 maxUsedSpace，GC 掃描的結果會使快取大小落在這兩個閾值之間。例如，如果 reservedSpace 設定為 10GB，且 maxUsedSpace 設定為 20GB，則 GC 執行後得到的快取大小將小於 20GB，但至少為 10GB。

您也可以定義完全自訂的 GC 策略。自訂策略還允許您定義篩選器，讓您能精確指定給定策略允許刪除的快取記錄類型。

BuildKit 中的自訂 GC 策略

自訂 GC 策略讓您能夠微調 BuildKit 管理其快取的方式，並能完全控制基於快取類型、持續時間或磁碟空間閾值的快取保留。如果您需要完全控制快取閾值以及快取記錄應如何優先排序，定義自訂 GC 策略是最佳途徑。

若要定義自訂 GC 策略，請在 buildkitd.toml 中使用 [[worker.oci.gcpolicy]] 配置區塊。每個策略都定義了該策略將使用的閾值。如果您使用自訂策略，reservedSpace、maxUsedSpace 和 minFreeSpace 的全域值將不適用。

以下是一個設定範例：

# Custom GC Policy 1: Remove unused local contexts older than 24 hours
[[worker.oci.gcpolicy]]
  filters = ["type==source.local"]
  keepDuration = "24h"
  reservedSpace = "5GB"
  maxUsedSpace = "50GB"

# Custom GC Policy 2: Remove remote Git contexts older than 30 days
[[worker.oci.gcpolicy]]
  filters = ["type==source.git.checkout"]
  keepDuration = "720h"
  reservedSpace = "5GB"
  maxUsedSpace = "30GB"

# Custom GC Policy 3: Aggressively clean all cache if disk usage exceeds 90GB
[[worker.oci.gcpolicy]]
  all = true
  reservedSpace = "5GB"
  maxUsedSpace = "90GB"

除了 reservedSpace、maxUsedSpace 和 minFreeSpace 閾值外，定義 GC 策略時您還有兩個額外的配置選項：

• all：預設情況下，BuildKit 會排除某些快取記錄在 GC 期間被刪除。將此選項設定為 true 將允許任何快取記錄被刪除。
• filters：篩選器讓您能夠指定 GC 策略允許刪除的特定快取記錄類型。