很多买了 VPS 或小主机的同学，手里总少不了一堆杂七杂八的文件：日常脚本、配置备份、电子书、公开分享的安装包，或者本地 NAS 里的照片视频。如果只想搭建一个轻巧漂亮、开箱即用的私有云盘或在线目录展示站，既不想忍受臃肿缓慢的企业级网盘，也不想面对复杂的外部对象存储配置，ZFile 绝对是自建圈子里最讨喜的神器之一。它专注做「存储聚合与文件直链展示」，不仅前端界面清爽优雅、支持图片灯箱预览、音视频流媒体在线播放和 Markdown/代码高亮，还能将本地硬盘、对象存储、各种网盘统一整合成一个干净的 Web 盘，非常适合极客、独立开发者和团队搭建私有下载站。

不过自建网盘最忌讳“照抄老攻略”。网上许多教程还混杂着老旧的 4.x/v4 架构甚至普通 Java 包启动方式，不仅容易踩进环境变量和运行时依赖的坑，目录映射也常让人头疼。本文基于官方最新稳定发布的 5.0.5 原生版（容器端口 8080）进行全流程实机安装与验证。在 5.0.5 版本下，系统底层采用 GraalVM Native 原生二进制构建，无需宿主机或容器额外配置 Java 运行时，整体资源占用极低且启动秒级完成。接下来跟着实测步骤，只需几分钟，我们就能用 Docker Compose 把它稳稳当当地跑起来。

成品长这样

部署完成后，你将获得一个现代感十足、加载极快的前台文件管理与直链分享界面。无论是多级文件夹遍历、文件名即时检索，还是文件大小、修改日期的元数据展示都一目了然，访客无需安装任何客户端就能直接在浏览器内预览或极速下载文件：

ZFile 本地存储文件列表界面
图 1：ZFile 本地演示盘前台展示，直观呈现文件列表与详情信息

准备工作

在开始敲命令部署之前，请先确认你的服务器环境满足以下几项准备要求：

  • 安装好 Docker 与 Docker Compose：推荐运行在 Ubuntu 22.04 / 24.04 或 Debian 12 等常见 64 位 Linux 系统上，确认已安装好 Docker 引擎及 docker compose 插件。
  • 防火墙放行 8080 端口：ZFile 官方默认使用 8080 端口提供 Web 服务。请在云厂商控制台的安全组规则以及云主机内部防火墙（如 ufw 或 firewalld）中，确保 TCP 8080 端口允许入站访问。
  • 准备一个存放文件的宿主机目录：既然是自建文件展示站，建议在宿主机上预留一个清晰的目录（例如项目目录下的 ./files 文件夹）专门存放你要对外展示或分享的文件。

第一步：Docker Compose 部署

使用 Docker Compose 部署是最推荐的生产维护方式。它能保证配置文件结构化，并在容器销毁或版本迭代时完整保留数据库与用户数据。

  1. 创建项目专项目录

    在你的服务器上建一个专门用来管理 ZFile 的文件夹，并切换到该目录中：

    BASH
    mkdir -p ~/zfile && cd ~/zfile

  2. 编写 docker-compose.yml 配置文件

    新建 docker-compose.yml 文件，将以下经过真机验证的编排内容粘贴进去：

    BASH
    services:
  zfile:
    image: zhaojun1998/zfile:5.0.5
    container_name: zfile
    restart: always
    ports:
      - "8080:8080"
    volumes:
      - ./db:/root/.zfile-v4/db
      - ./logs:/root/.zfile-v4/logs
      - ./files:/data

    为了搞懂容器是怎么运行的，我们逐一拆解这几个关键挂载项的用途：

    • ./db:/root/.zfile-v4/db：核心数据库挂载。ZFile 默认使用 SQLite 作为内置数据库，日志与代码实测确认其主库固定落在容器运行用户的家目录 /root/.zfile-v4/db/zfile 中。把这里映射到宿主机的 ./db 目录，能保证站点名称、管理员账密和添加的存储源配置永久保存。
    • ./logs:/root/.zfile-v4/logs：日志目录挂载。映射后系统的运行日志会输出到宿主机的 ./logs 文件夹，日后排查存储源连通性或排错时不必进入容器翻找。
    • ./files:/data：本地文件源映射。这是宿主机上真正存放文件的目录。映射到容器内的 /data 路径后，日后我们在后台配置「本地存储源」时，直接将文件路径填入 /data 即可读取该目录下的所有资源。

  3. 准备本地测试文件并后台启动服务

    提前创建映射所需的 files 目录，顺手放入两个测试文件供稍后验证，随后拉取镜像并在后台拉起容器：

    BASH
    mkdir -p files
