全部產品
Search

搜尋本產品

    Object Storage Service：配置ossutil

    文件中心

    Object Storage Service：配置ossutil

    更新時間：Nov 28, 2025

    本文介紹ossutil的一些配置操作，您可以通過本文瞭解如何更好地使用ossutil。

    版本升級

    推薦您使用全新升級的ossutil2.0，快速安裝並使用，請參見安裝ossutil。

    ossutil2.0重點功能如下：

    • 全新的命令組織圖：引入了多級命令支援，包括API級命令（例如ossutil api put-bucket-acl）和進階命令（如ossutil config）。

    • 改進的組態管理機制：簡化了初始配置流程，使用者僅需提供AccessKey ID、AccessKey Secret及地區ID即可完成安裝後的基礎配置，並且支援通過--profile參數指定多個設定檔，增強了靈活性。

    • 豐富的過濾參數：對於批量處理命令（如ls、cp、rm等），新增了基於路徑、檔案大小、修改時間以及對象中繼資料等多種過濾條件的支援，極大地提升了操作的精確性和效率。

    • 靈活的輸出格式調整：新增--output-format參數，允許使用者將輸出格式設定為JSON、YAML或XML，以便更好地適配不同的資料處理需求；同時引入了--output-query選項，讓使用者能夠對輸出內容進行篩選，擷取所需資訊。

    • 安全性增強：為了提高安全性，ossutil 2.0支援通過環境變數設定敏感參數，避免在命令列中直接暴露密鑰，減少了泄露風險；此外，新增的--dry-run選項使使用者能夠在實際執行命令前驗證其行為，確保操作無誤。

    通過config命令進行快速配置

    對於大多數情況，通過該命令可以快速設定您的ossutil工具。該命令提供了互動式方式組建組態檔案。

    以Linux環境為例進行說明。

    1. 輸入配置命令。

      ossutil config

    2. 根據提示設定設定檔路徑。

      您可以根據實際需要設定設定檔的路徑。預設情況下，設定檔儲存到~/.ossutilconfig檔案裡， 直接按斷行符號則使用預設配置。

      請輸入設定檔名，檔案名稱可以帶路徑（預設為：/home/user/.ossutilconfig，斷行符號將使用預設路徑。 如果使用者佈建為其他路徑，在使用命令時需要將--config-file選項設定為該路徑）：

    3. 根據提示設定工具的語言。

      請輸入語言CH或EN。工具使用的語言預設與作業系統保持一致。該配置項將在此次config命令設定成功後生效。

    4. 根據提示分別設定Endpoint、AccessKey ID、AccessKey Secret和STSToken參數。使用STS臨時授權帳號訪問OSS時需要配置STSToken，否則置空跳過即可。

      參數說明如下：

      參數

      是否必填

      說明

      endpoint

      是

      填寫Bucket所在地區的Endpoint。例如，本樣本使用新加坡外網Endpoint，設定為https://oss-ap-southeast-1.aliyuncs.com。

      如果希望通過與OSS同地區的其他阿里雲產品訪問OSS，請使用內網Endpoint，設定為https://oss-ap-southeast-1-internal.aliyuncs.com。

      關於各地區Endpoint的更多資訊，請參見地區和Endpoint。

      重要

      根據策略調整，為提升OSS服務的合規性和安全性，自2025年3月20日起，新開通OSS服務的使用者在中國內地地區的Bucket將無法通過預設外網網域名稱調用資料操作類API（如上傳、下載檔案），需通過自訂網域名（CNAME）方式訪問OSS服務。使用HTTPS協議訪問（如控制台）時，還需為自訂網域名配置SSL認證。

      accessKeyID

      是

      填寫帳號的AccessKey，AccessKey的擷取方式，請參見建立AccessKey。

      使用ROS指令碼快速建立有OSS系統管理權限的RAM使用者AccessKey

      在Resource Orchestration Service控制台的建立資源棧頁面的安全確認下，勾選確認，然後單擊建立。

      1.png

      建立完成後，在輸出中，複製建立的AccessKey。

      image

      accessKeySecret

      是

      stsToken

      否

      使用STS臨時授權帳號訪問OSS時需要配置該項，否則置空跳過即可。關於stsToken的產生方式，請參見AssumeRole - 擷取扮演角色的臨時身份憑證。

    5. 如果在步驟2設定了設定檔的路徑，則每次使用命令時需增加-c選項指定設定檔。

      例如，設定檔儲存為/home/config，使用ls時，命令格式如下：

      ossutil -c /home/config ls oss://examplebucket

    命令設定檔

    您可以將常用的憑證資訊和配置資訊儲存到設定檔裡，以方便使用。設定檔採用了INI格式結構，以節（section）和鍵（key）構成， 配置參數儲存在指定的節裡。常用的配置參數如下：

    配置參數

    說明

    範例程式碼

    language

    設定ossutil工具的語言。取值：

    • CH：中文。

    • EN：英文。

    [Credentials]
