Directory Lister 5.8.3 配置参数详解

目标：给出 Directory Lister v5.8.3 全部 22 个环境变量与 4 类高级配置项的权威默认值、取值范围与行为实测结论，并提供可直接落地的生产配置模板。默认值取自官方镜像 v5.8.3 内 app/config/app.php 与 app/config/cache.php 源码逐行核对，行为结论均为容器化部署实测回显。

一、环境信息

• 组件版本：Directory Lister v5.8.3（官方镜像 directorylister/directorylister:5.8.3，内含 PHP 8.5.12 / Apache 2.4.69 Debian）
• 配置事实来源：镜像内 /var/www/html/app/config/app.php、app/config/cache.php（2026-10-30 逐行实查）；高级配置语义同步核对官方文档 Advanced Configuration / File Matching Patterns 页
• 行为实测环境：Docker Compose 部署（8150 端口）、被列目录含子目录/文本文件/二进制文件/README.md
• 部署形态回顾：环境变量在容器创建时注入，改动后需重建容器生效（docker compose up -d --force-recreate）

二、前置条件

• 已按部署篇完成 Directory Lister 的容器化部署并能访问首页；配置修改均作用于 compose 的 environment: 段（或手动安装形态的应用根目录 .env 文件）
• 本文所有实测命令通过 curl http://127.0.0.1:8150/... 执行，读者替换为自己的端口即可

三、参数查看与修改方式

3.1 查看当前生效配置

容器形态下，环境变量即生效配置，直接进入应用环境核对：

docker exec directory-lister-5.8.3-web env | grep -E "APP_|SITE_|DISPLAY_|SORT_|HIDE_|ZIP_|TIMEZONE|FILES_PATH|HIDDEN"

实测回显：

HIDE_APP_FILES=true
APP_LANGUAGE=zh-CN
HIDE_VCS_FILES=true
REVERSE_SORT=false
DISPLAY_READMES=true
SORT_ORDER=type
HIDE_DOT_FILES=true
FILES_PATH=/data
SITE_TITLE=ops-file-repo
TIMEZONE=Asia/Shanghai
ZIP_DOWNLOADS=true

更权威的核对方式是直接读镜像内的配置定义（含默认值）：

docker exec directory-lister-5.8.3-web grep -nE "env\(" /var/www/html/app/config/app.php

实测回显：

17:    'debug' => env('APP_DEBUG', false),
26:    'language' => env('APP_LANGUAGE', 'en'),
34:    'site_title' => env('SITE_TITLE', 'Directory Lister'),
41:    'meta_description' => env('META_DESCRIPTION', 'Yet another directory listing, powered by Directory Lister.'),
49:    'home_text' => env('HOME_TEXT', null),
56:    'display_readmes' => env('DISPLAY_READMES', true),
63:    'readmes_first' => env('READMES_FIRST', false),
72:    'direct_links' => env('DIRECT_LINKS', null),
79:    'zip_downloads' => env('ZIP_DOWNLOADS', true),
87:    'zip_compress' => env('ZIP_COMPRESS', false),
95:    'sort_order' => env('SORT_ORDER', 'type'),
102:    'reverse_sort' => env('REVERSE_SORT', false),
110:    'hidden_files_list' => env('HIDDEN_FILES_LIST', '.hidden'),
128:    'hide_app_files' => env('HIDE_APP_FILES', true),
135:    'hide_dot_files' => env('HIDE_DOT_FILES', true),
143:    'hide_vcs_files' => env('HIDE_VCS_FILES', true),
151:    'date_format' => env('DATE_FORMAT', 'Y-m-d H:i:s'),
159:    'timezone' => env('TIMEZONE', date_default_timezone_get()),
167:    'max_hash_size' => env('MAX_HASH_SIZE', 1000000000),

3.2 修改方式与生效条件

官方镜像内置的 .env.example 全文（2026-10-30 镜像内实查）：

# Here you can control Directory Lister configuration through environment
# variables. See the configuration documentation for additional information:
# https://docs.directorylister.com/configuration

APP_DEBUG=false
APP_LANGUAGE=en

# FILES_PATH=

DISPLAY_READMES=true
READMES_FIRST=false
ZIP_DOWNLOADS=true

SORT_ORDER=type
REVERSE_SORT=false

