1
# Nginx 缓存策略配置（生产环境可用）
2

3
# HTML 文件：协商缓存，每次验证
4
location ~* \.html$ {
5
    add_header Cache-Control "no-cache";
6
    add_header Vary "Accept-Encoding";
7
}
8

9
# 带 hash 的静态资源：强缓存 + immutable
10
location ~* \.(?:css|js)$ {
11
    # 文件名带 hash 时用 immutable
12
    add_header Cache-Control "public, max-age=31536000, immutable";
13
    add_header Vary "Accept-Encoding";
14
    etag on;
15
}
16

17
# 图片资源：长缓存
18
location ~* \.(?:ico|gif|png|jpg|jpeg|webp|avif|svg)$ {
19
    add_header Cache-Control "public, max-age=2592000"; # 30 天
20
    etag on;
21
}
22

23
# Font 文件：长缓存
24
location ~* \.(?:woff2?|ttf|otf|eot)$ {
25
    add_header Cache-Control "public, max-age=31536000, immutable";
26
    add_header Vary "Accept-Encoding";
27
}
28

29
# API 接口：不缓存
30
location /api/ {
31
    add_header Cache-Control "no-store, no-cache, must-revalidate";
32
    add_header Pragma "no-cache";
33
    proxy_pass http://backend;
34
}

1
# generate_etag.py — 构建时生成 ETag
2
import hashlib
3
import os
4

5
def content_etag(filepath: str) -> str:
6
    """用文件内容的 SHA-256 前 16 位作为 ETag"""
7
    with open(filepath, "rb") as f:
8
        return '"' + hashlib.sha256(f.read()).hexdigest()[:16] + '"'
9

10
# 在 CI/CD 中生成 manifest
11
def build_cache_manifest(dist_dir: str) -> dict:
12
    manifest = {}
13
    for root, _, files in os.walk(dist_dir):
14
        for fname in files:
15
            fpath = os.path.join(root, fname)
16
            rel_path = os.path.relpath(fpath, dist_dir)
17
            manifest[rel_path] = {
18
                "etag": content_etag(fpath),
19
                "size": os.path.getsize(fpath),
20
            }
21
    return manifest

1
// sw.js — 生产级 Service Worker
2
const CACHE_NAME = "app-v2";
3
const STATIC_ASSETS = [
4
  "/",
5
  "/styles/main.css",
6
  "/scripts/app.js",
7
  "/offline.html",
8
];
9

