🚀 使用 Docker Compose 部署 WebDAV（多实例版）

🚀 使用 Docker Compose 部署 WebDAV

WebDAV（Web-based Distributed Authoring and Versioning）是一种基于 HTTP 协议的通信协议，它在标准 HTTP 方法之上扩展了额外的功能，使应用程序可以直接对 Web 服务器进行读写操作。它支持文件锁定、解锁，甚至版本控制，在广域网文件共享方面具有天然优势，移动端文件管理 APP 也大多支持此协议。

📦 项目简介

WebDAV 的核心特点可以概括为下表：

特点类别	具体说明
协议优势	基于 HTTP/HTTPS，易于穿越防火墙，适合广域网文件共享。支持文件直接读写、锁定（Locking）及解锁（Unlock），可有效防止编辑冲突。
跨平台性	被多种操作系统（Windows、Linux、macOS）和移动端（Android、iOS）的文件管理器或专用APP（如 RaiDrive、ES 文件浏览器）良好支持。
部署简便性	通过 Docker 容器化部署，环境统一，配置简单，避免了复杂的原生软件安装和编译过程。

使用场景 * 个人文件同步与备份：在不同设备（如个人电脑、NAS、手机）之间同步和备份重要文件、照片、文档等。 * 团队文件共享与协作：作为团队内部文件共享和协作的工具，设置不同权限的目录供成员访问。 * 应用程序数据存储：为某些支持 WebDAV 的应用程序（如笔记软件 Joplin、备份工具 Kopia）提供远程存储位置。

---

📦 项目简介2

WebDAV（Web-based Distributed Authoring and Versioning）是一种基于 HTTP 协议的 文件管理标准协议，核心功能是实现跨设备、跨平台的文件远程访问与管理（如上传、下载、修改、删除文件），可替代 FTP 服务，适配 Windows、macOS、Linux、手机等所有支持 HTTP 的设备。

本次部署为 3 个独立 WebDAV 实例，每个实例对应不同端口（81/82/83）、存储目录与访问密码，实现 “文件隔离管理”（如实例 1 存文档、实例 2 存备份、实例 3 存媒体文件），基于 bytemark/webdav 轻量镜像，资源占用低且配置简单。

核心特点

1. 多实例隔离：3 个实例独立运行，端口、存储目录、密码互不干扰，适合分类管理不同类型文件；
2. 安全认证：采用 Digest 认证（比 Basic 认证更安全，密码传输加密），避免明文泄露风险；
3. 权限可控：通过 PUID/PGID 统一用户权限，确保容器内文件与本地目录权限一致，避免 “无法读写” 问题；
4. 跨平台兼容：支持所有主流系统（Windows 映射网络驱动器、macOS 连接服务器、手机文件管理器访问）；
5. 数据持久化：文件存储在本地硬盘（如 /mnt/10t/file），容器删除后数据不丢失，支持大容量硬盘挂载；
6. 轻量高效：单个实例内存占用 < 50MB，1 核 1GB 服务器可轻松运行 3 个实例，无性能压力；
7. 标准协议：基于 HTTP 协议，无需额外安装客户端，系统原生支持访问。

---

📋 部署前准备

1.环境要求 确保你的服务器已安装 Docker 和 Docker Compose。你可以通过在终端执行 docker -v 和 docker compose version 来验证。

2.资源检查 * 端口：确认计划使用的端口（如配置中的 81, 82, 83）未被其他程序占用。 * 磁盘空间与权限：确保挂载目录（如示例中的 /mnt/10t/file/webdav/1, /mnt/10t/file/webdav/2, /mnt/10t/file/media）有足够空间，并且当前用户对这些目录有读写权限。权限问题可能导致容器无法启动或无法删除文件。

⚙️ 配置 Docker Compose

1.创建项目目录 创建一个目录（如 webdav）用于存放所有相关文件，并进入该目录。

    mkdir -p /path/to/your/webdav && cd /path/to/your/webdav

