Proxy Cache

用途說明

此插件會根據插件設定的狀態碼、內容類型以及請求方法暫存回應。它可根據一個用戶或一個 API 做快取。在資料保存一段時間之後，會再次從源頭取得並暫存資訊。

欄位配置說明

變數	類型	預設值	說明	必填
response_code	array of integer	[200, 301, 404]	根據服務回應的狀態碼，決定是否暫存回應。 可以設定的狀態碼範圍由 100 至 900。	V
request_method	array of string	["GET", "HEAD"]	根據傳送請求時的方法，決定是否暫存回應。	V
content_type	array of string	["text/plain", "application/json"]	根據服務回應的內容類型，決定是否暫存回應。 要注意的是此項目只接受完全符合的值。 舉例來說，如果服務預期會接收到 application/json; charset=utf-8 這個類型的內容，而設定並沒有跟上述類型一模一樣時，則會收到 Bypass 的快取狀態。	V
vary_headers	array of string		快取會考慮的相關標頭。 如未設定，則沒有任何標頭會被考慮。
vary_query_params	array of string		快取會考慮的相關查詢參數。 如未設定，則所有參數都會被考慮。
cache_ttl	integer	300	快取存活時間（單位為秒）。 填入的值要大於 0。
cache_control	boolean	false	請參考 RFC7234。	V
storage_ttl	integer		將資源保留在後端儲存裝置時間(單位為秒)。 此欄位值與 cache_ttl 或由 Cache-Control 行為定義之資源 TTLs 時間獨立。
strategy	string		後端資料儲存的地方(策略)，。 唯一可接受的值是： memory 。	V
memory.dictionary_name	string	kong_db_cache	擁有快取實體的共享 dictionary 的名字。 注意目前必需在 Nginx template 中手動定義此 dictionary。	V

用法示例

在全局啟用插件

1. 從網站左邊 Menu 中 外掛插件 頁面中，點選右上角的 新增外掛插件 ：

2. 點選後，選擇 流量控管 頁籤，並啟用 Proxy Cache，填寫內容參考欄位配置說明，設定成功後，任何請求(不分服務、路由、用戶)皆需經過計算才能通過。

在服務端上啟用插件

1. 從網站左邊 Menu 中 服務 > 服務列表 頁面中，選擇要啟用此插件的服務，假設為 google，點選對應的編輯按鈕：

2. 在編輯畫面中，點選上方的 外掛插件 頁籤，再點選頁籤內容上方的 新增外掛插件 按鈕：

點選後，選擇 流量控管 頁籤，並啟用 Proxy Cache，填寫內容參考欄位配置說明，設定成功後，僅有此服務(範例為google)請求需經過計算才能通過。

在路由端上啟用插件

可以由兩種方式來選擇路由，並啟用插件：

方式一：路由列表

1. 從網站左邊 Menu 中 服務 > 路由列表 頁面中，選擇要啟用此插件的路由，假設為 google，點選對應的編輯按鈕：

方式二：服務 > 服務列表 > 路由列表

1. 從網站左邊 Menu 中 服務 > 服務列表 頁面中，選擇要啟用此插件的路由 所屬之服務(假設為 google)，點選對應的編輯按鈕。

在編輯畫面中，點選上方的 路由 頁籤，選擇要啟用此插件的路由(假設為 google)，點選對應的編輯按鈕：

---

2. 承第1步，點擊上述兩種方式之一的編輯按鈕後，在編輯畫面中，點選上方的 外掛插件 頁籤，再點選頁籤內容上方的 新增外掛插件 按鈕：

點選新增外掛插件 按鈕後，選擇 流量控管 頁籤，並啟用 Proxy Cache，填寫內容參考欄位配置說明，設定成功後，僅有此路由(範例為google)請求需經過計算才能通過。

在用戶端上啟用插件

1. 從網站左邊 Menu 中 訂閱用戶 > 用戶列表 頁面中，選擇要啟用此插件的用戶，假設為 portaladmin，點選對應的編輯按鈕 ：

2. 在編輯畫面中，點選上方的 外掛插件 頁籤，再點選頁籤內容上方的 新增外掛插件 按鈕：

點選後，選擇 流量控管 頁籤，並啟用 Proxy Cache，填寫內容參考欄位配置說明，設定成功後，僅有此用戶(範例為 portaladmin)請求需經過計算才能通過。

驗證

開啟插件之後，送出請求後收到的回應會包含以下幾種：

X-Cache-Key: 1b8ee3fece7db9875431d2f006152233

X-Cache-Status: Bypass

X-Cache-Key: 79464524108607b02ad8e72ef833844b

X-Cache-Status: Miss

X-Cache-Key: 79464524108607b02ad8e72ef833844b

Cache-Control: public, max-age=2592000

X-Cache-Status: Hit

後面會詳細解釋快取狀態。

相關解釋

策略 (Strategies)

此插件目的在支持以不同的後端格式存儲代理 cache 數據。目前提供以下策略：

• memory： 一個 lua_shared_dict。請注意，默認的 dictionary：kong_db_cache 也用來存儲不相關的 database cache 實體。 使用這個 dictionary 是引導 Proxy Cache 插件的簡單方法，但不推薦用於大規模安裝，因為大量使用會給 GOC API Gateway 的 database caching 操作的其他方面帶來負擔。 建議大規模安裝時要透過自定義 Nginx template 去定義一個單獨使用的 lua_shared_dict。

