Directory Lister 5.8.3 Docker Compose 部署指南

目标：在真实服务器上用 Docker Compose 部署 Directory Lister v5.8.3（官方镜像 directorylister/directorylister:5.8.3），完成文件索引、搜索、哈希、zip 打包下载的部署后验证，并覆盖数据持久化、升级与常见部署故障。全文命令与回显均在 Ubuntu 22.04 服务器上逐条实测。

一、环境信息

本文实测部署所用的服务器环境与关键参数：

• 操作系统：Ubuntu 22.04（x86_64）
• Docker：24+（含 Docker Compose v5.6.1）
• 应用版本：Directory Lister v5.8.3（2026-10-30 发布的官方最新稳定版，镜像内 PHP 8.5.12 / Apache 2.4.69 Debian）
• 镜像：directorylister/directorylister:5.8.3（官方镜像，digest sha256:5498c8cc29d6...，约 1.02 GiB）
• 服务端口：8150（宿主）→ 80（应用内），部署前用 ss -ltn 确认空闲
• 数据目录：/opt/directory-lister/data（bind mount 到应用内 /data）
• 部署目录：/opt/directory-lister（docker-compose.yml 所在目录）
• 应用网络：directory-lister-5.8.3-net（bridge，显式子网 10.89.57.0/24）

💡 说明：Directory Lister 自 v5.0 起官方发布 Docker 镜像（docs.directorylister.com Installation 页，2026-10-30 实查），并同时维护官方 Compose 仓库 directory-lister-compose。本文采用官方镜像 + 自建 Compose 的方式，把端口、网络、配置显式写进 docker-compose.yml，便于版本固化与运维排查。

二、镜像选型说明

Directory Lister 的容器化路径有三条，差异如下：

（三条路径中前两条来自官方镜像仓库，第三、四条分别是 directory-lister-compose 与 DirectoryLister 源码仓库的 compose 文件，2026-10-30 实查。）

如何选：生产环境固定使用带完整版本号的官方镜像（本文 5.8.3），compose 项目名、容器名、网络名全部显式命名，避免多套部署相互干扰；latest 仅用于临时体验。

三、前置条件

部署前逐项确认以下条件：

1. Docker 与 Compose 插件可用：

docker --version && docker compose version

实测回显：

Docker version 27.3.1, build 941c5b7
Docker Compose version v5.6.1

2. 目标端口未被占用（本例选 8150，可按需更换）：

ss -ltn | grep 8150 || echo "8150 空闲"

实测回显：

8150 空闲

3. 准备待展示的文件目录并放入测试文件（正式使用时换成你的目录）：

sudo mkdir -p /opt/directory-lister/data/release-notes
sudo tee /opt/directory-lister/data/README.md >/dev/null <<'EOF'
# 运维资料仓库

本仓库收录团队日常运维所需的发布包、配置模板与文档资料。

> 提示：文件旁的文件信息图标可查看 MD5/SHA 校验值，用于下载后完整性核对。
EOF
printf 'Directory Lister v5.8.3 release notes\n' | sudo tee /opt/directory-lister/data/release-notes/changelog-v5.8.2.txt >/dev/null
printf 'deploy guide content v1\n' | sudo tee /opt/directory-lister/data/deploy-guide-v1.txt >/dev/null

4. （可选但推荐）准备隐藏清单 .hidden，把不想展示的文件从索引中过滤掉：

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

⚠️ 注意：Docker 形态下 .hidden 清单必须通过环境变量 HIDDEN_FILES_LIST 以绝对路径 /data/.hidden 指明（见第六章 6.4），只把文件放进目录而不配该变量是不会生效的。

四、部署步骤

4.1 编写 docker-compose.yml

在 /opt/directory-lister 下创建 docker-compose.yml：

name: "directory-lister-5.8.3-stack"

services:
  directory-lister:
    image: directorylister/directorylister:5.8.3
    container_name: directory-lister-5.8.3-web
    environment:
      SITE_TITLE: "ops-file-repo"
      APP_LANGUAGE: zh-CN
      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
      TIMEZONE: Asia/Shanghai
    ports:
      - "8150:80"
    volumes:
      - ./data:/data
      - dl-app-cache:/var/www/html/app/cache
    restart: unless-stopped
    networks:
      - dl-net

networks:
  dl-net:
    name: directory-lister-5.8.3-net
    driver: bridge
    ipam:
      config:
        - subnet: 10.89.57.0/24

