Cache Configuration

The HTTP Gateway supports configuring cache rules for custom domains: match by request characteristics (URL path, file extension, full URI), then pick a cache action — control edge and browser cache durations, or define a custom cache key strategy — to speed up resource access and reduce the load on your origin server.

Scope

Cache rules only take effect on custom domains. Before configuring cache rules, make sure the custom domain has Edge Acceleration enabled, or was previously integrated via the legacy CloudBase CDN (this integration is no longer available for new setups and only applies to existing domains).

Note: Default domains do not allow cache configuration.

Configuration Entry

Go to the CloudBase platform → HTTP Gateway → Cache Configuration to maintain a list of cache rules for each domain.

Each domain holds up to 3 rules. The rule listed lower in the list has the highest priority. Matching proceeds bottom-up in the rule list, and the first match wins. Each rule maps 1 condition (target + match type + values) to 1 action. The console supports drag-and-drop sorting: drag the handle on the left of a rule to reorder rules and adjust their priority. After reordering, you must click the "Save" button in the upper-right corner for the new order to take effect.

Overall Structure

Domain
 └─ Cache (cache configuration)
      └─ Rules[] (rule list; array order is priority, the lower, the higher)
           ├─ Condition: which requests the rule matches
           └─ Actions : what to do when matched

That's all you need to remember: for each incoming request, the gateway walks Rules from top to bottom, the first rule whose Condition matches applies, and its Actions are executed.

Supported Match Conditions

For each rule's "Match Condition" dropdown, you pick one target, one match type, and a list of values. The console offers three targets, corresponding to Condition.Target:

Console target	Target	What it matches
URL Path	url_path	Request path (excluding the part after ?)
File Extension	file_extension	File extension (e.g. css, jpg)
Full URI	full_uri	Full URI (path + query string)

The match type is specified by Condition.MatchType:

MatchType	Meaning
prefix	Prefix match (e.g. anything under /static/)
suffix	Suffix match (e.g. anything ending in .png)
contains	Contains match
exact	Exact match

Condition.Values is a string array; any hit triggers the rule (OR semantics), up to 100 entries, each 1~1024 bytes.

Constraint: each rule allows only 1 match condition (target + match type + values).

Cache Actions

Each rule picks exactly one cache action from the dropdown. The console offers only two actions, matching Actions.Type:

Console action	Maps to Type	Purpose
Custom Cache	Cache	Control edge and browser cache durations
Custom Cache Key	CacheKey	Define "what counts as the same cache" (requires Edge Acceleration)

Note

The CacheKey action only takes effect on domains with Edge Acceleration enabled. The legacy CloudBase CDN integration (existing domains) is not supported.

Action I: Custom Cache (Type=Cache)

Within "Custom Cache", there are three mutually exclusive strategies — pick exactly one:

Strategy A: Do not cache

Best for requests that must always return the latest result — dynamic APIs, real-time data, and similar.

{ "Type": "Cache", "Cache": { "NoCache": true } }

Effect: the response carries Cache-Control: no-cache, so neither the edge nor the browser caches.

Strategy B: Custom durations

Lets you independently set edge node and browser cache durations. Commonly used for static resources (images, CSS, JS, fonts, etc.).

{
  "Type": "Cache",
  "Cache": {
    "CacheTime": 86400,    // Edge cache for 1 day
    "MaxAgeTime": 3600     // Browser cache for 1 hour
  }
}

Don't confuse the two durations:

Field	Controls	Response Header
CacheTime	Edge node (Edge Acceleration / CDN)	s-maxage
MaxAgeTime	User browser	max-age

Range: [0, 31536000] (0 seconds to 1 year). You may set just one of them.

Strategy C: Follow the origin

Use when the origin (cloud function / static hosting) already supplies Cache-Control, and you don't want the edge to override that policy.

{ "Type": "Cache", "Cache": { "FollowOrigin": true } }

Effect: both edge and browser cache durations follow the origin's Cache-Control.

Action II: Custom Cache Key (Type=CacheKey)

Lets you tell the edge which parameters to ignore and which must distinguish entries, so the same resource hits the same cached entry more efficiently.

By default, URLs with different query strings are stored as separate cache entries — for example, page.html?a=1 and page.html?a=2 are cached twice.

Query-string handling offers two strategies via QueryStringAction:

QueryStringAction	Meaning
includeCustom	Allowlist: only the listed parameters participate in the cache key; others are ignored
excludeCustom	Denylist: the listed parameters are ignored; others participate

