基于Nginx实现目录列表展示与文件下载服务（K8s ConfigMap配置版）

在日常的服务部署与文件分发场景中，Nginx是实现静态文件托管、目录列表展示和文件下载的首选工具。本文将详细讲解如何通过Nginx配置实现目录列表可视化，并提供可直接在Kubernetes（K8s）环境中使用的ConfigMap配置，快速搭建稳定的文件下载服务。

一、核心需求与实现原理

1. 核心需求

• 展示指定目录的文件列表（支持中文文件名、易读的文件大小、本地时间）；
• 支持点击文件直接下载，目录可层级访问；
• 适配K8s环境，通过ConfigMap管理Nginx配置，便于运维与更新。

2. 关键Nginx指令说明

实现目录列表的核心是autoindex相关指令，关键参数如下：

指令	作用
autoindex on	开启自动目录列表功能（默认关闭）
autoindex_exact_size off	显示易读的文件大小（KB/MB/GB），默认显示字节数
autoindex_localtime on	显示服务器本地时间，默认显示UTC时间
charset utf-8	解决中文文件名乱码问题
alias	映射请求路径到服务器本地实际目录（区别于root，直接匹配路径）
try_files $uri $uri/ =404	优先检查文件/目录是否存在，避免提前触发404拦截目录列表
index off	强制关闭默认首页（即使目录下有index.html，也显示列表）

二、K8s ConfigMap完整配置

以下是可直接部署到K8s的Nginx配置ConfigMap，包含nginx.conf（全局配置）和default.conf（站点配置），已适配目录列表展示与文件下载需求：

kind: ConfigMap
apiVersion: v1
metadata:
  name: nginx-conf
  namespace: default
  annotations:
    kubesphere.io/creator: lifengqian
data:
  default.conf: |-
    server {
        listen       80;
        listen  [::]:80;
        server_name  localhost;

        # 根路径配置（可选，根据实际需求调整）
        location / {
             autoindex on; 
             alias   /usr/share/nginx/html;
             error_page 404 /index.html;
        }
        
        # 核心：文件下载目录配置（/download路径映射到服务器/local/download目录）
        location /download/ {
            # 映射到服务器实际目录，末尾必须加/（alias语法要求）
            alias   /download/;
            # 开启目录列表
            autoindex on;
            # 显示易读的文件大小（KB/MB/GB）
            autoindex_exact_size off;
            # 显示服务器本地时间（而非UTC）
            autoindex_localtime on;
            # 解决中文文件名乱码
            charset utf-8;
            # 优先检查文件/目录，不存在返回404，避免拦截autoindex
            try_files $uri $uri/ =404;
            # 强制不使用默认首页，确保列表始终显示
            index off;
        }

        # 5xx错误页配置
        error_page   500 502 503 504  /50x.html;
        location = /50x.html {
            root   /usr/share/nginx/html;
        }
    }
  nginx.conf: |-
    # Nginx全局配置
    user  nginx;
    worker_processes  auto;

    error_log  /var/log/nginx/error.log notice;
    pid        /run/nginx.pid;

    events {
        worker_connections  1024;
    }

    http {
        include       /etc/nginx/mime.types;
        # 默认下载文件的MIME类型，确保浏览器触发下载而非预览
        default_type  application/octet-stream;

        # 日志格式配置
        log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
                          '$status $body_bytes_sent "$http_referer" '
                          '"$http_user_agent" "$http_x_forwarded_for"';

        access_log  /var/log/nginx/access.log  main;

        # 开启高效文件传输
        sendfile        on;
        keepalive_timeout  65;

        # 引入站点配置
        include /etc/nginx/conf.d/*.conf;
    }