Metadata-Version: 2.4
Name: dfs-sync
Version: 1.0.10
Summary: 文件传输工具
Author-email: xigua <2587125111@qq.com>
License: MIT
Keywords: file transfer,sftp,sync,upload,download,concurrent,async,cli
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: File Transfer Protocol (FTP)
Classifier: Topic :: System :: Archiving
Classifier: Topic :: System :: Networking
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: paramiko<4.0.0,>=3.0.0
Requires-Dist: PyYAML<7.0,>=6.0
Requires-Dist: colorama<1.0.0,>=0.4.4
Requires-Dist: tqdm<5.0.0,>=4.64.0
Requires-Dist: rich<14.0.0,>=13.0.0
Requires-Dist: pathspec<1.0.0,>=0.12.0
Provides-Extra: dev
Requires-Dist: pytest<8.0.0,>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio<1.0.0,>=0.21.0; extra == "dev"
Requires-Dist: black<24.0.0,>=22.0.0; extra == "dev"
Requires-Dist: flake8<7.0.0,>=5.0.0; extra == "dev"
Requires-Dist: mypy<2.0.0,>=1.0.0; extra == "dev"
Dynamic: license-file

# DFS — 分布式文件同步工具

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

---

## 目录

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

---

## 安装与部署

**要求：** Python ≥ 3.8

```bash
# PyPI 安装
pip install dfs-sync

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

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

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

```bash
dfs -V
dfs --help
```

---

## 快速开始

```bash
# 配置服务器（或使用 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` 指定其他路径。

```yaml
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](https://github.com/cookiecutter/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` 仅预览，不实际传输

```bash
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` 节定义：

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

```bash
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`

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