volumes:
  dl-app-cache:
    name: directory-lister-5.8.3-cache

配置逐项说明：

• name: "directory-lister-5.8.3-stack"：显式 Compose 项目名，防止多套部署目录同名互相覆盖。⚠️ Compose 项目名规范不允许点号，5.8.3 会被归一化成 583（实测 docker compose config 显示 directory-lister-583-stack），这是预期行为，不影响网络名与容器名（这两者显式指定，保留完整版本号）。
• environment：Directory Lister 的运行时配置入口，逐项含义见第六章环境变量表与配置参数详解篇。
• ports: "8150:80"：宿主 8150 映射到应用内 80；官方镜像内是 Apache 2.4 直接监听 80。
• volumes：./data:/data 是被列目录（核心数据）；dl-app-cache 是应用缓存卷（模板编译/文件缓存），留空即可，勿删。
• restart: unless-stopped：服务器重启后自动拉起。
• 网络：显式 bridge 子网 10.89.57.0/24，与其他应用的 Docker 网络隔离（部署前应先确认该子网未被占用，见 4.2 排障）。

4.2 校验配置并启动

cd /opt/directory-lister
docker compose config --quiet && echo "compose 配置合法"

实测回显：

compose 配置合法

docker compose up -d

实测回显：

[+] Running 3/3
 ✔ Network directory-lister-5.8.3-net    Created
 ✔ Volume "directory-lister-5.8.3-cache" Created
 ✔ Container directory-lister-5.8.3-web  Started

确认运行状态：

docker compose ps

实测回显：

NAME                        IMAGE                                    COMMAND                  SERVICE             CREATED             STATUS              PORTS
directory-lister-5.8.3-web  directorylister/directorylister:5.8.3    "docker-php-entrypoi…"   directory-lister    8 seconds ago       Up 7 seconds        0.0.0.0:8150->80/tcp, [::]:8150->80/tcp

⚠️ 排障实录：首次启动时曾遇到两类报错，均与显式命名有关——

1. invalid pool request: Pool overlaps with other one on this address space：选定的 10.89.56.0/24 子网已被服务器上另一套栈占用。用 docker network inspect $(docker network ls -q) | grep Subnet 排查已占网段后换用 10.89.57.0/24 解决。
2. Bind for 0.0.0.0:8149 failed: port is already allocated：宿主端口被其他进程占用（ss -ltn 未必能反映 Docker 已分配端口）。用 docker ps --format '{{.Names}}\t{{.Ports}}' 核对后换用 8150 解决。

4.3 首页访问验证

curl -sS -o /dev/null -w "HTTP %{http_code}\n" http://127.0.0.1:8150/

实测回显：

HTTP 200

检查页面标题与元信息（确认 SITE_TITLE 与应用生效）：

curl -sS http://127.0.0.1:8150/ | head -c 600

实测回显（节选）：

<!DOCTYPE html>
<html lang="en">

<meta charset="utf-8">
<meta name="description" content="Yet another directory listing, powered by Directory Lister.">
<meta name="viewport" content="width=device-width, initial-scale=1">

<link rel="icon" href="app/images/favicon.light.png">
...
<title>Home • ops-file-repo</title>

<title> 中出现自定义的 ops-file-repo，应用已正常工作。

4.4 文件索引与 README 渲染验证

检查列表内容与排序（SORT_ORDER=type 时目录在前、文件在后）：

curl -sS http://127.0.0.1:8150/ | grep -oE '\?(dir|file)=[^"]+' | sort -u

实测回显：

?dir=release-notes
?file=deploy-guide-v1.txt
?file=release-notes-v5.8.3.txt

（backup-*.bin 与 *.tar.gz 未出现——.hidden 清单生效，见 6.4 节。）

验证 README Markdown 已渲染为 HTML：

curl -sS http://127.0.0.1:8150/ | grep -oE '<h2>目录说明</h2>|运维资料仓库' | head -3

实测回显：

运维资料仓库
<h2>目录说明</h2>

4.5 搜索验证

curl -sS "http://127.0.0.1:8150/?search=deploy" | grep -c "deploy-guide-v1.txt"
curl -sS "http://127.0.0.1:8150/?search=zzzznotexist" | grep -oE "No results found" | head -1

实测回显：

2
No results found

