Cache Rules

Sudun TeamMay 3, 2026 at 11:02Estimated reading time 4 min

How caching works

code

请求 → 边缘服务器 → 缓存检查
                            │
                    ┌───────┴───────┐
                    │               │
               缓存命中        缓存未命中
                    │               │
              返回缓存内容     从源站获取
                              缓存响应
                              返回给用户

Default caching behavior

By default, Sudun caches based on the following content types:

Content type	Default TTL	Cacheable
Images (jpg, png, gif, webp)	1 day	is
CSS、JavaScript	1 day	is
Font (woff, woff2, ttf)	1 day	is
HTML	No caching	Nope
API response	No caching	Nope

Create a caching rule

Go to Domain → and select your domain name
Navigate to Cache → Cache Rules
Click Create rule

Rules are constituents

elements	Description	Example
Matching conditions	Match the requested conditions	URL path, file extension
Cache operations	How to handle matching requests	Caching, bypassing, overwriting
TTL	Cache lifetime	3600 (1 hour)

Matching conditions

URL path matching

code

# 精确匹配
/images/logo.png

# 前缀匹配
/static/*

# 通配符匹配
/api/*/public

# 正则匹配 (高级)
^/blog/[0-9]{4}/.*$

File extension matches

Caching by file type:

json

{
  "match": {
    "file_extension": ["jpg", "jpeg", "png", "gif", "webp", "css", "js"]
  },
  "action": "cache",
  "ttl": 86400
}

Query string matches

json

{
  "match": {
    "path": "/search",
    "query_string": {
      "contains": "category"
    }
  }
}

Request header match

json

{
  "match": {
    "headers": {
      "Accept": "application/json"
    }
  },
  "action": "bypass"
}

Cache operations

Caching

Store content on edge servers:

json

{
  "match": { "path": "/static/*" },
  "action": "cache",
  "ttl": 604800,
  "settings": {
    "browser_ttl": 86400,
    "serve_stale": true
  }
}

Bypass cache

Always get from the origin:

json

{
  "match": { "path": "/api/*" },
  "action": "bypass"
}

Cover the head of the source station

Ignoring the origin cache header:

json

{
  "match": { "path": "/assets/*" },
  "action": "override",
  "ttl": 2592000,
  "ignore_origin_headers": true
}

TTL configuration

Edge TTL

How long content is cached on the edge server:

value	Duration	Usage scenarios
60	1 minute	Frequently updated content
3600	1 hour	Semi-dynamic content
86400	1 day	Static resources
604800	1 week	Minimal changes
2592000	30 days	Versioned resources

Browser TTL

When the browser caches content locally:

json

{
  "edge_ttl": 86400,
  "browser_ttl": 3600
}

Tip: Set the browser TTL to be shorter than the edge TTL to maintain control over cache invalidation.

Cache key configuration

The cache key determines what makes the cached object unique.

Default cache key

code

https://example.com/page?sort=date&page=1
         │            │        │
      协议方案      路径     查询字符串

Query string processing

options	behavior
Contains all	The cache changes with all query parameters
Exclude all	Ignore query strings for caching
Contains specific	Only specifying parameters affects the cache
Exclude specific	Ignore the specified parameters

Example: Contains specific parameters

json

{
  "cache_key": {
    "query_string": {
      "include": ["category", "page"]
    }
  }
}

Cache keys based on the request header

Cache based on request header changes:

json

{
  "cache_key": {
    "headers": ["Accept-Language", "Accept-Encoding"]
  }
}

Cache according to cookie changes (use with caution):

json

{
  "cache_key": {
    "cookies": ["session_type", "user_tier"]
  }
}

Stale content disposal

Stale content is available during revalidation

Serve cached content while fetching new content:

json

{
  "serve_stale": {
    "while_revalidate": true,
    "on_error": true,
    "max_stale_age": 86400
  }
}

Provide stale content when it goes wrong

Serve stale content when origin fails:

code

源站错误 (5xx) → 提供陈旧内容 → 记录错误

Cache control head

Follow the origin header

By default, Sudun follows the following origin headers:

head	behavior
Cache-Control: max-age=X	Cache X seconds
Cache-Control: no-cache	Revalidate before provision
Cache-Control: no-store	No caching
Cache-Control: private	Not cached at the edge
Expires	Cache until the specified date
ETag	Enable conditional requests

Cover the head of the source station

Force caching, ignoring the origin header:

json

{
  "match": { "path": "/static/*" },
  "action": "cache",
  "ttl": 86400,
  "respect_origin_headers": false
}

Rule priority

Rules are evaluated sequentially. The first matched rule takes effect:

code

规则 1: /api/* → 绕过 (优先级: 1)
规则 2: /api/public/* → 缓存 (优先级: 2)
规则 3: /* → 缓存 (优先级: 3)

请求: /api/users → 匹配规则 1 → 绕过
请求: /api/public/data → 匹配规则 1 → 绕过 (而非规则 2!)

Important: Put more specific rules before generic rules.

Common cache rule patterns

Static resources

json

{
  "name": "静态资源",
  "match": {
    "file_extension": ["css", "js", "jpg", "png", "gif", "ico", "woff2"]
  },
  "action": "cache",
  "ttl": 2592000,
  "browser_ttl": 86400
}

API response

json

{
  "name": "API 绕过",
  "match": { "path": "/api/*" },
  "action": "bypass"
}

HTML pages with short TTLs

json

{
  "name": "HTML 页面",
  "match": {
    "file_extension": ["html"],
    "path": "/*"
  },
  "action": "cache",
  "ttl": 300,
  "serve_stale": true
}

Versioned Resources (Long TTL)

json

{
  "name": "版本化资源",
  "match": {
    "path": "/assets/v*/*"
  },
  "action": "cache",
  "ttl": 31536000,
  "immutable": true
}

Debug cache rules

Cache state header

Check the X-Cache-Status response header:

state	Meaning
HIT	Provided from the cache
MISS	Get it from the origin source
BYPASS	The cache is bypassed
EXPIRED	The cache expires and is being revalidated
STALE	Provide stale content

Test the caching rules

bash

# 检查缓存状态
curl -I https://example.com/static/style.css

# 响应头部
X-Cache-Status: HIT
Cache-Control: max-age=86400
Age: 3600

API Reference

Manage caching rules via API:

bash

# 列出缓存规则
curl -X GET https://api.Sudun.com/v1/domains/example.com/cache-rules \
  -H "Authorization: Bearer YOUR_API_KEY"

# 创建缓存规则
curl -X POST https://api.sudun/v1/domains/example.com/cache-rules \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Static Assets",
    "match": {"file_extension": ["css", "js", "png"]},
    "action": "cache",
    "ttl": 86400
  }'

Need help with caching rules? Please contact admin@jindun.com

Cache Rules

How caching works

Default caching behavior

Create a caching rule

Rules are constituents

Matching conditions

URL path matching

File extension matches

Query string matches

Request header match

Cache operations

Caching

Bypass cache

Cover the head of the source station

TTL configuration

Edge TTL

Browser TTL

Cache key configuration

Default cache key

Query string processing

Cache keys based on the request header

Cookie-based cache keys

Stale content disposal

Stale content is available during revalidation

Provide stale content when it goes wrong

Cache control head

Follow the origin header

Cover the head of the source station

Rule priority

Common cache rule patterns

Static resources

API response

HTML pages with short TTLs

Versioned Resources (Long TTL)

Debug cache rules

Cache state header

Test the caching rules

API Reference

Tags

How caching works

Default caching behavior

Create a caching rule

Rules are constituents

Matching conditions

URL path matching

File extension matches

Query string matches

Request header match

Cache operations

Caching

Bypass cache

Cover the head of the source station

TTL configuration

Edge TTL

Browser TTL

Cache key configuration

Default cache key

Query string processing

Cache keys based on the request header

Cookie-based cache keys

Stale content disposal

Stale content is available during revalidation

Provide stale content when it goes wrong

Cache control head

Follow the origin header

Cover the head of the source station

Rule priority

Common cache rule patterns

Static resources

API response

HTML pages with short TTLs

Versioned Resources (Long TTL)

Debug cache rules

Cache state header

Test the caching rules

API Reference