echo "Hello ZFile 5.0.5!" > files/hello.txt
echo "# Readme\n欢迎访问自建云盘" > files/readme.md

docker compose up -d

  4. 查看启动日志确认就绪

    执行以下命令跟踪容器运行日志：

    BASH
    docker compose logs -f

    当你看到日志输出 Started ZfileApplication 以及服务成功监听端口的提示后，按 Ctrl + C 退出日志跟踪，此时后端服务已经平稳跑起来了。

踩坑预警：数据目录跟进程用户家目录绑定

ZFile 5.x 采用原生二进制运行，底层启动时读取的是当前运行用户的家目录路径（root 运行即固定解析为 /root/.zfile-v4/db），实测通过容器环境变量改写 HOME 均无法改变其落盘路径。因此务必严格按照上述配置将容器内 /root/.zfile-v4/db 挂载到宿主机，否则一旦容器更新或重建，所有配置与后台账号都会丢失！

关于版本号的小提示

进入后台有时会看到弹窗提示“发现新版本 5.1.0”，但目前 GitHub 官方 Releases 列表中的最新正式 Release 标签仍钉在 5.0.5。为了保证生产环境稳定与可复现性，本教程统一锁定 zhaojun1998/zfile:5.0.5 镜像。如需跟进新版，建议以 Docker Hub 官方发布的稳定 Tag 为准，不要盲目通过最新浮动标签覆盖。

第二步：初始化向导与登录

容器启动成功后，打开浏览器，访问 http://<你的服务器IP>:8080。如果是第一次启动，系统检测到还没有初始化数据库，会自动 302 重定向到 /install 安装向导页面。

在这里你需要填写三项基础信息：

  • 站点名称：随意填写，比如“我的个人私有网盘”或“文件分发站”，后续可以在后台系统设置里随时修改。
  • 管理员账号：登录管理后台的用户名，建议不要用默认弱账号，起一个自己好记的常用管理员名称。
  • 管理员密码：管理后台凭证。请务必设置复杂度足够的高强度密码并妥善保管（出于安全规范，教程演示中不会提供任何真实生产口令，请现场生成并存入密码管理器）。
ZFile 系统初始化向导页面
图2：ZFile 系统初始化向导页面（输入站点名称与初始管理员账户凭证）

确认信息填写无误后，点击下方的“确认并安装”。系统会在后台自动执行数据库初始化与表结构迁移，片刻后会弹出“初始化成功”的提示对话框，接着页面会自动跳转到 /login 登录页。

ZFile 登录页面
图3：ZFile 管理员登录页面

在登录页输入刚才在向导里设定的管理员账号与密码，点击登录即可正式进入 ZFile 管理后台。再次提醒：首次登录成功后请随手检查或备份好自己的管理员密码，一旦遗忘，就只能通过官方的管理员重置脚本或重置数据目录来找回了。

第三步：添加一个本地存储源

刚部署好的 ZFile 前台是完全空白的，因为我们还没有告诉它“要去哪里读文件”。ZFile 支持多种存储后端（各大云厂商的对象存储、WebDAV、OneDrive 等），这里我们先以最常见的“本地目录挂载”为例，跑通核心链路。