⚠️ 注意：APP_DEBUG 保持 false。官方配置参考明确警告：开启调试会向页面泄露敏感的服务器信息（原文为 "Leaving this enabled WILL cause leakage of sensitive server information"），仅在排障时临时打开。

四、参数总览

22 个环境变量按作用分四组（默认值均为镜像内源码实查值）：

💡 说明：FILES_PATH 与 COMPILE_CONTAINER 属于"引导配置"——它们在应用容器装配前生效，没有对应的 app/config 定义项，只能通过环境变量设置（官方 Configuration Reference 的 Bootstrap Configuration 节，2026-10-30 实查）。

五、核心参数分类详解

5.1 列表呈现：SORT_ORDER 与 REVERSE_SORT

SORT_ORDER 支持六个预定义值：type（默认，目录在前文件在后）、natural（自然数字排序）、name（名称）、accessed（访问时间）、changed（inode 变更时间）、modified（修改时间）；REVERSE_SORT=true 在排序后整体反转。

三种取值的行为实测（同一目录：release-notes/ 子目录、backup-demo.bin、deploy-guide-v1.txt、release-notes-v5.8.3.txt、README.md）：

• SORT_ORDER=type（默认）实测列表顺序：

release-notes → README.md → backup-demo.bin → deploy-guide-v1.txt → release-notes-v5.8.3.txt

• SORT_ORDER=name + REVERSE_SORT=true 实测列表顺序：

release-notes-v5.8.3.txt → release-notes → deploy-guide-v1.txt → backup-demo.bin → README.md

• SORT_ORDER=modified 实测列表顺序（按文件修改时间正序）：

README.md → backup-demo.bin → release-notes-v5.8.3.txt → deploy-guide-v1.txt → release-notes

需要超越预定义值的排序（例如按扩展名分组、按大小倒序）时，只能在 app/config/app.php 写匿名函数（必须用 \DI\value() 包装），官方示例：

'sort_order' => \DI\value(
    function (SplFileInfo $file1, SplFileInfo $file2): int {
        return strcmp($file1->getRealPath(), $file2->getRealPath());
    }
),

5.2 隐藏控制：HIDE_* 与 HIDDEN_FILES_LIST

三个布尔开关的语义（默认全为 true）：

• HIDE_DOT_FILES：隐藏点开头文件/目录（.git、.env 等）；
• HIDE_VCS_FILES：隐藏 Git/Mercurial 等版本控制元数据（.gitignore、.hg 等）；
• HIDE_APP_FILES：隐藏应用自身文件（index.php 与 app 目录）。Docker 形态下列表根是 /data，应用文件不在列表范围内，该开关通常无感——实测将其设为 false 后页面不出现 index.php 或 /app/（grep 计数为 0）；只有裸机安装且直接列出应用根目录时它才有实际作用。

HIDDEN_FILES_LIST 指向的清单文件每行一个匹配模式，支持通配（详见 5.3）。关键行为：清单路径按应用进程工作目录解析，Docker 形态必须写绝对路径 /data/.hidden，否则静默不生效。实测对照：不设该变量时 backup-demo.bin、tmp-archive.tar.gz 均在页面可见；设置后：

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

实测回显：

0

清单文件本身以 # 开头的行是注释，空行跳过，示例：

# 隐藏清单：每行一个文件匹配模式
backup-demo.bin
*.tar.gz

5.3 文件匹配模式语法

隐藏清单与 DIRECT_LINKS 共用一套匹配表达式（官方 File Matching Patterns 页，2026-10-30 实查，大小写敏感）：

官方示例与语义（逐条照抄）：

