本说明规范静态资源的落地方式与缓存策略：先约定目录与发布结构，再按资源类型设置缓存头，最后给出内容更新后的刷新路径。目标是让带指纹的资源长期缓存、入口 HTML 立即生效。

一、适用范围

• 适用：构建产物输出到 /srv/axis/www 的站点；资源文件名带内容指纹；需要按版本发布并保留上一版本以支持快速回退。
• 不适用：资源由后端动态生成、文件名固定的场景；需要按用户维度做差异化缓存；强依赖 CDN 边缘计算改写响应的架构。

二、准备工作

项目	要求	检查方法
站点目录	/srv/axis/www 存在且属主可写	ls -ld /srv/axis/www
构建产物	文件名含 hash，如 app.3f2a1c.js	ls /srv/axis/www/assets
Nginx	站点配置可编辑且语法正确	sudo nginx -t 通过
磁盘	至少保留两个版本的余量	df -h /srv/axis
CDN	如启用，已取得刷新权限	控制台可提交刷新任务
发布账号	deploy 对 releases 与 current 有写权限	sudo -u deploy test -w /srv/axis/www/releases

注意事项：

• 入口 HTML 不能设置长缓存，否则用户会长时间停留在旧版本的资源引用上。
• 目录结构一旦对外暴露就不要随意改名，回滚与 CDN 规则都依赖固定路径。

三、操作步骤

本节拆成三个子步骤，建议按顺序执行；每一步完成后先确认结果，再进入下一步。

3.1 目录结构规划

建立按版本发布的目录与原子切换的软链。详见 3.1 目录结构规划。

3.2 缓存规则配置

按资源类型区分长缓存与不缓存，并开启压缩。详见 3.2 缓存规则配置。

3.3 缓存刷新方法

发布后按正确顺序刷新层级缓存并逐层验证。详见 3.3 缓存刷新方法。

四、验证方法

1. 执行 curl -sSI https://example.com/assets/app.3f2a1c.js，预期 Cache-Control: public, max-age=31536000, immutable。
2. 执行 curl -sSI https://example.com/index.html，预期 Cache-Control: no-cache 且带 ETag。
3. 执行 ls -l /srv/axis/www/current，预期是指向 releases 下某个时间戳目录的软链。
4. 刷新后执行 curl -sSI https://example.com/index.html，预期出现 x-cache: MISS 或 Age: 0。

五、常见问题

现象	可能原因	处理方式
更新后页面仍是旧内容	index.html 被设置了长缓存	改为 no-cache，并刷新 CDN 的 HTML 路径
资源返回 404	新版本不再包含旧指纹文件，旧版本已删除	保留上一版本目录，或延长清理周期
缓存命中率低	文件名不含指纹，或查询串参与缓存键	使用内容指纹命名，固定查询串策略
刷新后仍旧内容	只刷新了 HTML 未刷新资源目录	按目录刷新，或改用带版本号的 URL
静态文件返回 403	目录缺少执行位或属主异常	核对属主与目录权限，逐级 namei -l 检查

六、回滚与注意事项

• 回滚：把 current 软链指回上一版本目录并重载 Nginx，然后刷新 CDN 的 HTML 路径。
• 注意：删除旧版本前确认 CDN 与浏览器缓存周期已过，通常保留两个版本足够。
• 注意：immutable 只对带指纹的文件名使用，用在 HTML 上会导致内容无法更新。

上一页3.3 自动续期配置

下一页3.1 目录结构规划