阿里云 ESA 加速与缓存

授权网站使用 ESA 分发静态资源。本文配置适用于当前宝塔 Nginx 静态站点，文件在仓库 config/nginx/；发布脚本不会自动安装这些配置或修改 ESA 控制台。

缓存范围

ESA 默认仅让 GET、HEAD 进入缓存组件。源站的 no-cache、no-store、max-age=0 等指令会阻止缓存；配置 ESA 缓存规则前，应先核对实际源站响应头。HTML 还需要显式设置缓存资格，不能仅设置响应头就认为必然命中。

请求	源站 Cache-Control	ESA 策略
无查询参数的 `/`、`/index.html`	`public, max-age=60, s-maxage=300`	显式允许缓存，遵循源站 TTL
`/assets/` 下构建生成的哈希资源	`public, max-age=31536000, immutable`	允许缓存，遵循源站 TTL
`/callback/web`、`/callback/mini` 及其他 SPA 页面	`no-store`	绕过缓存
携带查询参数的首页，例如 `/?scene=1&code=...`	`no-store`	绕过缓存
`/admin/verification`，含或不含 secret	`no-store`	绕过缓存
`/api/verification-files`	后端继续返回 `no-store`	绕过缓存，保持 POST 请求正常回源
根路径微信校验 `.txt`、`/.well-known/`	`no-store`（在对应源站规则中配置）	绕过缓存，包括不存在文件的 404

回调页面本身是静态 HTML，但授权 URL 含一次性参数，采用绕过策略避免缓存规则扩展到业务数据，并减少过期页面干扰。大体积 JS/CSS 仍由边缘节点分发。不要全站删除 no-store 或开启全站强制缓存。

宝塔 Nginx 配置

修改前通过宝塔备份主配置和站点配置。两个片段分别属于不同上下文，不能全部粘贴到站点 server 块中。

1. 在 http 块内加入 map

将仓库 config/nginx/auth-cache-http.conf 的内容放入 Nginx 主配置的 http { ... } 内，仅配置一次：

nginx

map $request_uri $weixin_auth_html_cache {
    default       "no-store";
    "/"           "public, max-age=60, s-maxage=300";
    "/index.html" "public, max-age=60, s-maxage=300";
}

也可以将文件保存到服务器固定配置目录，再在 http 块中 include 它。该文件不要放进随发布切换的 current 目录。map 不能放在 server 或 location 中。

使用 $request_uri 而非 $uri 是因为 SPA 请求会内部重写到 index.html；前者仍保留最初的路径及查询参数，确保授权回调和 secret 页面不会误用首页的公共缓存策略。

2. 在授权站点合并 location

将 config/nginx/auth-cache-server.conf 合并到授权站点的 server 块或它 include 的伪静态配置中：

nginx

location / {
    try_files $uri $uri/ /index.html;
}

location = /index.html {
    expires off;
    add_header Cache-Control $weixin_auth_html_cache;
    add_header Referrer-Policy "no-referrer" always;
    access_log off;
}

location ^~ /assets/ {
    try_files $uri =404;
    expires off;
    add_header Cache-Control "public, max-age=31536000, immutable";
    add_header Referrer-Policy "no-referrer" always;
}

已有相同 location 时修改原块。移除旧的 index.html 固定 no-store 响应头，以及针对这些可缓存资源的 Pragma: no-cache、expires -1 或重复 Cache-Control；保留业务 API 和校验文件的禁缓存规则。公共缓存头不使用 always，避免向缺失静态资源的错误响应添加长期缓存。

若父级已有安全响应头，注意 Nginx add_header 的继承行为，按现有版本与配置在新 location 中保留所需安全头。不要修改既有证书配置、ACME 读取路径、上传反代或 shared 校验文件规则。ACME 对应 location 可追加 add_header Cache-Control "no-store" always;，不要再新建重复的 ACME location。

