Directory Lister 5.8.3 高级配置与定制实战指南

Directory Lister 5.8.3 高级配置与定制实战：隐藏清单与文件匹配模式、Nginx 反向代理接入、HTTP Basic 认证（401/200 实测）、界面语言与主题定制、配置文件挂载进阶，全部配置实测可复现。

Directory ListerDirectory Lister文件服务器文件分享2026/10/30

Directory Lister 5.8.3 高级配置与定制实战指南

目标：在完成基础部署之后，对 Directory Lister 做进阶实战——用隐藏清单精确控制索引内容、接入 Nginx 反向代理、叠加 HTTP Basic 认证、完成界面与语言定制。全文每一项均给出可执行配置与实测回显；认证与反代部分同时覆盖官方推荐的两条外部认证路径。

一、环境信息

  • 操作系统：Ubuntu 22.04（x86_64）
  • 应用：Directory Lister v5.8.3（官方镜像，Apache 2.4.69 Debian + PHP 8.5.12），服务端口 8150
  • 反向代理：Nginx 1.29（alpine 版本线），监听 8151，反代上游 8150
  • 部署目录：/opt/directory-lister（docker-compose.yml 所在目录），被列目录 /opt/directory-lister/data
  • 演示账号：admin / q1w2e3r4（本文 Basic Auth 实测所用演示凭据）
  • 应用网络：directory-lister-5.8.3-net（bridge，子网 10.89.57.0/24），反代与应用同网络

💡 说明：Directory Lister 本体不带认证与访问控制（官方 Authentication 页明确这是有意的设计取舍），本文第三至五章的"隐藏清单 → 反代 → Basic Auth"构成一条从展示过滤到访问控制的完整加固链。

二、方案总览

Directory Lister 的定制能力分四个层面，本文逐层展开：

层面手段效果
索引内容过滤.hidden 清单 / hidden_files 数组指定文件不出现在列表（通配语法）
接入层Nginx 反向代理统一域名、收口访问入口、预留 TLS
访问控制HTTP Basic / Authelia无内置认证的应用获得鉴权
界面定制语言包 / 主题切换 / 图标映射界面语言、配色与文件图标

选型顺序建议：先做内容过滤（最小改动、立即生效），再做反代与认证（有安全诉求时），界面定制按需。

三、隐藏清单与文件匹配模式实战

3.1 建立隐藏清单

在被列目录放置 .hidden 文件，每行一个匹配模式，# 开头为注释：

cd /opt/directory-lister/data
tee .hidden >/dev/null <<'EOF'
# 每行一个文件匹配模式，支持通配
backup-demo.bin
*.tar.gz
EOF
touch backup-demo.bin tmp-archive.tar.gz

3.2 声明清单位置并验证

Docker 形态下清单路径必须以环境变量声明为绝对路径（部署篇 6.4 节已实测相对路径不生效的根因），在 docker-compose.yml 的 environment: 段加入：

      HIDDEN_FILES_LIST: /data/.hidden

重建后验证两类模式同时生效：

docker compose up -d
curl -sS http://127.0.0.1:8150/ | grep -cE "backup-demo|tmp-archive"

实测回显：

0

精确名（backup-demo.bin）与通配（*.tar.gz）命中的文件全部从索引消失。

3.3 断言语法精修（可选）

需要"排除更细"时使用断言语法（官方 File Matching Patterns 页）：file.tar(!.{gz,xz}) 匹配 file.tar、file.tar.bz 但排除 file.tar.gz/file.tar.xz；(=foo) 匹配名称中同时包含 foo 的文件。这类模式同样可用于隐藏清单。例如只隐藏未压缩的备份而保留 .tar.gz 分发包：

*.tar(!.{gz,xz})

⚠️ 注意：隐藏是展示层过滤，不是访问控制。知道文件名仍可直接访问（如 ?file=backup-demo.bin），敏感文件的访问拦截见第五、六章。

