如何同步本地檔案到OSS - Object Storage Service

sync命令用於將本地檔案或檔案夾同步到OSS。通過增量對比檔案的最後修改時間或快照資訊，sync命令可以高效識別並同步差異檔案，保持源和目標內容的一致性。

工作機制

檔案數量
通過sync命令執行同步任務時，如果沒有攜帶--delete選項，則單次同步任務同步的檔案個數無限制。如果攜帶了--delete選項，則單次同步任務最多可同步100萬個檔案。當同步的檔案個數超出100萬時，將報錯over max sync numbers 1000000.。
sync命令與cp命令的區別
- sync命令強制以遞迴的方式遍曆指定檔案夾內所有檔案或子檔案夾。cp命令需增加-r選項才會進行遞迴操作。
- 通過sync命令將資料同步到OSS時，ossutil支援通過--delete選項將目的端存在而源端不存在的檔案都刪除，僅保留本次同步的檔案。cp命令不支援--delete選項。
- sync不支援--version-id選項，無法在已開啟版本控制的Bucket內同步歷史版本檔案。cp命令支援--version-id選項。
除以上區別外，sync命令與cp命令用法類似。有關cp命令的用法及樣本，請參見cp（上傳檔案）。

注意事項

從ossutil 1.6.16版本開始，命令列中Binary名稱支援直接使用ossutil，您無需根據系統重新整理Binary名稱。如果您的ossutil版本低於1.6.16，則需要根據系統重新整理Binary名稱。更多資訊，請參見命令列工具ossutil命令參考。

許可權說明

預設情況下，只有阿里雲帳號擁有所有API的操作許可權。RAM使用者或RAM角色需要被阿里雲帳號或帳號管理員通過RAM Policy或Bucket Policy授予相應的許可權才能執行此命令。

API Action	說明
oss:ListObjects	列出目標Bucket內的檔案，用於與本地檔案進行對比。
oss:PutObject	上傳檔案到OSS。
oss:DeleteObject	[可選] 當使用--delete選項時，需要此許可權刪除目標Bucket中多餘的檔案。
oss:PutObjectTagging	[可選] 當使用--tagging選項為Object添加標籤時，需要此許可權。

命令格式

ossutil sync file_url cloud_url [options]

參數及選項說明如下：

參數	說明
file_url	待同步的本地檔案夾路徑。例如Linux系統檔案路徑`/localfolder/`，Windows系統檔案路徑`D:\localfolder\`。
cloud_url	OSS檔案夾路徑。格式為`oss://bucketname/path/`。例如`oss://examplebucket/exampledir/`。如果輸入的`cloud_url`沒有以正斜線（/）結尾，ossutil會自動在結尾處添加一個正斜線（/）。
-f --force	強制操作，不進行詢問提示。
-u，--update	只有當目標檔案不存在，或源檔案的最後修改時間晚於目標檔案時，ossutil才會執行同步操作。
--delete	刪除目的端指定路徑下的其他檔案，僅保留本次同步的檔案。警告建議您使用--delete選項前開啟版本控制，防止資料誤刪除。
--enable-symlink-dir	同步連結子目錄。
--disable-all-symlink	同步目錄時，忽略所有的連結子檔案以及連結子目錄。
--disable-ignore-error	大量操作時不忽略錯誤。
--only-current-dir	僅同步目前的目錄下的檔案，忽略子目錄及子目錄下的檔案。
--output-dir	指定輸出檔案所在的目錄。輸出檔案是指批量同步檔案出錯時產生的report檔案，預設儲存在目前的目錄下的ossutil_output目錄。
-bigfile-threshold	設定斷點續傳檔案的大小閾值，單位為位元組。預設值：100 MB 取值範圍：0~9223372036854775807
--part-size	設定分區大小，單位為位元組。預設情況下ossutil會根據檔案大小自行計算合適的分區大小值。取值範圍：1~9223372036854775807
--checkpoint-dir	指定斷點續傳記錄資訊所在的目錄。斷點續傳操作失敗時，ossutil會自動建立名為`.ossutil_checkpoint`的目錄，並在該目錄下記錄checkpoint資訊，斷點續傳成功後會刪除該目錄。如果通過該選項指定了目錄，請確保指定的目錄可以被刪除。
--encoding-type	檔案名稱的編碼方式。取值為url。如果不指定該選項，則表示檔案名稱未經過編碼。
--snapshot-path	指定儲存同步檔案時的快照資訊所在的目錄。在下一次同步檔案時，ossutil會讀取指定目錄下的快照資訊進行增量同步處理。
--include	包含符合指定條件的所有檔案。更多資訊，請參見include和exclude選項。
--exclude	不包含任何符合指定條件的檔案。更多資訊，請參見include和exclude選項。
--meta	設定檔案的中繼資料，格式為`header:value#header:value`，樣本為`Cache-Control:no-cache#Content-Encoding:gzip`。更多資訊，請參見set-meta（管理檔案中繼資料）。
--acl	檔案的讀寫權限ACL。取值如下： default：繼承Bucket的讀寫權限。 private（預設值）：只有該Bucket的擁有者可以對該Bucket內的檔案進行讀寫操作，其他人無法訪問該Bucket內的檔案。 public-read：只有Bucket擁有者可以對該Bucket內的檔案進行寫操作，其他使用者（包括匿名訪問者）都可以對該Bucket中的檔案進行讀操作。這有可能造成您資料的外泄以及費用激增，若被人惡意寫入違法資訊還可能會侵害您的合法權益。除特殊情境外，不建議您配置此許可權。 public-read-write：任何人（包括匿名訪問者）都可以對該Bucket內檔案進行讀寫操作。這有可能造成您資料的外泄以及費用激增，請謹慎操作。
--maxupspeed	最大上傳速度，單位為KB/s。預設值為0，表示不限制上傳速度。
--disable-crc64	關閉CRC64資料校正。
--payer	請求的支付方式。如果希望訪問指定路徑下的資源產生的流量、請求次數等費用由要求者支付，請將此選項的值設定為requester。
-j，--job	多檔案操作時的並發任務數，預設值為3，取值範圍為1~10000。
--parallel	單檔案操作時的並發任務數，取值範圍為1~10000。如果不設定此選項，預設由ossutil根據操作類型和檔案大小自行決定。
--retry-times	發生錯誤後的重試次數。預設值為10，取值範圍為1~500。
--tagging	檔案的標籤資訊，格式為`TagkeyA=TagvalueA&TagkeyB=TagvalueB....`。

