go getter

幹將

go-getter 是 Go (golang) 的一個函式庫，用於使用 URL 作為主要輸入形式從各種來源下載檔案或目錄。

該程式庫的強大之處在於能夠靈活地使用單一字串作為輸入從多個不同的來源（檔案路徑、Git、HTTP、Mercurial 等）下載。這消除了實現者了解如何從各種來源下載的負擔。

檢測器的概念會自動將無效 URL 轉換為正確的 URL。例如：「github.com/hashicorp/go-getter」將轉換為 Git URL。或「./foo」會變成一個檔案 URL。這些是可擴展的。

Terraform 使用此程式庫下載模組，Nomad 使用該程式庫下載二進位檔案。

安裝與使用

包文檔可以在 GoDoc 上找到。

可以使用普通的go get來完成安裝：

$ go get github.com/hashicorp/go-getter

go-getter 還有一個可用來測試 URL 字串的指令：

$ go install github.com/hashicorp/go-getter/cmd/go-getter
...

$ go-getter github.com/foo/bar ./foo
...

該命令對於驗證 URL 結構很有用。

安全

從使用者提供的 URL 取得資源本質上是一種危險的操作，可能會使您的應用程式容易受到伺服器端請求偽造、路徑遍歷、拒絕服務或其他安全漏洞的攻擊。

go-getter 包含針對其中一些安全問題的緩解措施，但在安全關鍵環境中仍應謹慎使用。查看可配置以減輕其中一些風險的可用安全選項。

go-getter 可能會傳回包含呼叫者提供的查詢參數的值，這些參數可能包含敏感資料。圍繞哪些參數敏感和不敏感的上下文只有 go-getter 的呼叫者知道，並且特定於每個用例。我們建議呼叫者確保正確處理和清理 go-getter 的回傳值（例如，錯誤訊息），以確保敏感資料不會保留到日誌中。

網址格式

go-getter 使用單一字串 URL 作為輸入來從各種協定下載。 go-getter 有各種「技巧」使用此 URL 來執行某些操作。本節記錄了 URL 格式。

支援的協定和檢測器

協定用於使用特定機制下載檔案/目錄。範例協定有 Git 和 HTTP。

檢測器用於將有效或無效的 URL 轉換為另一個 URL（如果它與特定模式相符）。範例：「github.com/user/repo」會自動轉換為完全有效的 Git URL。這使得 go-getter 變得非常用戶友好。

go-getter 開箱即用，支援以下協定。透過實現Getter接口，可以在運行時增強其他協定。

• 本地文件

• git

• 水銀

• HTTP協定

• 亞馬遜S3

• 谷歌GCP

除了上述協議之外，go-getter 還有所謂的「探測器」。它們採用 URL 並嘗試自動為其選擇最佳協議，這甚至可能涉及更改協議。預設內建以下檢測：

• 檔案路徑（例如“./foo”）會自動變更為絕對文件 URL。

• GitHub URL（例如「github.com/mitchellh/vagrant」）會自動變更為基於 HTTP 的 Git 協定。

• GitLab URL（例如「gitlab.com/inkscape/inkscape」）會自動變更為基於 HTTP 的 Git 協定。

• BitBucket URL（例如「bitbucket.org/mitchellh/vagrant」）會使用 BitBucket API 自動變更為 Git 或 Mercurial 協定。

強制協議

在某些情況下，根據來源 URL，要使用的協定是不明確的。例如，「http://github.com/mitchellh/vagrant.git」可以引用 HTTP URL 或 Git URL。強制協定語法用於消除此 URL 的歧義。

可以透過在 URL 前面加上協議前綴併後跟雙冒號來完成強制協議。例如： git::http://github.com/mitchellh/vagrant.git將使用 Git 協定下載給定的 HTTP URL。

強制協議也將覆蓋任何檢測器。

