🚀 使用 Docker Compose 部署 ZFile

🚀 使用 Docker Compose 部署 ZFile 容器

本文将详细介绍如何使用 Docker Compose 部署 ZFile —— 一款功能丰富的个人在线网盘目录列表程序。

📝 项目简介

ZFile 是一个专为个人设计的在线网盘目录列表程序，它能够将您多种类型的存储源统一到一个网页中查看、预览和维护。

核心特点：

多存储源支持：支持对接 S3、OneDrive、SharePoint、GoogleDrive、多吉云、又拍云、本地存储、FTP、SFTP 等多种存储源。
文件预览能力：支持在线浏览图片、播放音视频，预览文本文件、Office 文档、obj（3D）等多种文件类型。
简化文件管理：无需登录各个云存储平台，可在 ZFile 中统一管理所有文件。
Docker 化部署：提供官方 Docker 镜像，简化部署流程。

🔧 部署前准备

系统要求

操作系统：支持 Ubuntu、Debian、CentOS、RHEL、Rocky Linux 等主流 Linux 发行版
硬件配置：
CPU：至少 1 核
内存：推荐 ≥ 1GB
硬盘：无特殊要求，根据存储需求确定
权限：需要 root 或 sudo 权限

安装 Docker 和 Docker Compose

如果您的系统尚未安装 Docker 和 Docker Compose，可使用以下一键安装脚本：