Example: ignore tracking parameters so the same resource shares one cached entry:

{
  "Type": "CacheKey",
  "CacheKey": {
    "FullURLCache": "off",
    "QueryStringSwitch": "on",
    "QueryStringAction": "excludeCustom",
    "QueryStringValues": ["debug", "from"]
  }
}

Two constraints:

• FullURLCache=on and QueryStringSwitch=on are mutually exclusive.
• When QueryStringSwitch=on, QueryStringAction is required.

The two actions — "Custom Cache" and "Custom Cache Key" — can be stacked in the same rule: for example, set "Custom durations" (static resources cached for 1 day) and "Custom Cache Key" (ignore tracking params) together.

Configuration Examples

The five scenarios below show how to combine the two actions above into ready-to-use configurations.

Scenario 1: Cache static resources for faster loading

"Custom Cache → Custom durations":

{
  "Description": "Cache static resources",
  "Enable": true,
  "Condition": {
    "Target": "file_extension",
    "MatchType": "exact",
    "Values": ["jpg", "png", "gif", "css", "js", "svg", "woff2"]
  },
  "Actions": [
    {
      "Type": "Cache",
      "Cache": {
        "CacheTime": 86400,
        "MaxAgeTime": 3600
      }
    }
  ]
}

Scenario 2: Dynamic APIs and real-time data — never cache

"Custom Cache → Do not cache":

{
  "Description": "Do not cache API",
  "Enable": true,
  "Condition": {
    "Target": "url_path",
    "MatchType": "prefix",
    "Values": ["/api/"]
  },
  "Actions": [
    { "Type": "Cache", "Cache": { "NoCache": true } }
  ]
}

Scenario 3: Let the origin decide the cache policy

"Custom Cache → Follow the origin":

{
  "Condition": {
    "Target": "url_path",
    "MatchType": "prefix",
    "Values": ["/src/"]
  },
  "Actions": [
    { "Type": "Cache", "Cache": { "FollowOrigin": true } }
  ]
}

Scenario 4: Ignore tracking parameters so the same resource shares one cache entry

"Custom Cache Key → Denylist": HTML files would otherwise be cached separately per URL. By ignoring debug and from, every request carrying these tracking parameters shares the same cached entry.

{
  "Description": "Ignore debug, from parameters",
  "Condition": {
    "Target": "url_path",
    "MatchType": "suffix",
    "Values": [".html"]
  },
  "Actions": [
    {
      "Type": "CacheKey",
      "CacheKey": {
        "FullURLCache": "off",
        "QueryStringSwitch": "on",
        "QueryStringAction": "excludeCustom",
        "QueryStringValues": ["debug", "from"]
      }
    }
  ]
}

Scenario 5: Share one cache entry while keeping versioned parameters

A combination of "Custom Cache (Custom durations)" + "Custom Cache Key (Allowlist)": only v and lang participate in the cache key; everything else is ignored; cache for 1 day.

{
  "Description": "Keep versioned parameters",
  "Enable": true,
  "Condition": {
    "Target": "file_extension",
    "MatchType": "exact",
    "Values": ["js", "css"]
  },
  "Actions": [
    {
      "Type": "Cache",
      "Cache": {
        "CacheTime": 86400,
        "MaxAgeTime": 3600
      }
    },
    {
      "Type": "CacheKey",
      "CacheKey": {
        "FullURLCache": "off",
        "QueryStringSwitch": "on",
        "QueryStringAction": "includeCustom",
        "QueryStringValues": ["v", "lang"]
      }
    }
  ]
}

Meaning: only differences in v and lang produce different cache entries; other parameters are ignored.

Field Reference

Field	Type	Description
Rules	HTTPServiceCacheRule[]	Rule list; array order is priority — the lower, the higher

Single Rule

Field	Type	Required	Description
Description	string	No	Description, up to 128 bytes
Enable	boolean	No	Switch; true / omitted to enable, false to disable
Condition	HTTPServiceRuleCondition	Yes	Match condition
Actions	HTTPServiceCacheAction[]	No	List of cache actions; at most one Action of the same Type per rule

Cache Action Actions

Field	Type	Description
Type	string	Cache (Custom Cache) or CacheKey (Custom Cache Key)
Cache	HTTPServiceCacheParams	Required when Type=Cache
CacheKey	HTTPServiceCacheKeyParams	Required when Type=CacheKey

At most one Action of the same Type is allowed per rule.

