一、前言

在使用阿里云 ESA（边缘安全加速）为 Halo 站点加速时，一个关键的配置决策是：哪些请求应该走 ESA 缓存，哪些请求必须绕过缓存直接回源。如果配置不当，轻则导致后台无法正常登录，重则造成用户看到过期内容甚至敏感数据泄露。

Halo 作为一款现代化的博客/CMS 系统，其请求路径可以清晰地分为两大类：

• 动态请求：包括控制台（/console/）、用户中心（/uc/）、API 接口（/apis/、/api/）等，这些路径返回的内容与用户会话、权限密切相关，绝不能被 ESA 缓存。

• 静态资源：包括附件库（/upload/）、插件资源（/plugins/）、主题资源（/themes/）以及网站图标（/favicon.ico），这些内容更新频率低、对所有用户一致，非常适合 ESA 缓存。

本文将基于阿里云 ESA 的实际配置截图，详细讲解如何为 Halo 站点编写精准的缓存规则，帮助你在加速站点访问的同时确保后台功能正常运行。

二、需要绕过缓存的路径

Halo 的后台管理系统、用户中心以及所有 API 接口都是动态路径。这些路径返回的内容取决于当前登录用户的身份、权限和操作上下文。如果 ESA 将这些响应缓存下来，会导致以下严重问题：

• 安全风险：用户 A 登录后的控制台页面可能被缓存并展示给用户 B，造成会话泄露。

• 功能异常：API 返回的数据被缓存后，用户看到的是过时的内容，提交的表单可能无法正确处理。

• 登录失败：认证相关的接口被缓存后，登录流程可能完全中断。

因此，以下路径必须配置为绕过 ESA 缓存，直接回源：

• /console/ 和 /console —— Halo 管理后台

• /uc/ 和 /uc —— 用户中心

• /apis/ —— 公开 API 接口

• /api/ —— 内部 API 接口

• /plugins/plugin-safe-redirect/go —— 安全链接跳转插件（如已安装）

下面通过阿里云 ESA 配置截图来展示具体的规则设置。

如上图所示，在阿里云 ESA 的缓存规则配置中，我们将上述路径逐一添加为"不缓存"规则。ESA 支持基于 URL 路径的缓存规则配置，操作直观且灵活。

三、绕过缓存规则详解

以下是每条绕过缓存规则的详细说明，帮助你理解每条规则的作用和必要性。

上图中的表达式使用了阿里云 ESA 的规则语法。核心逻辑是：当请求路径匹配以下任一条件时，不进行缓存，直接回源。

3.1 规则表达式解析

(starts_with(lower(http.request.uri.path), "/console/")) or (starts_with(lower(http.request.uri.path), "/uc/")) or (starts_with(lower(http.request.uri.path), "/apis/")) or (starts_with(lower(http.request.uri.path), "/api/")) or (lower(http.request.uri.path) eq "/console") or (lower(http.request.uri.path) eq "/uc") or (starts_with(lower(http.request.uri.path), "/plugins/plugin-safe-redirect/go"))

下面对每条子规则逐一说明：

3.2 表达式语法说明

上述表达式使用了阿里云 ESA 规则引擎常用函数：

• starts_with(A, B)：判断字符串 A 是否以 B 开头。用于匹配路径前缀。

• lower(A)：将字符串 A 转换为小写。确保大小写不敏感的匹配。

• http.request.uri.path：获取请求 URI 的路径部分（不含查询参数）。

• eq：精确相等比较。用于精确匹配特定路径。

• or：逻辑或，满足任一条件即触发规则。

以上表达式语法在阿里云 ESA 中可直接使用，配置过程简单高效。

四、需要缓存的静态资源

与动态内容相反，Halo 站点中有大量静态资源非常适合通过阿里云 ESA 缓存来加速访问。这些资源通常不会频繁变动，缓存后可以显著降低源站负载、减少用户等待时间。

4.1 为什么需要缓存这些资源？

ESA 缓存的核心价值在于：

• 降低延迟：用户从就近的 ESA 边缘节点获取资源，而非每次都回源到你的服务器。

• 减轻源站压力：大量静态资源请求由 ESA 直接响应，源站只需处理动态请求。

• 节省带宽成本：ESA 承担了大部分流量，减少源站的出站流量消耗。

• 提升用户体验：页面加载速度更快，尤其在图片、CSS、JS 等资源较多的场景下效果显著。

4.2 适合缓存的资源类型

以下四类资源是 Halo 站点中最适合开启 ESA 缓存的：

