Object Storage Service：鏡像回源

步驟一：配置鏡像回源規則

1. 前往Bucket列表頁面，然後單擊目標Bucket名稱。

2. 在左側導覽列，選擇資料管理 > 鏡像回源。

3. 在鏡像回源頁面，單擊建立規則。

4. 在建立規則面板配置參數，未提及的參數保持預設即可。

   參數	配置
   回源類型	選擇鏡像。
   回源條件	勾選檔案名稱首碼，在輸入框中填寫examplefolder/。
   回源地址	第一列（協議）選擇 https，第二列（網域名稱）填寫 example.com，第三列（路徑首碼）留空。路徑首碼將拼接到網域名稱後，構成回源URL的路徑部分。

5. 單擊確定。

步驟二：驗證規則

1. 訪問https://examplebucket.oss-cn-hangzhou.aliyuncs.com/examplefolder/example.txt。

2. 如果examplebucket中不存在examplefolder/example.txt檔案，則OSS向https://example.com/examplefolder/example.txt請求檔案。

3. 擷取到目標檔案後，OSS將檔案重新命名為examplefolder/example.txt後儲存到examplebucket，並將檔案返回給要求者。

步驟一：配置鏡像回源規則

1. 前往Bucket列表頁面，然後單擊目標Bucket名稱。

2. 在左側導覽列，選擇資料管理 > 鏡像回源。

3. 在鏡像回源頁面，單擊建立規則。

4. 在建立規則面板，按以下說明配置必要參數，其他參數保留預設配置。

   參數	配置
   回源類型	選中鏡像。
   回源條件	選中檔案名稱首碼，並設定為examplefolder/。
   替換或截取首碼	選中是否替換或截取首碼，並設定為destfolder/。 說明 該選項僅在設定了回源條件中的檔案名稱首碼後顯示。
   回源地址	第一列設定為https，第二列設定為example.com，第三列置空。
   檢查MD5	選中是否檢查MD5。當回源請求的響應包含Content-MD5欄位時，OSS會檢查回源檔案的MD5值與Content-MD5欄位值是否匹配。 匹配：用戶端將擷取檔案，且OSS會儲存回源檔案。 不匹配：由於計算MD5需要完整的檔案資料，而此時檔案已經透傳回用戶端，所以用戶端能擷取到檔案，但OSS不會儲存回源檔案。

5. 單擊確定。

步驟二：驗證規則

1. 訪問https://bucket-01.oss-cn-hangzhou.aliyuncs.com/examplefolder/example.txt。

2. 如果bucket-01中不存在examplefolder/example.txt檔案，則OSS向https://example.com/destfolder/example.txt請求檔案。

3. 擷取到目標檔案後，OSS進行以下操作：

   • 如果回源請求的響應包含Content-MD5欄位，OSS會計算回源檔案的MD5值，並與Content-MD5欄位進行匹配。MD5匹配成功則將檔案重新命名為examplefolder/example.txt後儲存到bucket-01，並將檔案返回給要求者；匹配失敗時僅返迴文件給使用者，不儲存該檔案到bucket-01。

   • 如果回源請求的響應不包含Content-MD5欄位，OSS將檔案重新命名為examplefolder/example.txt後儲存到bucket-01，並將檔案返回給要求者。

步驟一：配置鏡像回源規則

1. 前往Bucket列表頁面，然後單擊目標Bucket名稱。

2. 在左側導覽列，選擇資料管理 > 鏡像回源。

3. 在鏡像回源頁面，單擊建立規則。

