ngx_path_t是Nginx中定义路径模板的结构体，用于将缓存key通过MD5哈希、按level分段生成多级子目录路径，实现高效缓存文件管理与自动目录创建。

Nginx 中的 ngx_path_t 并非单纯“路径类型”，而是缓存层级结构的元数据载体，其核心作用是定义如何将逻辑键（如缓存 key）映射为物理文件路径，并驱动多级子目录的自动创建与管理。

ngx_path_t 是什么：结构体与关键字段

ngx_path_t 是 Nginx 源码中定义在 src/core/ngx_file.h 的结构体，用于描述一个“路径模板”。它不表示某个具体路径，而是描述一类可扩展、可分层的路径生成规则。关键字段包括：

• name：基础路径名，如 /var/cache/nginx/proxy_temp，末尾不带斜杠
• len：name 的长度，供高效拼接使用
• level[3]：三个整数，指定三级子目录的位数，例如 {2, 1, 1} 表示按缓存 key 的十六进制哈希值，前两位、下一位、再下一位分别作为三级子目录名
• manager 和 resolver：回调函数指针，用于周期性清理过期缓存或解析临时文件归属

缓存路径如何从 key 生成：哈希 → 分段 → 拼接

Nginx 不直接用原始 key 做文件名，而是先计算 MD5（128 位 → 32 字符十六进制），再按 level 切分哈希字符串，逐级构造嵌套目录。例如：

• key = "https://example.com/api/data"
• MD5 后哈希值开头为 "f4a7b2c9e1d8..."
• 若 level = {2, 1, 1}，则取前 2 位 f4、接着 1 位 a、再 1 位 7
• 最终路径为：/var/cache/nginx/proxy_temp/f4/a/7/f4a7b2c9e1d8..._0000000001

这种设计避免单目录下文件过多导致性能下降（ext4 等文件系统对单目录 inode 数量敏感），也便于按目录粒度清理或迁移。

ngx_path_t 如何被初始化与使用

它通常在模块初始化阶段（如 ngx_http_proxy_module 的 create main configuration 钩子）通过 ngx_conf_merge_path_value 解析配置项（如 proxy_cache_path /path levels=2:1:1 ...）并构建。Nginx 会预先创建第一级子目录（如 /path/f0 到 /path/ff），后续二级、三级目录则在首次写入时按需创建——由 ngx_create_path 调用完成，确保原子性和并发安全。

实际运维中需注意的细节

• 修改 levels 后必须清空缓存目录并重启，否则旧 key 无法命中新结构
• levels 总位数不能超过 32（MD5 哈希总长），常见组合有 1:2、2:2:2，不宜过度细分（如 1:1:1:1），否则目录树太深且无实质收益
• 磁盘配额、inode 使用率需同时监控：大量小文件易耗尽 inode，而不仅是空间
• manager 回调默认每 200ms 执行一次，可通过 cache manager 相关指令微调频率与行为