language = CH

    endpoint

    設定Bucket所在地區的網域名稱資訊。

    • [Credentials]
endpoint  = oss-ap-southeast-1.aliyuncs.com
    • [Credentials]
endpoint  = https://oss-ap-southeast-1.aliyuncs.com

    accessKeyID

    存取金鑰的一部分，用於標識使用者身份，以對命令請求進行身分識別驗證。

    [Credentials]
accessKeyID = your_accesskey_id

    accessKeySecret

    存取金鑰的一部分，用於驗證使用者的密鑰，以對命令請求進行身分識別驗證。

    [Credentials]
accessKeySecret = your_accesskey_secret

    stsToken

    臨時密鑰的Token，以對命令請求進行身分識別驗證。

    [Credentials]
stsToken = your_sts_token

    mode

    採用的鑒權模式，取值可以為AK、StsToken、RamRoleArn或者EcsRamRole。

    [Credentials]
mode = RamRoleArn

    ramRoleArn

    鑒權模式下的RAM角色ARN。

    [Credentials]
ramRoleArn = your_ram_role_arn

    roleSessionName

    鑒權模式下的會話名稱，用於RamRoleArn模式。不設定時，會產生隨機值。

    [Credentials]
roleSessionName = your_ram_role_seesion_name

    tokenTimeout

    表示Token的有效時間，單位為秒，預設值為3600，用於RamRoleArn模式。

    [Credentials]
tokenTimeout = your_token_timetout

    ecsRoleName

    EcsRamRole鑒權模式下的角色名稱。

    [Credentials]
ecsRoleName = your_ecs_role_name

    更多命令配置參數，請參見編輯設定檔。

    命令列選項

    除了通過命令設定檔外，您還可以使用命令列參數設定相關的配置。命令列選項的優先順序要高於命令設定檔。常用命令列選項如下：

    選項

    說明

    範例程式碼

    --loglevel

    記錄層級，預設為空白，表示不輸出記錄檔。取值：

    • info：輸出提示資訊日誌。

    • debug：輸出詳細資料日誌（包括HTTP請求和響應資訊）。

    ossutil64 commandname options --loglevel debug

    --connect-timeout

    表示用戶端連線逾時的時間，單位為秒，預設值為120。

    ossutil64 commandname options --connect-timeout 60

    --read-timeout

    表示用戶端讀逾時的時間，單位為秒，預設值為1200。

    ossutil64 commandname options --read-timeout 60

    --retry-times

    當錯誤發生時的重試次數，預設值為10。

    ossutil64 commandname options --retry-times 20

    -e, --endpoint

    請求的網域名稱。

    • ossutil64 commandname options -e oss-ap-southeast-1.aliyuncs.com
    • ossutil64 commandname options -e https://oss-ap-southeast-1.aliyuncs.com

    -i, --access-key-id

    訪問OSS使用的訪問憑證。

    ossutil64 commandname options -i your_access_key

    -k, --access-key-secret

    訪問OSS使用的訪問憑證。

    ossutil64 commandname options -k your_access_key_secrect

    -t, --sts-token

    訪問OSS使用的STSToken。

    ossutil64 commandname options -i your_sts_token_accesskey_id -k your_sts_token_accesskey_secret -t your_sts_token

    --mode

    表示鑒權模式，取值可以為AK、StsToken、RamRoleArn、EcsRamRole，預設值為空白。

    使用AK模式訪問的範例程式碼如下：

    ossutil64 commandname options -i your_accesskey_id -k your_accesskey_secret --mode AK

    --ram-role-arn

    鑒權模式下的RAM角色ARN。

    ossutil64 commandname options --ram-role-arn your_ram_role_arn

    --role-session-name

    鑒權模式下的會話名字。

    ossutil64 commandname options --role-session-name your_ram_session_name

    --token-timeout

    表示Token的有效時間，單位為秒，預設值為3600。 

    ossutil64 commandname options --token-timeout 1800

    --ecs-role-name

    EcsRamRole鑒權模式下的角色名稱。

    ossutil64 commandname options --ecs-role-name your_ecs_role_name

    更多選項配置，請參見通用選項。

    配置訪問憑證

    您可以使用多種方式，通過設定檔或者命令列選項配置訪問憑證。

    使用存取金鑰訪問

    以新加坡地區名稱為example-bucket的Bucket為例進行說明。

    • 通過設定檔

      產生如下的設定檔，並儲存在~/.myossutilconfig。

      [Credentials]