4. 在建立規則面板，按以下說明配置兩條鏡像回源規則，其他參數保留預設配置。

   • 規則一

     參數	配置
     回源類型	選中鏡像。
     回源條件	選中檔案名稱首碼，並設定為dir1/。
     替換或截取首碼	選中是否替換或截取首碼，並設定為example1/。 說明 該選項僅在設定了回源條件中的檔案名稱首碼後顯示。
     回源地址	第一列設定為https，第二列設定為example.com，第三列置空。
     3xx請求響應策略	選中跟隨來源站點重新導向請求。 說明 未選中跟隨來源站點重新導向請求時，OSS會直接將來源站點重新導向規則指定的地址返回給要求者。

   • 規則二

     參數	配置
     回源類型	選中鏡像。
     回源條件	選中檔案名稱首碼，並設定為dir2/。
     替換或截取首碼	選中是否替換或截取首碼，並設定為example2/。 說明 該選項僅在設定了回源條件中的檔案名稱首碼後顯示。
     回源地址	第一列設定為https，第二列設定為example.org，第三列置空。
     3xx請求響應策略	選中跟隨來源站點重新導向請求。

5. 單擊確定。

步驟二：驗證規則

1. 訪問https://bucket-02.oss-cn-beijing.aliyuncs.com/dir1/example.txt。

2. 如果bucket-02下dir1目錄中不存在example.txt檔案，則OSS向https://example.com/example1/example.txt請求檔案。

   • 如果來源站點A針對example1/example.txt設定了重新導向規則，則OSS會向來源站點重新導向規則指定的地址重新發起請求，擷取到檔案後會將檔案命名為dir1/example1/example.txt儲存至bucket-02，並返回給要求者。

   • 如果來源站點A未針對example1/example.txt設定重新導向規則，則OSS擷取到檔案後會將檔案命名為dir1/example1/example.txt儲存至bucket-02，並返回給要求者。

3. 如果要求者訪問https://bucket-02.oss-cn-beijing.aliyuncs.com/dir2/example.txt，則通過鏡像回源規則擷取的檔案將儲存在bucket-02的dir2/example2目錄。

步驟一：配置鏡像回源規則

1. 前往Bucket列表頁面，然後單擊目標Bucket名稱。

2. 在左側導覽列，選擇資料管理 > 鏡像回源。

3. 在鏡像回源頁面，單擊建立規則。

4. 在建立規則面板，按以下說明配置必要參數，其他參數保留預設配置。

   參數	配置
   回源類型	選中鏡像。
   回源條件	選中檔案名稱首碼，並設定為examplefolder/。
   來源站點類型	選中回源OSS私人Bucket，並在回源Bucket下拉式清單選擇bucket-04。 配置該選項後，當使用者訪問不存在的對象時，OSS會通過預設角色AliyunOSSMirrorDefaultRole從指定來源站點私人Bucket中擷取資料。資料擷取過程中需要具備AliyunOSSReadOnlyAccess許可權，該許可權用於確保OSS只能以唯讀方式訪問來源站點資料，避免對來源站點資料進行修改或刪除。 RAM使用者配置鏡像回源OSS私人Bucket時，必須擁有ram:GetRole許可權，該許可權用於檢查AliyunOSSMirrorDefaultRole角色是否存在。 如果存在，則直接調用該角色。 如果不存在，建議通過RAM使用者關聯的阿里雲帳號預先建立AliyunOSSMirrorDefaultRole角色並授予該角色AliyunOSSReadOnlyAccess許可權，避免授予RAM使用者高風險許可權，如建立角色（ram:CreateRole）和為角色授權（ram:AttachPolicyToRole）。授權完成後，RAM使用者可直接複用已建立的角色，降低許可權配置風險。
   回源地址	第一列設定為https，其他置空。
   回源參數	選中攜帶請求字串。 OSS會將URL請求中的query string傳遞到來源站點。
   設定HTTP header路由規則	選中傳遞指定HTTP header參數，並添加header1、header2、header3三個HTTP header。回源規則不支援傳遞部分標準HTTP header，例如authorization、authorization2、range、content-length、date等，以及以x-oss-、oss-、x-drs-開頭的HTTP header。 重要 回源私人Bucket時，請勿選擇傳遞所有HTTP header參數，否則會導致回源失敗。

5. 單擊確定。

步驟二：驗證規則

1. 訪問https://bucket-03.oss-cn-shanghai.aliyuncs.com/examplefolder/example.png?caller=lucas&production=oss。