2.创建 docker-compose.yml 文件 将用户提供的配置内容保存到新创建的 docker-compose.yml 文件中。此配置定义了三个 WebDAV 服务实例，它们共享相似的配置但使用不同的端口和存储路径。

#version: '3'
services:
  # 实例1：端口81，存储目录/mnt/10t/file/webdav/1，密码aaaaa
  webdav1:
    image: bytemark/webdav  # 轻量 WebDAV 官方镜像，体积约 50MB
    restart: always  # 容器退出后自动重启，保障服务稳定
    ports:
      - "81:80"  # 端口映射：主机81 → 容器80（容器内默认HTTP端口）
    environment:
      #给相同的权限来通用 避免权限组不同无法创建删除文件名
      PUID: 1000  # 本地用户ID，需与存储目录所有者ID一致（避免权限问题） #这边1000后权限就是82:82了
      PGID: 1000  # 本地用户组ID，与PUID对应
      TZ: Asia/Shanghai  # 时区同步，确保日志时间正确
      #AUTH_TYPE: Basic # Basic确保kopia能用。pass,直接改用机械盘路径了。
      AUTH_TYPE: Digest  # 认证方式：Digest（安全，密码加密传输），不建议改为Basic
      USERNAME: user  # 访问用户名（可自定义，如 webdav_user1）
      PASSWORD: aaaaa  # 访问密码（必须修改！默认aaa安全性低，建议含字母+数字）
      #LOCATION: /webdav
    volumes:
      # 数据持久化：本地目录 ↔ 容器内文件存储目录
      - /mnt/10t/file/webdav/1:/var/lib/dav/data
      #- /home/compose/user.passwd:/user.passwd

  # 实例2：端口82，存储目录/mnt/10t/file/webdav/2，密码usera
  webdav2:  # 修正：删除原配置中"webdav2"后的空格（yaml语法不允许）
    image: bytemark/webdav
    restart: always
    ports:
      - "82:80"
    environment:
      PUID: 1000
      PGID: 1000
      TZ: Asia/Shanghai
      AUTH_TYPE: Digest
      USERNAME: usera  # 可与实例1不同用户名（如 webdav_user2）
      PASSWORD: usera  # 必须修改！建议改为强密码（如 WebDAV@2024）
      #LOCATION: /webdav
    volumes:
      - /mnt/10t/file/webdav/2:/var/lib/dav/data
      #- /home/compose/user.passwd:/user.passwd

  # 实例3：端口83，存储目录/mnt/10t/file/media，密码aaaaa
  webdav3  :
    image: bytemark/webdav
    restart: always
    ports:
      - "83:80"
    environment:
      PUID: 1000  # 原配置注释的82需删除，统一用1000避免权限混乱
      PGID: 1000 
      TZ: Asia/Shanghai
      #AUTH_TYPE: Basic
      AUTH_TYPE: Digest
      USERNAME: user  # 可自定义（如 webdav_media）
      PASSWORD: aaaaa  # 必须修改！与实例1密码可相同或不同
      #LOCATION: /webdav
    volumes:
      - /mnt/10t/file/media:/var/lib/dav/data
      #- /home/compose/user.passwd:/user.passwd

3.关键配置说明 * 镜像：bytemark/webdav 是一个流行且维护良好的 WebDAV 服务器 Docker 镜像。 * 数据持久化：volumes 部分将容器内的 /var/lib/dav/data 目录（WebDAV 的默认共享根目录）挂载到宿主机的指定路径，确保数据在容器重启后不会丢失。 * 认证方式：AUTH_TYPE 支持 Digest（摘要认证，更安全）和 Basic（基本认证，传输明文密码，安全性较低）。某些客户端（如用户提到的 Kopia）可能需要特定的认证方式，请根据客户端要求进行选择。强烈建议在生产环境中使用强密码并考虑启用 HTTPS。 * 用户与权限：PUID 和 PGID 用于指定容器内进程运行的用户和组ID，这会影响容器在宿主机上创建文件的属主。确保它们与宿主机上挂载目录的权限相匹配，以避免权限问题。如果遇到文件无法删除的问题，可能需要检查并调整挂载目录的权限，或者确保 PUID/PGID 有足够权限。