endpoint = oss-ap-southeast-1.aliyuncs.com
accessKeyID = yourAccessKeyID
accessKeySecret = yourAccessKeySecret

      通過如下命令查詢Bucket中的對象。

      ossutil64 -c ~/.myossutilconfig ls oss://example-bucket

    • 通過命令列選項

      您也可以直接將存取金鑰通過命令列參數傳入，範例程式碼如下：

      ossutil64 -e oss-ap-southeast-1.aliyuncs.com -i yourAccessKeyID -k yourAccessKeySecret ls oss://example-bucket
      重要

      通過命令列參數需要傳入存取金鑰，可能會被日誌系統記錄，存在密鑰泄露的風險，請謹慎使用。

    使用臨時Token訪問

    以新加坡地區名稱為example-bucket的Bucket為例進行說明。

    • 通過設定檔

      產生如下的設定檔，並儲存在~/.myossutilconfig。

      [Credentials]
endpoint = oss-ap-southeast-1.aliyuncs.com
accessKeyID = yourAccessKeyID
accessKeySecret = yourAccessKeySecret
stsToken = yourSecurityToken

      通過如下命令查詢Bucket中的對象。

      ossutil64 -c ~/.myossutilconfig ls oss://example-bucket

    • 通過命令列選項

      您也可以直接將存取金鑰通過命令列參數傳入，範例程式碼如下：

      ossutil64 -e oss-ap-southeast-1.aliyuncs.com -i yourAccessKeyID -k yourAccessKeySecret -t yourSecurityToken ls oss://example-bucket
      說明

      通過命令列參數需要傳入存取金鑰，可能會被日誌系統記錄，存在密鑰泄露的風險，請謹慎使用。

    使用RAM角色訪問

    以新加坡地區名稱為example-bucket的Bucket，需要扮演的角色為ramRoleArnExample為例進行說明。

    • 通過設定檔

      產生如下的設定檔，並儲存在~/.myossutilconfig。

      [Credentials]
endpoint = oss-ap-southeast-1.aliyuncs.com
accessKeyID = yourAccessKeyID
accessKeySecret = yourAccessKeySecret
mode = RamRoleArn
ramRoleArn = acs:ram::137918634953****:role/Alice
roleSessionName = session_name_example (可以不設定)
tokenTimeout = 1800 (可以不設定)

      通過如下命令查詢Bucket中的對象。

      ossutil64 -c ~/.myossutilconfig ls oss://example-bucket

    • 通過命令列選項

      您也可以直接將存取金鑰通過命令列參數傳入，範例程式碼如下：

      ossutil64 -e oss-ap-southeast-1.aliyuncs.com -i yourAccessKeyID -k yourAccessKeySecret --mode RamRoleArn --ram-role-arn acs:ram::137918634953****:role/Alice ls oss://example-bucket
      說明

      通過命令列參數需要傳入存取金鑰，可能會被日誌系統記錄，存在密鑰泄露的風險，請謹慎使用。

    使用執行個體RAM角色訪問

    在Elastic Compute Service上，您還可以通過執行個體RAM角色的方式來配置ossutil訪問憑證。執行個體RAM角色允許您將一個角色關聯到雲端服務器執行個體，在執行個體內部基於臨時憑證STS使用ossutil。臨時憑證由系統自動產生和更新，應用程式可以使用指定的執行個體中繼資料URL擷取臨時憑證，無需特別管理。藉助於RAM，一方面保證AccessKey安全，另一方面實現許可權的精細化控制和管理。

    使用前請先在ECS上建立執行個體RAM角色。更多資訊，請參見建立執行個體RAM角色。

    以新加坡地區名稱為example-bucket的Bucket、ECS上建立的角色名稱為EcsRamRoleOss為例進行說明。

    • 通過設定檔

      產生如下的設定檔，並儲存在~/.myossutilconfig。

      [Credentials]