在沒有強制協定的情況下，偵測器可以在 URL 上運行，無論如何都會轉換協定。無論哪種方式，上面的範例都會使用 Git 協議，因為 Git 偵測器會偵測到它是 GitHub URL。

協定特定選項

每個協定都可以支援特定於協定的選項來配置該協定。例如， git協定支援指定ref查詢參數，告訴它要為該 Git 儲存庫簽出什麼參考。

這些選項被指定為提供給 go-getter 的 URL（或類似 URL 的字串）上的查詢參數。使用上面的 Git 範例，下面的 URL 是 go-getter 的有效輸入：

github.com/hashicorp/go-getter?ref=abcd1234

特定於協定的選項記錄在 URL 格式部分下方。但因為它們是 URL 的一部分，所以我們在這裡指出它們，以便您知道它們的存在。

子目錄

如果只想從下載目錄下載特定子目錄，可以在雙斜線//後指定子目錄。 go-getter 會先下載雙斜線之前指定的 URL（就好像您沒有指定雙斜線一樣），但隨後會將雙斜線之後的路徑複製到目標目錄中。

例如，如果您正在下載此 GitHub 儲存庫，但只想下載testdata目錄，則可以執行以下操作：

https://github.com/hashicorp/go-getter.git//testdata

如果您將其下載到/tmp目錄，則檔案/tmp/archive.gz將存在。請注意，該檔案位於此儲存庫的testdata目錄中，但因為我們指定了一個子目錄，所以 go-getter 僅會自動複製該目錄內容。

子目錄路徑也可以使用檔案系統 glob 模式。該路徑必須與一個條目完全匹配，否則 go-getter 將返回錯誤。如果您不確定確切的目錄名稱，但它遵循可預測的命名結構，這非常有用。

例如，以下 URL 也可以運作：

https://github.com/hashicorp/go-getter.git//test-*

校驗和

對於任何協議的文件下載，go-getter 都可以自動為您驗證校驗和。請注意，校驗和僅適用於下載文件，不適用於目錄，但校驗和適用於任何協議。

若要對文件進行校驗和，請將checksum查詢參數附加到 URL。 go-getter 會自動解析出這個查詢參數並用它來驗證校驗和。參數值的格式可以為type:value或value ，其中 type 為 "md5"、"sha1"、"sha256"、"sha512" 或 "file" 。 「值」應該是「檔案」的實際校驗和值或下載 URL。當省略type部分時，將根據校驗和字串的長度猜測類型。範例：

./foo.txt?checksum=md5:b7d96c89d09d9e204f5fedc4d5d55b21

./foo.txt?checksum=b7d96c89d09d9e204f5fedc4d5d55b21

./foo.txt?checksum=file:./foo.txt.sha256sum

當從檔案中進行校驗和時 - 例如：使用checksum=file:url - go-getter 將使用相同的配置在file:之後取得 URL 中連結的檔案。例如，在file:http://releases.ubuntu.com/cosmic/MD5SUMS中，go-getter 將使用 http 協定在上述 url 下載校驗和檔案。 go-getter 支援的所有協定都可以使用。校驗和檔案將下載到臨時檔案中，然後進行解析。臨時檔案的目的地可以透過設定係統特定的環境變數來更改： TMPDIR for unix; Windows 上的TMP 、 TEMP或USERPROFILE 。有關臨時目錄選擇的更多信息，請閱讀 os.TempDir 的 godoc。文件內容應為 BSD 或 GNU 風格。一旦 go-getter 完成校驗和文件；它被刪除了。

校驗和查詢參數永遠不會傳送到後端協定實作。它被積極進取者本身在更高的層面上使用。

如果目標檔案存在且校驗和匹配：將跳過下載。

取消存檔

go-getter 會根據要求的檔案副檔名（透過任何協定）自動將檔案解檔到檔案或目錄中。這適用於檔案和目錄下載。