🚀 启动与验证

1.启动服务 在 docker-compose.yml 文件所在目录下，执行以下命令来后台启动所有服务：

    docker-compose up -d

2.检查服务状态 使用以下命令查看容器是否正常运行：

    docker-compose ps

如果所有服务的 State 栏均显示为 Up，则表明容器已成功启动。

3.查看日志 如果某个服务启动异常，可以通过日志来排查问题：

    docker-compose logs webdav1  # 查看特定服务日志
    docker-compose logs          # 查看所有服务日志

4.验证服务 您可以通过以下几种方式验证 WebDAV 服务是否正常工作： * 浏览器访问：在浏览器中输入 http://你的服务器IP:81（或其他映射端口），如果看到 WebDAV 目录列表（可能需要浏览器支持 WebDAV）或认证对话框，说明服务已运行。 * 命令行测试：使用 curl 命令进行测试：

        curl -X PROPFIND http://你的服务器IP:81 -u "user:aaaaa"

* 客户端连接：使用 WebDAV 客户端（如下文所述）尝试连接。

（2）验证 WebDAV 服务可用性（3 种方法）

方法 1：curl 命令测试（适合服务器端快速验证）

# 测试实例1（端口81，替换用户名/密码为实际配置）
curl -u user:你的密码 http://localhost:81
# 预期输出：<html><head><title>WebDAV Directory Listing</title>...</head></html>（目录列表页面）

方法 2：浏览器访问（直观验证）

1. 打开浏览器，输入 http://服务器IP:81（如局域网 http://192.168.1.100:81）；
2. 弹出认证窗口，输入配置的 USERNAME 和 PASSWORD；
3. 登录后显示目录列表（为空，因未上传文件），说明服务正常；
4. 重复测试 http://服务器IP:82 和 http://服务器IP:83，确认三个实例均可用。

方法 3：Windows 映射网络驱动器（实用场景）

1. 打开 “此电脑”→ 右键 “映射网络驱动器”；
2. “文件夹” 输入 http://服务器IP:81，勾选 “使用其他凭据连接”；
3. 输入 USERNAME 和 PASSWORD，点击 “确定”；
4. 成功映射后，“此电脑” 会新增一个 “网络驱动器”，双击可像本地文件夹一样上传 / 下载文件。

---

🔧 基础配置与使用

1. 连接 WebDAV 服务器

   • Windows 系统：可以使用 RaiDrive 这款工具。安装后，添加一个 WebDAV 驱动器，填写服务器地址、端口、用户名和密码即可挂载为网络驱动器。
   • Linux 系统：大多数文件管理器（如 Nautilus、Dolphin）支持通过 "添加网络位置" 或类似功能连接 WebDAV 服务器。
   • Android 移动端：可以使用 ES 文件浏览器、FE文件管理器 等 APP 添加 WebDAV 存储位置。

2. 认证类型选择

   • 您的配置中使用了 AUTH_TYPE: Digest。如果某些客户端（如用户注释中提到的 Kopia）要求使用 Basic 认证，您需要将配置中的 AUTH_TYPE 改为 Basic。请注意，Basic 认证在网络传输中是明文的，如果使用 Basic 认证，强烈建议通过 HTTPS（例如使用 Nginx 反向代理并配置 SSL 证书）来保障安全。

3. 多实例管理

   • 您的配置部署了三个 WebDAV 实例。它们可以分别用于不同的目的（例如，为不同用户、不同项目或不同应用程序提供隔离的文件共享空间）。管理时，记得通过不同的端口（81, 82, 83）来访问和操作它们。

