1
0

ZFile_Docker部署指南

2026-08-30
2026-08-30
文章摘要
|

ZFile Docker 部署指南

本文档记录在 Debian NAS 上通过 Docker Compose 部署 ZFile（开源网盘/在线文件目录程序）的完整步骤。

一、前置条件

  • NAS 已安装 Debian 系统
  • 已安装 Docker 和 Docker Compose（docker compose version 能正常输出即为已安装）
  • 已规划好存储路径：
    • 配置/数据库/日志 → 建议放在固态硬盘（SSD），读写频繁但文件小，追求速度
    • 实际存储的文件 → 建议放在机械硬盘（HDD），存放大容量数据

二、创建部署目录

mkdir -p /opt/zfile      # 在 /opt 目录下创建 zfile 文件夹，用于存放配置文件
cd /opt/zfile            # 进入该目录，后续操作都在这里进行

说明：目录路径可以自定义，不一定非要用 /opt/zfile，但后续所有相对路径都会基于你执行命令时所在的目录。

三、创建 docker-compose.yml 配置文件

nano docker-compose.yml   # 使用 nano 编辑器创建配置文件（没装 nano 可以用 vi）

将以下内容粘贴进去：

services:
  zfile:                                       # 服务名称，可自定义，用于标识这个服务
    image: zhaojun1998/zfile:latest            # 使用的镜像，latest 表示拉取最新版本
    container_name: zfile                       # 容器的实际名字，docker ps 中显示的名称
    restart: always                              # 容器意外退出或 NAS 重启后自动重新启动
    ports:
      - 8080:8080                                # 左边：宿主机端口（浏览器访问用这个）；右边：容器内部端口（不要改）
    volumes:
      - ./db:/root/.zfile-v4/db                  # 数据库文件，映射到当前目录下的 db 文件夹，存放账号、配置等信息，建议放 SSD
      - ./logs:/root/.zfile-v4/logs              # 运行日志，映射到当前目录下的 logs 文件夹，方便出问题时排查，建议放 SSD
      - /mnt/hdd/zfile-data:/data/file           # 实际文件存储目录，容器内固定路径是 /data/file，左边换成机械硬盘的真实挂载路径

保存并退出：

  • nano：按 Ctrl + O 保存 → 回车 → Ctrl + X 退出
  • vi：按 Esc → 输入 :wq → 回车

⚠️ YAML 文件对缩进非常敏感，必须使用空格（不能用 Tab 键），且各层级缩进要保持一致，否则启动会报错。建议直接复制粘贴整段内容，避免手动敲漏空格。

四、关键参数说明

配置项 容器内路径 建议存放位置 说明
端口 - - 8080:8080，如本机 8080 端口被占用，可改成其他端口，例如 9080:8080
数据库 /root/.zfile-v4/db SSD 存放账号、系统配置等小文件，读写频繁
日志 /root/.zfile-v4/logs SSD 存放运行日志，便于排查问题
文件存储 /data/file 机械硬盘 实际存放上传/管理的文件，占用空间大

关于路径映射的理解：

volumes 冒号左边是宿主机（NAS）的真实路径，右边是容器内部看到的路径。ZFile 软件本身跑在容器里，只认识容器内部的路径（如 /data/file），并不知道宿主机上的真实路径。两者通过 Docker 的 volume 映射打通，本质是同一份数据的两种视角。

使用前请将 /mnt/hdd/zfile-data 替换为你机械硬盘的真实挂载路径（可用 df -h 命令查看），并提前创建好该目录：

mkdir -p /mnt/hdd/zfile-data

五、启动容器

docker compose up -d    # -d 表示后台运行

启动完成后，执行以下命令确认容器状态：

docker ps                # 查看容器列表，zfile 容器状态应显示为 Up

六、访问并初始化

  1. 浏览器输入：http://NAS的IP地址:8080

  2. 按页面提示设置管理员账号密码，完成初始化

  3. 进入后台，点击"添加存储"，选择「本地存储」，路径填写容器内路径：

    /data/file

    即可看到映射进来的机械硬盘中的文件。

七、常用维护命令

docker compose down      # 停止并移除容器（数据不会丢失，因为数据在挂载的宿主机目录中）
docker compose up -d     # 重新启动容器
docker compose logs -f   # 实时查看容器日志，排查问题时使用
docker compose pull      # 拉取最新镜像（用于后续升级）

八、参考信息