Home Data Center Series: Accurate Cache Clearing with Cloudflare: Cache-Tag and Prefix Methods in Action
tangwudi
|
|
Home Data Center

6142 Words
|
29 minutes

1 Introduction

Many friends who use Cloudflare CDN often encounter this problem: after modifying some content on the website, they find that the changes do not take effect immediately after refreshing the webpage. At this time, everyone's first reaction is often to click on the Cloudflare dashboard "Erase everything":

image.png

Although this can solve the problem immediately, it has a big side effect -All static resources (HTML, CSS, JS, images, etc.) will be cleared, and visitors will have to reload all content from the source server when visiting the website, which will cause the page to slow down, waste traffic, and even affect SEO.

In fact, many times what we really want to clear isHTML Page, for example, if you modify functions.php, header.php, or footer.php, causing the page structure to change, but Cloudflare is still serving the old HTML cache,Only clear HTML, without touching CSS, JS, and images, is the most reasonable and accurate approach.

Although the Cloudflare dashboard itself does not provide an intuitive option to "Clean HTML Only", the good news is that now, including free users, can use the dashboard to provide 4 ways To flexibly clear cache contents (Previously, free users could only use the URL method, and the other 3 methods were exclusive to Pro and above plans.).

Currently Cloudflare supports 4 custom cache clearing methods:

image.png

In these ways:

  • Clear by URL —— It is too cumbersome, especially when you modify multiple pages. You need to list the complete URLs one by one, which is error-prone and difficult to maintain.
  • Clear by Hostname —— It is too rough, directly clearing all contents under the entire subdomain, which is equivalent to a "mild version" of clearing all caches, and the control granularity is too coarse.
  • Clear by tag and prefix —— These two methods take into account flexibility and control.If you consciously group resources reasonably by tags or path prefixes in the early stage of development, then in the later operation and maintenance, you only need to specify a label or path prefix to accurately clear the relevant cache and avoid the failure of the entire site.

So, fromFrom the perspective of long-term operation and maintenance and automated deploymentFrom this point of view, it is recommended to introduce Cache-Tag or path prefix design when building the website, so that in the future, whether through the dashboard or API operation, the cache content can be cleared elegantly instead of "indiscriminate bombing".

2 Based on cache marking method

2.1 Introduction to Cache Tags

Cache-Tag It is an advanced cache management feature provided by Cloudflare, which allows users to add custom tags to cached content to more precisely control cache purging. Cache-Tag is set by the origin server (such as WordPress) in the HTTP response header. When Cloudflare obtains and caches these contents in the CDN, it reads and associates these tags.

By using Cache-Tag, you can tag different types of resources (such as HTML pages, CSS files, JS files, images, etc.) so that when needed, you can precisely clear the cache of these specific resources by tag instead of clearing the cache of the entire site.

Note: Cache-Tag is for the Cloudflare cache system to see and has nothing to do with browser cache behavior.

2.2 Add cache tag to the origin server

You can use different methods to add it according to different source station deployment methods and environments. Cache-TagThe following are several common deployment methods and corresponding operation methods:

1. WordPress Deployment

For WordPress users, you can add Cache-Tag to the response through plugins or custom code. The common practice is to use PHP Functions Set a custom Cache-Tag in the functions.php file, or use a cache plugin that specifically supports Cache-Tag.

  • Custom code: Add Cache-Tag to the HTTP response header by using the header() function in functions.php. For example, you can dynamically generate different tags for specific pages, articles, or categories.
  • Plugins: Some cache plugins (such as W3 Total Cache,WP Super Cache etc.) provide the option to work with Cloudflare, allowing you to add custom tags to cached content.

Taking custom code as an example, you only need to add the following code to functions.php to set the cache tag "html-tag" for all HTML content (it is still strongly recommended to use code snippets to uniformly manage all codes that need to be inserted into theme files):