四、Nginx 反向代理接入实战

4.1 反代配置

让 Nginx 承接对外域名，转发给应用。在 /opt/directory-lister/proxy/default.conf 写入：

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

    location / {
        proxy_pass http://directory-lister-5.8.3-web:80;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

配置说明：proxy_pass 指向应用在内网的名字（与应用同网络时可直接用服务名）；四条 proxy_set_header 保留客户端真实 IP 与协议信息，X-Forwarded-Proto 为后续 TLS 终结预留。应用不依赖这些头也能正常工作，但保留它们是反代接入的标准姿势。

4.2 启动反代并验证

Nginx 与应用同网络启动（监听宿主 8151）：

docker run -d --name directory-lister-5.8.3-proxy \
  --network directory-lister-5.8.3-net \
  -p 8151:80 \
  -v /opt/directory-lister/proxy/default.conf:/etc/nginx/conf.d/default.conf:ro \
  nginx:alpine

以反代域名访问验证透传：

curl -sS -o /dev/null -w "HTTP %{http_code}\n" -H "Host: files.example.com" http://127.0.0.1:8151/
curl -sS -H "Host: files.example.com" http://127.0.0.1:8151/ | grep -c "运维资料仓库"

实测回显：

HTTP 200
1

状态码 200 且 README 渲染内容（运维资料仓库 标题）完整透传，反代接入完成。此后的认证、TLS 都叠加在这一层，应用本体无需改动。

五、HTTP Basic 认证实战

Directory Lister 无内置认证，官方 Authentication 页给出的外部认证路径即 HTTP Basic（Apache .htpasswd / Nginx Basic Auth）与 Authelia 反代授权。本章实测 Nginx 路径。

5.1 生成口令文件

用 openssl passwd -apr1 生成 apr1 哈希写入口令文件（演示账号 admin / q1w2e3r4）：

printf 'admin:%s\n' "$(openssl passwd -apr1 q1w2e3r4)" > /opt/directory-lister/proxy/.htpasswd
cat /opt/directory-lister/proxy/.htpasswd

实测回显：

admin:$apr1$9r8SSwAB$aX0tYL8a5FkrPbmdvZKGR1

（哈希盐值随机，每次生成不同，属正常现象。）

5.2 开启 auth_basic

在反代配置的 location / 段加入两行并重新加载：

    location / {
        auth_basic "Restricted";
        auth_basic_user_file /etc/nginx/.htpasswd;
        proxy_pass http://directory-lister-5.8.3-web:80;
        ...
    }

docker cp /opt/directory-lister/proxy/.htpasswd directory-lister-5.8.3-proxy:/etc/nginx/.htpasswd
docker exec directory-lister-5.8.3-proxy nginx -t
docker exec directory-lister-5.8.3-proxy nginx -s reload

nginx -t 实测回显：

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

5.3 三种情形实测

curl -sS -o /dev/null -w "无凭据:   HTTP %{http_code}\n" -H "Host: files.example.com" http://127.0.0.1:8151/
curl -sS -o /dev/null -w "错误口令: HTTP %{http_code}\n" -u admin:wrongpass -H "Host: files.example.com" http://127.0.0.1:8151/
curl -sS -o /dev/null -w "正确凭据: HTTP %{http_code}\n" -u admin:q1w2e3r4 -H "Host: files.example.com" http://127.0.0.1:8151/

实测回显：

无凭据:   HTTP 401
错误口令: HTTP 401
正确凭据: HTTP 200

无凭据与错误口令均被 401 拦截，正确凭据放行——应用获得了官方未内置的访问控制。企业内网需要统一登录时，把这一层换成 Authelia（反代转发授权，官方 Authentication 页同样收录该方案），应用侧零改动。

六、界面与语言定制

6.1 界面语言（APP_LANGUAGE）

APP_LANGUAGE=zh-CN 一项即可整体切换界面语言。实测开启后的界面文本（页面 HTML 中的关键文案）：

搜索        # 搜索框
日期 / 大小  # 列表头
文件信息     # 文件行悬浮按钮 title
目录起始页   # 面包屑起始链接（语言包 home 键）

语言包位于应用内 app/translations/（29 个 yaml，含 zh-CN.yaml、zh-TW.yaml），其中 zh-CN 包的关键键值实查：

home: 目录起始页
download: 下载
search: 搜索
file:
  name: 文件名
  size: 大小

需要微调个别文案时，按第七章的配置挂载方式覆盖对应语言包即可。

6.2 主题（亮/暗色）

页面内置亮/暗两套主题，导航栏右侧有切换按钮（页面元素 title="Toggle Light/Dark Mode"），用户偏好记录在 cookie（页面脚本 storeThemeCookie），无需服务端配置。默认主题跟随 light 样式类，整站无独立主题配置文件——如需品牌色定制，属于前端资源改写（app/assets 下的打包产物），建议通过反代层的子资源替换实现而不是改镜像内文件。

6.3 文件图标映射

文件行图标按扩展名映射，定义在应用内 app/config/icons.php（如文本文件与二进制文件分别对应不同 Font Awesome 图标）。实测文件行结构中 deploy-guide-v1.txt 用 fa-file-alt、backup-demo.bin 用 fa-file。需要为特殊扩展名补充图标时，参照该文件的键值格式覆盖挂载（同第七章方式）。

七、配置文件挂载方式（进阶定制入口）

进入"环境变量覆盖不了"的定制区（hidden_files 数组、缓存闭包、HTTP 缓存时长、自定义排序函数、语言包微调、图标映射）时，统一用 bind mount 覆盖应用内对应文件。docker-compose.yml 的 volumes 段：

    volumes:
      - ./data:/data
      - ./app-config/app.php:/var/www/html/app/config/app.php:ro
      - ./app-config/zh-CN.yaml:/var/www/html/app/translations/zh-CN.yaml:ro
      - dl-app-cache:/var/www/html/app/cache

操作要点：

  • 每次只覆盖单个文件，docker compose up -d 重建后生效；
  • app.php 覆盖前先从镜像导出当前版本的原件做底稿（docker exec directory-lister-5.8.3-web cat /var/www/html/app/config/app.php > app-config/app.php），再在原件上改，避免跨版本字段缺失；
  • 官方文档明确提示：app/config 的改动在升级时需手工重新套用，升级前先备份自己的覆盖文件。

八、常见问题

Q1：反代后页面能开，搜索/下载异常？

优先核对 proxy_set_header 四件套是否齐全，特别是 Host $host；搜索与下载是普通 GET 请求，经标准反代透传不应有差异。另确认反代没有对 ?zip=、?file= 等查询串做重写。

Q2：Basic Auth 想只保护部分目录？

把 auth_basic 从 location / 下沉到具体 location 块（如 location /private/），未覆盖的路径匿名可访问；auth_basic 可以在 location 级覆盖 server 级设置。

Q3：.hidden 清单改了没反应？

确认三点：清单路径是绝对路径 /data/.hidden（Docker 形态）；HIDDEN_FILES_LIST 变量已重建容器生效；模式大小写正确（匹配引擎大小写敏感）。

Q4：认证口令想给多人不同账号？

.htpasswd 一行一个账号，追加即可：printf 'ops:%s\n' "$(openssl passwd -apr1 <口令>)" >> .htpasswd，改完 nginx -s reload。角色级差异（如只读/可管理）Directory Lister 不支持——它本身只读，所有通过认证的用户能力相同。

Q5：需要 TLS 怎么做？

在反代层终结：listen 443 ssl + 证书配置，proxy_pass 仍指向应用；同时保留 X-Forwarded-Proto $scheme，让应用与日志能看到真实协议。应用本体（Apache 80）无需改动，也不建议直接在应用层配 TLS。

九、参考链接