2. 如果bucket-03中不存在examplefolder/example.png檔案，則OSS會向https://bucket-04.oss-cn-shanghai.aliyuncs.com/examplefolder/example.png?caller=lucas&production=oss請求檔案。

3. bucket-04會根據傳遞的?caller=lucas&production=oss參數，將example.png返回給OSS。

4. OSS會將擷取的檔案命名為examplefolder/example.png，並將命名後的檔案儲存體至bucket-03。

如果請求中還攜帶了header1、header2、header3的HTTP header時，也會被傳遞到bucket-04。

資料無縫遷移

遷移方案詳情請參見結合鏡像回源將業務無縫遷移至阿里雲OSS。

重新整理已回來源物件

由於鏡像回源是一次性緩衝機制，來源站點上的同名檔案更新後，OSS不會自動重新整理或重新擷取該對象。可以通過以下方式強制重新整理已儲存到OSS中的對象。

• 手動刪除：通過控制台或API刪除OSS中的對象，下次訪問時將重新觸發回源。

• 生命週期規則：為鏡像回源的對象配置到期策略，使其在固定時間後自動刪除，實現定期重新整理。

• 檔案名稱版本化：在來源站點更新檔案時使用新的名稱（如 style.v2.css），從根本上避免緩衝問題，這是推薦的做法。

風險防範與容錯

• 來源站點壓力：確保來源站點有足夠的頻寬和處理能力應對回源請求。在遷移初期，回源請求量可能較大，建議監控來源站點負載，並考慮在業務低峰期進行資料預熱。

• 成本控制：為避免意外的高額費用，建議在阿里雲費用管理中心設定費用預警，監控與回源相關的請求量。

• 安全配置：確保來源站點可以被OSS訪問，如果回源地址使用HTTPS協議，請確保來源站點認證由受信任的CA簽發、網域名稱匹配且未到期。

• 日誌查詢：通過即時日誌查詢功能查看回源相關日誌，回源請求的User-Agent包含aliyun-oss-mirror字樣。

鏡像回源檔案大小與來源站點檔案大小不一致？

如果鏡像回源檔案大小與來源站點檔案大小不一致，可以按照以下步驟進行排查。

1. 檢查鏡像回源檔案和來源站點檔案的Last-Modified時間戳記。

   import oss2
   import requests
   from datetime import datetime
   from oss2.credentials import EnvironmentVariableCredentialsProvider
   
   # 從環境變數中擷取訪問憑證。運行本程式碼範例之前，請確保已設定環境變數OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
   auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())
   
   # 填寫Bucket所在地區對應的Endpoint。以華東1（杭州）為例，Endpoint填寫為https://oss-cn-hangzhou.aliyuncs.com。
   endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
   
   # 填寫Endpoint對應的Region資訊，例如cn-hangzhou。注意，v4簽名下，必須填寫該參數
   region = "cn-hangzhou"
   
   # yourBucketName填寫配置鏡像回源規則的Bucket名稱。
   bucket = oss2.Bucket(auth, endpoint, "yourBucketName", region=region)
   # 填寫鏡像回源檔案的完整路徑。
   object_key = 'yourObjectKey'
   # 填寫來源站點檔案的完整路徑。
   source_url = 'yourSourceUrl'
   
   # 擷取鏡像回源檔案的Last-Modified時間戳記
   oss_object_info = bucket.get_object_meta(object_key)
   oss_last_modified = oss_object_info.headers['last-modified']
   print(f"OSS Last-Modified: {oss_last_modified}")
   
   # 擷取來源站點檔案的Last-Modified時間戳記。
   response = requests.head(source_url)
   source_last_modified = response.headers.get('last-modified')
   print(f"Source Last-Modified: {source_last_modified}")
   
   # 將字串格式的時間戳記轉換為datetime對象以便比較。
   oss_time = datetime.strptime(oss_last_modified, '%a, %d %b %Y %H:%M:%S %Z')
   source_time = datetime.strptime(source_last_modified, '%a, %d %b %Y %H:%M:%S %Z')
   
   if oss_time < source_time:
       print("來源站點檔案更新了")
   elif oss_time > source_time:
       print("鏡像回源檔案較新")
   else:
       print("兩個檔案的時間戳記一致")

   • 如果源檔案的Last-Modified時間戳記＞鏡像回源檔案的Last-Modified時間戳記，表明鏡像回源檔案產生之後，源檔案可能已經更新。

     說明

     OSS從來源站點擷取檔案並寫入目標Bucket時，不會保留源檔案的Last-Modified時間戳記（即源檔案最後一次修改的時間）。相反，OSS會將鏡像回源檔案的Last-Modified時間戳記設定為該檔案通過鏡像回源功能被建立或更新到OSS上的時間。

   • 如果源檔案的Last-Modified時間戳記≤鏡像回源檔案的Last-Modified時間戳記，表明鏡像回源檔案產生之後，源檔案沒有更新。需要繼續下一步，檢查兩者的MD5或CRC64校正值。