endpoint = oss-ap-southeast-1.aliyuncs.com
mode = EcsRamRole
ecsRoleName = EcsRamRoleOss

      通過如下命令查詢Bucket中的對象。

      ossutil64 -c ~/.myossutilconfig ls oss://example-bucket

    • 通過命令列選項

      您也可以直接將存取金鑰通過命令列參數傳入，範例程式碼如下：

      ossutil64 -e oss-ap-southeast-1.aliyuncs.com --mode EcsRamRole --ecs-role-name EcsRamRoleOss ls oss://example-bucket

    為Bucket單獨配置Endpoint

    在使用ossutil的過程中，您需要管理多個Bucket，此時需要對Bucket單獨配置Endpoint。您可以通過如下兩種方式進行配置：

    • 通過設定檔

      在設定檔裡，增加一個[Bucket-Endpoint]配置段，為每個指定的Bucket單獨配置Endpoint，格式如下：

      [Bucket-Endpoint]
bucket1 = endpoint1
bucket2 = endpoint2
...

      以新加坡地區Bucket（example-bucket-sg）、日本地區Bucket（example-bucket-jp）為例進行說明。

      產生如下的設定檔，並儲存在~/.myossutilconfig。

      [Credentials]
endpoint = oss-ap-southeast-1.aliyuncs.com
accessKeyID = yourAccessKeyID
accessKeySecret = yourAccessKeySecret
[Bucket-Endpoint]
example-bucket-sg=oss-ap-southeast-1.aliyuncs.com
example-bucket-jp=oss-ap-northeast-1.aliyuncs.com

      通過如下命令查詢Bucket中的對象。

      ossutil64 -c ~/.myossutilconfig ls oss://example-bucket-sg
ossutil64 -c ~/.myossutilconfig ls oss://example-bucket-jp

    • 通過命令列選項

      以新加坡地區Bucket（example-bucket-sg）、日本地區Bucket（example-bucket-jp）為例進行說明。

      將帳號資訊配置在~/.myossutilconfig中。

      [Credentials]
endpoint = oss-ap-southeast-1.aliyuncs.com
accessKeyID = yourAccessKeyID
accessKeySecret = yourAccessKeySecret

      通過-e參數指定Endpoint。

      ossutil64 -c ~/.myossutilconfig ls oss://example-bucket-sg
ossutil64 -c ~/.myossutilconfig -e oss-ap-northeast-1.aliyuncs.com ls oss://example-bucket-jp

    配置自訂網域名

    ossutil支援通過自訂網域名來訪問OSS資源。在使用之前，需要通過設定檔設定Bucket和自訂網域名的映射關係。

    在設定檔裡，增加一個[Bucket-Cname]配置段，為每個指定的Bucket單獨配置Endpoint，格式如下：

    [Bucket-Cname]
bucket1 = cname1
bucket2 = cname2
...

    以新加坡地區名稱為example-bucket的Bucket、通過cname.example-***.com自訂網域名訪問為例進行說明。

    產生如下的設定檔，並儲存在~/.myossutilconfig。

    [Credentials]
accessKeyID = yourAccessKeyID
accessKeySecret = yourAccessKeySecret
[Bucket-Cname]
example-bucket=cname.example-***.com

    通過如下命令查詢Bucket中的對象。

    ossutil64 -c ~/.myossutilconfig ls oss://example-bucket