按照下面的步骤操作：

  1. 点击管理后台左侧导航栏的存储源管理，在右上角点击添加存储源。
  2. 基本设置：
    • 存储源名称：填写“本地演示盘”（或者任何你喜欢的名字，这个名字会直接显示在前台目录列表顶端）。
    • 存储源别名：默认或自定义英文字符，用作 URL 路径的标识符（例如 /s/local）。
    • 存储策略：下拉菜单中选择本地存储。
  3. 点击下一步进入存储设置：
    • 文件路径：这里一定要注意，填写的必须是容器内部的绝对路径，即 /data。我们在写 docker-compose.yml 时把宿主机的 ./files 映射到了容器内的 /data，所以容器程序只能认 /data，千万不要直接填宿主机的物理目录路径。
  4. 其余的缓存策略、密码访问、仅显示特定后缀等高级参数保持默认即可，直接点击保存。
ZFile 存储源管理列表含本地演示盘
图4：ZFile 存储源管理列表（已成功挂载并启用本地演示盘）

保存成功后，存储源列表里就会出现刚才添加的“本地演示盘”，状态显示为开启。此时回到站点前台（访问根路径 /），点击进入这个存储源，就能直接看到宿主机 ./files 目录下的所有文件了！常见的图片、视频、Markdown、音视频、PDF 都可以直接在线预览或流式播放，无需下载到本地。

踩坑实录

1. 后台弹窗提示 5.1.0 可更新，但 GitHub 最新 Release 依然是 5.0.5
进入后台有时会弹出类似“发现新版本 5.1.0”的更新提示，但去官方 GitHub Releases 查看却发现最新稳定版仍停留在线上某个次级版本。这是因为 ZFile 的自动检查更新接口拉取的是最新构建包或测试分支标记，而镜像构建与官方 Release 节点往往存在时间差。建议在 docker-compose.yml 中明确锁定稳定镜像标签（如 zfile:5.0.5 或特定的成熟版本），避免使用浮动的 latest，这样能彻底防止容器意外重启时拉到不兼容的升级导致数据库结构错乱。

2. 漏挂载 /root/.zfile-v4 导致重建容器后配置全丢
ZFile 默认使用内置的嵌入式数据库（SQLite）存储站点配置、存储源连接信息与密码，其数据文件固定存放在容器内部的 /root/.zfile-v4/db，日志存放在 /root/.zfile-v4/logs。很多新手只挂载了媒体目录 /data，一旦执行 docker compose down 并在拉取更新后重新 up，容器层被销毁，之前的站点配置、管理员账密全部归零。务必在 compose 文件中把容器内的 /root/.zfile-v4 映射到宿主机持久化目录。

3. 游客未登录访问存储源提示“无权访问该目录”
刚配完存储源，登出管理员或开无痕窗口访问前台，可能会弹出红字警告“无权访问该目录”，很多朋友误以为是 Linux 目录权限（chmod/chown）没给对。其实这是 ZFile 的业务权限策略：默认情况下新存储源可能未开放“访客（未登录用户）只读浏览”。解决办法是进入管理后台 -> 存储源管理 -> 找到对应存储源编辑 -> 检查权限设置，确认是否允许“匿名访问/访客访问”。如果需要对公分享，请确保勾选了公开权限。

升级与备份

如何安全升级：

得益于 Docker 的容器化封装，升级流程非常轻量：

  1. 先停用现有服务：docker compose stop。
  2. 在 docker-compose.yml 中修改 image: zfile:x.y.z 的版本标签（若官方有升级说明，先浏览有无破坏性变更）。
  3. 拉取新镜像并启动：docker compose pull && docker compose up -d。
  4. 查看容器运行日志：docker compose logs -f zfile，确认数据库自动迁移完成、应用监听 8080 端口正常。

数据备份与恢复策略：

ZFile 的数据拆分为两个独立部分，备份时建议分开处理：

  • 系统配置与元数据：宿主机上挂载出来的 项目 目录（内含 db 与 logs）。这个目录体积通常只有几兆到几十兆，定时用 tar -czvf zfile-config-$(date +%F).tar.gz ./db 打包归档或同步到云端即可。只要这个数据库在，你的全部存储源配置、加密规则、自定义样式就永远丢不了。
  • 实际存储的业务文件：即挂载到 /data 的真实本地文件（如 ./files）。这些大文件体积较大，建议纳入服务器常规冷备或 rsync 增量同步流，不建议和轻量级的数据库配置打包在一起，以免备份臃肿且耗费 I/O。