go-getter 尋找archive查詢參數來指定存檔的格式。如果未指定，go-getter 將使用路徑的副檔名來查看它是否顯示為已存檔。可以透過將archive查詢參數設為false來明確停用取消存檔。

支援以下存檔格式：

• tar.gz和tgz

• tar.bz2和tbz2

• tar.xz和txz

• zip

• gz

• bz2

• xz

例如，範例 URL 如下所示：

./foo.zip

這將自動推斷為 ZIP 檔案並將被提取。您也可以明確說明存檔類型：

./some/other/path?archive=zip

最後，您可以完全停用歸檔：

./some/path?archive=false

您可以將取消歸檔與 go-getter 的其他功能（例如校驗和）結合。在進入最終協定下載器之前，特殊的archive查詢參數將從 URL 中刪除。

協定特定選項

本節記錄了可以為 go-getter 指定的特定於協定的選項。這些選項應作為普通查詢參數附加到輸入（但是，HTTP 標頭是一個例外）。根據 go-getter 的使用情況，應用程式可能會提供輸入選項的替代方法。例如，Nomad 提供了一個很好的選項區塊來指定選項而不是在 URL 中。

一般（所有協議）

以下選項適用於所有協定：

• archive - 用於取消存檔此文件的存檔格式，或「」（空字串）以停用取消存檔。有關更多詳細信息，請參閱上面有關存檔支援的完整部分。

• checksum - 用於驗證下載的檔案或存檔的校驗和。有關格式和更多詳細信息，請參閱上面有關校驗和的整個部分。

• filename - 當處於檔案下載模式時，允許指定磁碟上下載檔案的名稱。在目錄模式下無效。

本地文件（ file ）

沒有任何

git ( git )

• ref - 要簽出的 Git 引用。這是一個引用，因此它可以指向提交 SHA、分支名稱等。

• sshkey - 在複製期間使用的 SSH 私鑰。提供的密鑰必須是 base64 編碼的字串。例如，要從磁碟上的私鑰檔案產生適當的sshkey ，您可以執行base64 -w0 <file> 。

  注意：使用此功能需要 Git 2.3+。

• depth - Git 克隆深度。提供的編號指定要從儲存庫複製的最後n修訂版。

git getter 接受 URL 樣式的 SSH 位址（如git::ssh://[email protected]/foo/bar ）和「scp 樣式」位址（如git::[email protected]/foo/bar 。在後一種情況下，如果使用者名稱前綴恰好是git@則允許省略git:: force 前綴。

「scp 樣式」位址不能與ssh://方案前綴結合使用，因為在這種情況下，冒號用於標記要連接的可選連接埠號，而不是分隔來自主機的路徑。

汞 ( hg )

• rev - Mercurial 對結帳的修訂。

HTTP（ http ）

基本認證

若要將 HTTP 基本驗證與 go-getter 結合使用，只需在 URL 中的主機名稱前面新增username:password@即可，例如https://Aladdin:[email protected]/index.html 。所有特殊字符，包括使用者名稱和密碼，都必須進行 URL 編碼。

標頭

可以透過在自訂HttpGetter中提供可選請求標頭來新增它們（不像大多數其他選項那樣作為查詢參數）。這些標頭將在相關 getter 發出的每個請求中發送出去。

S3（ s3 ）

S3 在 URL 中採用各種存取配置。請注意，如果已設置，它也會從標準 AWS 環境變數中讀取這些變數。也支援 Minio 等 S3 相容伺服器。如果存在查詢參數，則這些參數優先。

• aws_access_key_id - AWS 存取金鑰。

• aws_access_key_secret - AWS 存取金鑰秘密。

• aws_access_token - AWS 存取權令牌（如果正在使用）。

• aws_profile - 使用本機 ~/.aws/ config 中的此設定檔。優先於其他三者。

將 IAM 實例設定檔與 S3 結合使用