---

🔧 基础配置与使用2

WebDAV 核心使用场景是 “跨设备文件访问”，以下介绍主流系统的连接方法与基础管理操作：

1. 各系统客户端连接方法

（1）Windows 系统

• 映射网络驱动器：参考上文 “验证方法 3”，适合长期使用；
• 临时访问：打开 “文件资源管理器”→ 地址栏输入 http://服务器IP:81，输入账号密码即可。

（2）macOS 系统

1. 打开 “访达”→ 顶部菜单 “前往”→“连接服务器”；
2. 输入 http://服务器IP:81，点击 “连接”；
3. 选择 “注册用户”，输入 USERNAME 和 PASSWORD，点击 “连接”；
4. 成功后，访达左侧 “位置” 会显示 WebDAV 目录，可直接拖拽文件操作。

（3）Linux 系统

• 命令行访问：使用 davfs2 工具挂载（需先安装：sudo apt install davfs2）：

    # 创建挂载点
    mkdir -p ~/webdav1
    # 挂载 WebDAV 实例1
    sudo mount -t davfs http://服务器IP:81 ~/webdav1
    # 输入账号密码，挂载后可通过 ~/webdav1 访问

• 图形化访问：文件管理器地址栏输入 dav://服务器IP:81，输入账号密码即可。

（4）手机端（Android/iOS）

• Android：使用 “ES 文件浏览器”→ 点击 “网络”→“WebDAV”→ 输入服务器地址、端口、账号密码；
• iOS：使用 “文件” APP→ 右上角 “...”→“连接服务器”→ 输入 http://服务器IP:81 和账号密码。

2. 基础文件管理操作

• 上传文件：直接将本地文件拖拽到 WebDAV 目录（或右键 “复制”→“粘贴”）；
• 下载文件：右键点击 WebDAV 中的文件，选择 “复制到” 本地目录；
• 创建文件夹：右键空白处→“新建”→“文件夹”，命名后可分类存储文件；
• 删除文件：右键文件→“删除”，会直接删除服务器上的文件（建议提前备份重要文件）。

3. 修改实例配置（如账号密码）

若需修改某实例的用户名 / 密码，步骤如下：

1.编辑 docker-compose.yml，找到对应实例（如 webdav1），修改 USERNAME 或 PASSWORD； 2.重启该实例（无需停止其他实例）：

# 重启 webdav1 实例（修改后生效）
docker compose restart webdav1

3.重新连接客户端时，需更新账号密码（如 Windows 映射需先断开再重新连接）。

---

🔄 维护与管理

1.更新服务 当有新的 bytemark/webdav 镜像发布时，可以按以下步骤更新：

    # 进入 docker-compose.yml 所在目录
    cd /path/to/your/webdav
    # 拉取最新的镜像
    docker-compose pull
    # 重新创建并启动容器
    docker-compose up -d
    # 清理无用的旧镜像
    docker image prune

2.数据备份 * WebDAV 的所有数据都保存在您挂载的宿主机目录（例如 /mnt/10t/file/webdav/1 等）下。 * 定期备份这些目录即可备份所有共享文件。

3.服务卸载 如需停止并移除所有 WebDAV 容器，在项目目录下执行：

    docker-compose down

如果希望彻底删除所有数据（包括共享的文件），在上述命令后手动删除宿主机上挂载的目录即可。

🐛 常见问题排查

