ngx_http_random_index_module 模块概述

一、使用场景

• 随机内容分发
  当同一目录下存放多份等价内容（如多张轮播图、不同版本静态页面等）时，可通过随机索引实现负载均衡或流量分散。
• A/B 测试
  通过目录请求自动随机分配用户到不同测试组，无需后端逻辑参与。
• 动态“首页”选择
  不同时间或不同访客展现不同首页文件，提升新鲜感。

二、示例配置

http {
    server {
        listen 80;
        server_name example.com;

        # 启用随机索引功能
        location /gallery/ {
            random_index on;

            # 如果目录中没有文件或模块被禁用，则回退到默认的 index.html
            index index.html;
        }

        # 其他常见静态服务配置
        location /assets/ {
            alias /var/www/assets/;
            # 不启用随机索引
            random_index off;
            index index.html;
        }
    }
}

• 当访问 http://example.com/gallery/ 时，模块会从 /gallery/ 目录下随机挑选一个文件（如 01.jpg、02.jpg、welcome.html 等）直接返回给客户端。
• 如果目录为空或未匹配到任何文件，则继续执行后续的 index 处理（例如返回 index.html）。

三、指令详解

Syntax:   random_index on | off;
Default:  random_index off;
Context:  location

• 作用范围：仅在指定的 location 块内生效，可根据目录或路径灵活开启/关闭。
• 执行顺序：当 random_index on; 时，模块在目录匹配后、index 模块生效前拦截请求，并尝试随机选取目录内文件；否则，按常规 index 规则执行。

四、工作流程

1. 请求匹配
   匹配到以 / 结尾的目录 location，且该位置启用了 random_index on。
2. 目录扫描
   模块异步读取目标目录的文件列表（忽略子目录），并构建可供选择的数组。
3. 随机选取
   从列表中随机挑选一个文件名。
4. 内部重写
   将请求 URI 内部重写为所选文件的相对路径，并将请求转交给静态文件处理流程返回内容。
5. 后续处理
   如果目录为空或重写失败，则继续执行后续的 index 或 autoindex 等指令逻辑。

五、注意事项

• 性能影响

  • 目录扫描开销：对于文件数量较多的目录，每次请求均要扫描一次目录，可能带来 I/O 开销。建议结合操作系统缓存和合理的 open_file_cache 配置使用。
  • 并发场景：高并发下频繁扫描同一目录时，可关闭模块，改为后台定期生成随机化列表或使用内存缓存方案。

• 文件顺序与过滤

  • 模块不会过滤隐藏文件（. 开头）或特定后缀；如需更精细控制，可配合 location、try_files、rewrite 等指令共同使用。

• 回退方案

  • 配置 index 或 autoindex 以防目录为空或选取失败时提供备选内容。

六、完整示例

http {
    # 打开缓存目录句柄，减少频繁 open/close 开销
    open_file_cache          max=1000 inactive=20s;
    open_file_cache_valid    30s;
    open_file_cache_min_uses 2;

    server {
        listen 80;
        server_name static.example.com;

        # 为用户相册目录启用随机封面
        location /albums/ {
            root /var/www/static;
            random_index on;

            # 当目录为空时返回默认封面
            index default.jpg;
        }

        # 普通静态文件目录
        location /assets/ {
            root /var/www/static/assets;
            # 随机索引无效
            random_index off;
            index index.html;
        }
    }
}

以上配置中，/albums/ 下每个相册目录可根据目录结构随机返回一张封面图，其他目录保持默认静态服务行为。

通过 ngx_http_random_index_module，您可以在 Nginx 层面轻松实现“目录随机索引”功能，降低后端实现复杂度，快速满足多种业务需求。