使用命令列工具 ossutil 2.0 在多種作業系統中高效管理阿里雲Object Storage Service 資源，實現檔案的快速上傳、下載、同步和管理，適合開發人員、營運人員和企業進行大規模資料移轉和日常營運操作。
|
作業系統 |
系統架構 |
下載地址 |
SHA256校正和 |
|
Linux |
x86_32 |
b6350a6c0c277961f138106e454e912189402dc45be364e83785a3292ce0a4e6 |
|
|
x86_64 |
85edf66b2fb7238f5c7e25cab820cf29312319fe4935b7c86a6b8485eb434f3c |
||
|
arm32 |
b377a9e4f4b79464176e2e122d7f8c9d3a3d1eae9703f71451c8cd5ef2b4b4fb |
||
|
arm64 |
7767240e9667d1f26fbe4e04f90b796b4356889e77d0076cc8a543c8ce081987 |
||
|
macOS |
x86_64 |
86685f129c76dbf94d7f9298152e24bb895289d866cb1a6115aa141c1a1b455b |
|
|
arm64 |
26e51080c6d6c9848fe3aea8a6b0cbd88453e65cd41c5a27573c59335a78a41d |
||
|
Windows |
x86_32 |
4efe875059fe501ab66d88af68fa54d111279f8d25d657cb422a96e4da348137 |
|
|
x86_64 |
dd68cffb62d88e59ff3d7fde6055ac7b8e2197e2adce7e540bcd6c706a2c4a49 |
||
|
amd64 |
f74f2afa637a7f59caae6ba54e7b6c3aa57c8fce007c77cc10f4338321ab632c |
快速接入
接入命令列工具ossutil 2.0的流程如下：
安裝ossutil
Linux
-
安裝unzip解壓工具。
Alibaba Cloud Linux
sudo yum install -y unzipCentOS
sudo yum install -y unzipUbuntu
sudo apt install -y unzip -
根據作業系統與架構選擇對應安裝包（Linux x86 32bit、Linux x86 64bit、Linux ARM 32bit、Linux ARM 64bit），也可通過 curl 下載。以下以在 Linux x86_64 上使用 curl 擷取為例：
curl -o ossutil-2.4.0-linux-amd64.zip https://gosspublic.alicdn.com/ossutil/v2/2.4.0/ossutil-2.4.0-linux-amd64.zip -
在下載壓縮包的所在目錄執行以下解壓命令。
unzip ossutil-2.4.0-linux-amd64.zip -
進入ossutil-2.4.0-linux-amd64目錄。
cd ossutil-2.4.0-linux-amd64 -
在目前的目錄執行以下命令。
chmod 755 ossutil -
執行以下命令，實現ossutil的全域調用。
sudo mv ossutil /usr/local/bin/ && sudo ln -s /usr/local/bin/ossutil /usr/bin/ossutil -
驗證是否成功安裝ossutil，執行
ossutil命令。ossutil返回ossutil的協助資訊即表示安裝成功。
Windows
-
安裝ossutil。
-
根據作業系統與架構選擇對應安裝包（Windows x86 32bit、Windows x86 64bit、Windows 7, Windows 8, Windows Server 2008R2）。
-
將下載好的.zip壓縮包解壓到目標檔案夾，然後進入解壓後的目錄。
-
複製當前解壓後ossutil檔案夾路徑配置系統內容變數。
-
單擊目前的目錄的路徑欄，複製其中顯示的當前檔案夾路徑。
-
開啟環境變數對話方塊，在系統變數欄中找到並雙擊Path變數，單擊建立按鈕，然後將複製好的ossutil檔案夾路徑粘貼到新的條目框中。
-
-
驗證是否成功安裝ossutil，執行ossutil命令。
ossutil返回ossutil的協助資訊即表示安裝成功。
-
macOS
-
根據作業系統與架構選擇對應安裝包（macOS x86 64bit、macOS ARM 64bit），也可通過 curl 下載。以下以在 macOS ARM64 位元系統上使用 curl 擷取為例：
curl -o ossutil-2.4.0-mac-arm64.zip https://gosspublic.alicdn.com/ossutil/v2/2.4.0/ossutil-2.4.0-mac-arm64.zip -
在下載壓縮包的所在目錄執行以下解壓命令。
unzip ossutil-2.4.0-mac-arm64.zip -
進入ossutil-2.4.0-mac-arm64目錄。
cd ossutil-2.4.0-mac-arm64 -
在目前的目錄執行以下命令。
chmod 755 ossutil -
執行以下命令，實現ossutil的全域調用。
sudo mv ossutil /usr/local/bin/ && sudo ln -s /usr/local/bin/ossutil /usr/bin/ossutil -
驗證是否成功安裝ossutil。
ossutil返回ossutil的協助資訊即表示安裝成功。
配置ossutil
為避免因配置缺失導致操作失敗，推薦使用 ossutil config 命令的設定精靈快速完成 AccessKey ID、AccessKey Secret 和地區 ID 的配置。若還需管理進階配置，可參考配置指南進行手動配置訪問憑證等。
以使用 RAM 使用者的 AccessKey 配置為訪問憑證為樣本，結合設定精靈快速完成配置。
Linux
-
輸入配置命令。
ossutil config -
根據提示設定設定檔路徑。可以直接斷行符號使用預設的設定檔路徑。
Please enter the config file name,the file name can include path(default /root/.ossutilconfig, carriage return will use the default file. If you specified this option to other file, you should specify --config-file option to the file when you use other commands):ossutil預設使用/root/.ossutilconfig作為設定檔。
-
根據提示分別設定AccessKey ID、AccessKey Secret、地區ID資訊。
-
輸入建立的AccessKey ID。
Please enter Access Key ID [****************id]:yourAccessKeyID -
輸入建立的AccessKey Secret。
Please enter Access Key Secret [****************sk]:yourAccessKeySecret -
輸入OSS的資料中心所在的地區，如無任何輸入，預設值為cn-hangzhou。
Please enter Region [ap-southeast-1]:ap-southeast-1 -
輸入OSS的資料中心的Endpoint，如果不需要自訂 Endpoint，可以直接按斷行符號跳過該參數的配置。
在上一步配置完地區資訊後，將預設使用該地區 ID 對應的外網 Endpoint。例如，如果設定的
region-id為ap-southeast-1，預設使用的外網 Endpoint 是https://oss-ap-southeast-1.aliyuncs.com。如果需要自訂 OSS 資料中心所在地區的 Endpoint，請輸入 Endpoint 資訊。例如，如果希望通過與OSS同地區的其他阿里雲產品訪問OSS，請使用內網Endpoint如
https://oss-ap-southeast-1-internal.aliyuncs.com。Please enter Endpoint (optional, use public endpoint by default) [None]: https://oss-ap-southeast-1-internal.aliyuncs.com
參數說明如下：
參數
是否必填
說明
accessKeyID
是
帳號的AccessKey，AccessKey的擷取方式參見建立AccessKey。
accessKeySecret
是
Region
是
Bucket所在的地區ID，本文以新加坡地區為例，設定為
ap-southeast-1，其他地區的ID參見地區和Endpoint。endpoint
否
Bucket所在地區的Endpoint。若未手動設定Endpoint，Region將自動產生對應的外網endpoint，內網需顯式指定。例如，本樣本使用新加坡外網Endpoint，設定為
https://oss-ap-southeast-1.aliyuncs.com。如果希望通過與OSS同地區的其他阿里雲產品訪問OSS，請使用內網Endpoint，設定為
https://oss-ap-southeast-1-internal.aliyuncs.com。關於各地區Endpoint的更多資訊，請參見地區和Endpoint。
-
Windows
-
輸入配置命令。
ossutil config -
根據提示設定設定檔路徑。可以直接斷行符號使用預設的設定檔路徑。
Please enter the config file name,the file name can include path(default "C:\Users\issuser\.ossutilconfig", carriage return will use the default file. If you specified this option to other file, you should specify --config-file option to the file when you use other commands):ossutil預設使用C:\Users\issuser\.ossutilconfig作為設定檔。
-
根據提示分別設定AccessKey ID、AccessKey Secret、地區ID資訊。
-
輸入建立的AccessKey ID。
Please enter Access Key ID [****************id]:yourAccessKeyID -
輸入建立的AccessKey Secret。
Please enter Access Key Secret [****************sk]:yourAccessKeySecret -
輸入OSS的資料中心所在的地區，如無任何輸入，預設值為cn-hangzhou。
Please enter Region [ap-southeast-1]:ap-southeast-1 -
輸入OSS的資料中心的Endpoint，如果不需要自訂 Endpoint，可以直接按斷行符號跳過該參數的配置。
在上一步配置完地區資訊後，將預設使用該地區 ID 對應的外網 Endpoint。例如，如果設定的
region-id為ap-southeast-1，預設使用的外網 Endpoint 是https://oss-ap-southeast-1.aliyuncs.com。如果需要自訂 OSS 資料中心所在地區的 Endpoint，請輸入 Endpoint 資訊。例如，如果希望通過與OSS同地區的其他阿里雲產品訪問OSS，請使用內網Endpoint如
https://oss-ap-southeast-1-internal.aliyuncs.com。Please enter Endpoint (optional, use public endpoint by default) [None]: https://oss-ap-southeast-1-internal.aliyuncs.com
參數說明如下：
參數
是否必填
說明
accessKeyID
是
帳號的AccessKey，AccessKey的擷取方式參見建立AccessKey。
accessKeySecret
是
Region
是
Bucket所在的地區ID，本文以新加坡地區為例，設定為
ap-southeast-1，其他地區的ID參見地區和Endpoint。endpoint
否
Bucket所在地區的Endpoint。若未手動設定Endpoint，Region將自動產生對應的外網endpoint，內網需顯式指定。例如，本樣本使用新加坡外網Endpoint，設定為
https://oss-ap-southeast-1.aliyuncs.com。如果希望通過與OSS同地區的其他阿里雲產品訪問OSS，請使用內網Endpoint，設定為
https://oss-ap-southeast-1-internal.aliyuncs.com。關於各地區Endpoint的更多資訊，請參見地區和Endpoint。
-
macOS
-
輸入配置命令。
ossutil config -
根據提示設定設定檔路徑。可以直接斷行符號使用預設的設定檔路徑。
Please enter the config file name,the file name can include path(default "/Users/user/.ossutilconfig", carriage return will use the default file. If you specified this option to other file, you should specify --config-file option to the file when you use other commands):ossutil預設使用/Users/user/.ossutilconfig作為設定檔。
-
根據提示分別設定AccessKey ID、AccessKey Secret、地區ID資訊。
-
輸入建立的AccessKey ID。
Please enter Access Key ID [****************id]:yourAccessKeyID -
輸入建立的AccessKey Secret。
Please enter Access Key Secret [****************sk]:yourAccessKeySecret -
輸入OSS的資料中心所在的地區，如無任何輸入，預設值為cn-hangzhou。
Please enter Region [ap-southeast-1]:ap-southeast-1 -
輸入OSS的資料中心的Endpoint，如果不需要自訂 Endpoint，可以直接按斷行符號跳過該參數的配置。
在上一步配置完地區資訊後，將預設使用該地區 ID 對應的外網 Endpoint。例如，如果設定的
region-id為ap-southeast-1，預設使用的外網 Endpoint 是https://oss-ap-southeast-1.aliyuncs.com。如果需要自訂 OSS 資料中心所在地區的 Endpoint，請輸入 Endpoint 資訊。例如，如果希望通過與OSS同地區的其他阿里雲產品訪問OSS，請使用內網Endpoint如
https://oss-ap-southeast-1-internal.aliyuncs.com。Please enter Endpoint (optional, use public endpoint by default) [None]: https://oss-ap-southeast-1-internal.aliyuncs.com
參數說明如下：
參數
是否必填
說明
accessKeyID
是
帳號的AccessKey，AccessKey的擷取方式參見建立AccessKey。
accessKeySecret
是
Region
是
Bucket所在的地區ID，本文以新加坡地區為例，設定為
ap-southeast-1，其他地區的ID參見地區和Endpoint。endpoint
否
Bucket所在地區的Endpoint。若未手動設定Endpoint，Region將自動產生對應的外網endpoint，內網需顯式指定。例如，本樣本使用新加坡外網Endpoint，設定為
https://oss-ap-southeast-1.aliyuncs.com。如果希望通過與OSS同地區的其他阿里雲產品訪問OSS，請使用內網Endpoint，設定為
https://oss-ap-southeast-1-internal.aliyuncs.com。關於各地區Endpoint的更多資訊，請參見地區和Endpoint。
-
運行命令
-
建立Bucket。
ossutil mb oss://examplebucket以下輸出結果表明已成功建立examplebucket。
0.668238(s) elapsed -
上傳檔案到Bucket。
-
建立本地檔案
uploadFile.txt。echo 'Hello, OSS!' > uploadFile.txt -
上傳檔案到儲存空間
examplebucket。ossutil cp uploadFile.txt oss://examplebucket以下輸出結果表明檔案已成功上傳至
examplebucket。Success: Total 1 file, size 12 B, Upload done:(1 objects, 12 B), avg 44 B/s 0.271779(s) elapsed
-
-
下載檔案。
將已上傳的樣本檔案uploadFile.txt從examplebucket下載至本地localfolder檔案夾下。
ossutil cp oss://examplebucket/uploadFile.txt localfolder/以下輸出結果表明檔案已成功下載至本地localfolder檔案夾下。
Success: Total 1 object, size 12 B, Download done:(1 files, 12 B), avg 74 B/s 0.162447(s) elapsed -
列舉examplebucket下的檔案。
ossutil ls oss://examplebucket以下輸出結果表明已成功列舉examplebucket下的檔案。
LastModifiedTime Size(B) StorageClass ETAG ObjectName 2024-11-26 14:35:29 +0800 CST 12 Standard 1103F650EB2C292D179A032D2A97B0F5 oss://examplebucket/uploadFile.txt Object Number is: 1 0.124679(s) elapsed -
刪除examplebucket下的uploadFile.txt。
ossutil rm oss://examplebucket/uploadFile.txt以下輸出結果表明已成功刪除examplebucket下的uploadFile.txt。
0.295530(s) elapsed -
刪除examplebucket。
ossutil rb oss://examplebucket以下輸出結果表明已成功刪除examplebucket。
0.478659(s) elapsed
配置指南
ossutil 支援通過設定檔、環境變數和命令列選項進行配置，靈活性高。
配置的優先順序
ossutil 按以下順序讀取配置：
命令列選項 (如 -i, -k, -e) > 環境變數 (如 OSS_ACCESS_KEY_ID) > 設定檔 (~/.ossutilconfig)
-
從 2.2.0 版本開始，支援通過--ignore-env-var 命令列選項忽略 OSS_為首碼的環境變數配置。
-
從 2.3.0 版本開始，
--job、--parallel、--bigfile-threshold、--part-size、--write-buffer-size選項支援通過設定檔設定。在設定檔對應 profile 段下以key=value格式追加（例如job=10），或通過ossutil config set寫入。命令列選項的優先順序高於設定檔。
設定檔
可以利用設定檔（預設路徑為 ~/.ossutilconfig，或通過 -c 選項指定自訂路徑）配置 ossutil。如果使用預設設定檔，則不需要額外指定設定檔路徑。直接運行 ossutil 命令即可，例如：
ossutil ls oss://examplebucket如果使用自訂設定檔路徑，例如 /path/yourconfig，則需要通過 -c 選項指定設定檔路徑。例如：
ossutil -c /path/yourconfig ls oss://examplebucket設定檔格式
設定檔採用INI格式結構，以節（section）和索引值（key）構成，配置參數儲存在指定的節裡。這些配置按照節分成多個段，可以通過--profile使用某一個節的配置。 預設情況下，ossutil使用設定檔中的[default]設定。要使用其他設定，可以建立和引用其他配置。
節和索引值對
設定檔中的每個節由方括弧 [ ] 包圍的名稱標識，節內的設定項採用 key=value 形式。例如：
[default]
accessKeyID = "your-access-key-id"
accessKeySecret = "your-access-key-secret"-
節中的設定項採用
key=value形式。 -
節名和索引值中的key不區分大小寫。
-
配置參數的key支援多種格式，全小寫、小駝峰、短劃線（-）串連和底線（_）串連，例如：accesskeyid、accessKeyId、access-key-id、access_key_id表示同一個參數名。
-
井號字元（#）開頭的行表示注釋行。
支援的節類型
|
節（Section）名稱 |
說明 |
其它說明 |
|
[default] |
用於儲存預設設定，即當不設定--profile選項時，使用該節裡的配置。 |
為[profile default]簡化形式。 |
|
[profile name] |
用於配置參數，通過--profile name來引用。 |
支援通過source_profile方式引用其它配置。 |
|
[buckets name] |
針對具體bucket配置訪問網域名稱，包括region、 endpoint和addressing style。 |
支援內聯寫法。 |
可以使用config命令查看和設定配置內容。更多資訊，請參見config。
節類型：profile
用於配置訪問憑證和全域配置參數，支援的參數名如下：
-
訪問憑證相關參數
參數名
別名
含義
mode
/
鑒權模式。
取值：AK、StsToken、RamRoleArn、EcsRamRole、Anonymous。
access-key-id
accessKeyId
access_key_id
訪問OSS使用的AccessKey ID。
access-key-secret
accessKeySecret
access_key_secret
訪問OSS使用的AccessKey Secret。
sts-token
stsToken
sts_token
訪問OSS使用的STS Token。
role-arn
roleArn
role_arn
RAM角色的ARN，主要用於RamRoleArn模式。
role-session-name
roleSessionName
role_session_name
會話名字，主要用於RamRoleArn模式。
ecs-role-name
ecsRoleName
ecs_role_name
角色名稱，主要用於EcsRamRole模式。
credential-process
credentialProcess
credential_process
指定一個外部命令。
credential-uri
credentialUri
credential_uri
指定一個擷取訪問憑證的URI地址。
oidc-provider-arn
oidcProviderArn
oidc_provider_arn
指定OIDC提供者的ARN（Aliyun Resource Name），格式為
acs:ram::account-id:oidc-provider/provider-name。oidc-token-file-path
oidcTokenFilePath
oidc_token_file_path
指定OIDC令牌的檔案路徑，用於儲存OIDC令牌。
credential-process-timeout
credentialProcessTimeout
credential_process_timeout
用於指定外部憑證請求的逾時時間，單位為秒。預設值為15即指定15秒；最大值為600即指定10分鐘；
credential-process-timeout = 60即指定60秒的逾時時間。自 2.0.3 版本起支援。 -
全域參數
參數名
別名
含義
region
/
地區ID，必須設定。
loglevel
/
記錄層級 。取值：
-
off（預設值）
-
info
-
debug
read-timeout
readTimeout
read_timeout
用戶端讀寫請求逾時時間。單位為秒，預設值20。
connect-timeout
connectTimeout
connect_timeout
用戶端連線逾時的時間。單位為秒，預設值10。
retry-times
retryTimes
retry_times
當錯誤發生時的重試次數。預設值10。
skip-verify-cert
skipVerifyCert
skip_verify_cert
不校正服務端的數位憑證。
sign-version
signVersion
sign_version
請求使用的簽名演算法版本。取值：
-
v1
-
v4（預設值）
output-format
outputFormat
output_format
輸出格式。取值：
-
raw（預設值）
-
json
-
xml
-
yaml
addressing-style
addressingStyle
addressing_style
請求地址的格式 。取值：
-
virtual（預設值）
-
path
-
cname
language
/
顯示的語言。
endpoint
/
對外服務的訪問網域名稱，可不設定。
-
-
其它參數
參數名
別名
含義
source-profile
sourceProfile
source_profile
引用指定profile裡的參數，例如：
[profile cred] access-key-id=ak access-key-secret=sk [profile dev] region=cn-hangzhou source-profile=credbuckets
/
引用指定buckets裡的參數。
[profile dev] region=cn-hangzhou access-key-id=ak access-key-secret=sk buckets=dev-bucket [buckets dev-bucket] bucket-name-hz = endpoint=oss-cn-hangzhou-internal.aliyuncs.com bucket-name-bj = region=cn-beijingendpoint-suffix-list-path-style
/
指定自動使用 path-style 請求模式的 Endpoint 尾碼列表，多個尾碼以英文逗號（
,）分隔。自 2.2.0 版本起支援。樣本1：
endpoint-suffix-list-path-style=DEFAULT樣本2：
endpoint-suffix-list-path-style=DEFAULT,.path-style.comDEFAULT：表示內建的預設列表，當前為 .privatelink.aliyuncs.com
節類型：buckets
用於配置特定Bucket和訪問點的映射關係。支援嵌套寫法，即buckets節按bucket-name = 行分成多個小節。格式如下：
[buckets name]
bucket-name =
key=value其中，name為該buckets節的名字，bucket-name為具體的Bucket名字，key=value配置參數，支援的參數如下：
|
參數名 |
別名 |
含義 |
|
region |
/ |
資料中心所在的地區。 當不設定時，使用引入該參數的profile裡的region值。 |
|
endpoint |
/ |
對外服務的訪問網域名稱，可不設定。 |
|
addressing-style |
addressingStyle addressing_style |
請求地址的格式。取值： virtual（預設值）：使用Bucket虛擬網域名稱請求地址格式。 path：使用path style請求地址格式。 cname：使用cname請求地址格式。 |
節類型buckets樣本如下：
[buckets dev-bucket]
bucket-hz-01 =
region=cn-hangzhou
bucket-hz-02 =
region=cn-hangzhou
endpoint=test.com
addressing-style=cname
bucket-bj-01 =
region=cn-beijing配置環境變數
可以參照以下步驟配置環境變數。
Linux系統
-
在命令列介面執行以下命令來將環境變數設定追加到
~/.bashrc檔案中。echo "export OSS_ACCESS_KEY_ID='your-access-key-id'" >> ~/.bashrc echo "export OSS_ACCESS_KEY_SECRET='your-access-key-secret'" >> ~/.bashrc -
執行以下命令使變更生效。
source ~/.bashrc -
執行以下命令檢查環境變數是否生效。
echo $OSS_ACCESS_KEY_ID echo $OSS_ACCESS_KEY_SECRET
macOS系統
-
在終端中執行以下命令，查看預設Shell類型。
echo $SHELL -
根據預設Shell類型進行操作。
Zsh
-
執行以下命令來將環境變數設定追加到
~/.zshrc檔案中。echo "export OSS_ACCESS_KEY_ID='your-access-key-id'" >> ~/.zshrc echo "export OSS_ACCESS_KEY_SECRET='your-access-key-secret'" >> ~/.zshrc -
執行以下命令使變更生效。
source ~/.zshrc -
執行以下命令檢查環境變數是否生效。
echo $OSS_ACCESS_KEY_ID echo $OSS_ACCESS_KEY_SECRET
Bash
-
執行以下命令來將環境變數設定追加到
~/.bash_profile檔案中。echo "export OSS_ACCESS_KEY_ID='your-access-key-id'" >> ~/.bash_profile echo "export OSS_ACCESS_KEY_SECRET='your-access-key-secret'" >> ~/.bash_profile -
執行以下命令使變更生效。
source ~/.bash_profile -
執行以下命令檢查環境變數是否生效。
echo $OSS_ACCESS_KEY_ID echo $OSS_ACCESS_KEY_SECRET
-
Windows系統
-
在CMD中運行以下命令。
setx OSS_ACCESS_KEY_ID "your-access-key-id" setx OSS_ACCESS_KEY_SECRET "your-access-key-secret" -
開啟一個新的CMD視窗。
-
在新的CMD視窗運行以下命令，檢查環境變數是否生效。
echo %OSS_ACCESS_KEY_ID% echo %OSS_ACCESS_KEY_SECRET%
當前支援配置的環境變數如下：
|
環境變數名 |
對應的參數名 |
|
OSS_ACCESS_KEY_ID |
access-key-id |
|
OSS_ACCESS_KEY_SECRET |
access-key-secret |
|
OSS_SESSION_TOKEN |
sts-token |
|
OSS_ROLE_ARN |
ram-role-arn |
|
OSS_ROLE_SESSION_NAME |
role-session-name |
|
OSS_REGION |
region |
|
OSS_ENDPOINT |
endpoint |
|
OSSUTIL_CONFIG_FILE |
config-file |
|
OSSUTIL_PROFILE |
profile |
配置命令列選項
ossutil提供了多個命令列選項，支援配置全域命令列選項。命令列選項的優先順序最高，可以覆蓋設定檔設定或環境變數設定的參數。
通過命令列選項需要傳入存取金鑰，可能會被日誌系統記錄，存在密鑰泄露的風險，請謹慎使用。
ossutil ls oss://examplebucket -i "your-access-key-id" -k "your-access-key-secret" --region cn-hangzhou訪問憑證配置
使用 RAM 使用者的 AK
如果應用程式部署運行在安全、穩定且不易受外部攻擊的環境中，需要長期訪問的OSS，且不能頻繁輪轉憑證時，可以使用阿里雲主帳號或RAM使用者的AK（Access Key ID、Access Key Secret）初始化憑證提供者。需要注意的是，該方式需要手動維護一個AK，存在安全性風險和維護複雜度增加的風險。
設定檔
產生如下設定檔，並儲存在~/.ossutilconfig。
[default]
accessKeyID = yourAccessKeyID
accessKeySecret = yourAccessKeySecret
region=ap-southeast-1通過如下命令查詢examplebucket中的對象。
ossutil ls oss://examplebucket -c ~/.ossutilconfig環境變數
export OSS_ACCESS_KEY_ID=yourAccessKeyID
export OSS_ACCESS_KEY_SECRET=yourAccessKeySecret
ossutil ls oss://examplebucket命令列選項
通過如下命令查詢examplebucket中的對象。
ossutil ls oss://examplebucket -i yourAccessKeyID -k yourAccessKeySecret使用STS臨時訪問憑證
如果應用程式需要臨時訪問OSS，可以使用通過STS服務擷取的臨時身份憑證（Access Key ID、Access Key Secret和Security Token）初始化憑證提供者。需要注意的是，該方式需要手動維護一個STS Token，存在安全性風險和維護複雜度增加的風險。此外，如果需要多次臨時訪問OSS，需要手動重新整理STS Token。
設定檔
產生如下的設定檔，並儲存在~/.ossutilconfig。
[default]
accessKeyID = yourSTSAccessKeyID
accessKeySecret = yourSTSAccessKeySecret
stsToken = yourSecurityToken
region=ap-southeast-1通過如下命令查詢examplebucket中的對象。
ossutil ls oss://examplebucket -c ~/.ossutilconfig環境變數
export OSS_ACCESS_KEY_ID=yourSTSAccessKeyID
export OSS_ACCESS_KEY_SECRET=yourSTSAccessKeySecret
export OSS_SESSION_TOKEN=yourSecurityToken
ossutil ls oss://examplebucket命令列選項
通過如下命令查詢examplebucket中的對象。
ossutil ls oss://examplebucket -i yourSTSAccessKeyID -k yourSTSAccessKeySecret -t yourSecurityToken --region cn-hangzhou使用RAMRoleARN
如果應用程式需要授權訪問OSS，例如跨阿里雲帳號訪問OSS，可以使用RAMRoleARN初始化憑證提供者。該方式底層實現是STS Token。通過指定RAM角色的ARN（Alibabacloud Resource Name），Credentials工具會前往STS服務擷取STS Token，並在會話到期前調用AssumeRole介面申請新的STS Token。此外，還可以通過為policy賦值來限制RAM角色到一個更小的許可權集合。
-
阿里雲帳號擁有資源的全部許可權，AK一旦泄露，會給系統帶來巨大風險，不建議使用。推薦使用最小化授權的RAM使用者的AK。
-
如需建立RAM使用者的AK，請直接存取建立AccessKey。RAM使用者的Access Key ID、Access Key Secret資訊僅在建立時顯示，請及時儲存，如若遺忘請考慮建立新的AK進行輪換。
-
如需擷取RAMRoleARN，請直接存取建立角色。
產生如下設定檔，並儲存在~/.ossutilconfig。不支援通過環境變數或者命令列選項方式設定。
[default]
accessKeyID = yourAccessKeyID
accessKeySecret = yourAccessKeySecret
mode = RamRoleArn
roleArn = acs:ram::137918634953****:role/Alice
roleSessionName = session_name_example
region=ap-southeast-1通過如下命令查詢examplebucket中的對象。
ossutil ls oss://examplebucket -c ~/.ossutilconfig使用ECSRAMRole
如果應用程式運行在ECS執行個體、ECI執行個體、Container ServiceKubernetes版的Worker節點中，建議使用ECSRAMRole初始化憑證提供者。該方式底層實現是STS Token。ECSRAMRole允許將一個角色關聯到ECS執行個體、ECI執行個體或Container Service Kubernetes 版的Worker節點，實現在執行個體內部自動重新整理STS Token。該方式無需提供一個AK或STS Token，消除了手動維護AK或STS Token的風險。如何擷取ECSRAMRole，請參見建立角色。
不支援通過環境變數方式設定。
EcsRamRole模式
設定檔
產生如下設定檔，並儲存在~/.ossutilconfig。
[default]
mode = EcsRamRole
# ecsRoleName可以不設定，當不設定時，自動擷取。
ecsRoleName = EcsRamRoleOss
region=ap-southeast-1通過如下命令查詢examplebucket中的對象。
ossutil ls oss://examplebucket -c ~/.ossutilconfig命令列工具
通過如下命令查詢examplebucket中的對象。
ossutil ls oss://examplebucket --mode EcsRamRoleEcsRamRole IMDSv2模式
從 2.2.0 版本開始，支援 EcsRamRole IMDSv2 模式。
設定檔
產生如下設定檔，並儲存在~/.ossutilconfig。
[default]
mode = Ali-EcsRamRole
# ecsRoleName可以不設定，當不設定時，自動擷取。
ecsRoleName = EcsRamRoleOss
region=ap-southeast-1通過如下命令查詢examplebucket中的對象。
ossutil ls oss://examplebucket -c ~/.ossutilconfig命令列工具
通過如下命令查詢examplebucket中的對象。
ossutil ls oss://examplebucket --mode Ali-EcsRamRole使用OIDCRoleARN
在Container ServiceKubernetes版中設定了Worker節點RAM角色後，對應節點內的Pod中的應用也就可以像ECS上部署的應用一樣，通過中繼資料服務（Meta Data Server）擷取關聯角色的STS Token。但如果容器叢集上部署的是不可信的應用（比如部署的客戶提交的應用，代碼也沒有對開放），可能並不希望它們能通過中繼資料服務擷取Worker節點關聯執行個體RAM角色的STS Token。為了避免影響雲上資源的安全，同時又能讓這些不可信的應用安全地擷取所需的STS Token，實現應用層級的許可權最小化，可以使用RRSA（RAM Roles for Service Account）功能。該方式底層實現是STS Token。阿里雲容器叢集會為不同的應用Pod建立和掛載相應的服務賬戶OIDC Token檔案，並將相關配置資訊注入到環境變數中，Credentials工具通過擷取環境變數的配置資訊，調用STS服務的AssumeRoleWithOIDC介面換取綁定角色的STS Token。該方式無需提供一個AK或STS Token，消除了手動維護AK或STS Token的風險。詳情請參見通過RRSA配置ServiceAccount的RAM許可權實現Pod許可權隔離。
產生如下的設定檔，並儲存在~/.ossutilconfig。不支援通過環境變數或者命令列選項方式設定。
[default]
mode = oidcRoleArn
#指定 OIDC 提供者的 ARN（Aliyun Resource Name），格式為 acs:ram::account-id:oidc-provider/provider-name。
OIDCProviderArn=acs:ram::113511544585****:oidc-provider/TestOidcProvider
#指定 OIDC 令牌的檔案路徑，用於儲存 OIDC 令牌
OIDCTokenFilePath=OIDCTokenFilePath
#填寫角色的ARN資訊，即需要扮演的角色ID。格式為acs:ram::113511544585****:oidc-provider/TestOidcProvider
roleArn=acs:ram::113511544585****:role/testoidc
# 自訂角色會話名稱，用於區分不同的令牌。
roleSessionName= TestOidcAssumedRoleSession
region=ap-southeast-1通過如下命令查詢examplebucket中的對象。
ossutil ls oss://examplebucket -c ~/.ossutilconfig外部進程擷取憑證
ossutil通過外部命令啟動一個進程，該進程與ossutil進程是獨立的，稱為外部進程。外部進程執行後，通過標準輸出把結果返回給進程的啟動者，即ossutil。可以通過外部進程擷取憑證。
-
產生憑證的命令不可由未經獲批准的進程或使用者訪問，否則可能存在安全風險。
-
產生憑證的命令不會把任何秘密資訊寫入stderr或stdout，因為該資訊可能會被捕獲或記錄，可能會將其向未經授權的使用者公開。
外部命令返回的憑證，支援長期憑證和臨時憑證，格式如下。
長期憑證
{
"AccessKeyId" : "ak",
"AccessKeySecret" : "sk"
}臨時憑證
{
"AccessKeyId" : "ak",
"AccessKeySecret" : "sk",
"Expiration" : "2023-12-29T07:45:02Z",
"SecurityToken" : "token"
}產生如下設定檔，並儲存在~/.ossutilconfig。不支援通過環境變數或者命令列選項方式設定。
[default]
mode = Process
credentialProcess = user-cmd
region=ap-southeast-1通過如下命令查詢examplebucket中的對象。
ossutil ls oss://examplebucket -c ~/.ossutilconfig匿名訪問
如果只需要訪問公用讀取許可權的OSS資源，可以使用匿名訪問方式，無需提供任何憑證。
ossutil cat oss://bucket/public-object --mode Anonymous命令參考
ossutil提供了進階命令、API級命令、輔助命令等三類命令。
命令結構
ossutil常用命令格式如下：
ossutil command [argument] [flags]
ossutil command subcommond [argument] [flags]
ossutil topic-
argument：參數，為字串。
-
flags：選項，支援短名字風格
-o[=value]/ -o [ value]和長名字風格--options[=value]/--options[ value]。如果多次指定某個排它參數，則僅最後一個值生效。
命令樣本如下：
-
命令：
ossutil cat oss://bucket/object -
多級命令：
ossutil api get-bucket-cors --bucket bucketexample -
說明主題：
ossutil filter
命令列表
ossutil 提供了三類命令：
-
進階命令
用於常用的儲存空間或者對象的操作環境，例如儲存空間建立、刪除、資料拷貝、對象屬性修改等。
命令名
含義
建立儲存空間
刪除儲存空間
擷取儲存或者指定首碼所佔的儲存空間大小
顯示儲存空間或者對象的描述資訊
建立一個名字有尾碼字元
/的對象將內容上傳到追加類型的對象末尾
將對象內容串連到標準輸出
列舉儲存空間或者對象
上傳、下載或拷貝對象
刪除儲存空間裡的對象
設定對象的屬性
產生對象的預簽名URL
恢複冷凍狀態的對象為可讀狀態
將對象恢複成指定的版本
將本地檔案目錄或者對象從源端同步到目的端
計算檔案/對象的雜湊值
-
API級命令，提供了API操作的直接存取，支援該介面的配置參數。
說明僅列舉部分命令，可以通過
ossutil api -h查看所有命令。命令名
含義
設定、修改Bucket的存取權限
擷取存取權限
....
設定跨域資源共用規則
擷取跨域資源共用規則
刪除跨域資源共用規則
-
輔助命令，例如設定檔的配置、額外的說明主題等。
命令名
含義
擷取協助資訊
建立設定檔用以儲存配置項和訪問憑證
版本更新
顯示版本資訊
探測命令
命令選項類型
|
選項類型 |
選項 |
說明 |
|
字串 |
--option string |
例如：--acl private。 |
|
布爾值 |
--option |
開啟或關閉某一選項。 例如：--dry-run。 |
|
整數 |
--option Int |
不帶正負號的整數。 例如：--read-timeout 10。 |
|
時間戳記 |
--option Time |
ISO 8601格式，即DateTime或Date。 例如：--max-mtime 2006-01-02T15:04:05。 |
|
位元組單位尾碼 |
--option SizeSuffix |
預設單位是位元組（B），也可以使用單位尾碼形式，支援的單位尾碼為：K（KiB）=1024位元組、M（MiB）、G（GiB）、G（GiB）、T（TiB）、P（PiB）、E（EiB） 例如：最小size為1024位元組 --min-size 1024 --min-size 1K |
|
時間單位尾碼 |
--option Duration |
時間單位，預設單位是秒。支援的單位尾碼為：ms 毫秒，s 秒，m 分鐘，h 小時，d 天，w 星期，M 月，y 年。 支援小數。例如：1.5天 --min-age 1.5d |
|
字串列表 |
--option strings |
支援單個或者多個同名選項，支援以逗號（,）分隔的多個值。 支援多選項輸入的單值。 例如：--metadata user=jack,email=ja**@test.com --metadata address=china |
|
字串數組 |
--option stringArray |
支援單個或者多個同名選項，只支援多選項輸入的單值。 例如 ：--include *.jpg --include *.txt。 |
從非命令列中載入資料
一般情況下，參數的值都放在命令列裡，當參數值比較複雜時，需要從檔案載入參數值；當需要串聯多個命令操作時，需要標準輸中載入參數值。所以，對需要支援多種載入參數值的參數，做了如下約定：
-
以
file://開始的，表示從檔案路徑中載入。 -
當參數值為
-時，表示從標準輸入中載入。
例如， 設定儲存空間的跨網域設定，以JSON參數格式為例，通過檔案方式載入跨域參數。cors-configuration.json檔案如下：
{
"CORSRule": {
"AllowedOrigin": ["www.aliyun.com"],
"AllowedMethod": ["PUT","GET"],
"MaxAgeSeconds": 10000
}
}ossutil api put-bucket-cors --bucket examplebucket --cors-configuration file://cors-configuration.json通過選項參數值載入跨域參數，cors-configuration.json的緊湊形式如下：
{"CORSRule":{"AllowedOrigin":["www.aliyun.com"],"AllowedMethod":["PUT","GET"],"MaxAgeSeconds":10000}}ossutil api put-bucket-cors --bucket examplebucket --cors-configuration "{\"CORSRule\":{\"AllowedOrigin\":[\"www.aliyun.com\"],\"AllowedMethod\":[\"PUT\",\"GET\"],\"MaxAgeSeconds\":10000}}"從標準輸入載入參數的樣本如下：
cat cors-configuration.json | ossutil api put-bucket-cors --bucket examplebucket --cors-configuration -控制命令輸出
輸出格式
對ossutil api下的子命令，以及du、stat命令，支援通過--output-format參數調整其輸出格式，當前支援的格式如下：
|
格式名稱 |
說明 |
|
raw |
以原始方式輸出，即服務端返回什麼內容，則輸出什麼內容。 |
|
json |
輸出採用JSON字串的格式。 |
|
yaml |
輸出採用YAML字串的格式。 |
|
xml |
輸出採用XML字串的格式。 |
例如：以get-bucket-cors為例，原始內容如下：
ossutil api get-bucket-cors --bucket bucketexample
<?xml version="1.0" encoding="UTF-8"?>
<CORSConfiguration>
<CORSRule>
<AllowedOrigin>www.aliyun.com</AllowedOrigin>
<AllowedMethod>PUT</AllowedMethod>
<AllowedMethod>GET</AllowedMethod>
<MaxAgeSeconds>10000</MaxAgeSeconds>
</CORSRule>
<ResponseVary>false</ResponseVary>
</CORSConfiguration>轉成JSON如下：
ossutil api get-bucket-cors --bucket bucketexample --output-format json
{
"CORSRule": {
"AllowedMethod": [
"PUT",
"GET"
],
"AllowedOrigin": "www.aliyun.com",
"MaxAgeSeconds": "10000"
},
"ResponseVary": "false"
}篩選輸出
ossutil提供了基於JSON的內建用戶端篩選功能，通過--output-query value選項使用。
該選項僅支援ossutil api下的子命令。
該功能基於JMESPath文法，當使用該功能時，會把返回的內容轉成JSON，然後再使用JMESPath進行篩查，最後按照指定的輸出格式輸出。有關JMESPath 文法的說明，請參見JMESPath Specification。
例如：以get-bucket-cors為例，只輸出AllowedMethod內容，樣本如下：
ossutil api get-bucket-cors --bucket bucketexample --output-query CORSRule.AllowedMethod --output-format json
[
"PUT",
"GET"
]友好顯示
對於進階命令（du、stat），提供了--human-readable選項，對位元組、數量資料，提供了以人類可讀方式輸出資訊。即位元組資料轉成Ki|Mi|Gi|Ti|Pi尾碼格式（1024 base），數量資料轉成k|m|g|t|p尾碼格式(1000 base)。
例如：原始模式
ossutil stat oss://bucketexample
ACL : private
AccessMonitor : Disabled
ArchiveObjectCount : 2
ArchiveRealStorage : 10
ArchiveStorage : 131072
...
StandardObjectCount : 119212
StandardStorage : 66756852803
Storage : 66756852813
StorageClass : Standard
TransferAcceleration : Disabled友好模式
ossutil stat oss://bucketexample --human-readable
ACL : private
AccessMonitor : Disabled
ArchiveObjectCount : 2
ArchiveRealStorage : 10
ArchiveStorage : 131.072k
...
StandardObjectCount : 119.212k
StandardStorage : 66.757G
Storage : 66.757G
StorageClass : Standard
TransferAcceleration : Disabled命令返回碼
通過進程等方式調用ossutil時，無法即時查看回顯資訊。ossutil支援在進程運行結束後，根據不同的運行結果產生不同的返回碼，具體的返回碼及其含如下。可以通過以下方式擷取最近一次運行結果的返回碼，然後根據返回碼分析並處理問題。
Linux
執行命令擷取返回碼：echo $?。
Windows
執行命令擷取返回碼：echo %errorlevel%。
macOS
執行命令擷取返回碼：echo $?。
|
返回碼 |
含義 |
|
0 |
命令操作成功，發送到服務端的請求執行正常，服務端返回200響應。 |
|
1 |
參數錯誤，例如缺少必需的子命令或參數，或使用了未知的命令或參數。 |
|
2 |
該命令已成功解析，並已對指定服務發出了請求，但該服務返回了錯誤（非2xx響應）。 |
|
3 |
調用OSS GO SDK時，遇到的非服務端錯誤。 |
|
4 |
大量操作時，例如cp、rm部分請求發生了錯誤。 |
|
5 |
中斷錯誤。命令執行過程中，通過ctrl +c取消某個命令。 |
命令列選項
在命令列操作中，部分命令需要附加參數以指定操作對象或設定選項，而其他命令則不需要參數。對於帶參數的命令，可以根據具體要求提供適當的參數值，以實現預期功能，例如，帶參數的命令如：
ossutil ls --profile devossutil ls --profile dev允許使用者通過參數值dev指定特定的設定檔。帶參數的選項通常需要通過空格或等號（=）將選項名稱與參數值分隔，例如--profile dev或--profile=dev。當參數值包含空格時，必須使用雙引號將整個參數值括起來，以確保命令正確解析，例如 --description "OSS bucket list"。
全域命令列選項
|
參數 |
類型 |
說明 |
|
-i, --access-key-id |
string |
訪問OSS使用的AccessKey ID。 |
|
-k, --access-key-secret |
string |
訪問OSS使用的AccessKey Secret。 |
|
--addressing-style |
string |
請求地址的格式。取值範圍如下：
|
|
-c, --config-file |
string |
設定檔的路徑。 預設值為 |
|
--connect-timeout |
int |
用戶端連線逾時的時間。單位為秒，預設值為10。 |
|
-n, --dry-run |
/ |
在不進行任何更改的情況下執行試運行。 |
|
-e, --endpoint |
string |
對外服務的訪問網域名稱。 |
|
-h, --help |
/ |
顯示協助資訊。 |
|
--language |
string |
顯示的語言。 |
|
--loglevel |
string |
記錄層級。取值範圍如下：
|
|
--mode |
string |
鑒權模式。取值：
|
|
--output-format |
string |
輸出格式，預設值為raw。 |
|
--output-query |
string |
JMESPath查詢條件。 |
|
--profile |
string |
指定設定檔裡的profile。 |
|
-q, --quiet |
/ |
安靜模式，列印儘可能少的資訊。 |
|
--read-timeout |
int |
用戶端讀寫請求逾時時間。單位為秒，預設值為20。 |
|
--region |
string |
資料中心所在的地區，配置值可設定為cn-hangzhou。 |
|
--retry-times |
int |
當錯誤發生時的重試次數。預設值為10。 |
|
--sign-version |
string |
請求使用的簽名演算法版本。取值：
|
|
--skip-verify-cert |
/ |
表示不校正服務端的數位憑證。 |
|
-t, --sts-token |
string |
訪問OSS使用的STS Token。 |
|
--proxy |
string |
指定Proxy 伺服器。自 2.0.1 版本起支援。 配置值可以為以下幾種：
|
|
--log-file |
string |
指定日誌輸出檔案，自 2.0.1 版本起支援。配置值為：
如果未指定日誌輸出檔案，輸出到預設設定檔上。 |
|
--cloudbox-id |
string |
雲盒ID，應用於雲盒情境。自 2.1.0 版本起支援。 |
|
--ignore-env-var |
/ |
忽略所有以 |
|
--bind-address |
string |
指定出站串連所綁定的本地 IP 位址（支援 IPv4、IPv6）。自2.2.0 版本起支援。 |
|
--account-id |
string |
帳號ID，用於向量 Bucket 情境中的身份識別與資源歸屬判斷。自 2.2.0 版本起支援。 |
|
--user-agent |
string |
在預設的 User-Agent 末尾追加指定的值。自 2.2.2 版本起支援。 |
常用命令列選項
|
命令範圍 |
支援的選項 |
|
所有進階命令 |
|
|
支援大量操作的命令 |
|
|
支援目的過濾規則的命令 |
|
|
支援單個對象的命令 |
--version-id string：對象的版本標識。 |
|
支援列表模式的命令 |
--list-format：列表檔案的格式，取值：plain、inventory。 --list-manifest-from：從檔案中讀取列表檔案格式的描述資訊，當列表檔案格式為inventory時，需要設定該參數。 |
常見問題
使用ossutil執行相關命令時，報錯region must be set in sign version 4
問題原因：在配置ossutil2.0時沒有配置地區ID項。
解決方案：為避免在使用ossutil時因配置項缺失導致操作失敗，請確保按照以下步驟配置必要的基礎項：AccessKey ID、AccessKey Secret、地區ID。特別是地區ID，由於簽名已升級到V4版本，因此成為必需項。關於如何擷取地區ID，請參見地區和Endpoint。