问题现象	可能原因与解决方案
容器启动失败	1. 检查 docker-compose.yml 文件语法是否正确（如缩进、冒号后空格）。 2. 执行 docker-compose logs <服务名> 查看具体错误日志。
无法连接 WebDAV 服务器	1. 确认服务器防火墙/安全组是否开放了所使用的端口（81, 82, 83）。 2. 检查 docker-compose ps 确认对应容器状态是否为 Up。
认证失败	1. 确认用户名和密码与配置中设置的完全一致，注意大小写。 2. 检查 AUTH_TYPE（Digest/Basic）是否与客户端支持的类型匹配。某些客户端可能只支持其中一种。
可以列出文件但无法上传/删除/修改	1. 这是常见的权限问题。检查宿主机上挂载目录的权限，确保 Docker 容器内的进程（由 PUID/PGID 指定）有读写权限。 2. 可以尝试进入容器内部，手动检查并修改 /var/lib/dav/data 目录的权限： docker-compose exec webdav1 bash chown -R www-data:www-data /var/lib/dav/data （注意：镜像内部的实际用户可能并非 www-data，此命令仅供参考，更推荐确保宿主机目录权限正确）。
部分客户端连接不正常	1. 某些客户端可能对 WebDAV 协议的支持有特殊性。尝试更换其他客户端进行测试。 2. 如果使用 HTTPS，请确保证书有效且客户端信任该证书。

希望这篇教程能帮助你顺利搭建并管理你的 WebDAV 文件共享服务！如果在部署和使用过程中遇到更多问题，Docker 和 WebDAV 相关的社区论坛是寻求帮助的好去处。

---

🐛 常见问题排查2

1. 连接失败（提示 “无法访问此网站”）

• 原因 1：服务器端口未开放或实例未启动。解决：

  1. 检查实例状态：docker compose ps，确保对应实例 State 为 Up；
  2. 检查端口开放：sudo ufw status，确认 81/82/83 端口已允许。

  3. 原因 2：服务器 IP 错误或网络不通。解决：

  4. 验证服务器 IP 可达：ping 服务器IP（手机端需在同一局域网或服务器有公网 IP）；

  5. 公网访问需确认服务器有公网 IP 且端口已映射（云服务器无需额外配置，家庭宽带需端口转发）。

2. 认证失败（提示 “用户名或密码错误”）

• 原因 1：输入的账号密码与配置不一致。解决：

  1. 核对 docker-compose.yml 中对应实例的 USERNAME 和 PASSWORD；
  2. 注意区分大小写（如 User 与 user 不同），密码避免空格或特殊字符（如 !@# 需确认客户端是否支持）。
  3. 原因 2：AUTH_TYPE 不兼容（如客户端不支持 Digest 认证）。解决：临时将对应实例的 AUTH_TYPE 改为 Basic（仅测试用，测试后改回 Digest），重启实例后重试。

3. 无法上传 / 删除文件（提示 “权限不足”）

• 原因 1：本地存储目录权限与 PUID/PGID 不匹配。解决：

  1. 查看当前用户 PUID：id -u（如输出 1001）；
  2. 修改 docker-compose.yml 中对应实例的 PUID 和 PGID 为 1001；
  3. 重新设置目录权限：sudo chown -R 1001:1001 /mnt/10t/file/webdav/1，重启实例。
  4. 原因 2：文件大小超过限制（默认无限制，若有反向代理需检查代理配置）。解决：若使用 Nginx 反向代理 WebDAV，需在 Nginx 配置中添加 client_max_body_size 10G;（允许 10GB 大文件上传）。

4. 连接后频繁断开（稳定性问题）

• 原因 1：网络不稳定（如 Wi-Fi 信号弱、公网延迟高）。解决：

  1. 局域网优先：尽量在同一局域网使用，避免跨网络高延迟；
  2. 有线网络：服务器与客户端优先使用网线连接，减少无线波动。
  3. 原因 2：容器内存不足（极端情况）。解决：检查服务器内存使用：free -m，若内存不足（剩余 < 100MB），需关闭其他无用服务或升级服务器内存。

通过以上步骤，新手可成功部署 WebDAV 多实例并实现跨设备文件管理。WebDAV 适合个人家庭 “文件共享中心” 或小型团队 “轻量文件服务器”，后续可结合 Nginx 反向代理添加 HTTPS 加密（提升安全性），具体可参考 WebDAV 官方文档 或 Nginx 反向代理教程。