dfs-sync 1.0.11

文件传输工具

DFS — 分布式文件同步工具

基于 SFTP 的高性能并发文件上传/下载 CLI，支持 .gitignore 过滤、并发传输与快捷方式。

---

目录

• 安装与部署
• 快速开始
• 配置文件
• 文件过滤
• 完整参数列表
  • 通用
  • 主要操作
  • 配置管理
  • 连接选项
  • 传输选项
  • 过滤选项
  • 日志选项
• 环境变量
• 快捷方式
• 连接优先级

---

安装与部署

要求： Python ≥ 3.8

# PyPI 安装
pip install dfs-sync

# 源码安装
git clone <repo-url> && cd dfs-sync
pip install -e .

# 开发依赖
pip install -e ".[dev]"

首次运行会自动生成配置文件 ~/.dfs.yaml。验证安装：

dfs -V
dfs --help

---

快速开始

# 配置服务器（或使用 user@host 位置参数覆盖）
dfs --config-set server.host 10.0.0.1
dfs --config-set server.username root
dfs --config-set server.private_key ~/.ssh/id_rsa

# 测试连接
dfs root@10.0.0.1 --check

# 上传目录
dfs root@10.0.0.1 -u ./src /backup/src

# 下载目录
dfs root@10.0.0.1 -d /backup/src ./src

---

配置文件

默认路径：~/.dfs.yaml。可通过 --config 指定其他路径。

server:
  host: '10.0.0.1'
  port: 22
  username: 'root'
  private_key: '~/.ssh/id_rsa'   # 推荐
  password: ''                   # 或用环境变量 DFS_PASSWORD

transfer:
  concurrent_connections: 4
  skip_file_check: true          # true=直接覆盖；false=相同文件跳过

shortcuts:
  backup:
    action: upload
    local: ./src
    remote: /backup/src

---

文件过滤

默认尊重 Git 生态规则（基于 pathspec）：

模式	说明
默认	.gitignore + --exclude / --include
--no-gitignore	忽略 .gitignore，仅 --exclude / --include
--no-filter	关闭全部过滤，完整同步

优先级	来源（默认 / --no-gitignore 时跳过 git 规则）
低	Git 全局 excludes → .git/info/exclude → 目录树 .gitignore
中	--exclude
高	--include

• 无 .gitignore 时同步全部文件（含隐藏文件）
• --no-gitignore 适合「不用 git 规则、但要用 CLI 排除大目录」
• --no-filter 与 --no-gitignore 不能同时使用
• -n / --dry-run 仅预览，不实际传输

dfs -u ./proj /proj --no-gitignore \
  --exclude 'node_modules/' \
  --exclude '.git/' \
  --include 'sycm/'

---

完整参数列表

命令格式：dfs [[user@]host[:port]] [选项]

-u、-d、--shortcut 互斥，每次只能选一个主要操作。

通用

参数	说明	示例
[user@]host[:port]	服务器连接字符串（优先级最高）	dfs root@10.0.0.1 -u ./a.txt /tmp/a.txt
	仅主机	dfs 10.0.0.1 --check
	指定端口	dfs admin@10.0.0.2:2222 -d /data ./data
-h, --help	显示帮助	dfs --help
-V, --version	显示版本	dfs -V

主要操作

参数	说明	示例
-u, --upload LOCAL REMOTE	上传文件或目录	dfs -u ./app.tar.gz /tmp/app.tar.gz
	上传目录	dfs root@10.0.0.1 -u ./src /var/www/src
-d, --download REMOTE LOCAL	下载文件或目录	dfs -d /etc/nginx/nginx.conf ./nginx.conf
	下载目录	dfs root@10.0.0.1 -d /var/log/app ./logs
--shortcut NAME	执行配置文件中的快捷方式	dfs --shortcut backup
	指定服务器执行	dfs root@10.0.0.1 --shortcut backup

配置管理

