如何通過cp命令將本地檔案上傳至OSS - Object Storage Service

將本地檔案或目錄上傳至指定的儲存空間（Bucket），支援簡單上傳、斷點續傳、批量上傳、增量上傳，並支援在上傳時指定檔案中繼資料、儲存類型、存取權限等。

工作機制

使用cp命令上傳檔案時，ossutil會根據檔案大小自動選擇不同的上傳方式：

簡單上傳：當檔案大小小於斷點續傳檔案的大小閾值（可通過 --bigfile-threshold 選項指定，預設值為 100 MB）時，採用簡單上傳方式。
斷點續傳：當檔案大小大於或等於該閾值時使用。若上傳意外中斷，已上傳的分區（Part）會臨時儲存在Bucket中。為避免產生儲存費用，建議定期清理分區。可手動刪除分區，或配置生命週期規則自動刪除。

注意事項

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

許可權說明

阿里雲帳號預設擁有全部許可權。阿里雲帳號下的RAM使用者或RAM角色預設沒有任何許可權，需要阿里雲帳號或帳號管理員通過RAM Policy或Bucket Policy授予操作許可權。

API Action	說明
`oss:PutObject`	上傳Object。
`oss:PutObjectTagging`	可選。上傳Object並設定標籤資訊時，需要此許可權。
`kms:GenerateDataKey`	可選。上傳Object並設定KMS伺服器端加密時，需要此許可權。
`kms:Decrypt`	可選。上傳Object並設定KMS伺服器端加密時，需要此許可權。

命令格式

ossutil cp file_url cloud_url [options]

參數及選項說明如下：

參數	說明
file_url	本地檔案路徑。如果目標是目錄，需以路徑分隔字元（/ 或 \）結尾。如Linux系統檔案路徑`/localfolder/examplefile.txt`，Windows系統檔案路徑`D:\localfolder\examplefile.txt`。
cloud_url	OSS檔案路徑，格式為`oss://bucket[/prefix]`。如`oss://examplebucket/examplefile.txt`。
-r, --recursive	遞迴操作。當指定該選項時，ossutil會對Bucket下所有合格Object進行操作，否則只對指定的單個Object進行操作。
-f --force	強制操作，不進行詢問提示。
-u，--update	只有當目標檔案不存在，或源檔案的最後修改時間晚於目標檔案時，ossutil才會執行上傳操作。
--maxupspeed	最大上傳速度，單位為KB/s。預設值為0，表示不限制上傳速度。
--enable-symlink-dir	上傳連結子目錄，預設不上傳。
--disable-all-symlink	上傳時忽略所有的軟連結子檔案以及軟連結子目錄。
--disable-ignore-error	大量操作時不忽略錯誤。
--only-current-dir	僅上傳目前的目錄下的檔案，忽略子目錄及子目錄下的檔案。
--bigfile-threshold	設定斷點續傳檔案的大小閾值，單位為位元組。預設值：100 MB 取值範圍：0~9223372036854775807
--part-size	設定分區大小，單位為位元組。預設情況下ossutil會根據檔案大小自行計算合適的分區大小值。取值範圍：1~9223372036854775807
--checkpoint-dir	指定斷點續傳記錄資訊所在的目錄。斷點續傳操作失敗時，ossutil會自動建立名為`.ossutil_checkpoint`的目錄，並在該目錄下記錄checkpoint資訊，斷點續傳成功後會刪除該目錄。如果指定了該選項，請確保指定的目錄可以被刪除。
--encoding-type	檔案名稱的編碼方式。取值為url。如果不指定該選項，則表示檔案名稱未經過編碼。
--include	包含符合指定條件的所有檔案。文法規範和使用樣本，請參見批量上傳合格檔案。
--exclude	不包含任何符合指定條件的檔案。文法規範和使用樣本，請參見批量上傳合格檔案。
--meta	檔案的中繼資料。包括部分HTTP標準屬性（HTTP Header）以及以`x-oss-meta-`開頭的使用者自訂中繼資料（User Meta）。檔案中繼資料格式為`header:value#header:value`，樣本為`Cache-Control:no-cache#Content-Encoding:gzip`。有關OSS支援中繼資料的更多介紹，請參見管理檔案中繼資料。
--acl	檔案的讀寫權限ACL。取值如下： default（預設值）：繼承Bucket的讀寫權限。 private：只有該Bucket的擁有者可以對該Bucket內的檔案進行讀寫操作，其他人無法訪問該Bucket內的檔案。 public-read：只有Bucket擁有者可以對該Bucket內的檔案進行寫操作，其他使用者（包括匿名訪問者）都可以對該Bucket中的檔案進行讀操作。這有可能造成資料的外泄以及費用激增，如果被人惡意寫入違法資訊還可能會侵害您的合法權益。除特殊情境外，不建議配置此許可權。 public-read-write：任何人（包括匿名訪問者）都可以對該Bucket內檔案進行讀寫操作。這有可能造成資料的外泄以及費用激增，請謹慎操作。
--snapshot-path	指定儲存上傳檔案時的快照資訊所在的目錄。在下一次上傳檔案時，ossutil會讀取指定目錄下的快照資訊進行增量上傳。
--disable-crc64	關閉CRC64資料校正。預設情況下，ossutil進行資料轉送時都會開啟CRC64校正。
--disable-dir-object	表示上傳檔案時不為目錄產生Object。
--payer	請求的支付方式。如果希望訪問指定路徑下的資源產生的流量、請求次數等費用由要求者支付，請將此選項的值設定為requester。
--tagging	上傳檔案時設定標籤資訊，格式為`TagkeyA=TagvalueA&TagkeyB=TagvalueB....`。
-j，--jobs	多檔案操作時的並發任務數，預設值為3，取值範圍為1~10000。
--parallel	單檔案操作時的並發任務數，取值範圍為1~10000。如果不設定此選項，預設由ossutil根據操作類型和檔案大小自行決定。
--start-time	Unix時間戳記。如果輸入這個選項，最後更新時間早於該時間的Object會被忽略。說明僅1.7.18及以上版本支援設定該參數。關於如何升級版本，請參見update（ossutil版本升級）。
--end-time	Unix時間戳記。如果使用該選項，則最後更新時間晚於通過此選項指定時間的Object會被忽略。說明如果同時指定了start-time和end-time，檔案的修改時間在start-time和end-time之間才會執行拷貝命令。僅1.7.18及以上版本支援設定該參數。關於如何升級版本，請參見update（ossutil版本升級）。

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

