ustcmirror/lftpsync

lftpsync 镜像文档

镜像概述

lftpsync镜像是一个基于lftp工具的轻量级文件同步解决方案，专为高效、灵活的跨服务器/协议文件镜像同步设计。该镜像集成lftp的核心功能，支持FTP、FTPS、HTTP、HTTPS、SFTP等多种文件传输协议，可实现断点续传、增量同步、定时任务等高级同步需求，广泛应用于开源软件镜像站点维护、服务器数据备份、跨环境文件分发等场景。

核心功能与特性

• 多协议支持：兼容FTP、FTPS、HTTP、HTTPS、SFTP等主流文件传输协议，适配不同源站和目标环境的网络架构。
• 高效同步机制：
  • 增量同步：仅同步新增/变更文件，减少带宽占用和同步耗时
  • 断点续传：支持中断后恢复传输，避免重复传输大文件
  • 并发控制：可配置并发连接数，平衡同步效率与服务器负载
• 灵活配置选项：支持通过命令行参数、环境变量或配置文件自定义同步行为，如排除指定文件/目录、设置同步深度、调整超时时间等。
• 定时任务集成：内置crontab服务，可配置周期性同步任务，满足定时备份、定期镜像更新等自动化需求。
• 轻量级设计：基于Alpine Linux构建，镜像体积小（<50MB），资源占用低，部署便捷。

使用场景

• 开源镜像站点维护：同步上游开源软件镜像（如Debian、Ubuntu、PyPI等）到本地服务器，搭建私有或公共镜像站点。
• 跨服务器数据同步：在分布式服务器架构中，同步配置文件、静态资源或业务数据，确保多节点数据一致性。
• 定期数据备份：定时将生产服务器数据同步到备份服务器或对象存储，实现数据容灾与恢复能力。
• 文件分发网络：将本地文件分发到多个边缘节点，适用于CDN节点更新、多区域部署等场景。

使用方法与配置说明

基本使用（单次同步）

通过docker run命令直接触发单次同步任务，需指定源地址（SRC）、目标地址（DST）及必要的同步参数。

基础示例（FTP协议同步到本地目录）

bash
docker run --rm \
  -e SRC="ftp://ftp.example.com/source" \  # 源地址（支持多种协议）
  -e DST="/data/mirror" \  # 容器内目标路径（需挂载宿主机目录）
  -v /path/to/local/dst:/data/mirror \  # 挂载宿主机目录作为同步目标
  ustclug/lftpsync:latest

高级示例（SFTP协议+增量同步+排除文件）

bash
docker run --rm \
  -e SRC="sftp://user@remote.server:/data/source" \  # SFTP源地址（格式：sftp://用户@主机:路径）
  -e DST="/data/mirror" \
  -e SYNC_OPTS="-n -X *.log -P 5" \  # 同步选项：-n（增量）、-X（排除.log文件）、-P（5个并发连接）
  -v /path/to/ssh-key:/root/.ssh/id_rsa:ro \  # SFTP协议需挂载SSH私钥（只读权限）
  -v /path/to/local/dst:/data/mirror \
  ustclug/lftpsync:latest

定时同步配置（周期性任务）

通过挂载crontab配置文件实现定时同步，配置格式遵循标准crontab语法，任务命令需调用内置的sync.sh脚本。

步骤1：创建crontab配置文件（如/host/crontab.txt）

crontab
# 每天凌晨2点执行同步（语法：分 时 日 月 周 命令）
0 2 * * * /sync.sh

步骤2：启动容器并挂载配置文件

bash
docker run -d \
  --name lftpsync-cron \
  -e SRC="http://mirror.ustc.edu.cn/ubuntu" \  # 上游Ubuntu镜像源
  -e DST="/data/ubuntu-mirror" \
  -e SYNC_OPTS="-c -n -L" \  # -c（断点续传）、-n（增量）、-L（跟随符号链接）
  -v /host/ubuntu-mirror:/data/ubuntu-mirror \  # 宿主机镜像存储目录
  -v /host/crontab.txt:/etc/crontabs/root:ro \  # 挂载crontab配置（root用户）
  ustclug/lftpsync:latest

docker-compose配置示例

yaml
version: '3'
services:
  lftpsync:
    image: ustclug/lftpsync:latest
    container_name: lftpsync
    restart: always
    environment:
      - SRC="https://upstream.example.com/packages"  # HTTPS源地址
      - DST="/data/mirror"
      - SYNC_OPTS="-n -X .git -t 300"  # 排除.git目录，超时300秒
      - CRON_ENABLE="true"  # 启用定时任务（默认true，单次同步设为false）
    volumes:
      - /local/mirror:/data/mirror  # 本地存储目录
      - ./crontab.txt:/etc/crontabs/root:ro  # 定时任务配置
      # SFTP协议需额外挂载SSH密钥（如使用SFTP源）
      # - ./ssh_key:/root/.ssh/id_rsa:ro

核心配置参数说明

环境变量配置

常用lftp mirror选项（SYNC_OPTS）

高级配置：自定义lftp全局设置

如需调整lftp全局配置（如代理、被动模式、重试次数等），可通过挂载/etc/lftp.conf文件实现。示例配置文件（custom-lftp.conf）：

conf
# 启用被动模式（FTP默认推荐）
set ftp:passive-mode yes
# 设置网络超时时间（秒）
set net:timeout 300
# 设置最大重试次数
set net:max-retries 3
# 配置HTTP代理（如需通过代理访问源站）
set proxy http://proxy.example.com:8080

挂载配置文件启动容器：

bash
docker run --rm \
  -v /path/to/custom-lftp.conf:/etc/lftp.conf:ro \  # 自定义lftp配置
  -e SRC="[***]" \
  -e DST="/data/mirror" \
  -v /path/to/local/dst:/data/mirror \
  ***/lftpsync:latest