Cache Key

GOC API Gateway 根據請求方法、完整的客戶端請求（例如：請求路徑和查詢參數）以及與請求關聯的 API 或 Consumer 的 UUID 對每個 cache 元素進行鍵控。

這也意味著 cache 在 API 且/或 Consumer 之間是不同的。目前，cache key 格式是 hard-coded 的，無法調整。在內部，cache key 表示為組成部分串聯的十六進制編碼 MD5 和。計算如下：

key = md5(UUID | method | request)

其中 method 是被定義透過 OpenResty ngx.req.get_method() 所呼叫的，request 是透過 Nginx $request 變數定義的。 GOC API Gateway 將返回與給定請求關聯的 cache key 作為 X-Cache-Key response header。如上所述，也可以為給予的請求預先計算 cache key。

Cache Control

當開啟 cache_control 選項， GOC API Gateway 即會遵照 RFC7234 之規則，除了以下幾點例外：

• 尚未支援 Cache revalidation，因此像是 proxy-revalidate 相關資訊也會直接忽略。
• 同樣地，no-cache 的行為簡化為直接將實體從整個快取中排除。
• 尚未支援藉由 Vary 計算 Secondary Key。

Cache 狀態

共有四種狀態可以從標頭 X-Cache-Status 識別：

• Miss： 請求滿足快取，但快取目前沒有相關資料存在。此請求必需導向代理服務。
• Hit： 請求滿足快取並能取得存在於快取的資料。
• Refresh： 資料存在於快取，但不符合 Cache-Control 行為中的定義請求內容或是 cache 的存活時間已到。
• Bypaas： 請求不符合插件的設定值。

Storage TTL

GOC API Gateway 可以在存儲引擎中存儲資源實體的時間超過規定的 cache_ttl 或 Cache-Control 值標示的時間。

這允許 GOC API Gateway 在 cache 過期後能保存著資源的 cache 副本。

這允許客戶端可以在必要時使用 max-age 和 max-stale headers 來請求過時的 data。

上游中斷

當一個上游服務無法訪問時，由於 GOC API Gateway 的核心請求處理模型實作方式，導致此時 Proxy Cache 插件不能用於提供舊的 cache data。

為了讓 GOC API Gateway 能夠在上游服務無法訪問時提供 cache data 而不是返回錯誤，我們建議定義一個非常大的 storage_ttl（大約幾小時或幾天），以便將舊的 data 保留在 cache 中。

在上游服務中斷的情況下，通過增加 cache_ttl 配置值，可以將舊的 data 視為 "新的" data。透過這種方式，在 GOC API Gateway 嘗試連接到失敗的上游服務之前，先前被認為過時的舊 data，現在可以正常提供給客戶端。

Admin API

此插件為了託管的 cache 實體提供了多個 API Endpoints。 Admin API 上提供了以下端點可以檢查、清除 cache 實體：

info

Admin API 與透過 GOC API Gateway 呼叫後端服務的 URL 是不同的。

舉例來說，GOC API Gateway 在安裝完畢時會提供 2 種 URLs：

• Admin API URL： 用來設定、取得、修改 GOC API Gateway 本身的設定、數據資料所使用的管理用 API。

• Proxy API URL： 用來呼叫後端服務的代理用 API。

而下方 檢查 Cache Entity 所提到的 Endpoints 就是需要使用 Admin API URL 來呼叫。

註：若不清楚如何取得上述的 2 種 URLs，可以參考 常見問題。

檢查 Cache 實體

有兩個單獨的 Endpoints 可用：一個用於查找已知的插件實例，另一個透過給予的 cache key 來搜索所有 Proxy Cache 插件的 data store。兩個 Endpoints 具有相同的回傳值。

• Endpoint

  GET /proxy-cache/:plugin_id/caches/:cache_id

  屬性	描述
  plugin_id	Proxy Cache 插件的 UUID。
  cache_id	X-Cache-Key response header 報告的 cache 實體 key。

• Endpoint

  GET /proxy-cache/:cache_id

  屬性	描述
  cache_id	X-Cache-Key response header 報告的 cache 實體 key。

如果 cache 實體存在，則會回傳：

HTTP 200 OK

如果給予的 cache key 實體並不存在，則會回傳：

HTTP 404 Not Found

刪除 Cache 實體

• Endpoint

  DELETE /proxy-cache/:plugin_id/caches/:cache_id

  屬性	描述
  plugin_id	Proxy Cache 插件的 UUID。
  cache_id	X-Cache-Key response header 報告的 cache 實體 key。

• Endpoint

  DELETE /proxy-cache/:cache_id

  屬性	描述
  cache_id	X-Cache-Key response header 報告的 cache 實體 key。

如果 cache 實體存在，則會回傳：

HTTP 204 No Content

如果給予的 cache key 實體並不存在，則會回傳：

HTTP 404 Not Found

清除所有 Cache 實體

• Endpoint

  DELETE /proxy-cache/

caution

請注意，此 Endpoint 會清除所有代理緩存 Proxy Cache 插件的所有 Cache 實體。