當預設並發數達不到使用者的效能要求時，可以調整-j，--jobs和--parallel選項來升降效能。預設情況下，ossutil根據檔案大小來計算parallel。當批量傳輸大檔案時，實際的並發數為jobs數乘以parallel數。

若執行命令的ECS或伺服器的資源（網路、記憶體、CPU）有限，建議將並發數調低（如100以下）。如果資源未佔滿，可適當增加並發數。
並發數過高可能因線程切換開銷和資源競爭導致效能下降，甚至引發EOF錯誤。請根據機器的實際資源狀況調整-j，--jobs和--parallel。進行效能壓測時，建議從較低的並發數開始，逐步增加以找到最佳值。

使用樣本

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

Bucket 名稱：examplebucket
OSS 目錄：desfolder/
本地目錄：localfolder/
本地檔案：examplefile.txt

上傳單個檔案

上次檔案到指定目錄，並沿用原檔案名稱。若不指定上傳至OSS的檔案名稱，則預設使用原檔案名稱進行儲存；若指定檔案名稱，則按照指定的檔案名稱儲存在OSS中。
```
ossutil cp examplefile.txt oss://examplebucket/desfolder/
```

上傳單個檔案並指定--meta選項設定檔案的meta資訊，其內容格式為header:value#header:value...。

ossutil cp examplefile.txt oss://examplebucket/desfolder/examplefile.txt --meta=Cache-Control:no-cache#Content-Encoding:gzip

批量上傳

僅上傳檔案夾內的檔案
使用cp命令時增加-r選項，可以只將本地檔案夾內的檔案上傳到OSS指定路徑。
```
ossutil cp -r localfolder/ oss://examplebucket/desfolder/
```
上傳檔案夾內的檔案並指定時間戳記
將本地檔案夾內的檔案上傳到OSS指定路徑，檔案修改時間限定在北京時間2023年10月31日10:09:18至2023年10月31日12:55:58內。
```
ossutil cp -r localfolder/ oss://examplebucket/desfolder/ --start-time 1698718158 --end-time 1698728158
```
上傳檔案夾及檔案夾內的檔案
使用cp命令時增加-r選項，並在OSS指定路徑下添加本地檔案夾名稱，可以將本地檔案夾以及檔案夾內的檔案上傳到OSS指定路徑。對於檔案夾內的檔案夾，OSS會對應建立0 KB大小、以正斜線（/）結尾的Object；對於指定的檔案夾，OSS不會建立對應的Object。如果需要建立對應的Object，可以使用mkdir（建立目錄）。
```
ossutil cp -r localfolder/ oss://examplebucket/desfolder/localfolder/
```
上傳檔案夾並跳過已有檔案
批量上傳失敗重傳時，可以指定--update（可縮寫為-u）選項跳過已經上傳成功的檔案，實現增量上傳。樣本如下：
```
ossutil cp -r localfolder/ oss://examplebucket/desfolder/ -u
```