如果您使用 go-getter 並希望使用 EC2 IAM 執行個體設定檔來避免使用憑證，則只需忽略這些設定檔即可，如果可用，將自動使用設定檔。

將 S3 與 Minio 結合使用

如果您使用 go-gitter 來支援 Minio，則必須考慮以下事項：

• aws_access_key_id （必需）- Minio 存取金鑰。

• aws_access_key_secret （必需）- Minio 存取金鑰秘密。

• region （可選 - 預設為 us-east-1） - 要使用的區域識別碼。

• version （可選 - 預設為 Minio 預設值） - 設定檔格式。

S3 儲存桶範例

S3 有多種尋址方案用於引用您的儲存桶。此處列出：https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-bucket-intro.html

這些尋址方案的一些範例：

• s3::https://s3.amazonaws.com/bucket/foo

• s3::https://s3-eu-west-1.amazonaws.com/bucket/foo

• Bucket.s3.amazonaws.com/foo

• Bucket.s3-eu-west-1.amazonaws.com/foo/bar

• “s3::http://127.0.0.1:9000/test-bucket/hello.txt?aws_access_key_id=KEYID&aws_access_key_secret=SECRETKEY&region=us-east-2”

地面站 ( gcs )

地面站認證

為了存取 GCS，應提供身份驗證憑證。更多資訊可以在這裡找到

GCS 桶範例

• gcs::https://www.googleapis.com/storage/v1/bucket

• gcs::https://www.googleapis.com/storage/v1/bucket/foo.zip

• www.googleapis.com/storage/v1/bucket/foo

GCS測試

get_gcs.go的測試要求您在環境中設定 GCP 憑證。 這些憑證可以對任何項目具有任何級別的權限，它們只需要存在。 這表示設定GOOGLE_APPLICATION_CREDENTIALS="~/path/to/credentials.json"或GOOGLE_CREDENTIALS="{stringified-credentials-json}" 。 由於此配置，CircleCI 中的外部貢獻者的get_gcs_test.go將失敗。

安全選項

禁用符號連結

在您的 getter 用戶端配置中，我們建議使用DisableSymlinks選項，該選項可防止寫入或複製符號連結（可能指向目錄外部）。

 client := getter.Client{ // 這將阻止透過符號連結複製或寫入檔案 DisableSymlinks: true,
}

停用或限制X-Terraform-Get

Go-Getter 支援透過X-Terraform-Get標頭進行任意重定向。此功能的存在是為了支援 Terraform 用例，但在大多數應用程式中可能不需要。

對於使用HttpGetter的程式碼，請新增以下設定選項：

 var httpGetter = &getter.HttpGetter{ // 大多數客戶端應該停用X-Terraform-Get // 請參考下面的註解XTerraformGetDisabled: true, // 您的軟體可能不依賴X-Terraform-Get，但// 如果依賴的話，您應該將上述欄位設為 false，加上 // 設定 XTerraformGet Limit 以防止無休止的重定向 // XTerraformGetLimit: 10,}

強制超時

HttpGetter支援逾時和其他資源限製配置選項。 GitGetter和HgGetter僅支援逾時。

HttpGetter的配置：

 var httpGetter = &getter.HttpGetter{ // 停用預取 HEAD 請求 DoNotCheckHeadFirst: true,
        // 作為上述設定的替代方案，您可以為 HEAD 請求設定合理的逾時 // HeadFirstTimeout: 10 * time.Second, // HTTP 操作的讀取逾時 ReadTimeout: 30 * time.Second, // 設定getter 可以讀取取的最大位元組數MaxBytes: 500000000, // 500 MB}

對於使用GitGetter或HgGetter的程式碼，請設定Timeout選項：

 var gitGetter = &getter.GitGetter{ // 為 git 操作設定合理的逾時時間 Timeout: 5 * time.Minute,
}

 var hgGetter = &getter.HgGetter{ // 為 hg 操作設定合理的逾時時間 Timeout: 5 * time.Minute,
}