Nginx 中 fastcgi_cache_path 配置缓存目录结构

fastcgi_cache_path的目录结构由levels参数控制，按哈希值自动分层建目录以避免inode瓶颈；必须显式配置levels（如1:2），禁用use_temp_path=off，并确保缓存路径独立可写且权限正确。

fastcgi_cache_path 的目录结构由 levels 参数决定，它不是简单建一个文件夹存所有缓存，而是按哈希值自动分层建目录，核心目的是避免单目录海量文件导致的 inode 性能瓶颈和文件系统卡顿。

levels 控制缓存文件的嵌套层级

levels=1:2 表示两级子目录：第一级取 key 哈希值最后 1 位（16 进制），第二级取后 2 位。例如 key 哈希为 ab12cd34，最终路径是 /cache/a/b1/ab12cd34；若设为 levels=2:2:2，则生成三级目录，如 /cache/ab/cd/34/ab12cd34。

1. 必须显式配置 levels，不写或写成 levels=0 会导致所有缓存挤在根目录，高并发下容易触发 ext4 或 XFS 的目录项查找延迟
2. 推荐用 levels=1:2 或 levels=2:2，兼顾散列均匀性与路径深度，避免过深（如 levels=3:3:3）增加 stat 开销
3. 层级数字对应十六进制位数，不是目录名长度，也不支持十进制或其他进制

缓存路径本身需独立且可写

缓存根目录不能复用系统临时路径（如 /tmp、/dev/shm），尤其在宝塔、phpEnv 等环境中，这些路径常受 SELinux 上下文、挂载选项（noexec、nosuid）或权限隔离限制，导致缓存静默失败——Nginx 不报错，但 X-FastCGI-Cache 始终显示 MISS 或 BYPASS。

1. 推荐路径：宝塔环境用 /www/server/nginx/cache/fastcgi，phpEnv 用 /www/phpenv/nginx/fastcgi_cache
2. 创建后必须确保 Nginx 工作进程用户（通常是 www 或 nginx）对该路径有完整读写权限：chown -R www:www /www/server/nginx/cache/fastcgi
3. 不要用相对路径（如 cache/），Nginx 会以运行时工作目录为基准，易因启动方式不同导致路径错乱

use_temp_path=off 决定写入方式

默认情况下 Nginx 先写临时文件再 rename 到目标路径，而 use_temp_path=off 强制跳过临时中转，直接写入最终缓存位置。这能规避 /tmp 满、权限不足、磁盘配额超限等常见写入失败场景。

1. 必须显式加上 use_temp_path=off，否则即使目录权限正确，也可能因临时路径问题导致缓存不落地
2. 配合 keys_zone 使用，元数据与实体文件路径解耦，不影响 keys_zone 内存管理逻辑
3. 该参数不改变目录结构，只改变文件落盘路径和时机

max_size 和 inactive 共同管理磁盘空间

max_size 是硬上限，达到后 Nginx 会按 LRU 清理最久未访问的缓存文件；inactive 是软策略，指定缓存项若在设定时间内未被命中（注意：不是“过期”，而是“冷数据”），就从 keys_zone 中移除其元数据，并在下次清理周期删除对应文件。

1. max_size 应略小于所在分区可用空间，留出日志、临时文件余量，例如磁盘剩 10G，设 max_size=8g
2. inactive 时间要匹配业务更新节奏：API 列表页更新频繁可设 5m～30m；静态内容为主的后台页可设 1h～24h
3. 两者无依赖关系，max_size 触发的是物理文件清理，inactive 触发的是元数据释放，后者更影响内存占用