ossutil cp localfolder/ oss://examplebucket/desfolder/ --only-current-dir -r

上傳時不為目錄產生Object
OSS的目錄是用一個0 KB大小，名稱以正斜線（/）結尾的Object類比的。上傳時增加--disable-dir-object參數，ossutil不會為該目錄產生Object，但仍可以在OSS控制台看到對應的目錄結構。當刪除目錄內的檔案時，該目錄也會消失。
```
ossutil cp localfolder/ oss://examplebucket/desfolder/ --disable-dir-object -r
```

上傳軟連結子目錄下的檔案

ossutil cp localfolder/ oss://examplebucket/desfolder/ --enable-symlink-dir -r

上傳時忽略所有的軟連結子檔案以及軟連結子目錄

ossutil cp localfolder/ oss://examplebucket/desfolder/ -r --disable-all-symlink

批量上傳合格檔案

批量上傳時，如果指定--include和--exclude選項，ossutil會批量上傳符合指定條件的檔案。

--include和--exclude選項支援格式：

萬用字元星號（*）：匹配所有字元。例如：*.txt表示匹配所有TXT格式的檔案。
萬用字元問號（？）：匹配單個字元。例如：abc?.jpg表示匹配所有檔案名稱為abc+任意單個字元的JPG格式的檔案，如abc1.jpg。
[sequence]：匹配序列的任一字元，例如：abc[1-5].jpg表示匹配檔案名稱為abc1.jpg~abc5.jpg的檔案。
[!sequence]：匹配序列外的任一字元，例如：abc[!0-7].jpg表示匹配檔案名稱不為abc0.jpg~abc7.jpg的檔案。

一條規則中可以包含多個include（包含）和exclude（排除）條件，且每個檔案從左至右逐一運用每個規則，直至最後才能最終確定匹配的結果。例如指定生效的檔案夾中包含名為test.txt的檔案，匹配不同的規則產生的結果如下。

規則一：--include "*test*" --exclude "*.txt" ，當規則匹配到--include "*test*"，匹配的結果為test.txt符合條件；當規則繼續匹配到--exclude "*.txt"時，因test.txt檔案名稱包含.txt，所以被排除。則匹配的最終結果為test.txt不符合條件。
規則二：--exclude "*.txt" --include "*test*"，當規則匹配到--exclude "*.txt"，匹配的結果為test.txt不符合條件；當規則繼續匹配到--include "*test*"，因test.txt檔案名稱包含test，所以符合條件。則匹配的最終結果為test.txt符合條件。
規則三：--include "*test*" --exclude "*.txt" --include "te?t.txt" ，當規則匹配到--include "*test*"，匹配的結果為test.txt符合條件；當規則繼續匹配到--exclude "*.txt"時，因test.txt檔案名稱包含.txt，所以被排除；當規則最後匹配到--include "te?t.txt"時，因test.txt符合條件，所以被包含。則匹配的最終結果為test.txt符合條件。

重要

設定條件時不支援目錄格式，例如--include "/usr/test/.jpg"。

樣本如下：

上傳所有檔案格式為TXT的檔案

ossutil cp localfolder/ oss://examplebucket/desfolder/ --include "*.txt" -r

上傳所有檔案名稱包含abc且不是JPG和TXT格式的檔案

ossutil cp localfolder/ oss://examplebucket/desfolder/ --include "*abc*" --exclude "*.jpg" --exclude "*.txt" -r

上傳時限速

可以在上傳檔案時，結合--maxupspeed選項來限制上傳的最大速度，單位為KB/s。樣本如下：

上傳檔案並設定限速為1 MB/s

ossutil cp examplefile.txt oss://examplebucket/desfolder/ --maxupspeed 1024

上傳檔案夾並設定限速為1 MB/s