Cache Parameters Cache

Three mutually exclusive switches — pick exactly one:

Combination	Field	Effect
Do not cache	NoCache: true	Neither edge nor browser caches (Strategy A)
Custom duration	CacheTime and/or MaxAgeTime	Edge and browser cache durations in seconds (Strategy B)
Follow origin	FollowOrigin: true	Both edge and browser follow the origin's Cache-Control (Strategy C)

CacheTime / MaxAgeTime range: [0, 31536000] (0 seconds to 1 year).

Cache Key Parameters CacheKey

Field	Values	Meaning
FullURLCache	on / off	Use the full URL (including query string) as the cache key
QueryStringSwitch	on / off	Whether query parameters participate in the cache key
QueryStringAction	includeCustom	Allowlist: only listed parameters participate in the cache key
	excludeCustom	Denylist: listed parameters are ignored
QueryStringValues	string array	Parameter names, up to 100 entries, each 1~128 bytes

Two constraints:

• FullURLCache=on and QueryStringSwitch=on are mutually exclusive.
• When QueryStringSwitch=on, QueryStringAction is required.

Full Configuration Example

A typical setup that covers both dynamic APIs and static resources:

{
  "Domain": "your-domain.com",
  "Extension": {
    "Cache": {
      "Rules": [
        {
          "Description": "Cache static resources",
          "Enable": true,
          "Condition": {
            "Target": "file_extension",
            "MatchType": "exact",
            "Values": ["jpg", "png", "css", "js", "svg"]
          },
          "Actions": [
            {
              "Type": "Cache",
              "Cache": { "CacheTime": 86400, "MaxAgeTime": 3600 }
            }
          ]
        },
        {
          "Description": "Do not cache API",
          "Enable": true,
          "Condition": {
            "Target": "url_path",
            "MatchType": "prefix",
            "Values": ["/api/"]
          },
          "Actions": [{ "Type": "Cache", "Cache": { "NoCache": true } }]
        }
      ]
    }
  }
}

Rule priority

The "Cache static resources" rule is placed above "Do not cache API" because the rule lower in the list has the highest priority, so the "Do not cache API" rule listed below wins; a .js request under /api/ is caught by that NoCache rule, preventing API scripts from being cached.

Verifying the Configuration

1. Check the configuration: call DescribeHTTPServiceRoute and verify that the returned Domain.Extension.Cache matches what you submitted.
2. Check the response headers: send a request to the target resource and inspect Cache-Control:
   • max-age=3600 ← from MaxAgeTime
   • s-maxage=86400 ← from CacheTime
3. Check cache hits: send the same request twice in a row. When eo-cache-status changes from MISS to HIT, the edge cache is working.

Purging the Cache

After configuring cache rules, updates to the origin (e.g. redeploying static resources, changing API content) do not automatically propagate to edge nodes, because the edge cache continues to follow the rules. You need to actively purge the cache so that edge nodes fetch the latest content from the origin on the next request.

Go to the CloudBase platform → HTTP Gateway → Cache Configuration → Purge Cache tab.

Purge Mode

Field	Type	Description
Domain	Required	The custom domain to purge
Cache Type	Required	Edge Acceleration (edge node cache for custom domains with Edge Acceleration on) or CDN Cache (Legacy) (cache for the legacy CloudBase CDN integration; no longer used for new integrations)
Purge Mode	URL / Directory	Single-file URL purge, or batch purge by directory prefix
Targets	Required	List of URLs or directory prefixes, depending on the chosen Purge Mode

Use Cases

• Static resource updates: after redeployment, use URL purge to make all edge nodes fetch the new version.
• Batch rollback: use directory purge to force an entire directory to re-fetch from the origin.
• Incident fix: when a cached resource version goes wrong, immediately purge by URL.

Note

Purging only clears the edge node cache, not the browser's local cache. To force end users to see the latest content immediately, also use Cache-Control: no-cache or change version numbers / file names.

Viewing Purge History

Switch to the History tab to query past purge tasks by time range:

Field	Description
Time	Task submission time
Task ID	Backend task identifier
Domain	The purged domain
Cache Type	Edge Acceleration / CDN Cache (Legacy)
Purge Mode	URL / Directory
Target	URL or directory prefix
Status	Processing / Success / Failed
Created Time	Same as the Time field

Related Documentation

• API: ModifyHTTPServiceRoute
• Query: DescribeHTTPServiceRoute
• Data structure: HTTPServiceDomainParam