# 执行一键安装脚本 (支持国内镜像源)
bash <(curl -sSL https://xuanyuan.cloud/docker.sh)

此脚本支持多种 Linux 发行版，可一键完成 Docker 和 Docker Compose 的安装，同时自动配置国内镜像加速源。

安装完成后，使用以下命令验证安装是否成功：

# 检查 Docker 版本
docker --version

# 检查 Docker Compose 版本
docker compose version

# 检查 Docker 服务状态
sudo systemctl status docker

若 Docker 服务未正常运行，可使用以下命令启动：

sudo systemctl start docker
sudo systemctl enable docker

⚙️ 配置 Docker Compose

创建部署目录结构

建议首先创建一个专门的目录来管理 ZFile 的所有相关文件：

mkdir zfile && cd zfile

创建 Docker Compose 配置文件

在 zfile 目录中创建 docker-compose.yml 文件，内容如下：

#version: '3'
services:
  zfile:
    image: zhaojun1998/zfile:latest  # 官方最新镜像
    container_name: zfile  # 容器名称，便于管理
    restart: always  # 容器退出后自动重启（开机自启）
    #restart: unless-stopped
    ports:
      - "8081:8080"  # 端口映射：服务器8081端口 → 容器8080端口（Web访问用）
    volumes:
      #- ./file:/data/file
      #- ./data:/data        # 持久化配置及数据库
      #- ./logs:/logs        # 日志目录
      - './db:/root/.zfile-v4/db'  # 持久化数据库：保存存储源、用户配置等
      - './logs:/root/.zfile-v4/logs'  # 持久化日志：系统运行记录（排查问题用）
      - './file:/data/file'  # 本地文件存储目录：ZFile管理的文件会保存在这里
      #- './file1:/data/file1'
      - './application.properties:/root/application.properties'  # 映射自定义配置文件
    environment:
      #格式不匹配把前面加上'-'，再':'换成'='； TZ: Asia/Shanghai     # 时区配置
      - PUID=1000  # 运行用户ID（低权限模式，可能影响文件删除）
      - PGID=1000  # 运行用户组ID
      # 注意：官方不推荐低权限，可能导致无法删除文件（下载功能正常），新手建议注释这两行
    deploy:
      resources:
        limits:  # 限制资源占用（避免服务器过载）
          cpus: '1.5'  # 最多使用1.5个CPU核心
          memory: 2G  # 最多使用2GB内存

#先在宿主机下载配置文件，然后映射到容器内
#curl -k -o /home/compose/zfile/application.properties https://c.jun6.net/ZFILE/application.properties

配置说明：

image: 使用官方镜像 zhaojun1998/zfile
ports: 8081:8080 表示将容器内部的 8080 端口映射到宿主机的 8081 端口，您可以根据需要修改左侧的宿主机端口
volumes: 数据卷配置：
db: 数据库文件存储路径
logs: 日志文件存储路径
file: 文件存储目录（用于本地存储）
application.properties: 自定义配置文件
resources: 资源限制可防止单个容器耗尽系统资源

创建应用程序配置文件

在相同目录下创建 application.properties 文件，内容如下：

# 基础配置 # 引入默认配置
spring.config.import=classpath:application-default.properties
# 调试模式（生产环境关闭）
zfile.debug=false
# 日志与数据库路径（需与docker-compose.yml的挂载路径对应）
zfile.log.path=${user.home}/.zfile-v4/logs
zfile.db.path=${user.home}/.zfile-v4/db/zfile
# 预览设置 # 文本预览最大文件大小（512KB）
zfile.preview.text.maxFileSizeKb=512
# 启用数据库缓存（提升性能）
zfile.dbCache.enable=true
zfile.version=4.2.0
# 静态资源路径
# read external static resources
spring.web.resources.static-locations=file:static/
# 容器内服务端口（需与docker-compose.yml的内部端口一致）
server.port=8080

# -------------- 数据库配置（默认SQLite，无需修改）--------------
# -------------- database config start --------------
## SQLite（默认使用，无需改动）
## sqlite
spring.datasource.driver-class-name=org.sqlite.JDBC
spring.datasource.url=jdbc:sqlite:${zfile.db.path}
#spring.datasource.characterEncoding=utf8
#spring.datasource.serverTimezone=Asia/Shanghai
#spring.datasource.useSSL=false
#spring.datasource.allowPublicKeyRetrieval=true

## 如需使用MySQL，取消以下注释并修改信息（新手建议先用SQLite）
## mysql
#spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver
#spring.datasource.url=jdbc:mysql://127.0.0.1:3306/zfile?characterEncoding=utf8&serverTimezone=Asia/Shanghai&useSSL=false&allowPublicKeyRetrieval=true
#spring.datasource.username=root
#spring.datasource.password=password

# 环境配置
spring.profiles.active=prod
# MyBatis 配置
mybatis-plus.type-handlers-package=im.zhaojun.zfile.core.config
# -------------- database config end --------------


# -------------- Redis配置（可选，用于缓存提升性能）--------------
# -------------- redis config start --------------
# 如需启用Redis，取消以下注释并修改信息
#spring.data.redis.host=127.0.0.1
#spring.data.redis.port=6379
#spring.data.redis.password=
#spring.data.redis.database=1
#spring.data.redis.timeout=5s
#spring.data.redis.lettuce.pool.max-active=20
#spring.data.redis.lettuce.pool.max-idle=10
#spring.data.redis.lettuce.pool.min-idle=5

# -------------- redis config end ----------------

🚀 启动与验证

启动 ZFile 容器

在 docker-compose.yml 文件所在目录执行以下命令启动容器：

docker compose up -d

-d 参数表示在后台运行容器。

验证部署状态

使用以下命令检查容器是否正常运行：

# 查看容器状态
docker compose ps

# 或使用 Docker 命令查看
docker ps

正常启动时，应看到类似以下输出：

NAME      IMAGE               COMMAND                  SERVICE   CREATED          STATUS          PORTS
zfile     zhaojun1998/zfile   "/bin/sh -c 'java $J…"   zfile     44 seconds ago   Up 42 seconds   0.0.0.0:8081->8080/tcp

访问 ZFile

在浏览器中输入以下地址访问 ZFile：

http://你的服务器IP:8081

首次访问将进入系统初始化页面。

重要：如果您的服务器是云服务器（如阿里云、腾讯云等），需要在安全组规则中开放使用的端口（如 8081）。如果使用的是本地服务器或虚拟机，请确保防火墙已关闭或已放行相应端口。

🔍 基础配置与使用

系统初始化

首次访问 ZFile 时，需要完成系统初始化设置：

访问 http://你的服务器IP:8081
按照页面提示完成初始化设置
设置管理员账号和密码

配置本地存储源

登录后进入管理员页面
点击"存储源设置"
选择"添加存储源"
选择"本地存储"类型
在"绝对路径"中填写容器内的目录路径：/data/file

注意：此路径对应您在 Docker Compose 中配置的 ./file 目录，您在此存储源中上传的文件将实际保存在宿主机的 ./file 目录下。

文件管理

添加存储源后，返回主页即可查看和浏览文件
支持在线预览图片、播放音视频
支持下载和分享文件链接

🛠️ 维护与管理

容器日常操作

# 停止服务
docker compose down

# 重新启动服务
docker compose start

# 查看服务日志
docker compose logs -f

数据备份

建议定期备份以下目录：

db：包含数据库文件，保存了系统配置和存储源信息
file：包含用户上传的文件（如果使用本地存储）
logs：系统运行日志

更新 ZFile

当有新版本发布时，可以通过以下步骤更新：

# 拉取最新镜像
docker compose pull

# 重新启动容器
docker compose up -d

🐛 常见问题排查

1. 端口冲突问题

问题：如果宿主机上的 8081 端口已被其他程序占用，容器将无法启动。

解决： - 修改 docker-compose.yml 文件中的端口映射，如改为 "8082:8080" - 或者停止占用端口的服务

使用以下命令检查端口占用情况：

sudo netstat -tulnp | grep :8081

2. 文件权限问题

问题：如果容器内应用无法写入文件，可能是文件权限配置不正确。

解决： - 确保宿主机上的挂载目录具有适当的读写权限 - 可以尝试将目录权限设置为 777（测试环境）： bash chmod -R 777 ./db ./logs ./file

3. 容器无法启动

解决步骤： 1. 查看容器日志以了解具体错误： bash docker compose logs -f 2. 检查 Docker Compose 配置文件的语法是否正确 3. 确认所有挂载目录存在且具有适当权限

4. 无法访问 Web 界面

解决步骤： 1. 确认容器正在运行：docker ps 2. 检查防火墙设置，确保端口已开放 3. 验证云服务器安全组规则是否允许该端口访问 4. 检查 application.properties 中的 server.port 是否与 Docker Compose 内部端口一致

通过以上步骤，您应该能够成功部署和运行 ZFile。如需更详细的使用指南，请参考 ZFile 官方文档。