通過 Referer 黑白名單防盜鏈 - Object Storage Service

配置OSS Bucket的Referer黑白名單可以防止資源被非法盜用，從而降低不必要的流量成本。

工作原理

當瀏覽器向OSS請求檔案時，HTTP請求的Referer標題會標識發起請求的源頁面URL。OSS通過校正Referer值來判斷請求來源的合法性，基於預設規則允許或拒絕訪問。

配置防盜鏈後，OSS將按照以下優先順序順序執行存取控制判斷：

空Referer檢查
- OSS首先判斷請求的Referer欄位是否為空白。
- 如果為空白：
  - 如果配置了允許空Referer，請求將通過。
  - 如果配置了不允許空Referer，則會進入一個特殊判斷：只有當白名單也為空白時，請求才會被允許；否則，請求將被拒絕。
黑名單檢查
- 對於Referer不為空白的請求，OSS會檢查黑名單。
- 如果請求的Referer匹配到黑名單中的任何一項，請求將立即被拒絕，後續的白名單檢查不再進行。
白名單檢查
- 如果請求的Referer不為空白，且沒有命中黑名單，OSS會最後檢查白名單。
- 如果請求的Referer能匹配到白名單中的某一項，請求將通過。
- 如果遍曆完整個白名單都無法匹配，請求將被拒絕。

僅允許受信任的網站訪問

通過白名單機制僅允許受信任的網站訪問OSS資源，同時支援使用者直接通過瀏覽器訪問資源，並確保OSS控制台功能正常工作。

步驟一：擷取請求的Referer

配置防盜鏈規則前，需準確擷取訪問OSS資源的請求來源Referer，確保規則配置的準確性。

通過OSS即時日誌查詢
1. 登入OSS管理主控台。
2. 在左側導覽列，單擊Bucket 列表，然後單擊目標Bucket名稱。
3. 在左側導覽列，選擇日誌管理 > 即時查詢。
4. 在日誌記錄中尋找referer欄位，該欄位即為請求的Referer值。若該欄位顯示為-，表示這是空Referer請求。
通過瀏覽器開發人員工具查看
1. 使用Chrome等現代瀏覽器訪問引用了OSS資源的網頁。
2. 按F12鍵開啟開發人員工具，切換到網路（Network）面板。
3. 重新整理頁面，找到對OSS資源的請求記錄。
4. 選中該請求，在右側的標題（Headers）地區中尋找Referer欄位的值。

步驟二：配置防盜鏈規則

登入OSS管理主控台。
在左側導覽列，單擊Bucket 列表，然後單擊目標Bucket名稱。
在左側導覽列，選擇資料安全 > 防盜鏈。
開啟防盜鏈開關，並按以下說明配置：
- 白名單 Referer：輸入允許訪問的網域名稱，每個網域名稱佔一行。由於使用者可能通過HTTP或HTTPS協議訪問網站，建議同時添加兩種協議版本。同時添加OSS控制台網域名稱以確保管理功能正常使用。
```
https://www.aliyun.com
http://www.aliyun.com
*.console.aliyun.com
```
  Referer規則支援萬用字元星號（*）和問號（?）。例如*.aliyun.com可匹配所有aliyun.com的子網域名稱。
- 黑名單 Referer：保持為空白。當黑白名單同時存在時，黑名單具有更高優先順序。
- 空 Referer：選擇允許。此配置確保使用者可直接在瀏覽器地址欄輸入檔案URL進行訪問，或從某些不發送Referer的用戶端（如案頭應用）正常訪問資源。
- 截斷 QueryString：選擇允許（預設）。OSS在匹配Referer時將忽略URL中的查詢字串（即?之後的部分），提高匹配的靈活性。
單擊儲存。

步驟三：驗證配置是否生效

使用curl命令類比不同來源的請求，驗證防盜鏈配置是否按預期工作。

類比白名單內的Referer訪問（預期成功）
```
curl -e "http://www.aliyun.com" http://your-bucket-name.oss-cn-hangzhou.aliyuncs.com/demo.txt
```
預期結果：成功返回demo.txt檔案的內容。
類比白名單外的Referer訪問（預期被拒絕）
```
curl -e "http://www.example.com" http://your-bucket-name.oss-cn-hangzhou.aliyuncs.com/demo.txt
```
預期結果：返回包含AccessDenied和You are denied by bucket referer policy.的錯誤資訊。
類比空Referer訪問（預期成功）
```
curl http://your-bucket-name.oss-cn-hangzhou.aliyuncs.com/demo.txt
```
預期結果：成功返迴文件內容，因為配置允許空Referer。

禁止特定惡意網站盜用

