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

當您需要將本地檔案、圖片、視頻等資源上傳到OSS，或者需要上傳大檔案至OSS時，可以使用ossutil的cp命令。您也可以指定--include和--exclude選項，批量上傳符合指定條件的檔案。

注意事項

要上傳檔案，您必須具有oss:PutObject許可權。具體操作，請參見為RAM使用者授權自訂的權限原則。
從ossutil 1.6.16版本開始，命令列中Binary名稱支援直接使用ossutil，您無需根據系統重新整理Binary名稱。如果您的ossutil版本低於1.6.16，則需要根據系統重新整理Binary名稱。更多資訊，請參見命令列工具ossutil命令參考。

使用cp命令上傳檔案時，ossutil會根據檔案大小自動選擇不同的上傳方式：
- 如果上傳的檔案大小小於斷點續傳上傳檔案大小的閾值（該閾值通過--bigfile-threshold選項指定，預設值是100 MB），ossutil將採用簡單上傳的方式。
- 如果上傳的檔案大小大於等於斷點續傳上傳檔案大小的閾值，ossutil將採用斷點續傳上傳的方式。
  如果您因意外中斷了檔案上傳的過程，且未繼續完成該檔案的上傳，則已上傳的部分會以片段（Part）的形式儲存在OSS的儲存空間（Bucket）中。如果您不再需要這些Part，建議您通過以下方式刪除，以免產生額外的儲存費用。
  - 手動刪除Part，請參見刪除片段。
  - 通過生命週期規則自動刪除Part，請參見設定生命週期規則。

命令格式

ossutil cp file_url cloud_url
[-r, --recursive]
[-f --force]
[-u --update]
[--maxupspeed <value>]
[--enable-symlink-dir]
[--disable-all-symlink]
[--disable-ignore-error]
[--only-current-dir]
[--bigfile-threshold <value>]
[--part-size <value>]
[--checkpoint-dir <value>]
[--encoding-type <value>]
[--include <value>]
[--exclude <value>]
[--meta <value>]
[--acl <value>]
[--snapshot-path <value>]
[--disable-crc64]
[--disable-dir-object]
[--payer <value>]
[--tagging <value>]
[-j, --job <value>]
[--parallel <value>]
[--start-time <value>]
[--end-time <value>]

參數及選項說明如下：

配置項	說明
file_url	本地檔案路徑。例如Linux系統檔案路徑`/localfolder/examplefile.txt`，Windows系統檔案路徑`D:\localfolder\examplefile.txt`。
cloud_url	OSS檔案路徑。格式為`oss://bucketname/objectname`。例如`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自行設定的預設並發數達不到使用者的效能要求時，您可以自行調整這兩個選項來升降效能。預設情況下，ossutil會根據檔案大小來計算parallel個數。當批量上傳大檔案時，實際的並發數為jobs個數乘以parallel個數。

當ECS虛擬機器或者伺服器在網路、記憶體、CPU等資源不是特別大的情況下，建議將並發數調整到100以下。如果網路、記憶體、CPU等資源沒有佔滿，可以適當增加並發數。
由於線程間資源切換及搶奪等原因，如果並發數過大，ossutil上傳效能可能會下降。此外，並發數過大還可能產生EOF錯誤。所以請根據實際的機器情況調整-j，--jobs和--parallel選項的數值。如果要進行壓測，可在一開始時調低這兩項數值，然後逐漸調大直至找到最優值。

樣本環境

本文以Linux系統為例，將本地檔案或檔案夾上傳至OSS中。您在實際使用中，請根據您的系統和使用環境修改對應參數。本文涉及的通用樣本說明如下：

本地檔案：examplefile.txt（根目錄下的檔案）
本地檔案夾：localfolder（根目錄下的檔案夾）
目標Bucket：examplebucket
目標Bucket指定目錄：desfolder

簡單上傳

當您需要將本地檔案、圖片、視頻等資源上傳到OSS，可以使用ossutil，樣本如下：

上傳單個檔案
上傳檔案時，如果不指定上傳至OSS的檔案名稱，則預設使用原檔案名稱進行儲存；如果指定檔案名稱，則按照指定的檔案名稱儲存在OSS中。
```
ossutil cp examplefile.txt oss://examplebucket/desfolder/
```
僅上傳檔案夾內的檔案
使用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/
```
上傳單個檔案並指定--meta選項
上傳檔案的同時可以使用--meta選項設定檔案的meta資訊，其內容格式為header:value#header:value...。
```
ossutil cp examplefile.txt oss://examplebucket/desfolder/examplefile.txt --meta=Cache-Control:no-cache#Content-Encoding:gzip
```
上傳檔案夾並跳過已有檔案
批量上傳失敗重傳時，可以指定--update（可縮寫為-u）選項跳過已經上傳成功的檔案，實現增量上傳。樣本如下：
```
ossutil cp -r localfolder/ oss://examplebucket/desfolder/ -u
```

上傳檔案到開通了要求者付費模式的Bucket

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

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

上傳時限速

您可以在上傳檔案時，結合--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判斷是否跳過此檔案。

批量上傳合格檔案

批量上傳時，如果指定--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

通用選項

當您需要通過命令列工具ossutil切換至另一個地區的Bucket時，可以通過-e選項指定該Bucket所屬的Endpoint。當您需要通過命令列工具ossutil切換至另一個阿里雲帳號下的Bucket時，可以通過-i選項指定該帳號的AccessKey ID，並通過-k選項指定該帳號的AccessKey Secret。

例如，您需要將本地檔案exampleobject.txt上傳至另一個阿里雲帳號下，華東2（上海）地區的儲存空間examplebucket的destfolder目錄下，命令如下：

ossutil cp exampleobject.txt oss://examplebucket/desfolder/ -e oss-cn-shanghai.aliyuncs.com -i LTAI4Fw2NbDUCV8zYUzA****  -k 67DLVBkH7EamOjy2W5RVAHUY9H****

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