搜索命中时页面列出匹配文件，无结果时返回 "No results found" 页面。页面搜索框支持快捷键 ? 聚焦。

4.6 文件哈希与 zip 打包下载验证

文件哈希（File Info 按钮背后的接口，返回 JSON）：

curl -sS "http://127.0.0.1:8150/?info=deploy-guide-v1.txt"

实测回显：

{"hashes":{"md5":"35e5e2a09a3f5984a50107abe58a881d","sha1":"4951a5fa4f782e2db8a1ae7b70fad44041f1dfaa","sha256":"078bd47d4c0f838f5c68668be370754b426e9b02b7652bebcdb9b74bfc3b7823"}}

与本地文件核对（MD5 应一致）：

md5sum /opt/directory-lister/data/deploy-guide-v1.txt

实测回显：

35e5e2a09a3f5984a50107abe58a881d  /opt/directory-lister/data/deploy-guide-v1.txt

?info= 返回的 md5 字段与 md5sum 输出一致（35e5e2a09a3f...881d），哈希校验可用。

目录 zip 打包下载：

curl -sS -o /tmp/rn.zip -w "HTTP %{http_code} type=%{content_type} size=%{size_download}\n" "http://127.0.0.1:8150/?zip=release-notes"
python3 -c "import zipfile; print(zipfile.ZipFile('/tmp/rn.zip').namelist())"

实测回显：

HTTP 200 type=application/zip size=203
['changelog-v5.8.2.txt']

五、数据持久化说明

Directory Lister 的全部状态由三部分组成，持久化策略各不相同：

结论：只需要保证 ./data 的 bind mount 指向正确，其余皆可再生。迁移服务器时拷贝 docker-compose.yml 与 data/ 目录即可完整恢复。

六、环境变量表

Directory Lister 通过环境变量完成几乎所有常规配置（官方镜像内已预设 FILES_PATH=/data）。下表为部署常用子集（完整 22 个变量的默认值与逐项详解见配置参数详解篇）：

6.4 隐藏清单的生效条件（重点）

.hidden 清单文件与被列目录放在一起即可被读取，但清单路径的解析基准是应用进程的工作目录：Docker 形态下工作目录不是 /data，因此默认值 .hidden 找不到文件、清单静默不生效。

实测对照（同一份 /opt/directory-lister/data/.hidden，内容含 backup-*.bin 与 *.tar.gz 两行）：

• 未设置 HIDDEN_FILES_LIST 时：backup-demo.bin 与 tmp-archive.tar.gz 仍出现在页面（清单未生效）；
• 设置 HIDDEN_FILES_LIST: /data/.hidden 后再次 docker compose up -d：

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

实测回显：

0

两类模式（精确名与 *.tar.gz 通配）全部从索引消失，清单生效。

七、配置文件挂载

如需覆盖无法用环境变量表达的高级配置（hidden_files 数组、Memcached/Redis 连接闭包、HTTP 缓存时长、自定义排序函数等，官方 Advanced Configuration 页，2026-10-30 实查），有两种挂载方式：

1. 挂载整个配置目录（推荐做法是挂载单个文件）：

    volumes:
      - ./data:/data
      - ./app-config/app.php:/var/www/html/app/config/app.php:ro
      - dl-app-cache:/var/www/html/app/cache

2. 使用官方 Compose 仓库模板：git clone https://github.com/DirectoryLister/directory-lister-compose.git /opt/directory-lister && cd /opt/directory-lister && make init，然后编辑其 .env（官方 Installation 页流程，2026-10-30 实查）。该模板适合希望跟随官方维护的场景；本文自建 compose 的方式则把所有配置显式固化在一个文件里，两者二选一即可。

⚠️ 注意：官方文档提醒 app/config/app.php 的改动在升级时需要手工重新套用，因此优先用环境变量，仅在确无对应变量时才改该文件。

八、等价 docker run

与本文 compose 等价的单命令启动形式（用于快速验证，不建议长期使用；官方文档同样将 docker run 定位为测试用途）：

docker run --detach \
  --name directory-lister-5.8.3-web \
  --env SITE_TITLE="ops-file-repo" \
  --env APP_LANGUAGE=zh-CN \
  --env DISPLAY_READMES=true \
  --env ZIP_DOWNLOADS=true \
  --env SORT_ORDER=type \
  --env HIDDEN_FILES_LIST=/data/.hidden \
  --env TIMEZONE=Asia/Shanghai \
  --volume /opt/directory-lister/data:/data \
  --publish 8150:80 \
  --restart unless-stopped \
  directorylister/directorylister:5.8.3