適用於需要允許大部分來源訪問，但明確禁止某些惡意網站盜用資源的情境。通過黑名單機制精準攔截惡意來源，同時保持對其他合法來源的開放訪問。

步驟一：擷取惡意網站的Referer

配置防盜鏈規則前，需準確識別惡意網站的Referer值。建議通過OSS即時日誌查詢分析異常流量，識別盜用資源的來源。

登入OSS管理主控台。
在左側導覽列，單擊Bucket 列表，然後單擊目標Bucket名稱。
在左側導覽列，選擇日誌管理 > 即時查詢。
篩選異常流量記錄，查看referer欄位，識別惡意網站網域名稱pattern。

步驟二：配置防盜鏈規則

登入OSS管理主控台。
在左側導覽列，單擊Bucket 列表，然後單擊目標Bucket名稱。
在左側導覽列，選擇資料安全 > 防盜鏈。
開啟防盜鏈開關，並按以下說明配置：
- 白名單 Referer：輸入萬用字元*表示允許所有來源訪問。
```
*
```
- 黑名單 Referer：輸入需要禁止的惡意網站網域名稱，每行一個。
```
*bad-site.example
http://malicious-site.example
https://malicious-site.example
```
  使用萬用字元可有效禁止整個網域名稱及其子網域名稱的訪問。
- 空 Referer：選擇允許。確保直接存取和來自不發送Referer的正常用戶端能正常訪問。
- 截斷 QueryString：選擇允許（預設）。OSS在匹配Referer時將忽略URL中的查詢字串（即?之後的部分），提高匹配的靈活性。
單擊儲存。

步驟三：驗證配置是否生效

類比正常網站的請求（預期成功）

curl -e "http://www.example.com" http://your-bucket-name.oss-cn-hangzhou.aliyuncs.com/demo.txt

預期結果：成功返迴文件內容。

類比黑名單內網站的請求（預期被拒絕）
```
curl -e "http://bad-site.example" http://your-bucket-name.oss-cn-hangzhou.aliyuncs.com/demo.txt
```
預期結果：返回AccessDenied錯誤資訊。
類比空Referer訪問（預期成功）
```
curl http://your-bucket-name.oss-cn-hangzhou.aliyuncs.com/demo.txt
```
預期結果：成功返迴文件內容。

支援微信小程式訪問

當OSS資源需要在微信小程式中使用時，需要針對微信小程式特定的Referer格式進行配置。微信小程式發起的請求Referer固定為https://servicewechat.com/{appid}/{version}/page-frame.html格式。

步驟一：瞭解微信小程式Referer格式

微信小程式的Referer格式固定且規律，無需特別擷取，可直接使用萬用字元配置。如需確認具體格式，可通過以下方式驗證：

在小程式中訪問OSS資源
通過OSS即時日誌查詢確認Referer格式
在日誌中查看referer欄位，應顯示類似https://servicewechat.com/wx1234567890abcdef/1/page-frame.html的格式

步驟二：配置防盜鏈規則

登入OSS管理主控台。
在左側導覽列，單擊Bucket 列表，然後單擊目標Bucket名稱。
在左側導覽列，選擇資料安全 > 防盜鏈。
開啟防盜鏈開關，並按以下說明配置：
- 白名單 Referer：輸入微信小程式的萬用字元規則和OSS控制台網域名稱。
```
*servicewechat.com
*.console.aliyun.com
```
  使用萬用字元可相容所有微信小程式的appid和版本號碼，簡化組態管理。同時添加控制台網域名稱確保管理功能正常。
- 黑名單 Referer：保持為空白。
- 空 Referer：選擇允許。某些情況下小程式可能不發送Referer，允許空Referer可確保相容性。
- 截斷 QueryString：選擇允許（預設）。OSS在匹配Referer時將忽略URL中的查詢字串（即?之後的部分），提高匹配的靈活性。
單擊儲存。

步驟三：驗證配置是否生效

類比微信小程式的請求（預期成功）

curl -e "https://servicewechat.com/wx1234567890abcdef/1/page-frame.html" http://your-bucket-name.oss-cn-hangzhou.aliyuncs.com/demo.txt

預期結果：成功返迴文件內容。

類比其他來源的請求（預期被拒絕）
```
curl -e "http://www.example.com" http://your-bucket-name.oss-cn-hangzhou.aliyuncs.com/demo.txt
```
預期結果：返回AccessDenied錯誤資訊。
類比空Referer訪問（預期成功）
```
curl http://your-bucket-name.oss-cn-hangzhou.aliyuncs.com/demo.txt
```
預期結果：成功返迴文件內容。

允許OSS控制台預覽和下載

