git 遠端 s3

git-remote-s3

該程式庫允許使用 Amazon S3 作為 git 遠端和 LFS 伺服器。

它提供了 git 遠端幫助程式的實現，以將 S3 用作無伺服器 Git 伺服器。

它還提供了 git-lfs 自訂傳輸的實現，以將 LFS 託管檔案推送到用作遠端的相同 S3 儲存桶。

安裝

git-remote-s3是一個 Python 腳本，適用於任何 >= 3.9 的 Python 版本。

跑步：

 pip install git-remote-s3

先決條件

在使用git-remote-s3之前，您必須：

• 完成初始配置：

  • 建立 AWS 帳戶
  • 配置 IAM 使用者或角色

• 在您的 AWS 帳戶中建立一個 AWS S3 儲存桶（或已有一個）。

• 向該使用者/角色附加一個允許存取 S3 儲存桶的最小策略：

  ", "arn:aws:s3:::*/*"] }">

  {
    "Sid" : " S3Access " ,
    "Effect" : " Allow " ,
    "Action" : [ " s3:PutObject " , " s3:GetObject " , " s3:ListBucket " ],
    "Resource" : [ " arn:aws:s3::: " , " arn:aws:s3:::*/* " ]
  }

• 可選（但建議）- 使用 SSE-KMS 儲存桶金鑰對儲存桶的內容進行加密，確保先前建立的使用者/角色有權存取和使用該金鑰。

::key/"] }">

{
  "Sid" : " KMSAccess " ,
  "Effect" : " Allow " ,
  "Action" : [ " kms:Decrypt " , " kms:GenerateDataKey " ],
  "Resource" : [ " arn:aws:kms:::key/ " ]
}

• 如果尚未安裝 Python 及其套件管理器 pip，請安裝它們。若要下載並安裝最新版本的 Python，請造訪 Python 網站。
• 在 Linux、macOS、Windows 或 Unix 電腦上安裝 Git。
• 在您的 Linux、macOS、Windows 或 Unix 電腦上安裝最新版本的 AWS CLI。您可以在此處找到說明。

安全

資料加密

預設情況下，所有資料在靜態和傳輸過程中都會進行加密。若要新增額外的安全層，您可以使用客戶管理的 KMS 金鑰來加密 S3 儲存桶上的靜態資料。我們建議使用 Bucket 金鑰來最大程度地降低 KMS 成本。

存取控制

透過 IAM 權限確保遠端的存取控制，並且可以在以下位置進行控制：

• 鏟鬥液位
• 前綴等級（您可以使用前綴將多個儲存庫儲存在同一個 S3 儲存桶中，從而最大限度地減少設定工作）
• KMS金鑰級別

使用 S3 遙控器

建立一個新的儲存庫

S3 遠端設備由前綴s3://標識，並且至少指定儲存桶的名稱。您也可以提供金鑰前綴（如s3://my-git-bucket/my-repo和設定檔s3://my-profile@my-git-bucket/myrepo 。

mkdir my-repo
cd my-repo
git init
git remote add origin s3://my-git-bucket/my-repo

然後，您可以新增文件、提交並將變更推送到遠端：

hello.txt git add -A git commit -a -m "hello" git push --set-upstream origin main">

 echo " Hello " > hello.txt
git add -A
git commit -a -m " hello "
git push --set-upstream origin main

遠端 HEAD 設定為追蹤首先推送到遠端儲存庫的分支。若要變更遠端 HEAD 分支，請刪除 HEAD s3:////HEAD ，然後執行git-remote-s3 doctor s3:/// 。

克隆一個倉庫

要將儲存庫複製到另一個資料夾，只需使用正常的 git 語法，並使用 s3 URI 作為遠端：

git clone s3://my-git-bucket/my-repo my-repo-clone

分公司等

建立分支並推送它們可以正常工作：

 cd my-repo
git checkout -b new_branch
touch new_file.txt
git add -A
git commit -a -m " new file "
git push origin new_branch

所有不依賴與伺服器通訊的 git 操作都應該照常工作（例如git merge ）

線性FS

要使用 LFS，您需要先安裝 git-lfs。您可以參考官方文件以了解如何在您的系統上執行此操作。

接下來，您需要透過在 repo 資料夾中執行以下命令來啟用 S3 整合：

lfs-s3-py install

這是以下的捷徑：

git config --add lfs.customtransfer.lfs-s3-py.path lfs-s3-py
git config --add lfs.standalonetransferagent lfs-s3-py

使用範例

建立倉庫並推送

假設我們要在 LFS 中儲存 TIFF 檔案。

git add file.tiff git commit -a -m "my first tiff file" git remote add origin s3://my-git-bucket/lfs-repo git push --set-upstream origin main">

