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

| 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) |
# 精确匹配
/images/logo.png
# 前缀匹配
/static/*
# 通配符匹配
/api/*/public
# 正则匹配 (高级)
^/blog/[0-9]{4}/.*$
Caching by file type:
{
"match": {
"file_extension": ["jpg", "jpeg", "png", "gif", "webp", "css", "js"]
},
"action": "cache",
"ttl": 86400
}
{
"match": {
"path": "/search",
"query_string": {
"contains": "category"
}
}
}
{
"match": {
"headers": {
"Accept": "application/json"
}
},
"action": "bypass"
}
Store content on edge servers:
{
"match": { "path": "/static/*" },
"action": "cache",
"ttl": 604800,
"settings": {
"browser_ttl": 86400,
"serve_stale": true
}
}
Always get from the origin:
{
"match": { "path": "/api/*" },
"action": "bypass"
}
Ignoring the origin cache header:
{
"match": { "path": "/assets/*" },
"action": "override",
"ttl": 2592000,
"ignore_origin_headers": true
}
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 |
When the browser caches content locally:
{
"edge_ttl": 86400,
"browser_ttl": 3600
}
Tip: Set the browser TTL to be shorter than the edge TTL to maintain control over cache invalidation.
The cache key determines what makes the cached object unique.
https://example.com/page?sort=date&page=1
│ │ │
协议方案 路径 查询字符串
| 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
{
"cache_key": {
"query_string": {
"include": ["category", "page"]
}
}
}
Cache based on request header changes:
{
"cache_key": {
"headers": ["Accept-Language", "Accept-Encoding"]
}
}
Cache according to cookie changes (use with caution):
{
"cache_key": {
"cookies": ["session_type", "user_tier"]
}
}
Serve cached content while fetching new content:
{
"serve_stale": {
"while_revalidate": true,
"on_error": true,
"max_stale_age": 86400
}
}
Serve stale content when origin fails:
源站错误 (5xx) → 提供陈旧内容 → 记录错误
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 |
Force caching, ignoring the origin header:
{
"match": { "path": "/static/*" },
"action": "cache",
"ttl": 86400,
"respect_origin_headers": false
}
Rules are evaluated sequentially. The first matched rule takes effect:
规则 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.
{
"name": "静态资源",
"match": {
"file_extension": ["css", "js", "jpg", "png", "gif", "ico", "woff2"]
},
"action": "cache",
"ttl": 2592000,
"browser_ttl": 86400
}
{
"name": "API 绕过",
"match": { "path": "/api/*" },
"action": "bypass"
}
{
"name": "HTML 页面",
"match": {
"file_extension": ["html"],
"path": "/*"
},
"action": "cache",
"ttl": 300,
"serve_stale": true
}
{
"name": "版本化资源",
"match": {
"path": "/assets/v*/*"
},
"action": "cache",
"ttl": 31536000,
"immutable": true
}
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 |
# 检查缓存状态
curl -I https://example.com/static/style.css
# 响应头部
X-Cache-Status: HIT
Cache-Control: max-age=86400
Age: 3600
Manage caching rules via API:
# 列出缓存规则
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