設定防盜鏈後，為了允許通過OSS控制台下載、預覽OSS檔案，您需要在白名單Referer中添加一條*.console.aliyun.com，以確保來自OSS控制台的請求不會被Referer防盜鏈策略所阻止。

步驟一：配置防盜鏈規則

登入OSS管理主控台。
在左側導覽列，單擊Bucket 列表，然後單擊目標Bucket名稱。
在左側導覽列，選擇資料安全 > 防盜鏈。
開啟防盜鏈開關，並按以下說明配置：
- 白名單 Referer：OSS控制台網域名稱。
```
*.console.aliyun.com
```
  使用萬用字元*.console.aliyun.com可相容所有OSS控制台的子網域名稱，確保在不同地區或版本的控制台中都能正常預覽。
- 黑名單 Referer：保持為空白。
- 空 Referer：選擇允許。確保直接存取和控制台預覽功能都能正常工作。
- 截斷 QueryString：選擇允許（預設）。OSS在匹配Referer時將忽略URL中的查詢字串（即?之後的部分），提高匹配的靈活性。
單擊儲存。

步驟二：驗證配置是否生效

類比控制台訪問（預期成功）

curl -e "https://oss.console.alibabacloud.com" http://your-bucket-name.oss-cn-hangzhou.aliyuncs.com/demo.txt

預期結果：成功返迴文件內容。

驗證控制台預覽和下載（預期成功）
1. 登入OSS控制台
2. 導航到目標Bucket
3. 嘗試預覽和下載檔案

禁止通過URL直接存取

適用於需要強制所有訪問都必須來自指定網站頁面的情境，通過禁止空Referer有效阻止使用者直接通過URL訪問資源，增強資源存取控制的嚴格性。

注意事項：

此配置會阻止所有直接存取方式，包括從書籤、郵件連結等途徑的訪問
某些瀏覽器外掛程式或下載工具可能無法正常工作
視頻播放等媒體應用可能受到影響，因為媒體請求通常不包含Referer

步驟一：確定網站的Referer

確定業務網站的所有可能網域名稱和協議組合，確保配置覆蓋所有合法訪問情境：

通過瀏覽器開發人員工具確認網站訪問OSS資源時的實際Referer值
考慮所有可能的網域名稱變體（www首碼、不帶www、不同子網域名稱）
確認HTTP和HTTPS協議的支援情況

步驟二：配置防盜鏈規則

登入OSS管理主控台。
在左側導覽列，單擊Bucket 列表，然後單擊目標Bucket名稱。
在左側導覽列，選擇資料安全 > 防盜鏈。
開啟防盜鏈開關，並按以下說明配置：
- 白名單 Referer：包含業務網站的網域名稱和OSS控制台網域名稱。
```
https://www.example.com
http://www.example.com
*.console.aliyun.com
```
  根據實際情況添加所有需要支援的網域名稱和協議組合。添加控制台網域名稱確保管理功能正常。
- 黑名單 Referer：保持為空白。
- 空 Referer：選擇不允許。這是關鍵配置，不允許空Referer可有效阻止通過地址欄直接存取資源。
- 截斷 QueryString：選擇允許（預設）。OSS在匹配Referer時將忽略URL中的查詢字串（即?之後的部分），提高匹配的靈活性。
單擊儲存。

步驟三：驗證配置是否生效

類比網站頁面的請求（預期成功）

curl -e "http://www.example.com" http://your-bucket-name.oss-cn-hangzhou.aliyuncs.com/demo.txt

預期結果：成功返迴文件內容。

類比直接存取（預期被拒絕）
```
curl http://your-bucket-name.oss-cn-hangzhou.aliyuncs.com/demo.txt
```
預期結果：返回AccessDenied錯誤資訊，說明直接存取被成功阻止。
類比其他網站的請求（預期被拒絕）
```
curl -e "http://other.example" http://your-bucket-name.oss-cn-hangzhou.aliyuncs.com/demo.txt
```
預期結果：返回AccessDenied錯誤資訊。

應用於生產環境

CDN緩衝繞過風險：當OSS資源配置了CDN加速時，盜鏈請求可能直接命中CDN邊緣節點緩衝並獲得服務，從而繞過OSS的防盜鏈驗證。為確保防護體系完整有效，必須在CDN層面配置相同的Referer防盜鏈規則，實現多層防護。
瀏覽器Referrer-Policy策略影響：現代瀏覽器支援Referrer-Policy標題，允許網站控制跨域請求中發送Referer的詳細程度。某些策略（如no-referrer）會導致瀏覽器不發送Referer資訊，這類請求將被OSS視為"空Referer"處理，需要在配置時予以考慮。
視頻播放相容性：使用瀏覽器原生video標籤播放線上視頻檔案時，瀏覽器通常發起兩種請求：帶Referer的初始頁面載入請求和用於擷取媒體資料的空Referer請求。為確保視頻播放功能正常，必須允許空Referer訪問。

