在 nginx 中实现按需清理缓存，核心做法是安装并配置第三方模块 ngx_cache_purge。该模块通过监听特定的 url 路径（如 /purge/），当请求到达时，根据传入的原始请求参数（通常是域名和 uri）从缓存目录中删除对应的文件。配置的关键在于定义一个专用的 location 块，设置允许清理的 ip 白名单以防止未授权访问，并确保该路径不会与业务逻辑冲突。
如何配置 purge 路径以匹配特定域名的缓存？
要实现按域名清理，需要在 proxy_cache_purge 指令中使用变量组合来构建缓存键。通常使用 $host$uri 作为键值，这样不同域名的同名资源会被隔离存储。配置时，必须确保这个变量组合与你实际 proxy_cache_key 的设置完全一致，否则模块无法找到对应的缓存文件进行删除。
server {
listen 80;
server_name example.com;
# 定义缓存路径和键
proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=my_cache:10m max_size=1g inactive=60m use_temp_path=off;
proxy_cache_key "$host$request_uri";
# 业务代理配置
location / {
proxy_pass http://backend;
proxy_cache my_cache;
}
# 清理缓存专用路径
location /purge/ {
allow 127.0.0.1; # 仅允许本地或特定IP
deny all;
# 关键：这里的变量必须与上面的 proxy_cache_key 一致
set $cache_purge_key "$host$uri";
proxy_cache_purge my_cache $cache_purge_key;
}
}
在上述配置中，proxy_cache_purge 接收两个参数：第一个是缓存区域名称（my_cache），第二个是用于查找缓存文件的键（$cache_purge_key）。当用户访问 http://example.com/purge/example.com/index.html 时，模块会解析出主机名和 URI，并在 /var/cache/nginx 目录下查找对应的哈希文件并删除。如果 proxy_cache_key 中包含了查询字符串（如 $query_string），则清理 URL 也必须包含相同的查询字符串才能成功匹配。
如何处理动态内容或 API 接口的缓存清理？
对于 API 接口，通常不需要按完整 URI 清理，而是可能希望清理某个资源的所有版本或特定前缀。虽然 ngx_cache_purge主要基于精确键匹配，但可以通过调整 proxy_cache_key 的策略来简化清理逻辑。例如，如果 API 响应不依赖 URI 中的 ID，只依赖方法或头部，可以自定义更简单的键。但在大多数标准 RESTful API 场景中，依然推荐使用精确键匹配，并通过脚本批量发送清理请求。
# 假设有一个 Python 脚本来触发清理
import requests
def purge_cache(domain, uri):
url = f"http://{domain}/purge/{domain}{uri}"
try:
response = requests.get(url)
if response.status_code == 200:
print(f"Successfully purged {url}")
else:
print(f"Failed to purge {url}, status: {response.status_code}")
except Exception as e:
print(f"Error: {e}")
# 示例：清理首页缓存
purge_cache("example.com", "/index.html")
在实际运维中，手动访问 URL 清理效率较低。通常会结合 CI/CD 流程或 CMS 后台，在发布新内容后自动调用上述清理接口。需要注意的是，ngx_cache_purge 返回的是 HTTP 状态码，200 表示成功删除，404 表示缓存不存在，500 表示内部错误。开发者应编写重试机制来处理网络波动导致的临时失败。此外，若使用了 CDN，Nginx 层的清理仅清除边缘节点到源站之间的缓存，若需清除 CDN 缓存，还需额外调用 CDN 厂商的 API。
清理操作返回 404 或 500 错误时如何排查？
当执行清理操作时遇到非 200 状态码，最常见的原因是缓存键不匹配。请仔细检查 location /purge/ 中设置的 $cache_purge_key 变量是否与业务 location 中的 proxy_cache_key 完全一致。任何额外的空格、不同的变量引用（如一个用了 $request_uri 另一个用了 $uri）都会导致模块找不到文件而返回 404。如果是 500 错误，通常是因为缓存目录权限问题，或者磁盘空间不足。确保 Nginx 运行用户（通常是 www-data 或 nginx）对 proxy_cache_path 指定的目录拥有读写权限。另外，检查 Nginx 错误日志（error.log）获取详细的调试信息，这能直接指出是哪个步骤失败了。
