tickstep/aliyunpan-sync

阿里云盘同步备份工具

镜像概述和主要用途

本镜像提供阿里云盘同步备份功能，支持两种备份方向：备份本地文件到云盘（上传模式）和备份云盘文件到本地（下载模式）。具备灵活的备份策略，可满足不同场景的文件备份需求，尤其适用于NAS等系统，用于定期备份照片、文档等重要文件。

核心功能和特性

备份模式

• 上传模式（upload）：将本地文件备份到阿里云盘，保持本地文件在云盘有完整备份
• 下载模式（download）：将阿里云盘文件备份到本地，保持云盘文件在本地有完整备份

备份策略

• 排他备份（exclusive）：目标目录与源目录文件严格一致，源目录文件删除时目标目录对应文件也删除，确保一比一备份
• 增量备份（increment）：仅备份源目录新增或修改的文件，目标目录多余文件不删除，源目录文件删除不影响目标目录

其他特性

• 支持JavaScript插件对备份文件进行过滤，可自定义文件包含/排除规则
• 支持配置备份周期（永久循环/仅运行一次）、并发数、数据块大小等参数

使用场景和适用范围

• NAS系统文件备份：定期将NAS中的照片、视频等媒体文件备份到阿里云盘
• 本地数据灾备：将本地重要文档通过增量备份保存到云盘，防止数据丢失
• 云盘文件本地化：将阿里云盘中的文件下载到本地存储，实现数据多副本保存

详细使用方法和配置说明

准备工作：获取aliyunpan_config.json配置文件

登录凭据文件aliyunpan_config.json需通过官方工具获取，步骤如下：

1. 参考https://github.com/tickstep/aliyunpan/blob/main/docs/manual.md#%E7%99%BB%E5%BD%95%E9%98%BF%E9%87%8C%E4%BA%91%E7%9B%98%E5%B8%90%E5%8F%B7%E4%B8%8B%E8%BD%BD%E5%AF%B9%E5%BA%94%E7%B3%BB%E7%BB%9F%E7%9A%84%E7%A8%8B%E5%BA%8F
2. 运行程序并执行login命令登录阿里云盘账号
3. 登录成功后，程序会生成aliyunpan_config.json文件，将其用于Docker配置

直接运行

bash
docker run -d --name=aliyunpan-sync --restart=always \
  -v "<your aliyunpan_config.json>:/home/app/config/aliyunpan_config.json" \
  -v "<your local dir>:/home/app/data" \
  -e ALIYUNPAN_PAN_DIR="<your drive pan dir>" \
  -e ALIYUNPAN_SYNC_MODE="upload" \
  -e ALIYUNPAN_SYNC_POLICY="increment" \
  -e ALIYUNPAN_SYNC_DRIVE="backup" \
  -e ALIYUNPAN_SYNC_LOG="true" \
  tickstep/aliyunpan-sync:<tag>

参数说明：

• <your aliyunpan_config.json>：本地登录凭据文件绝对路径
• <your local dir>：本地备份目录绝对路径（如/tickstep/Documents/设计文档）
• ALIYUNPAN_PAN_DIR：阿里云盘目标目录绝对路径
• ALIYUNPAN_SYNC_MODE：备份模式，取值upload（本地到云盘）或download（云盘到本地）
• ALIYUNPAN_SYNC_POLICY：备份策略，取值exclusive（排他备份）或increment（增量备份）
• ALIYUNPAN_SYNC_DRIVE：网盘类型，取值backup（备份盘）或resource（资源盘）
• ALIYUNPAN_SYNC_LOG：是否开启同步日志，true开启，false关闭
• <tag>：镜像版本标签

docker-compose运行

创建docker-compose.yml文件如下（注释可删除后部署）：

yaml
version: '3'
services:
  sync:
    image: tickstep/aliyunpan-sync:<tag>
    container_name: aliyunpan-sync
    restart: always
    volumes:
      # 必须：映射本地备份目录
      - ./data:/home/app/data:rw
      # 可选：JS插件文件，用于文件过滤（详见插件说明）
      #- ./plugin/js/sync_handler.js:/home/app/config/plugin/js/sync_handler.js
      # 推荐：映射同步数据库目录，容器销毁后数据不丢失
      #- ./sync_drive:/home/app/config/sync_drive
      # 必须：映射登录凭据文件
      - /your/file/path/for/aliyunpan_config.json:/home/app/config/aliyunpan_config.json
    environment:
      # 时区设置（东8区）
      - TZ=Asia/Shanghai
      # 下载并发数
      - ALIYUNPAN_DOWNLOAD_PARALLEL=2
      # 上传并发数
      - ALIYUNPAN_UPLOAD_PARALLEL=2
      # 下载数据块大小（KB，1024~10240，默认10240）
      - ALIYUNPAN_DOWNLOAD_BLOCK_SIZE=1024
      # 上传数据块大小（KB，1024~10240，默认10240）
      - ALIYUNPAN_UPLOAD_BLOCK_SIZE=10240
      # 云盘目标目录（绝对路径，不要使用根目录）
      - ALIYUNPAN_PAN_DIR=/my_sync_dir
      # 备份模式：upload（本地到云盘）/download（云盘到本地）
      - ALIYUNPAN_SYNC_MODE=upload
      # 备份策略：exclusive（排他）/increment（增量）
      - ALIYUNPAN_SYNC_POLICY=increment
      # 备份周期：infinity（永久循环）/onetime（仅运行一次）
      - ALIYUNPAN_SYNC_CYCLE=infinity
      # 网盘类型：backup（备份盘）/resource（资源盘）
      - ALIYUNPAN_SYNC_DRIVE=backup
      # 是否显示备份过程日志：true/false
      - ALIYUNPAN_SYNC_LOG=true
      # 本地文件修改检测延迟（秒），避免上传未完成修改的文件（如视频录制）
      - ALIYUNPAN_LOCAL_DELAY_TIME=3

