inactive 是 nginx 清理长尾冷缓存的核心参数，按最后一次命中后闲置时长触发异步删除；需结合 max_size、keys_zone 大小、use_temp_path=off 及 proxy_cache_valid 协同配置，文档类场景推荐 inactive=30d、keys_zone=30m、max_size=10g。

inactive 参数是 Nginx 实现长尾冷缓存自动清理最直接、最可靠的方式——它不看响应头是否过期，也不管请求频率高低，只认一个标准：这个缓存项最后一次被成功命中后，已经闲置多久了。

理解 inactive 在负载均衡场景下的真实作用

在多节点负载均衡架构中，流量分散导致单个 Nginx 实例对同一资源的访问频次显著降低。比如一份归档文档，全站每月总访问 3 次，但均匀打到 3 台机器上，每台每月仅 hit 1 次。若 inactive=10m，该缓存会在首次访问后 10 分钟就被清除，完全失去意义。

它不是“缓存有效期”，而是“缓存驻留容忍期”：

• 每次成功命中（proxy_cache hit）都会重置该计时器
• cache manager 进程周期性扫描（默认每秒一次），检查共享内存中记录的最后访问时间
• 只要超过 inactive 设定值且当前无活跃请求占用，就标记为待删除
• 删除动作异步执行，不影响正在服务的请求

针对长尾冷数据的 inactive 值推荐

不能套用通用值，需按资源实际访问周期设定：

FastAPI Flask Proxy

FastAPI + Flask 混合部署最佳实践，解决路由定义、API 代理等常见问题，适用于同时运行 FastAPI API 与 Flask 前端的场景。

下载

• API 配置类数据（如系统开关、白名单）、低频管理页：inactive=24h
• 博客/文档库中的旧文章、技术手册页面：inactive=7d～30d
• 日志归档页、历史版本接口、法规文件 PDF：inactive=90d
• 避免设为 inactive=1y：keys_zone 共享内存会持续保留 key 元信息，浪费空间；cache loader 启动变慢；且磁盘空间长期无法释放

必须配合的协同配置

单独调大 inactive 不够，需与以下参数形成闭环：

• max_size：设为合理上限（如 5g / 20g），当磁盘逼近该值时，Nginx 会优先淘汰最久未访问（即最符合 inactive 条件）的条目，这是第一级空间回收策略
• keys_zone 大小：inactive 时间越长，key 的元信息驻留越久，需按比例扩大。例如 inactive=30d 时，建议 keys_zone ≥ 30m（1MB ≈ 8000 个 key）
• use_temp_path=off：关闭临时路径，让缓存文件直落目标目录，避免 cache manager 清理时因 rename 残留引发误判或延迟
• inactive ≥ proxy_cache_valid：例如 proxy_cache_valid 200 2h，则 inactive 至少设为 2h 或 4h。否则缓存“有效但不存活”，形同虚设

典型生产配置示例

适用于文档类负载均衡集群：

proxy_cache_path /var/cache/nginx/docs levels=1:2 keys_zone=docs_cache:30m inactive=30d max_size=10g use_temp_path=off;

说明：

• 30MB keys_zone 足够支撑数百万个长周期缓存 key
• 30 天未访问才清理，匹配文档类内容的真实热度衰减曲线
• 10GB 磁盘上限 + inactive 双控，既防冷数据淤积，又保热数据稳定驻留
• use_temp_path=off 提升清理准确率和 I/O 效率