關於此命令的其他通用選項，請參見通用選項。

使用樣本

以下樣本均以 Linux 系統為例，請根據作業系統和實際環境修改參數。樣本環境假定：

本地根目錄下localfolder檔案夾內有d.txt和e.png檔案，OSS中名為examplebucket的Bucket下檔案夾destfolder內有檔案a.txt、b.txt和子檔案夾C，其初始內容如下。

本地根目錄                  examplebucket
    └── localfolder         └── destfolder/
            ├── d.txt               ├── a.txt
            └── e.png               ├── b.txt
                                    └── C/

將本地檔案夾同步到OSS

將本地localfolder/下的所有檔案同步到目標目錄destfolder/。此操作僅上傳新增檔案，目標Bucket中已有的檔案a.txt、b.txt和目錄C/將被保留。

ossutil sync localfolder/ oss://examplebucket/destfolder/

同步成功後，返回結果中將包含同步的檔案數量、檔案大小以及完成同步操作所用時間長度：

Succeed: Total num: 2, size: 750,081. OK num: 2(upload 2 files).

average speed 1641000(byte/s)

同步後，destfolder/目錄的結構如下：

destfolder/
├── a.txt
├── b.txt
├── d.txt 
├── e.png 
└── C/

同步時刪除目標目錄中的多餘檔案

在同步本地localfolder/的同時，使用--delete選項刪除destfolder/目錄中多餘的檔案和目錄（即a.txt、b.txt和C/）。

ossutil sync localfolder/ oss://examplebucket/destfolder/ --delete

同步完成後，destfolder/的目錄結構將與localfolder/完全一致：

destfolder/
├── d.txt
└── e.png

篩選並同步特定檔案

通過--include和--exclude選項可以篩選需要同步的檔案。

例如，以下命令僅同步.txt檔案。

ossutil sync localfolder/  oss://examplebucket/destfolder/ --include "*.txt"

執行後，只有d.txt被上傳，e.png被忽略。目標Bucket中原有的檔案不受影響。

destfolder/
├── a.txt
├── b.txt
├── d.txt 
└── C/

以下命令僅同步非.txt檔案。

ossutil sync localfolder/  oss://examplebucket/destfolder/ --exclude "*.txt"

執行後，只有e.png被上傳，d.txt被忽略。目標Bucket中原有的檔案不受影響。

destfolder/
├── a.txt
├── b.txt
├── e.png 
└── C/

強制覆蓋目標目錄的同名檔案

當目標目錄中存在與待上傳檔案同名的檔案時，ossutil預設會提示確認是否覆蓋。如果您確認目的端檔案均可被覆寫，使用-f或--force選項可以跳過互動式確認，直接強制覆蓋。

ossutil sync localfolder/ oss://examplebucket/destfolder/ -f

命令執行成功後，返回結果中會包含同步的檔案數量、總大小和平均速度等資訊。輸出樣本如下：

Succeed: Total num: 2, size: 750,081. OK num: 2(upload 2 files).

average speed 1641000(byte/s)

跨帳號同步

使用 -e,-i, -k 通用選項，將本地檔案夾srcfolder的檔案同步至另一個阿里雲帳號下位於“華東2（上海）”地區的儲存空間examplebucket的testfolder目錄下。

說明

需要根據Bucket所在地區填寫對應的Endpoint。更多資訊，請參見地區和Endpoint。

ossutil sync srcfolder/ oss://examplebucket/testfolder/ -e oss-cn-shanghai.aliyuncs.com -i yourAccessKeyID -k yourAccessKeySecret

安全提示：在命令列中直接使用AccessKey存在安全風險。對於自動化或長期任務，建議為源帳號建立RAM角色並授權給目標帳號使用，以實現更安全的跨帳號訪問。