对应的缓存规则表达式如下：

(starts_with(lower(http.request.uri.path), "/upload/")) or (starts_with(lower(http.request.uri.path), "/plugins/")) or (starts_with(lower(http.request.uri.path), "/themes/")) or (lower(http.request.uri.path) eq "/favicon.ico")

下面逐一说明每类资源的缓存策略：

五、缓存规则详解

上一节列出了需要缓存的四类路径，本节深入解析每条 ESA 缓存规则的含义和配置细节。

5.1 规则表达式解析

(starts_with(lower(http.request.uri.path), "/upload/")) or (starts_with(lower(http.request.uri.path), "/plugins/")) or (starts_with(lower(http.request.uri.path), "/themes/")) or (lower(http.request.uri.path) eq "/favicon.ico")

这条规则由四个条件通过 or 连接，匹配任意一个条件即命中缓存策略：

5.2 关键函数说明

• lower()：将字符串转为小写，确保大小写不敏感的匹配。例如 /Upload/Image.PNG 会被转为 /upload/image.png 后再匹配。

• starts_with()：检查字符串是否以指定前缀开头。适合匹配整个目录下的所有资源。

• eq：精确相等比较。用于匹配单个文件（如 /favicon.ico），避免误匹配其他路径。

5.3 ESA 配置界面参考

以下是在阿里云 ESA 管理后台配置缓存规则的界面示例：

5.4 缓存路径汇总

六、最佳实践与注意事项

完成上述规则配置后，还需要关注以下几个方面的最佳实践，以确保 ESA 缓存策略长期稳定运行。

6.1 缓存时间设置建议

不同类型的静态资源适合不同的缓存过期时间：

6.2 缓存刷新策略

当更新了插件、主题或替换了附件后，需要及时刷新 ESA 缓存，否则用户仍会看到旧版本资源。建议采取以下措施：

• 手动刷新：在阿里云 ESA 管理后台提交缓存刷新任务，指定需要刷新的目录（如 /themes/ 或 /plugins/）。

• 版本号机制：在主题或插件的静态资源引用中加入版本号参数，例如 style.css?v=2.0，这样即使 ESA 缓存未过期，浏览器也会请求新版本。

• 定时刷新：阿里云 ESA 支持设置定时刷新任务，可在凌晨低峰期自动刷新缓存。

6.3 安全链接插件处理

如果站点使用了安全链接插件（plugin-safe-redirect），其路径 /plugins/plugin-safe-redirect/go 已在绕过缓存规则中配置。需要注意：

• 该路径用于外部链接的安全跳转，必须实时处理，不可缓存。

• 如果未安装此插件，该规则不会产生负面影响，但建议保留以应对将来可能的安装。

• 如果安装了其他类似功能插件，请确认其路径也已加入绕过缓存规则。

6.4 QA

6.4.1 后台样式异常或功能失效怎么办？

如果 Halo 后台（/console/）出现样式错乱或功能异常，请按以下步骤排查：

1. 确认 /console/ 和 /apis/ 路径是否已在 ESA 中正确配置为绕过缓存。

2. 打开浏览器开发者工具，查看 Network 面板中是否有资源返回了缓存的旧版本。

3. 清除浏览器缓存后重新测试。

6.4.2 上传新附件后前端未更新？

这种情况通常是因为 ESA 缓存了旧附件或附件列表接口。排查步骤：

1. 确认附件资源（/upload/）的缓存规则是否生效，缓存时间是否过长。

2. 在 ESA 后台手动刷新 /upload/ 目录缓存。

3. 检查附件列表 API（/apis/）是否被错误地加入了缓存规则——该路径应绕过缓存。

6.4.3 主题切换后页面显示旧主题？

主题切换后，ESA 可能仍缓存着旧主题的静态资源。解决方法：

1. 在 ESA 后台刷新 /themes/ 目录缓存。

2. 如果主题支持，可在 Halo 后台重新保存一次主题设置，触发资源路径更新。

3. 临时关闭 ESA 缓存，确认新主题正常后再重新开启。

6.5 规则优先级说明

在阿里云 ESA 中，规则通常按顺序匹配，命中即停止。因此绕过缓存规则应放在缓存规则之前，确保动态请求优先被排除。配置顺序建议如下：

1. 绕过缓存规则（/console/、/uc/、/apis/、/api/ 等动态路径）

2. 缓存规则（/upload/、/plugins/、/themes/、/favicon.ico 等静态路径）

3. 默认规则（根据需要设置全局缓存策略）