• foo：根目录下的 foo 文件或目录
• foo/bar：foo 目录下的 bar
• *.txt：根目录下所有 .txt
• **/*.txt：一层及更深目录中的 .txt（如 foo/bar.txt、foo/bar/baz.txt）
• **.txt：任意深度的 .txt（含根目录，如 foo.txt、foo/bar.txt）
• foo/bar/**.txt：foo/bar 及其子目录中全部 .txt
• file.{yml,yaml}：file.yml 或 file.yaml
• file.tar(!.{gz,xz})：file.tar、file.tar.bz，但排除 file.tar.gz、file.tar.xz

5.4 README 渲染：DISPLAY_READMES 与 READMES_FIRST

DISPLAY_READMES=true（默认）时，目录内的 README 文件解析为 Markdown 渲染在页面上；READMES_FIRST=false（默认）时渲染块位于文件列表之后，设为 true 则置于列表之前。实测两种状态的页面结构：

• READMES_FIRST=true：README 渲染块位置（HTML 偏移 10695 → 列表前）在文件列表锚点（偏移 5619）之前；
• READMES_FIRST=false：README 渲染块在文件列表之后。

关闭渲染（DISPLAY_READMES=false）后页面不再包含 README 内容，实测验证：

curl -sS http://127.0.0.1:8150/ | grep -c "运维资料仓库"

实测回显：

0

README 的识别规则与样式由应用内模板决定；多个 README 变体（README.md/README.html 等）的优先级同样由应用内定义，常规使用 README.md 即可。

5.5 下载链路：ZIP_DOWNLOADS、ZIP_COMPRESS、DIRECT_LINKS、MAX_HASH_SIZE

• ZIP_DOWNLOADS=true（默认）：页面每个目录提供 zip 打包下载入口，请求形式 ?zip=<目录名>。实测响应头（节选）：

HTTP/1.1 200 OK
Content-Disposition: attachment; filename="release-notes.zip"
Content-Length: 203
Cache-Control: max-age=300, private, must-revalidate

• ZIP_COMPRESS=true：zip 内部条目改用 Deflate 压缩（默认不压缩，打包更快）。实测开关前后用 file 命令识别同一目录的下载产物：

/tmp/dl-zc.zip: Zip archive data, at least v4.5 to extract, compression method=deflate

官方文档同时提示：开启压缩后无法预估 zip 文件大小、暂停后续传可能失效——对大目录分发场景，若客户端依赖"文件大小/断点续传"，保持默认 false。

• DIRECT_LINKS：逗号分隔的匹配模式列表，命中的文件不由应用处理而是直接交给 web 服务器链接。⚠️ 官方明确：该设置在设置了 FILES_PATH 时（含 Docker 形态）无效——Docker 形态必然预设 FILES_PATH=/data，因此此变量仅在裸机/Composer 安装且未设 FILES_PATH 的部署中有意义。

• MAX_HASH_SIZE=1000000000（默认，约 1GB）：File Info 哈希计算的文件大小上限，防止超大文件在请求线程上做 MD5/SHA 计算导致超时。超过上限的文件不展示哈希。按需调小（如 100MB）可降低误点大文件哈希的等待成本。

5.6 通用外观：SITE_TITLE、META_DESCRIPTION、HOME_TEXT、DATE_FORMAT、TIMEZONE、APP_LANGUAGE

• SITE_TITLE：浏览器标签页标题主体，与当前路径一并显示。实测首页 <title> 为 Home • ops-file-repo（自定义值 ops-file-repo 生效）。
• META_DESCRIPTION：首页 <meta name="description"> 内容。实测页面 head 为默认值 Yet another directory listing, powered by Directory Lister.
• HOME_TEXT：面包屑起始链接文本；未设置（默认 null）时使用语言包 home 键的译文——zh-CN 语言包实查为 目录起始页。
• DATE_FORMAT=Y-m-d H:i:s：文件行的修改时间显示格式。实测文件行显示 2026-10-30 14:27:12，与默认格式一致。
• TIMEZONE：配合 DATE_FORMAT 渲染时间，实测 Asia/Shanghai 下时间与文件系统 mtime 一致。
• APP_LANGUAGE：界面语言。实测设为 zh-CN 后界面文本切换为中文（搜索、日期、大小、文件信息等），语言包位于应用内 app/translations/（29 个 yaml，含 zh-CN.yaml、zh-TW.yaml）。HOME_TEXT、搜索框占位符等未单独定制的文本均随语言包联动。

5.7 缓存：CACHE_DRIVER 与连接参数

CACHE_DRIVER 默认 file（缓存写入应用缓存目录，即 compose 中的 dl-app-cache 卷），可切换为 memcached 或 redis；对应连接参数 MEMCACHED_HOST（默认 localhost）/MEMCACHED_PORT（默认 11211）、REDIS_HOST（默认 localhost）/REDIS_PORT（默认 6379）。切换外部缓存前先确认网络可达（容器形态下用服务名），缓存仅加速请求处理，清空不丢数据。

5.8 高级配置（仅 app/config/app.php）

以下配置项没有对应环境变量，只能修改 app/config/app.php（官方 Advanced Configuration 页，2026-10-30 实查；升级后需手工重新套用）：

hidden_files 官方示例（数组写法，适合不想维护清单文件的场景）：

'hidden_files' => [
    'somefile.txt',          // 精确匹配
    'README.*',              // 任意扩展名的 README
    'foo/*',                 // foo 目录下全部文件
    'schema.{yml,yaml}',     // schema.yml 或 schema.yaml
],

六、生产配置模板

适用场景：内网/公网文件分发站，8GB 内存、普通 SSD、目录规模在数万文件以内。以 compose 环境变量段给出，可直接替换进部署篇的 docker-compose.yml：

    environment:
      SITE_TITLE: "ops-file-repo"
      APP_LANGUAGE: zh-CN
      APP_DEBUG: "false"
      DISPLAY_READMES: "true"
      READMES_FIRST: "false"
      ZIP_DOWNLOADS: "true"
      SORT_ORDER: type
      REVERSE_SORT: "false"
      HIDE_DOT_FILES: "true"
      HIDE_APP_FILES: "true"
      HIDE_VCS_FILES: "true"
      HIDDEN_FILES_LIST: /data/.hidden
      MAX_HASH_SIZE: 100000000
      TIMEZONE: Asia/Shanghai

与默认值的差异及理由：

• MAX_HASH_SIZE=100000000（约 100MB，默认 1GB）：文件分发场景中小文件占多数，收窄上限避免大包哈希拖慢请求；需要校验大包时用命令行工具本地计算。
• HIDDEN_FILES_LIST=/data/.hidden：显式声明隐藏清单（Docker 形态必须绝对路径），配合清单文件隐藏构建中间产物。
• 其余保持默认：SORT_ORDER=type 目录优先符合浏览习惯；APP_DEBUG=false 安全基线；缓存保持 file 驱动，单机部署无需引入外部缓存组件。

配套的 .hidden 清单（按需增删）：

# 构建中间产物与备份原件不对外展示
*.tar.gz
*.sha256
backup-*.bin

七、常见问题

Q1：改了环境变量不生效？

环境变量在容器创建时注入。compose 下 docker compose up -d 会检测 environment 变化并重建；若用了 docker stop/start 流程，改完记得 up -d --force-recreate。

Q2：SORT_ORDER 哪个值最合适？

默认 type（目录在前）对浏览场景最友好；modified 适合"最新产物优先"的分发目录；name/natural 适合版本号命名的文件（natural 对 v2、v10 这类排序更符合直觉）。accessed/changed/modified 三者对应 atime/ctime/mtime，一般用 modified 即可。

Q3：隐藏了文件，直接输 URL 还能访问吗？

能。隐藏规则是索引层的展示过滤，不拦截对文件本身的请求；对敏感目录的访问控制应在 web 服务器/反代层解决（Basic Auth、allow/deny、外部认证）。

Q4：.hidden 在裸机安装下也要绝对路径吗？

不一定。清单路径相对应用进程工作目录解析，裸机 Apache/Nginx + PHP-FPM 的工作目录通常是应用根目录，默认值 .hidden 一般直接可用；Docker 形态因工作目录不同必须写 /data/.hidden。拿不准时直接写绝对路径最稳。

Q5：zip 下载对超大目录会怎样？

zip 是请求线程上的实时流式打包，目录越大首次响应越慢且占用带宽；ZIP_COMPRESS=true 时还要额外承担压缩 CPU。超大目录建议预打包（把 zip 放进目录本身），应用层 zip 仅用于中小目录。

八、参考链接

• 配置参考（官方，含全部环境变量）：https://docs.directorylister.com/configuration/configuration-reference
• 高级配置（app/config 专属项）：https://docs.directorylister.com/configuration/advanced-configuration
• 文件匹配模式：https://docs.directorylister.com/configuration/file-matching-patterns
• 本专栏相关：《Directory Lister 介绍与选型指南》、《Directory Lister 5.8.3 Docker Compose 部署指南》