sync_handler.js插件说明

通过JavaScript插件可自定义文件过滤规则，控制哪些文件参与备份。插件需实现以下回调函数，映射到容器内/home/app/config/plugin/js/sync_handler.js路径。

插件示例代码

javascript
// ==========================================================================================
// 阿里云盘同步备份JS插件回调函数
// 支持 JavaScript ECMAScript 5.1 规范
// 更多文档：https://github.com/tickstep/aliyunpan
// ==========================================================================================

// ------------------------------------------------------------------------------------------
// 同步备份-扫描本地文件前回调函数
// 参数：
// context - 上下文信息，包含appName、version、userId等用户及应用信息
// params - 本地文件信息，包含localFilePath（路径）、localFileName（名称）、localFileSize（大小）等
// 返回：{"syncScanLocalApproved": "yes"/"no"}，控制文件是否允许扫描（参与备份）
// ------------------------------------------------------------------------------------------
function syncScanLocalFilePrepareCallback(context, params) {
    console.log(params);
    var result = {"syncScanLocalApproved": "yes"};

    // 禁止隐藏文件（.开头）上传
    if (params["localFileName"].indexOf(".") == 0) {
        result["syncScanLocalApproved"] = "no";
    }

    // 禁止Office临时文件（~$开头）上传
    if (params["localFileName"].indexOf("~$") == 0) {
        result["syncScanLocalApproved"] = "no";
    }

    // 禁止.txt文件上传（正则匹配）
    if (params["localFileName"].search(/.txt$/i) >= 0) {
        result["syncScanLocalApproved"] = "no";
    }

    return result;
}

// ------------------------------------------------------------------------------------------
// 同步备份-扫描云盘文件前回调函数
// 参数：
// context - 上下文信息，同本地文件回调
// params - 云盘文件信息，包含driveFilePath（路径）、driveFileName（名称）、driveFileSize（大小）等
// 返回：{"syncScanPanApproved": "yes"/"no"}，控制文件是否允许扫描（参与备份）
// ------------------------------------------------------------------------------------------
function syncScanPanFilePrepareCallback(context, params) {
    console.log(params);
    var result = {"syncScanPanApproved": "yes"};

    // 禁止隐藏文件（.开头）下载
    if (params["driveFileName"].indexOf(".") == 0) {
        result["syncScanPanApproved"] = "no";
    }

    // 禁止Office临时文件（~$开头）下载
    if (params["driveFileName"].indexOf("~$") == 0) {
        result["syncScanPanApproved"] = "no";
    }

    return result;
}

配置文件获取

登录凭据文件aliyunpan_config.json的获取方法详见https://github.com/tickstep/aliyunpan/blob/main/docs/manual.md#%E7%99%BB%E5%BD%95%E9%98%BF%E9%87%8C%E4%BA%91%E7%9B%98%E5%B8%90%E5%8F%B7%E3%80%82%E9%9C%80%E5%85%88%E4%B8%8B%E8%BD%BD%E5%AF%B9%E5%BA%94%E7%B3%BB%E7%BB%9F%E7%9A%84%E7%A8%8B%E5%BA%8F%EF%BC%8C%E6%9C%AC%E5%9C%B0%E8%BF%90%E8%A1%8C%E5%90%8E%E6%89%A7%E8%A1%8C%60login%60%E5%91%BD%E4%BB%A4%E7%99%BB%E5%BD%95%E9%98%BF%E9%87%8C%E4%BA%91%E7%9B%98%EF%BC%8C%E7%99%BB%E5%BD%95%E6%88%90%E5%8A%9F%E5%90%8E%E8%87%AA%E5%8A%A8%E7%94%9F%E6%88%90%E8%AF%A5%E6%96%87%E4%BB%B6%EF%BC%8C%E6%8B%B7%E8%B4%9D%E8%87%B3Docker%E6%98%A0%E5%B0%84%E8%B7%AF%E5%BE%84%E5%8D%B3%E5%8F%AF%E4%BD%BF%E7%94%A8%E3%80%82

更多信息请参考GitHub主页：https://github.com/tickstep/aliyunpan