在宝塔执行配置检查，通过后重载 Nginx。若检查失败，恢复备份，不要强行重载。上述片段为 Nginx 语法，不能粘贴到 Apache .htaccess；使用 Apache 的站点需单独实现同等路径区分与响应头策略。

ESA 控制台规则

按当前控制台的规则优先级与覆盖机制设置，确保“绕过”不会被更宽泛的允许缓存规则覆盖：

绕过缓存：路径 /callback/、/admin/、/api/、/.well-known/ 下的请求及根目录校验 .txt；所有带查询字符串的页面请求也绕过。包含 Authorization 请求头或业务会话 Cookie 的请求绕过。
允许缓存哈希资源：仅 GET/HEAD、路径以 /assets/ 开头且无上述绕过条件。TTL 遵循源站，不缓存错误状态码，不强制覆盖源站禁缓存指令。
允许缓存普通首页：仅 GET/HEAD、路径精确为 / 或 /index.html、查询字符串为空，且无 Authorization 或会话 Cookie。TTL 遵循源站。

不要全局忽略查询字符串，不要移除回源请求中的 code、state、scene、origin、minipath、secret，也不要删除上传接口需要的 Authorization、Origin 请求头。缓存键保留主机名，避免不同站点混用内容。不配置真实 code、state、secret 到缓存预热任务；在边缘日志中隐藏或脱敏敏感查询参数，源站关闭访问日志不能控制 ESA 日志。

发布、回滚与校验文件更新

首页边缘 TTL 为 300 秒、浏览器 TTL 为 60 秒。每次发布或回滚后，清理对应域名 / 和 /index.html 的 ESA 缓存；已存在的浏览器缓存仍可能存活 60 秒。更新哈希资源不必清理旧资源缓存，但不可覆盖相同哈希名称的内容。

旧 HTML 或仍打开的页面可能继续请求旧哈希资源；仅保留历史 releases 不代表 current 能读取旧资源。清理边缘 HTML 缓存后仍应验证升级场景，必要时在发布方案中保留旧资源的可访问窗口。不要将旧资源可用性当作已经实现的功能。

微信校验文件同名覆盖后应立即回源读取新内容。此前若曾缓存 .txt 或 ACME 路径，需要先清理旧缓存并确认绕过规则生效，再进行微信验证或证书签发。不要给验证文件设置长期缓存。

验收

用本机 curl.exe（Windows）或 curl（Linux）检查实际响应头：

curl -I https://webauth.wx.ax3672.cn/
curl -I https://webauth.wx.ax3672.cn/index.html
curl -I 'https://webauth.wx.ax3672.cn/?scene=1&code=TEST&state=TEST'
curl -I https://webauth.wx.ax3672.cn/callback/web
curl -I https://webauth.wx.ax3672.cn/admin/verification

用构建产物的真实文件名检查 /assets/实际哈希文件.js，不要用不存在的占位路径判断缓存。重复请求同一 URL，通过 X-Site-Cache-Status 等实际 ESA 响应头确认缓存命中；首页和资源期望由 MISS 变为 HIT，回调及校验文件不能 HIT。HEAD 检查后也应使用 GET 验证真实页面内容。

对照源站响应和 ESA 响应，确认没有重复矛盾的 Cache-Control、Pragma、Set-Cookie；源站检查可以用 curl --resolve 域名:443:源站IP https://域名/（仅在源站访问控制允许时），不要关闭 TLS 验证。额外检查上传 POST、同名校验文件覆盖、未知路径及静态资源 404。示例中的 TEST 仅用于检查 HTTP 响应头，不代表有效微信授权。

参考：ESA 缓存与源站响应头、默认缓存策略、绕过缓存。

阿里云 ESA 加速与缓存 ​

缓存范围 ​

宝塔 Nginx 配置 ​

1. 在 http 块内加入 map ​

2. 在授权站点合并 location ​

ESA 控制台规则 ​

发布、回滚与校验文件更新 ​

验收 ​