2. 比較鏡像回源檔案和源檔案的MD5或CRC64校正值。

   # -*- coding: utf-8 -*-
   import oss2
   import hashlib
   import requests
   # 如果需要比較CRC64，由於Python標準庫不支援CRC64，可以使用第三方庫如crcmod
   # 安裝crcmod：pip install crcmod
   import crcmod
   from oss2.credentials import EnvironmentVariableCredentialsProvider
   
   # 從環境變數中擷取訪問憑證。運行本程式碼範例之前，請確保已設定環境變數OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
   auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())
   
   # 填寫Bucket所在地區對應的Endpoint。以華東1（杭州）為例，Endpoint填寫為https://oss-cn-hangzhou.aliyuncs.com。
   endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
   
   # 填寫Endpoint對應的Region資訊，例如cn-hangzhou。注意，v4簽名下，必須填寫該參數
   region = "cn-hangzhou"
   
   # yourBucketName填寫配置鏡像回源規則的Bucket名稱。
   bucket = oss2.Bucket(auth, endpoint, "yourBucketName", region=region)
   # 填寫鏡像回源檔案的完整路徑。
   object_key = 'yourObjectKey'
   # 填寫來源站點檔案的完整路徑。
   source_url = 'yourSourceUrl'
   
   # 擷取鏡像回源檔案的中繼資料。
   oss_object_info = bucket.get_object_meta(object_key)
   
   oss_md5 = oss_object_info.headers.get('etag', '').strip('"')  # ETag通常為MD5
   oss_crc64 = oss_object_info.headers.get('x-oss-hash-crc64ecma', '')
   
   print(f"OSS MD5: {oss_md5}")
   print(f"OSS CRC64: {oss_crc64}")
   
   # 擷取來源站點檔案的內容並計算MD5和CRC64。
   response = requests.get(source_url)
   if response.status_code == 200:
       source_content = response.content
       source_md5 = hashlib.md5(source_content).hexdigest()
       print(f"Source MD5: {source_md5}")
   
       crc64_func = crcmod.predefined.mkCrcFun('crc-64')
       source_crc64 = hex(crc64_func(source_content))[2:].upper().zfill(16)  # 轉換為16進位字串並格式化
       print(f"Source CRC64: {source_crc64}")
   
       # 比較MD5值。
       if oss_md5 == source_md5:
           print("MD5校正值一致")
       else:
           print("MD5校正值不一致")
   
       # 比較CRC64值。
       if oss_crc64.upper() == source_crc64:
           print("CRC64校正值一致")
       else:
           print("CRC64校正值不一致")
   else:
       print(f"Failed to fetch source file. HTTP Status Code: {response.status_code}")
       

   • 如果兩者的MD5或CRC64校正值一致，表明這兩個檔案內容相同。這種情況下，這兩個檔案的大小應該是一致的。

   • 如果兩者的MD5或CRC64校正值不一致，表明這兩個檔案的內容並不相同。需要繼續下一步，檢查是否存在特殊要求標頭。