ossutil cp -r localfolder/ oss://examplebucket/desfolder/ --maxupspeed 1024

上傳並設定對象標籤

可以在上傳檔案時，通過--tagging選項設定檔案對象標籤，多個標籤以and（&）符號隔開。樣本如下：

ossutil cp examplefile.txt oss://examplebucket/desfolder/ --tagging "abc=1&bcd=2&……"

關於對象標籤的更多說明請參見object-tagging（對象標籤）。

上傳並指定儲存類型

可以在上傳檔案時，通過--meta選項設定檔案儲存體類型。儲存類型可選值為：

Standard：標準儲存
IA：低頻訪問
Archive：Archive Storage
ColdArchive：冷Archive Storage
DeepColdArchive：深度冷Archive Storage

如果上傳時未指定儲存類型，則以儲存空間的儲存類型為準。更多資訊，請參見儲存類型。

上傳並指定儲存類型的樣本如下：

上傳單個檔案並指定儲存類型為低頻訪問類型

ossutil cp examplefile.txt oss://examplebucket/desfolder/ --meta X-oss-Storage-Class:IA

上傳檔案夾並指定儲存類型為標準儲存類型

ossutil cp localfolder/ oss://examplebucket/desfolder/ --meta X-oss-Storage-Class:Standard -r

上傳並指定ACL

可以在上傳檔案時，通過--acl選項設定檔案的讀寫權限ACL。檔案ACL可選值為：

default：繼承Bucket（預設）
private：私人
public-read：公用讀取
public-read-write：公用讀寫

樣本如下：

上傳單個檔案並指定ACL為私人

ossutil cp examplefile.txt oss://examplebucket/desfolder/ --acl private

上傳檔案夾並指定ACL為公用讀取

ossutil cp localfolder/ oss://examplebucket/desfolder/ --acl public-read  -r

上傳並指定加密方式

可以在上傳檔案時指定檔案的伺服器端加密方式，將檔案加密後儲存在Bucket內。樣本如下：

上傳檔案並指定加密方式為OSS完全託管，密碼編譯演算法為AES256

ossutil cp examplefile.txt oss://examplebucket/desfolder/ --meta=x-oss-server-side-encryption:AES256

上傳檔案並指定加密方式為KMS，不指定CMK ID
```
ossutil cp examplefile.txt oss://examplebucket/desfolder/ --meta=x-oss-server-side-encryption:KMS
```
使用KMS加密時，會產生少量KMS密鑰使用費用，詳情請參見KMS計費標準。

上傳檔案並指定加密方式為KMS，指定CMK ID

ossutil cp examplefile.txt oss://examplebucket/desfolder/ --meta=x-oss-server-side-encryption:KMS#x-oss-server-side-encryption-key-id:7bd6e2fe-cd0e-483e-acb0-f4b9e1******

有關伺服器端加密功能介紹，請參見伺服器端加密。

上傳並產生快照

批量上傳時，如果指定--snapshot-path選項，ossutil在指定的目錄下組建檔案上傳的快照，記錄成功上傳的檔案的本地lastModifiedTime，在下次上傳時通過比較lastModifiedTime來決定是否跳過相同檔案，所以在使用該選項時，請確保兩次上傳期間沒有其他使用者更改了OSS上對應的Object。--snapshot-path選項適用於加速增量上傳的情境。樣本如下：

ossutil cp -r localfolder/ oss://examplebucket/desfolder/ --snapshot-path=path

重要

ossutil不會主動刪除snapshot-path檔案夾中的快照資訊。為避免快照資訊過多，請定期刪除snapshot-path檔案夾內無用的快照。
由於讀寫snapshot資訊需要額外開銷，當待批量上傳的檔案數量較少、網路狀況較好、或有其他使用者操作相同Object時，不建議使用該選項。針對以上情況，可以使用--update選項來增量上傳。
--update選項和--snapshot-path選項可以同時使用，ossutil會優先根據snapshot-path資訊判斷是否跳過此檔案，如果不滿足跳過條件，再根據--update判斷是否跳過此檔案。

上傳並配置要求者付費

ossutil cp localfolder/examplefile.txt oss://examplebucket/ --payer=requester

跨帳號或跨地區上傳

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

說明

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

ossutil cp exampleobject.txt oss://examplebucket/desfolder/ -e oss-cn-shanghai.aliyuncs.com -i yourAccessKeyID  -k yourAccessKeySecret