mkdir lfs-repo
cd lfs-repo
git init
git lfs install
lfs-s3-py install
git lfs track " *.tiff "
git add .gitattributes
< put file.tiff in the repo >
git add file.tiff
git commit -a -m " my first tiff file "
git remote add origin s3://my-git-bucket/lfs-repo
git push --set-upstream origin main

有關 Amazon S3 遙控器的特定行為的注意事項

任意 Amazon S3 URI

有效儲存桶的 Amazon S3 URI 和其下方不包含正確結構的任意前綴被視為有效。

git ls-remote傳回一個空列表，並且git clone克隆一個空儲存庫，其中 S3 URI 設定為遠端來源。

 % git clone s3://my-git-bucket/this-is-a-new-repo
Cloning into 'this-is-a-new-repo'...
warning: You appear to have cloned an empty repository.
% cd this-is-a-new-repo
% git remote -v
origin  s3://my-git-bucket/this-is-a-new-repo (fetch)
origin  s3://my-git-bucket/this-is-a-new-repo (push)

提示：此行為可用於快速建立新的 git 儲存庫。

並發寫入

由於git的分散式特性，可能會出現（儘管很少見）不同使用者同時執行 2 個或更多git push情況，並對同一分支進行自己的修改。

git 指令分兩步驟執行推播：

1. 首先，它檢查遠端引用是否是正在推送的提交的正確祖先
2. 如果正確，它將呼叫git-remote-s3命令，該命令將套件寫入refs/heads/路徑處的 S3 儲存桶

如果從不同的客戶端同時執行兩個（或多個） git push命令，則在步驟1 中會取得相同的有效引用，因此兩個客戶端都會繼續步驟2，從而導致多個套件儲存在S3 中。

該分支現在有多個頭引用，任何後續的git push都會失敗並出現錯誤：

 error: dst refspec refs/heads/> matches more than one
error: failed to push some refs to 's3:///'

要解決此問題，請執行git-remote-s3 doctor 命令。預設情況下，它將為每個不應保留的捆綁包建立一個新分支。然後，使用者可以在本地檢出該分支並將其合併到原始分支。如果您想要刪除捆綁包，請指定--delete-bundle 。

克隆儲存庫

當使用 LFS 的 S3 遠端克隆儲存庫時， git-lfs無法知道如何取得文件，因為我們尚未新增配置。

它涉及 2 個額外步驟。

% git clone s3://my-git-bucket/lfs-repo lfs-repo-clone
Error downloading object: file.tiff (54238cf): Smudge error: Error downloading file.tiff (54238cfaaaa42dda05da0e12bf8ee3156763fa35296085ccdef63b13a87837c5): batch request: ssh: Could not resolve hostname s3: Name or service not known: exit status 255
...

修復：

 cd lfs-repo-clone
lfs-s3-py install
git reset --hard main

管理 Amazon S3 遠端

刪除分支

若要刪除不再使用的遠端分支，可以使用git-s3 delete-branch -b 指令。此指令從分支路徑下的 Amazon S3 中刪除捆綁物件。

受保護的分支

若要保護/取消保護分支，請分別執行git s3 protect git s3 unprotect 。

在引擎蓋下

S3 遠距工作原理

捆綁包以//.bundle形式儲存在 S3 儲存桶中。

當列出遠端引用時（例如透過git ls-remote明確列出），我們列出給定 下存在的所有鍵。

當推送新的引用（例如提交）時，我們獲取引用的 sha，我們透過git bundle create .bundle 捆綁引用並根據上面的模式將其儲存到 S3。

如果推送成功，程式碼將刪除與引用關聯的先前套件。

如果兩個使用者同時將基於相同目前分支頭的提交推送到遠端，則兩個捆綁包都將寫入儲存庫，並刪除目前捆綁包。不會遺失任何數據，但除非刪除除一個捆綁包之外的所有捆綁包，否則無法進一步推送。為此，您可以使用git s3 doctor 命令。

LFS 的工作原理

LFS 整合將檔案儲存在由遠端 URI 定義的儲存桶中，位於鍵/lfs/下，其中 oid 是 git-lfs 指派給檔案的唯一識別碼。

如果具有相同金鑰的物件已存在，git-lfs-s3 不會再次上傳它。

偵錯

使用--verbose標誌在執行 git 操作時列印一些偵錯資訊。日誌將被放入 stderr。

對於 LFS 操作，您可以分別透過git-lfs-s3 enable-debug和git-lfs-s3 disable-debug啟用和停用偵錯日誌記錄。日誌放在儲存庫中的.git/lfs/tmp/git-lfs-s3.log中。

製作人員

git S3 整合的靈感來自 Bryan Gahagan 在 git-remote-s3 上的工作。

LFS 的實作受益於 @nicolas-graves 的 lfs-s3。如果您不需要使用 git-remote-s3 傳輸，則應該使用該項目。