3. 檢查特殊要求標頭。

   

   • 檢查鏡像回源請求中是否包含特殊的HTTP要求標頭部，例如Accept-Encoding: gzip, deflate, br，該頭部表示用戶端能夠接受壓縮格式的資料。

   • 如果鏡像回源請求使用了HTTP壓縮邏輯，並且請求的檔案滿足壓縮條件，也會導致這兩個檔案大小不一致。

   • 如果存在Accept-Encoding頭部，需要禁止傳遞該頭部。

     • 如果設定了允許傳遞所有HTTP header，需要在禁止傳遞指定HTTP header中指定accept-encoding。

       

     • 如果設定了傳遞指定HTTP header，確保指定的header中不包含accept-encoding。

       

回源失敗如何排查？

遇到回源失敗（如返回 424 MirrorFailed 錯誤）時，可按以下步驟排查。

1. 檢查來源站點可達性。

   # 將URL替換為您的實際來源站點地址和檔案路徑
   curl -I "https://www.example.com/images/test.jpg"

2. 檢查DNS解析。

   # 請將網域名稱替換為實際來源站點網域名稱
   nslookup www.example.com

3. 檢查HTTPS認證（如果來源站點是HTTPS）。

   # 請將網域名稱替換為實際來源站點網域名稱
   openssl s_client -connect www.example.com:443 -servername www.example.com

4. 通過OSS的即時日誌查詢進行問題分析。

為什麼沒有產生鏡像回源檔案？

用戶端發起HEAD請求來擷取檔案中繼資料時，僅擷取檔案的基本資料（如大小、類型等），並不下載實際的檔案內容。HEAD請求不會觸發鏡像回源規則從來源站點請求檔案並寫入OSS目標Bucket。

鏡像回源返回非預期狀態代碼？

當請求觸發鏡像回源時，如果來源站點返回的狀態代碼不是404、200或者206，需要具體分析來源站點的響應情況。

• 來源站點為OSS：需要檢查以下配置項。

  • 禁止傳遞指定HTTP header參數：禁止傳遞host頭部用於避免暴露來源站點資訊，同時確保回源請求能按照預期正確處理。如果不配置禁止傳遞host，則回源請求會透傳目標Bucket的host值到來源站點。由於每個Bucket的host值是唯一的，如果請求的host與來源站點的實際host不匹配，來源站點會返回403錯誤，然後OSS會向用戶端返回424錯誤，表示由於來源站點未能成功處理請求導致操作失敗。

    

  • 回源OSS私人Bucket：如果未配置許可權，請確認目標Bucket及其Object的ACL許可權是否設定為公用讀取。如果已配置許可權，請確認用於鏡像回源的角色授權策略是否發生變更，導致許可權不足。鏡像回源預設使用的角色為AliyunOSSMirrorDefaultRole，該角色的預設系統策略是AliyunOSSReadOnlyAccess。

• 來源站點不是OSS：結合服務側的日誌，檢查攜帶SNI（伺服器名稱指示）、回源參數、header傳遞等配置，以分析具體的來源站點異常原因。來源站點可能會返回401（未授權）、403（禁止訪問）、5xx（伺服器內部錯誤）等狀態代碼。

回源規則的匹配順序是怎樣的？

按規則編號（RuleNumber）從小到大進行匹配。命中第一條滿足條件的規則後，立即執行該規則並停止匹配後續規則。

可以回源到VPC內的服務或內網IP嗎？

不可以。來源站點必須擁有一個可公網訪問的地址，如需訪問VPC內的服務，請通過NAT Gateway或公網SLB將其暴露到公網。

來源站點檔案更新後，OSS中的檔案為什麼沒有更新？

鏡像回源是一次性拉取機制，不會自動同步來源站點的更新。需要手動刪除OSS上的回源檔案，或採用檔案名稱版本化的策略來擷取新檔案。