参数	说明	示例
--config PATH	指定配置文件路径	dfs --config ./dfs.prod.yaml --show-config
--show-config	显示当前配置	dfs --show-config
--config-set KEY VALUE	设置配置项并保存	dfs --config-set server.host 10.0.0.1
	设置端口	dfs --config-set server.port 2222
	设置私钥	dfs --config-set server.private_key ~/.ssh/id_rsa
	设置并发数	dfs --config-set transfer.concurrent_connections 8
--config-get KEY	读取配置项	dfs --config-get server.host
--config-reset	重置为默认配置	dfs --config-reset

连接选项

参数	说明	示例
-H, --host HOST	服务器地址	dfs -H 10.0.0.1 --check
-P, --port PORT	SFTP 端口（scp 风格，大写 P）	dfs -P 2222 -H 10.0.0.1 --check
-l, --login-name USER	登录用户名（ssh -l 风格）	dfs -l deploy -H 10.0.0.1 -u ./dist /www/dist
--password PASS	密码（不推荐，会进 shell 历史）	dfs --password 'secret' -H 10.0.0.1 --check
--password-stdin	从标准输入读取密码	echo 'secret' | dfs --password-stdin -H 10.0.0.1 --check
-i, --identity-file PATH	SSH 私钥路径（ssh -i 风格）	dfs -i ~/.ssh/id_ed25519 root@10.0.0.1 --check
--check	测试服务器连接	dfs root@10.0.0.1 --check

传输选项

参数	说明	示例
-j, --jobs N	并发连接数（1–16，make -j 风格）	dfs -u ./big ./big -j 8
--chunk-size BYTES	传输块大小（字节）	dfs -u ./file.bin /tmp/file.bin --chunk-size 65536
--no-verify	跳过传输后完整性校验	dfs -u ./src /src --no-verify
--retries N	失败重试次数	dfs -u ./src /src --retries 5

过滤选项

参数	说明	示例
--exclude PATTERN	排除文件（rsync 风格，可重复）	dfs -u ./proj /proj --exclude '*.log'
	多条排除	dfs -u ./proj /proj --exclude 'node_modules/' --exclude '.cache/'
--include PATTERN	强制包含（优先级高于 exclude 和 gitignore）	dfs -u ./data /data --include 'sycm/'
--no-gitignore	忽略 .gitignore，仅用 CLI 过滤	dfs -u ./proj /proj --no-gitignore --exclude 'node_modules/' --exclude '.git/' --include 'sycm/'
--no-filter	完整同步，忽略全部过滤规则（含 CLI）	dfs -u ./proj /proj --no-filter
-n, --dry-run	预览待传输文件，不实际上传/下载	dfs -u ./src /src -n
	预览完整同步	dfs -u ./proj /proj --no-filter -n

日志选项

参数	说明	示例
--log-level LEVEL	日志级别：debug info warning error critical	dfs -u ./src /src --log-level debug
--log-file PATH	日志写入文件	dfs -u ./src /src --log-file ~/dfs.log
-q, --quiet	静默模式，仅显示错误	dfs -q -u ./src /src
-v, --verbose	详细模式，等同 --log-level debug	dfs -v -u ./src /src

---

环境变量

变量	说明	示例
DFS_PASSWORD	SFTP 登录密码（优于 --password）	DFS_PASSWORD=secret dfs root@10.0.0.1 -u ./src /src

---

快捷方式

在 ~/.dfs.yaml 的 shortcuts 节定义：

shortcuts:
  logs:
    action: download
    remote: /var/log/myapp
    local: ~/downloads/myapp-logs
  deploy:
    action: upload
    local: ./dist
    remote: /var/www/html

dfs --shortcut logs
dfs root@10.0.0.1 --shortcut deploy

---

连接优先级

认证与连接信息按以下顺序覆盖（高 → 低）：

1. 位置参数 [user@]host[:port]
2. 环境变量 DFS_PASSWORD
3. --password-stdin
4. --password
5. 命令行 -H / -P / -l / -i
6. 配置文件 ~/.dfs.yaml

密码和私钥均未配置时，会交互式提示输入密码。