wiserain/rclone

docker-rclone

镜像概述和主要用途

docker-rclone是一个用于https://rclone.org/%E6%8C%82%E8%BD%BD%E7%9A%84Docker%E9%95%9C%E5%83%8F%EF%BC%8C%E5%9F%BA%E4%BA%8EUbuntu 24.04系统构建。该镜像提供远程存储挂载功能，支持mergerfs或unionfs文件系统池化，并包含实用脚本，方便用户将远程存储与本地目录合并管理，适用于文件同步、媒体存储等场景。

核心功能和特性

• rclone挂载支持：通过rclone将远程存储挂载到本地，支持自定义挂载参数
• 文件系统池化：可选mergerfs或unionfs，实现远程存储与本地目录的合并访问
• 辅助脚本：提供copy_local和move_local脚本，方便本地与远程目录间的文件同步
• rclone serve功能：支持通过HTTP、FTP等多种方式共享挂载的文件系统
• 灵活配置：通过环境变量自定义UID/GID、时区、日志级别等参数

使用场景和适用范围

• 需要将远程存储（如S3、Google Drive等）挂载到本地并与本地目录合并管理的场景
• 媒体服务器（如Plex、Emby）的媒体文件存储与访问
• 本地与云端文件的统一访问和同步
• 需要定期将本地文件同步到远程存储的自动化场景

使用方法和配置说明

基本用法

Docker Compose配置

yaml
version: '3'

services:
  rclone:
    container_name: rclone
    image: docker.xuanyuan.run/wiserain/rclone                      # 或 ghcr.io/wiserain/rclone
    restart: always
    network_mode: "bridge"
    volumes:
      - ${DOCKER_ROOT}/rclone/config:/config     # rclone配置文件目录
      - ${DOCKER_ROOT}/rclone/log:/log           # 日志目录
      - ${DOCKER_ROOT}/rclone/cache:/cache       # 缓存目录
      - /your/mounting/point:/data:shared        # 挂载点（本地路径）
      - /local/dir/to/be/merged/with:/local     # 可选：需与远程存储合并的本地目录
    devices:
      - /dev/fuse                                # 必要设备
    cap_add:
      - SYS_ADMIN                                # 必要权限
    security_opt:
      - apparmor:unconfined                      # 安全选项
    environment:
      - PUID=${PUID}                             # 用户ID
      - PGID=${PGID}                             # 用户组ID
      - TZ=Asia/Seoul                            # 时区
      - RCLONE_REMOTE_PATH=remote_name:path/to/mount  # rclone远程路径（需在配置文件中定义）

Docker Run命令

等效的Docker命令：

bash
docker run -d \
    --name=rclone \
    --cap-add SYS_ADMIN \
    --device /dev/fuse \
    --security-opt apparmor=unconfined \
    -v ${DOCKER_ROOT}/rclone/config:/config \
    -v ${DOCKER_ROOT}/rclone/log:/log \
    -v ${DOCKER_ROOT}/rclone/cache:/cache \
    -v /your/mounting/point:/data:shared \
    -v /local/dir/to/be/merged/with:/local \
    -e PUID=${PUID} \
    -e PGID=${PGID} \
    -e TZ=Asia/Seoul \
    -e RCLONE_REMOTE_PATH=remote_name:path/to/mount \
    docker.xuanyuan.run/wiserain/rclone

初始化配置

使用前需准备rclone配置文件，可通过内置脚本生成：

bash
docker-compose exec <service_name> rclone_setup

配置文件需位于/config/rclone.conf。容器启动时会检查配置文件及RCLONE_REMOTE_PATH的有效性，日志可通过以下命令查看：

bash
docker logs <container name or sha1, e.g. rclone>

rclone mount 配置

内部挂载命令

容器内部执行的rclone挂载命令如下：

bash
rclone mount ${RCLONE_REMOTE_PATH} ${rclone_mountpoint} \
    --uid=${PUID:-911} \
    --gid=${PGID:-911} \
    --cache-dir=/cache \
    --use-mmap \
    --allow-other \
    --umask=002 \
    --rc \
    --rc-no-auth \
    --rc-addr=:5574 \
    ${RCLONE_MOUNT_USER_OPTS}

环境变量配置

rclone serve 配置

通过RCLONE_SERVE_MODE环境变量可启用rclone serve功能，将挂载的文件系统通过指定协议共享。

内部服务命令

bash
rclone serve ${RCLONE_SERVE_MODE} ${rclone_mountpoint} \
    ${RCLONE_SERVE_ARGS:---use-mmap --addr=:5678}

环境变量配置

mergerfs/unionfs 文件系统池化（可选）

通过POOLING_FS环境变量选择文件系统池化方式，可将远程存储与本地目录合并为单一访问点。

mergerfs 配置

设置POOLING_FS=mergerfs启用mergerfs，内部执行命令：

bash
mergerfs \
    -o uid=${PUID:-911},gid=${PGID:-911},umask=022,allow_other \
    -o ${MFS_USER_OPTS} \
    /local=RW:/cloud=NC /data

默认MFS_USER_OPTS参数：

bash
MFS_USER_OPTS="rw,use_ino,func.getattr=newest,category.action=all,category.create=ff,cache.files=auto-full,dropcacheonclose=true"

unionfs 配置

设置POOLING_FS=unionfs启用unionfs，内部执行命令：

bash
unionfs \
    -o uid=${PUID:-911},gid=${PGID:-911},umask=022,allow_other \
    -o ${UFS_USER_OPTS} \
    /local=RW:/cloud=RO /data

默认UFS_USER_OPTS参数：

bash
UFS_USER_OPTS="cow,direct_io,nonempty,auto_cache,sync_read"

内置脚本

提供copy_local和move_local脚本，用于本地与远程目录间的文件同步（需挂载/local目录）。

copy_local

将/local目录文件复制到/cloud（远程存储）：

bash
docker exec -it <container name or sha1, e.g. rclone> copy_local

排除机制：在需排除的文件夹根目录创建空文件.nocopy，脚本将跳过该目录。

move_local

将/local目录文件移动到/cloud，包含三个阶段：

1. 移动超过MOVE_LOCAL_AFTER_DAYS天的文件
2. 移动超过MOVE_LOCAL_EXCEEDS_GB大小的文件（释放MOVE_LOCAL_FREEUP_GB空间）
3. 若MOVE_LOCAL_ALL=true，移动剩余文件

移动完成后自动清理空目录（KEEP_EMPTY_DIRS=1可保留空目录）：

bash
docker exec -it <container name or sha1, e.g. rclone> move_local

排除机制：在需排除的文件夹根目录创建空文件.nomove，脚本将跳过该目录。

定时任务（默认禁用）

通过环境变量配置脚本定时执行：

参考来源

• https://github.com/madslundt/docker-cloud-media-scripts