与 compose 的差异：无命名缓存卷（缓存随容器删除）、无显式网络（使用默认 bridge）。验证方式与 4.3 节相同。

九、常用运维命令

日常运维围绕 docker compose 子命令展开（均在 /opt/directory-lister 下执行）：

docker compose ps                 # 运行状态
docker compose logs -f --tail 50  # 跟踪日志（Apache 访问/错误日志都在这里）
docker compose restart            # 修改环境变量后应用配置（重建容器）
docker compose stop               # 停止（保留容器）
docker compose down               # 停止并删除容器与网络（数据卷与 ./data 保留）
docker compose down -v            # 连同缓存卷一起删除（缓存可再生，放心用）

docker compose logs -f --tail 50 实测回显（节选）：

directory-lister-5.8.3-web  | 127.0.0.1 - - [30/Oct/2026:14:41:59 +0800] "GET /?zip=release-notes HTTP/1.1" 200 203 "-" "curl/7.81.0"
directory-lister-5.8.3-web  | 127.0.0.1 - - [30/Oct/2026:14:41:40 +0800] "GET / HTTP/1.1" 200 15164 "-" "curl/7.81.0"

升级方法（官方 Upgrade Guide 的 Docker 路径：docker compose pull + docker compose up -d，2026-10-30 实查）：把 docker-compose.yml 中的镜像标签改成新版本号（如 5.8.4），然后：

docker compose pull && docker compose up -d

实测回显（升级到同版本时 pull 无更新）：

[+] Running 1/1
 ✔ Container directory-lister-5.8.3-web  Running

被列目录与 .hidden 清单在 bind mount 中，升级不受影响；若曾按第七章挂载过 app.php，按新版默认配置复核一遍再上线。

十、常见问题

Q1：docker compose up 报 invalid pool request: Pool overlaps with other one on this address space？

所选子网与其他 Docker 网络冲突。列出已占网段后换一个：

docker network inspect $(docker network ls -q) | grep '"Subnet"'

实测回显（示例）：

"Subnet": "172.17.0.0/16",
"Subnet": "10.89.56.0/24",
"Subnet": "10.89.57.0/24",

Q2：Bind for 0.0.0.0:8150 failed: port is already allocated？

宿主端口已被占用（其他进程或已存在的容器）。ss -ltn 看进程监听，docker ps --format '{{.Names}}\t{{.Ports}}' 看容器占用，换空闲端口后 docker compose up -d 重建。

Q3：compose 项目名显示成 directory-lister-583-stack，版本号丢了？

Compose 项目名规范不允许点号，5.8.3 被归一化为 583（实测 Docker Compose v5.6.1 行为）。这是预期现象；显式命名的容器名 directory-lister-5.8.3-web 与网络名 directory-lister-5.8.3-net 不受影响，运维定位以这两个名字为准。

Q4：.hidden 清单放了但不生效？

清单路径默认相对应用工作目录解析，Docker 形态下必须在环境变量里写绝对路径：HIDDEN_FILES_LIST: /data/.hidden，改完 docker compose up -d 重建容器（见 6.4 节实测对照）。

Q5：修改了环境变量页面没变化？

环境变量在容器创建时注入，docker compose restart 对 environment 变更不生效时用：

docker compose up -d --force-recreate

Q6：想限制某些文件只能内网访问？

Directory Lister 无内置认证与 ACL（官方 Authentication 页明确该设计取向），访问控制应放在 web 服务器/反代层：Nginx Basic Auth、allow/deny 网段限制或 Authelia 等外部认证（实战配置见本专栏高级配置与定制实战篇）。

十一、参考链接

• 官方安装文档（Docker Compose / Docker Run / Manual / Composer 四路径）：https://docs.directorylister.com/installation
• 官方升级指南：https://docs.directorylister.com/upgrade-guide
• 配置参考（环境变量全集）：https://docs.directorylister.com/configuration/configuration-reference
• 官方 Docker Hub：https://hub.docker.com/r/directorylister/directorylister
• 官方 Compose 仓库：https://github.com/DirectoryLister/directory-lister-compose
• 本专栏相关：《Directory Lister 介绍与选型指南》