10
// API 路径模式（需要网络优先）
11
const API_PATTERNS = [/^\/api\//, /\/graphql$/];
12

13
self.addEventListener("install", (event) => {
14
  event.waitUntil(
15
    caches.open(CACHE_NAME).then((cache) => cache.addAll(STATIC_ASSETS))
16
  );
17
  self.skipWaiting(); // 立即激活，不等旧 SW 关闭
18
});
19

20
self.addEventListener("activate", (event) => {
21
  event.waitUntil(
22
    caches.keys().then((keys) =>
23
      Promise.all(
24
        keys.filter((key) => key !== CACHE_NAME).map((key) => caches.delete(key))
25
      )
26
    )
27
  );
28
  self.clients.claim(); // 立即接管所有客户端
29
});
30

31
self.addEventListener("fetch", (event) => {
32
  const { request } = event;
33
  const url = new URL(request.url);
34

35
  // 跨域请求不拦截
36
  if (url.origin !== location.origin) return;
37

38
  // GET 请求才缓存
39
  if (request.method !== "GET") return;
40

41
  // API 请求：Network First
42
  if (API_PATTERNS.some((p) => p.test(url.pathname))) {
43
    event.respondWith(networkFirst(request));
44
    return;
45
  }
46

47
  // HTML 导航：Network First（保证页面最新）
48
  if (request.destination === "document") {
49
    event.respondWith(networkFirst(request));
50
    return;
51
  }
52

53
  // 静态资源：Cache First
54
  event.respondWith(cacheFirst(request));
55
});
56

57
async function cacheFirst(request) {
58
  const cached = await caches.match(request);
59
  if (cached) return cached;
60
  const response = await fetch(request);
61
  if (response.ok) {
62
    const cache = await caches.open(CACHE_NAME);
63
    cache.put(request, response.clone());
64
  }
65
  return response;
66
}
67

68
async function networkFirst(request) {
69
  try {
70
    const response = await fetch(request);
71
    if (response.ok) {
72
      const cache = await caches.open(CACHE_NAME);
73
      cache.put(request, response.clone());
74
    }
75
    return response;
76
  } catch {
77
    const cached = await caches.match(request);
78
    if (cached) return cached;
79
    // 最终降级：返回离线页面
80
    if (request.destination === "document") {
81
      return caches.match("/offline.html");
82
    }
83
    throw new Error("Network error and no cache available");
84
  }
85
}

1
# Dockerfile — 前端应用多阶段构建
2
FROM node:20-alpine AS builder
3

4
WORKDIR /app
5
# 先装依赖（利用 Docker 层缓存）
6
COPY package.json pnpm-lock.yaml ./
7
RUN corepack enable && pnpm install --frozen-lockfile
8

9
# 构建应用
10
COPY . .
11
RUN pnpm build
12

13
# 生产阶段：用 Nginx 提供静态文件
14
FROM nginx:alpine AS production
15

16
# 复制自定义缓存配置
17
COPY nginx/cache.conf /etc/nginx/conf.d/cache.conf
18
COPY nginx/default.conf /etc/nginx/conf.d/default.conf
19

20
# 复制构建产物
21
COPY --from=builder /app/dist /usr/share/nginx/html
22

23
# 健康检查
24
HEALTHCHECK --interval=30s --timeout=3s \
25
  CMD wget -q --spider http://localhost/ || exit 1
26

27
EXPOSE 80

1
# test_cache_headers.py — 自动化缓存头测试
2
import httpx
3
import pytest
4
from dataclasses import dataclass
5
from typing import List
6

7

8
@dataclass
9
class CacheTestResult:
10
    url: str
11
    status_code: int
12
    cache_control: str
13
    etag: str | None
14
    expected_pattern: str
15
    passed: bool
16
    message: str
17

18

19
class CacheHeaderTester:
20
    """缓存头自动化测试器"""
21

22
    def __init__(self, base_url: str = "http://localhost"):
23
        self.client = httpx.Client(base_url=base_url, follow_redirects=True)
24
        self.results: List[CacheTestResult] = []
25

26
    def test_static_resource(self, path: str, min_max_age: int = 86400):
27
        """测试静态资源应该有长缓存"""
28
        resp = self.client.get(path)
29
        cc = resp.headers.get("cache-control", "")
30

31
        # 检查 max-age
32
        max_age = self._parse_max_age(cc)
33
        passed = max_age >= min_max_age
34

35
        self.results.append(CacheTestResult(
36
            url=f"{self.client.base_url}{path}",
37
            status_code=resp.status_code,
38
            cache_control=cc,
39
            etag=resp.headers.get("etag"),
40
            expected_pattern=f"max-age >= {min_max_age}",
41
            passed=passed,
42
            message=f"max-age={max_age}" if passed else f"max-age={max_age} 太小",
43
        ))
44

45
    def test_html_page(self, path: str = "/"):
46
        """测试 HTML 页面应该有协商缓存"""
47
        resp = self.client.get(path)
48
        cc = resp.headers.get("cache-control", "")
49

50
        passed = "no-cache" in cc or "must-revalidate" in cc
51

52
        self.results.append(CacheTestResult(
53
            url=f"{self.client.base_url}{path}",
54
            status_code=resp.status_code,
55
            cache_control=cc,
56
            etag=resp.headers.get("etag"),
57
            expected_pattern="no-cache 或 must-revalidate",
58
            passed=passed,
59
            message="协商缓存正确" if passed else "HTML 不应该强缓存",
60
        ))
61

62
    def test_api_endpoint(self, path: str):
63
        """测试 API 不应该被缓存"""
64
        resp = self.client.get(path)
65
        cc = resp.headers.get("cache-control", "")
66

67
        passed = "no-store" in cc or "no-cache" in cc
68

69
        self.results.append(CacheTestResult(
70
            url=f"{self.client.base_url}{path}",
71
            status_code=resp.status_code,
72
            cache_control=cc,
73
            etag=resp.headers.get("etag"),
74
            expected_pattern="no-store 或 no-cache",
75
            passed=passed,
76
            message="API 缓存正确" if passed else "API 不应该被缓存",
77
        ))
78

79
    def test_conditional_request(self, path: str):
80
        """测试条件请求（ETag / If-None-Match）"""
81
        # 第一次请求，获取 ETag
82
        resp1 = self.client.get(path)
83
        etag = resp1.headers.get("etag")
84

85
        if not etag:
86
            self.results.append(CacheTestResult(
87
                url=f"{self.client.base_url}{path}",
88
                status_code=resp1.status_code,
89
                cache_control=resp1.headers.get("cache-control", ""),
90
                etag=None,
91
                expected_pattern="有 ETag",
92
                passed=False,
93
                message="响应没有 ETag，无法做条件请求",
94
            ))
95
            return
96

97
        # 第二次请求，带 If-None-Match
98
        resp2 = self.client.get(path, headers={"If-None-Match": etag})
99

100
        passed = resp2.status_code == 304
101
        self.results.append(CacheTestResult(
102
            url=f"{self.client.base_url}{path}",
103
            status_code=resp2.status_code,
104
            cache_control=resp2.headers.get("cache-control", ""),
105
            etag=etag,
106
            expected_pattern="304 Not Modified",
107
            passed=passed,
108
            message=f"返回 {resp2.status_code}" + (" ✅ 条件请求生效" if passed else " ❌ 应该返回 304"),
109
        ))
110

111
    @staticmethod
112
    def _parse_max_age(cache_control: str) -> int:
113
        """从 Cache-Control 头提取 max-age 值"""
114
        for directive in cache_control.split(","):
115
            directive = directive.strip()
116
            if directive.startswith("max-age="):
117
                try:
118
                    return int(directive.split("=")[1])
119
                except (ValueError, IndexError):
120
                    return 0
121
        return 0
122

123
    def print_report(self):
124
        """打印测试报告"""
125
        passed = sum(1 for r in self.results if r.passed)
126
        total = len(self.results)
127

128
        print(f"\n{'='*60}")
129
        print(f"缓存头测试报告: {passed}/{total} 通过")
130
        print(f"{'='*60}")
131

132
        for r in self.results:
133
            icon = "✅" if r.passed else "❌"
134
            print(f"{icon} {r.url}")
135
            print(f"   Cache-Control: {r.cache_control or '(无)'}")
136
            print(f"   ETag: {r.etag or '(无)'}")
137
            print(f"   → {r.message}")
138
            print()
139

140
        return passed == total
141

142

143
# 使用示例
144
if __name__ == "__main__":
145
    tester = CacheHeaderTester("http://boke.hackerdream.xyz")
146

147
    # 测试各类资源
148
    tester.test_html_page("/")
149
    tester.test_static_resource("/scripts/app.js", min_max_age=31536000)
150
    tester.test_static_resource("/styles/main.css", min_max_age=31536000)
151
    tester.test_static_resource("/images/logo.webp", min_max_age=2592000)
152
    tester.test_api_endpoint("/api/posts")
153
    tester.test_conditional_request("/scripts/app.js")
154

155
    # 生成报告
156
    all_passed = tester.print_report()
157
    exit(0 if all_passed else 1)

1
# .github/workflows/cache-test.yml（或 Gitee 对应的 CI 配置）
2
name: Cache Header Test
3

4
on:
5
  deployment:
6
    types: [created]
7

8
jobs:
9
  test-cache:
10
    runs-on: ubuntu-latest
11
    steps:
12
      - uses: actions/checkout@v4
13
      - uses: actions/setup-python@v5
14
        with:
15
          python-version: "3.12"
16
      - run: pip install httpx
17
      - run: python test_cache_headers.py
18
        env:
19
          BASE_URL: ${{ vars.DEPLOY_URL }}