Referer配置規範

在配置白名單Referer或黑名單Referer時，需要遵循以下規範：

規範	說明
匹配Referer時，不忽略URL的Scheme	配置為`http://www.aliyun.com`，可匹配`http://www.aliyun.com/123`、`http://www.aliyun.com.cn`等以`http://www.aliyun.com`為首碼的地址，但不能匹配`https://www.aliyun.com/123`、`https://www.aliyun.com.cn`、`www.aliyun.com`。
Referer支援萬用字元星號（*）表示使用星號代替0個或多個字元	配置為``，可匹配所有網域名稱和IP地址。配置為`www.example.com`，可匹配`http://www.example.com`、`https://www.example.com`、`www.example.com`。配置為`*.example.com`，可匹配`http://help.example.com`、`https://help.example.com`、`http://www.example.com`、`https://www.example.com`。
Referer支援萬用字元問號（?）表示使用問號代替一個字元	配置為`http://www.aliyun?.com`，可匹配`http://www.aliyunc.com`。
Referer支援帶連接埠的網域名稱或IP地址	配置為`http://www.example.com:8080`、`10.10.10.10:8080`。

QueryString解析規則

如果設定不允許截斷QueryString，OSS將按照以下規則解析QueryString：

規則	說明
不解碼QueryString	在請求URL為`http://www.example.com/?job_id=task$01`時，如果白名單Referer或者黑名單Referer設定為`http://www.example.com/?job_id=task%2401`，則判斷結果為請求URL不匹配白名單Referer或者黑名單Referer。
忽略QueryString中的參數大小寫	在請求URL為`http://www.examplecom/?ACTION=NOP`時，如果白名單Referer或者黑名單Referer設定為`http://www.example.com/?action=nop`，則判斷結果為請求URL匹配白名單Referer或者黑名單Referer。
不解析QueryString中的參數	在請求URL為`http://example.com/?b=c&a=b`時，如果白名單Referer或者黑名單Referer設定為`http://example.com/?a=b&b=c`，則判斷結果為請求URL不匹配白名單Referer或者黑名單Referer。

配額與限制

觸發條件：僅當通過匿名訪問或簽名URL方式訪問Object時，OSS才執行防盜鏈驗證。使用AccessKey等簽名方式的API調用（即請求包含Authorization標題）不受防盜鏈規則限制。
名單大小限制：Referer白名單和黑名單的總資料大小不能超過20 KB。超出此限制時，儲存配置會返回InlineDataTooLarge錯誤。
格式規範：支援萬用字元星號（*）和問號（?）進行模式比對。匹配時包含協議名稱，支援帶連接埠號碼的網域名稱或IP地址格式。
生效範圍：防盜鏈規則在Bucket層級生效，無法為Bucket內的特定檔案或目錄單獨配置不同規則。

常見問題

配置防盜鏈後為何未生效？

請按以下順序排查：

瀏覽器環境檢查：某些特定瀏覽器環境（如微信小程式、iframe等）可能修改或設定特定的Referer值。通過OSS即時日誌或瀏覽器開發人員工具查詢請求的實際Referer值，然後重新設定防盜鏈規則。
Referer格式規範：確認填寫的Referer是否規範。來自瀏覽器的請求通常帶有http://或https://協議首碼，如果配置時遺漏協議部分，則無法正確匹配請求。請按照OSS的Referer配置規範填寫。
CDN緩衝繞過：如果使用CDN加速OSS且未在CDN配置防盜鏈，可能導致通過CDN訪問時繞過驗證。例如，首次CDN請求帶正確Referer並快取檔案後，後續即使請求不帶Referer，CDN也會響應快取檔案。請在CDN上配置與OSS一致的防盜鏈規則。

微信小程式中訪問OSS資源提示拒絕訪問如何解決？

微信小程式發起的請求具有固定的Referer格式，通常為https://servicewechat.com/開頭。在防盜鏈白名單中添加*servicewechat.com規則即可相容所有小程式的訪問需求。

瀏覽器地址欄直接存取檔案提示拒絕訪問如何解決？

直接在瀏覽器地址欄訪問屬於空Referer請求。如果防盜鏈配置為不允許空Referer，此類訪問會被拒絕。若需支援直接存取，請將防盜鏈配置中的空 Referer選項修改為允許。

儲存配置時出現InlineDataTooLarge錯誤如何處理？

此錯誤表示配置的Referer名單（白名單和黑名單合計）總大小超過了20 KB限制。建議使用萬用字元合并多條相似規則，或刪除不必要的規則條目以減小配置大小。