function add_cache_tags_to_headers() { // Only execute on the front-end page, avoid the back-end management page if (is_admin()) { return; } // Set Cache-Tag only for HTML pages if (is_page() || is_single() || is_home() || is_archive()) { header('Cache-Tag: html-tag'); } } add_action('send_headers', 'add_cache_tags_to_headers');

Key points explained:

  1. Front page limitation：Use is_admin() to ensure that cache tags are only executed on the front-end page to avoid unnecessary addition of Cache-Tags on the back-end management page.
  2. For HTML pages only：Use is_page(), is_single(), is_home(), and is_archive() to determine the current page type, and only add Cache-Tag to these page types to avoid taking effect on resources such as CSS and JS.
  3. Setting HTTP headers directly: Omit the array processing logic and directly use header('Cache-Tag: html-tag') to reduce additional operations and improve code execution efficiency.
  4. Simplify logic and improve readability: Removed the matching logic for CSS, JS, images and other resources to make the code clearer and easier to understand, maintain and adjust.

How to verify whether it is successful? After setting it up, when you directly access the origin site, you can see it in the response header of the HTML page under the "Network"-"Headers" tab of the browser developer tools (only visible when you directly access the origin site):

image.png

The reason why HTML Cache-Tag works is that WordPress processes page requests through PHP and adds corresponding tags in the send_headers Hook. However, static resources such as CSS, JS, and images are directly provided by Nginx or Apache and will not go through WordPress's PHP processing logic, so send_headers cannot work on these files.

If you want to implement Cache-Tag settings for CSS and JS, you need to set it up in Apache or Nginx that is paired with WordPress. Taking Apache as an example (because WordPress deployed in docker is based on Apache), you need tohtml/.htaccessAdd the following settings:

# ensures Apache version compatibility to prevent unexpected crashes"> Header always set Cache-Tag "css-tag""> Header always set Cache-Tag "js-tag" Header always set Cache-Tag "image-tag"

Then restart Docker, and you can set corresponding Cache-Tags for CSS, JS, and images (only for images in the source site under the same domain name, such as images in the WordPress media library).

2. Use Nginx as a reverse proxy

If the origin site uses Nginx as a reverse proxy server, you usually need to set Cache-Tag in the Nginx configuration file. Nginx can dynamically add Cache-Tags to different resources based on the requested URL path, request header, query parameters, and other conditions.

  • Based on URL path：Determine which tags to use based on the requested URL path. For example, add Cache-Tag: product to all page resources under the /products/ path.

Nginx configuration example:

For example, you want to add Cache-Tag: product to all page resources under the /products/ path:

location /products/ { add_header Cache-Tag "product"; }

explain：When the requested URL path starts with /products/, Nginx will add Cache-Tag: product to the response. This method is very suitable for path-based resource grouping (such as product pages, category pages, etc.).

  • Based on request headers or query parameters: You can dynamically add different Cache-Tags to different requests based on the HTTP request header (for example, User-Agent) or query parameters (for example, ?category=xyz).

Nginx configuration example:

If you want to add different Cache-Tags based on the user's User-Agent request header:

location / { if (http_user_agent ~* "mobile") { add_header Cache-Tag "mobile-tag"; } if (http_user_agent !~* "mobile") { add_header Cache-Tag "desktop-tag"; } }

explain: Based on the value of the User-Agent request header, if the user is accessing the site using a mobile device, Nginx will add Cache-Tag: mobile-tag to the response; if the user is accessing the site using a desktop device, it will add Cache-Tag: desktop-tag.

  • Add Cache-Tag based on query parameters

For example, if the URL contains the query parameter ?category=xyz, you want to add Cache-Tag: category-xyz to all such requests:

location / { if ($arg_category = "xyz") { add_header Cache-Tag "category-xyz"; } }

explain：When the requested URL contains the query parameter category=xyz, Nginx will add Cache-Tag: category-xyz to the response. This method is particularly suitable for adding tags to different content based on different filtering conditions (such as product categories, article categories, etc.).

3. Use Apache as a Web Server

If the origin uses Apache as a web server, you can usually add Cache-Tags through .htaccess files. Apache provides a powerful conditional judgment function that allows you to dynamically add custom tags to responses based on the request path, query parameters, or request headers. This makes it more flexible to fine-tune cache control in different situations.

.htaccess Configuration Example:

  • Add Cache-Tag based on URL path

For example, you want to add Cache-Tag: product to all pages under the /products/ path:

Header set Cache-Tag "product"

explain：When the requested URL path starts with /products/, Apache will add Cache-Tag: product to all resource responses under this path. This method is suitable for grouping resources according to the path structure, such as adding a unified tag to all product pages.

  • Add Cache-Tag based on request header

If you want to determine the Cache-Tag based on the request header (such as User-Agent), you can use the following configuration:

SetEnvIf User-Agent "mobile" CACHE_TAG=mobile-tag SetEnvIf User-Agent "desktop" CACHE_TAG=desktop-tag Header set Cache-Tag %{CACHE_TAG}e env=CACHE_TAG

explain：Based on the value of the User-Agent request header, Apache will check whether it is a mobile device or a desktop device. If it is a mobile device, add Cache-Tag: mobile-tag, if it is a desktop device, add Cache-Tag: desktop-tag. This method is suitable for setting different cache tags according to different access devices.

  • Add Cache-Tag based on query parameters

If you want to add a Cache-Tag to a request based on a query parameter in the URL (e.g. ?category=xyz), you can use the following configuration:

RewriteEngine On RewriteCond %{QUERY_STRING} category=xyz RewriteRule .* - [E=CACHE_TAG:category-xyz] Header set Cache-Tag %{CACHE_TAG}e env=CACHE_TAG

explain：When the URL query parameter category=xyz exists, Apache will add Cache-Tag: category-xyz to the request response. This method is suitable for distinguishing cache tags based on specific query parameters (such as product categories, article categories, etc.).

4. Use other CDN or reverse proxy services

If your site does not use Cloudflare, but other CDN or reverse proxy services (such as Fastly, AWS CloudFront, etc.), you can add Cache-Tag or similar tags according to the documentation of these services. Most modern CDNs support some form of cache tag mechanism, although the specific implementation may vary.

2.3 CDN content removal based on cache tag

If you want to clear the classified content corresponding to a cache tag in CDN, the operation is very simple. You only need to go to the "Cache" - "Configuration" - "Custom Clear" section of the dashboard:

image.png

Select "Tag", then enter the tag of the corresponding category to clear:
image.png

3 Based on path prefix method

If you want to clear the content under a certain path in the CDN, the operation is very simple. You don’t need to spend a long time marking the source server like the cache marking method. Instead, you only need to go to the “Cache”-“Configuration”-“Custom Clear” section of the dashboard:

image.png

Select "Prefix" and enter the corresponding prefix to clear it:
image.png

If the website considers the issue of cache cleanup in the early design stage, then by regularly planning the URL path structure, it is equivalent to implementing a "category classification" mechanism in advance. The biggest advantage of doing this is that even if you do not use the Cache-Tag function, you can still use the Cloudflare API to provide prefix match clearing function, efficiently implement cache cleaning of logical groups.

For example, if you put all your blog posts in the /posts/ directory and all your product pages in /products/, then when you publish or update an article, you only need to clear the cache under the /posts/ prefix through the API to clear the HTML, cover image, related scripts, etc. of the related articles at the same time, without having to list the URLs one by one.

In contrast, if the URL path design is chaotic and irregular, you can only specify specific URLs one by one in the later stage, which is easy to miss and increases maintenance costs.

This "structured path = implicit cache tag" design is suitable for:

  • Static blog/documentation website: URL composition is usually very regular;
  • E-commerce websites: You can design prefix paths by category, brand, activity, etc.;
  • Multilingual Website: You can use the language as the path prefix, such as /en/, /zh/, /fr/, etc.;
  • Large portal website: Different modules can be divided into paths according to functional modules, such as /news/, /events/, /videos/, etc.

In other words, if you do not have the conditions to use Cache-Tag and are unwilling to modify the server-side logic, then "good URL prefix planning" is one of the most reliable assets for your operation and maintenance of cache cleaning. Rather than being a stopgap measure, it is an architectural foresight in itself.

4 Use the API to clear specific cached content in CDN

4.1 Overview

Some friends may not like to frequently open the Cloudflare dashboard to operate manually, especially in daily maintenance or automatic deployment processes. This method is neither efficient nor realistic. In some automated scenarios, such as publishing new articles, updating page templates, and running CI/CD deployment scripts, we cannot rely on the graphical interface to clear the cache. At this time, the API provided by Cloudflare is particularly important.

By calling Cloudflare's cache purge API, we can programmatically manage cache and accurately purge caches under specific URLs, paths, tags (Cache-Tags), or host names without logging into the dashboard. This approach is not only flexible, but also very suitable for integration into automated processes, such as:

  • Automatically clear the cache of the corresponding page after publishing an article in WordPress;
  • After deploying static resources, only clear old resources under a specific path;
  • Regularly clean up cached content under certain tags to ensure that updates to the front-end pages can be reflected to visitors in a timely manner.

Compared with the crude approach of "clearing all caches", the fine-grained control capabilities of the API can effectively avoid unnecessary cache invalidation, thereby improving the performance of the website and user experience.

4.2 Clear the cache content of the specified category through the API

4.2.1 Prerequisites

To use the API, you will need the following information:

  • API Token(Recommended): Have the Zone.Cache Purge permission.
  • Zone ID: Your domain's unique identifier within Cloudflare.
  • Account Email(Such as using API Key).
  • API Endpoint: Address to use for cache clearing.

4.2.2 API request structure (clear cache tag)

Request address:

POST https://api.cloudflare.com/client/v4/zones/{zone_id}/purge_cache

Request Header(Using API Token):

Authorization: Bearer YOUR_API_TOKEN Content-Type: application/json

Request Body(Clear by tag):

{ "tags": ["html-tag"] }

4.2.3 curl call example

curl -X POST "https://api.cloudflare.com/client/v4/zones/YOUR_ZONE_ID/purge_cache" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ --data '{"tags": ["html-tag"]}'

You can add this command to your website deployment scripts, WordPress hooks (such as publish_post), and CI/CD processes to automatically clear the cache when specific events are triggered.

Note 1:Multiple Tags They can be cleared at the same time by writing them in array form, e.g. ["html-tag", "homepage", "footer"].

Note 2:API Token Permissions Recommendations: For security reasons, it is recommended to create a dedicated API Token and grant only Cache Purge permissions to avoid using the global API Key.

Note 3: If you are using API Key instead of Token, please use the following header instead

X-Auth-Email: [email protected] X-Auth-Key: your-global-api-key

4.3 Clear the cache content under the specified path through API

4.3.1 Prerequisites

To use the API to clear the cache content under a specified path, you need the following information:

  • API Token(Recommended): Have the Zone.Cache Purge permission.
  • Zone ID: Your domain's unique identifier within Cloudflare.
  • Account Email(Such as using API Key).
  • API Endpoint: Address to use for cache clearing.

4.3.2 API request structure (clear the cache under the specified path)

Request address:

POST https://api.cloudflare.com/client/v4/zones/{zone_id}/purge_cache

Request Header(Using API Token):

Authorization: Bearer YOUR_API_TOKEN Content-Type: application/json

Request Body(Clear by path prefix):

{ "prefixes": ["https://example.com/blog/"] }

In the request body, the prefixes array contains the path prefixes that need to be cleared. Cloudflare will clear all cached resources matching these path prefixes.

4.3.3 curl call example

curl -X POST "https://api.cloudflare.com/client/v4/zones/YOUR_ZONE_ID/purge_cache" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ --data '{"prefixes": ["https://example.com/blog/", "https://example.com/products/"]}'

You can add this command to your website deployment scripts, WordPress hooks (such as publish_post), and CI/CD processes to automatically clear the cache when specific events are triggered.

Note 1:Path prefix cleanup: By specifying a path prefix (such as /blog/ or /products/), you can purge all cached resources matching that path. This is much more concise than listing URLs one by one, especially when you know that all resources under a certain path need to be purged.

Note 2:Multiple path clearing: You can clear multiple path prefixes at the same time by writing them in array form, for example:["https://example.com/blog/", "https://example.com/products/"].

Note 3:API Token Permissions Recommendations: For security reasons, it is recommended to create a dedicated API Token and grant only Cache Purge permissions to avoid using the global API Key.

Note 4:If you are using an API Key: Instead of API Token, please use the following headers for authentication

X-Auth-Email: [email protected] X-Auth-Key: your-global-api-key

5 How to verify whether the Cache-Tag is effective?

image.png

From the official documentation of Cloudflare on Cache-Tag in the figure above, we can know that before receiving the response with Cache-Tag from the origin site and returning it to the website visitor, Cloudflare will directly delete all Cahce-Tags (understandably, Cache-Tag is originally for CDN providers to see and has nothing to do with visitors), so Cache-Tag cannot be seen in the developer tools of the visitor's browser (so I emphasized in the previous article that it can only be seen by directly visiting the origin site).

But how do you verify that Cache-Tag is really effective? In fact, it is very simple. Take my test site that does not use APO but uses regular page rules for caching as an example. First, set the rules as follows:

image.png

Use this page rule to enable caching for the test site, set to "Cache all content + Edge cache TTL is 2 hours". After this configuration, Cloudflare's edge nodes will cache the homepage content for 2 hours, but because the browser TTL is not set, the browser will not cache the page content locally.

The purpose of doing this is for the next test: I will use the "normal reload" (non-forced refresh) function to revisit the homepage. If the browser also caches the homepage locally, then even if Cloudflare's edge cache has expired, the browser may still read the page content directly from the local cache, interfering with the judgment. The current setting ensures that each load must obtain resources from Cloudflare, so as to more accurately observe and test the CDN cache status (for example, determine whether cf-cache-status is HIT or MISS).

Normally, the result of CF-Cahce-Status seen when visiting the homepage is "HIT":

image.png

At this time, as mentioned earlier in the article, first clear it directly in the "mark" of the custom clearing of the dashboard cachehtml-tagmark:

image.png

Then reload (refresh) the page normally. At this time, if the html-tag tag is cleared successfully, there should be no such page in the cache, so the result of Cf-Cache-Status should be "MISS":
image.png

6 Conclusion

For general personal webmasters, the operation and maintenance work will be much more efficient after using Cache-Tag, and they no longer have to "clear all content" with tears. Even for webmasters who use the APO function, Cache-Tag can often work wonders. Why do you say that?

Generally speaking,Using APO, you don’t need to manually clear the cache frequently., because APO itself is designed to solve the cache refresh problem of WordPress: it will monitor some typical update operations of WordPress in the background, such as publishing new articles, updating pages, modifying menus, etc. After these events occur,APO will automatically trigger the cache refresh of the corresponding pageThat is, in most cases,Just wait a few minutes to a few hoursThe new content will take effect automatically (Cloudflare officially says “within a few minutes”) without any manual intervention.

but,This "auto refresh" is not real-time and cannot cover all scenarios.For example, if you modify functions.php, theme template files, or adjust the header/footer structure, even if these changes directly affect the final output content of the page,APO will not detect these changes and will not automatically refresh the cacheThis is because APO's cache refresh mechanism essentially relies on WordPress's hook system to sense content changes - such as updating articles, publishing pages, switching themes, saving menus, etc. These are changes at the WordPress content level, and Cloudflare can automatically clear the corresponding cache through API notifications. However, changes to template files, plugin files, and PHP logic code,It does not trigger WordPress related event hooks, Cloudflare will naturally "not see" these changes, and the cached content may always remain in the old state.

In other words, in this type of "structural modification" scenario,APO is not "slow to refresh automatically", but "not refresh at all", no matter how long you wait, it will not take effect unless you manually clear the cache, or make a content-level modification through the background. For example, casually changing and saving an article can also trigger APO to refresh the relevant pages (in fact, this method is the simplest, but it is very low in technical content, and I disdain to use it. In addition, this can only be used for changes in templates and structures, such as modifying functions.php).

Therefore, for thoseNeed to frequently adjust templates, optimize structures, or debug output logicFor the site,APO alone is not enough, you still need to use the "manual clearing" function to ensure that the latest content is presented in the front end immediately. If you also want this "manual clearing" to be as smart and selective as possible (for example, clearing only HTML, clearing only certain types of pages), then Cache-Tag is a great tool. Of course, planning prefixes in advance and clearing the specified prefixes in the cache with custom functions is similar.

Share this article
The content of the blog is original. Please indicate the source when reprinting! For more blog articles, you can go toSitemapUnderstand. The RSS address of the blog is:https://blog.tangwudi.com/feed, welcome to subscribe; if necessary, you can joinTelegram GroupDiscuss the problem together.
cloudflareWordPressHome Data CenterTutorial
No Comments

Send Comment Edit Comment 


				

			

						

				

					

						

							

								
							

							
						

					

				

				

					

						

							

								
							

							
						

					

				

				

					

						

							

								
							

							
							
													

					

				

			

			
			

				

					
				

			

				

											

							
							
						

																					

							
							
						

										
					
											
						

	

		
|´・ω・)ノ
ヾ(≧∇≦*)ゝ
(☆ω☆)
(╯‵□′)╯︵┴─┴
￣﹃￣
(/ω＼)
∠(ᐛ 」∠)＿
(๑•̀ㅁ•́ฅ)
→_→
୧(๑•̀⌄•́๑)૭
٩(ˊᗜˋ*)و
(ノ°ο°)ノ
(´இ皿இ｀)
⌇●﹏●⌇
(ฅ´ω`ฅ)
(╯°A°)╯︵○○○
φ(￣∇￣o)
ヾ(´･ ･｀｡)ノ"
( ง ᵒ̌ᵒ̌)ง⁼³₌₃
(ó﹏ò｡)
Σ(っ°Д °;)っ
( ,,´･ω･)ﾉ"(´っω･｀｡)
╮(╯▽╰)╭
o(*////▽////*)q
＞﹏＜
( ๑´•ω•) "(ㆆᴗㆆ)
😂
😀
😅
😊
🙂
🙃
😌
😍
😘
😜
😝
😏
😒
🙄
😳
😡
😔
😫
😱
😭
💩
👻
🙌
🖕
👍
👫
👬
👭
🌚
🌝
🙈
💊
😶
🙏
🍦
🍉
😣
Source: github.com/k4yt3x/flowerhd
	

	

		
Emoticons
Emoji
Little Dinosaur
flower!
	


									

			

			
			
		

	






Previous
Next 

                    

                    
			        Related Posts
		            

		            

							
The second reconstruction of the home data center series blog architecture: service migration and active-active disaster recovery practice caused by VPS relocation

							
							

							
Home Data Center Series My Blog Security Assessment (Part 1): Test Tool Preparation Chapter Kali Linux Installation and Initialization

							
							

							
Home Data Center Series: Lightweight Bypass Gateway Construction Based on HTTP Proxy: Redsocks2 + iptables Practical Guide

							
							

							
Home Data Center Series Adding Social Sharing Buttons to WordPress Using Sassy Social Share Plugin

							
							

							
Home Data Center Series Cloudflare Monitoring Alarm Combination Practice: Health Check + Event Alarm Brings Lightweight Operation and Maintenance Experience

							
							

							
Home Data Center Series "API Shield" In-depth Analysis: Building a More Secure Cloudflare API Protection System

							
							

							
Home Data Center Series WordPress Icon Font Optimization: Local Hosting FontAwesome, Say Goodbye to API Limitations

							
							

							
Home Data Center Series Cloudflare Worker + KV: Building WordPress Cloud Article Reading Statistics

							
							

							
Home Data Center Series Cloudflare APO Cache Failure Analysis: Causes and Solutions for Cf-Cache-Status BYPASS

							
							

							
Home Data Center Series Cloudflare Pro In-depth Experience: From Free to Pro, is it worth upgrading?

							
							

					
				

			

		

        
		
						
					
		
	


    
    	
error: 

	
		
		
        
                
                

            


                
					en_US				

            

            


                
                    
          						  zh_CN					          
                en_US