# rsync_shell_with_config

**Repository Path**: blowhunter/rsync_shell_with_config

## Basic Information

- **Project Name**: rsync_shell_with_config
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-25
- **Last Updated**: 2025-11-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# rsync 文件同步脚本

一个功能强大的文件同步脚本，支持通过rsync和scp将文件从本地上传到远程服务器，具有完整的文件属性保持、智能回退和灵活的配置选项。

## 🚀 特性

- ✅ **多种同步模式** - 单文件、批量文件、目录同步
- ✅ **智能回退** - 远程无rsync时自动使用scp
- ✅ **完整属性保持** - 保持文件时间戳、权限、所有者、符号链接等
- ✅ **灵活配置** - 三种属性保持级别：full、standard、minimal
- ✅ **智能路径处理** - 正确处理不同用户的远程路径展开
- ✅ **文件排除** - 支持配置文件和命令行排除模式
- ✅ **预览模式** - --dry-run 预览操作而不执行
- ✅ **详细输出** - -v 选项显示详细执行信息

## 📦 安装

### 前置要求

- 本地系统：bash, rsync, scp, jq
- 远程服务器：ssh访问（推荐安装rsync以获得完整功能）

### 快速开始

1. **克隆或下载脚本文件**
   ```bash
   # 确保脚本可执行
   chmod +x sync.sh
   ```

2. **创建配置文件**
   ```bash
   cp settings.example.json settings.json
   ```

3. **配置远程连接**

   编辑 `settings.json` 文件：
   ```json
   {
     "remote_path": "~/backup",
     "private_key_path": "~/.ssh/id_rsa",
     "host": "your-server-ip",
     "port": 22,
     "username": "your-username"
   }
   ```

4. **测试连接**
   ```bash
   # 预览模式测试
   ./sync.sh -f /path/to/test-file.txt --dry-run -v

   # 实际上传
   ./sync.sh -f /path/to/test-file.txt
   ```

## ⚙️ 配置

### 配置文件说明

脚本使用JSON格式的配置文件 `settings.json`：

```json
{
  "remote_path": "~/backup",
  "private_key_path": "~/.ssh/id_rsa",
  "host": "your-server-ip",
  "port": 22,
  "username": "your-username",
  "local_path": "~/work/project",
  "max_file_size": 10485760,
  "exclude_patterns": [
    ".git/",
    "*.tmp",
    "*.log",
    ".DS_Store",
    "node_modules/"
  ],
  "preserve_attributes": "full",
  "preserve_permissions": true,
  "preserve_ownership": true,
  "preserve_timestamps": true,
  "preserve_links": true,
  "preserve_hardlinks": false
}
```

### 配置项说明

| 配置项 | 说明 | 示例 |
|--------|------|------|
| `host` | 远程服务器地址 | `"192.168.1.100"` |
| `username` | SSH登录用户名 | `"root"` 或 `"deploy"` |
| `private_key_path` | SSH私钥路径 | `"~/.ssh/id_rsa"` |
| `remote_path` | 远程目录路径 | `"~/backup"` |
| `port` | SSH端口 | `22` (默认) |
| `max_file_size` | 最大文件大小(字节) | `10485760` (10MB) |

### 文件属性保持配置

```json
{
  "preserve_attributes": "full",        // 属性级别: full|standard|minimal
  "preserve_permissions": true,         // 保持文件权限
  "preserve_ownership": true,           // 保持所有者和组 (需要root权限)
  "preserve_timestamps": true,          // 保持修改和访问时间
  "preserve_links": true,               // 保持符号链接
  "preserve_hardlinks": false           // 保持硬链接 (可能影响性能)
}
```

**属性保持级别：**

- **full** - 完整保持所有属性（推荐开发环境）
- **standard** - 标准保持（适合生产环境）
- **minimal** - 最小保持（适合简单同步）

## 🔧 使用方法

### 基本用法

```bash
# 上传单个文件
./sync.sh -f /path/to/file.txt

# 上传整个目录 (创建子目录)
./sync.sh -d /path/to/directory

# 同步当前目录到配置的远程路径
./sync.sh -d .

# 批量上传文件
./sync.sh -b file1.txt file2.txt file3.txt

# 使用自定义配置文件
./sync.sh -c custom.json -f /path/to/file.txt
```

### 高级选项

```bash
# 预览模式（不执行实际同步）
./sync.sh -d /path/to/dir --dry-run

# 详细输出模式
./sync.sh -f file.txt -v

# 添加额外的排除模式
./sync.sh -d /path/to/dir --exclude "*.bak" --exclude "node_modules/"

# 上传目录内容到远程根路径 (不创建子目录)
./sync.sh -D /path/to/directory

# 将当前目录内容同步到远程根路径
./sync.sh -D .

# 组合使用
./sync.sh -b file1.txt file2.txt --dry-run -v
```

### 目录同步行为

| 命令 | 行为 | 远程路径 | 说明 |
|------|------|----------|------|
| `./sync.sh -d .` | 当前目录同步 | `~/backup/` | 直接同步到配置路径 |
| `./sync.sh -d my_project` | 指定目录同步 | `~/backup/my_project/` | 创建子目录 |
| `./sync.sh -D .` | 当前目录内容同步 | `~/backup/` | 同步目录内容，不创建子目录 |
| `./sync.sh -D my_project` | 指定目录内容同步 | `~/backup/` | 同步目录内容，不创建子目录 |

**关键区别：**
- **`-d` (目录模式)**：保持目录结构
  - `.` → 直接同步到远程根路径
  - `dirname` → 创建远程子目录
- **`-D` (目录内容模式)**：只同步内容，不保持目录结构

### 远程路径展开规则

脚本会根据配置文件中的`username`参数按照标准Linux系统规则正确展开远程路径：

```json
{
  "username": "root",
  "remote_path": "~/test"
}
// 展开为: /root/test

{
  "username": "deploy",
  "remote_path": "~/app"
}
// 展开为: /home/deploy/app

{
  "username": "www-data",
  "remote_path": "/var/www/html"
}
// 保持: /var/www/html (绝对路径不变)
```

**路径展开规则：**
- **root用户**: `~/path` → `/root/path`
- **普通用户**: `~/path` → `/home/username/path`
- **绝对路径**: `/absolute/path` → `/absolute/path` (保持不变)

## 📚 常见使用场景

### 开发环境配置

```json
{
  "username": "deploy",
  "remote_path": "~/app",
  "exclude_patterns": [
    ".git/",
    "node_modules/",
    "*.log",
    ".env",
    "dist/"
  ],
  "preserve_attributes": "full"
}
```

### 网站部署配置

```json
{
  "username": "www-data",
  "remote_path": "/var/www/html",
  "exclude_patterns": [
    ".git/",
    "*.md",
    "src/",
    "package.json",
    "README.md"
  ],
  "preserve_attributes": "standard",
  "preserve_ownership": false
}
```

### 备份同步配置

```json
{
  "username": "backup",
  "remote_path": "~/backups",
  "preserve_attributes": "full",
  "preserve_hardlinks": true,
  "exclude_patterns": [
    "*.tmp",
    "*.log",
    ".cache/",
    "temp/"
  ]
}
```

## 🔒 安全注意事项

- 脚本会在远程无rsync时自动使用scp作为回退方案
- 使用scp时，文件属性保持功能受限，排除模式不会生效
- 建议在远程服务器安装rsync以获得完整功能和属性保持
- 配置文件中的路径支持波浪号(~)展开，使用配置的username而非本地用户
- 保持所有者信息(`preserve_ownership: true`)需要root权限
- 保持ACL和扩展属性需要文件系统支持
- 硬链接保持可能影响大目录的同步性能

### SSH安全

```bash
# 确保私钥权限正确
chmod 600 ~/.ssh/id_rsa

# 测试SSH连接
ssh -i ~/.ssh/id_rsa -p 22 username@server "echo 'connection ok'"

# 检查远程rsync
ssh username@server "which rsync"
```

## 🛠️ 故障排除

### 常见问题

1. **连接被拒绝**
   - 检查SSH服务是否运行：`ssh username@server`
   - 确认防火墙设置
   - 验证私钥路径和权限

2. **权限被拒绝**
   - 检查SSH密钥权限：`chmod 600 ~/.ssh/id_rsa`
   - 确认远程用户有写入权限
   - 验证私钥是否正确

3. **文件过大**
   - 调整`max_file_size`配置
   - 使用排除模式排除大文件

4. **目录不存在**
   - 脚本会自动创建远程目录
   - 检查远程用户权限

### 调试技巧

```bash
# 使用详细模式
./sync.sh -f file.txt -v

# 使用预览模式检查操作
./sync.sh -d /path/to/dir --dry-run

# 测试不同配置文件
./sync.sh -c test-config.json -f file.txt
```

## 📖 命令行选项

```
用法: ./sync.sh [选项] [文件或目录...]

选项:
    -h, --help              显示此帮助信息
    -c, --config FILE       指定配置文件路径 (默认: settings.json)
    -f, --file FILE         上传单个文件
    -d, --dir DIR           上传整个目录 (创建子目录)
    -D, --dir-to-root DIR   上传目录内容到远程根路径 (不创建子目录)
    -b, --batch FILES       批量上传文件，多个文件用空格分隔
    --dry-run              显示将要同步的文件但不执行实际同步
    --exclude PATTERN       添加排除模式 (可重复使用)
    --include PATTERN       添加包含模式 (可重复使用)
    -v, --verbose          详细输出模式
```

## 📄 文件保持的属性说明

| 属性 | 说明 | 需要权限 | rsync选项 |
|------|------|----------|-----------|
| 时间戳 | 文件修改和访问时间 | 无 | `--times` |
| 权限 | 文件读写执行权限 | 无 | `--perms` |
| 所有者 | 文件用户和组 | root | `--owner --group` |
| 符号链接 | 链接关系而非内容 | 无 | `--links` |
| 硬链接 | 多个文件名指向同一数据 | 无 | `--hard-links` |
| 设备文件 | 块设备和字符设备 | root | `--devices` |
| ACL | 访问控制列表 | 需要支持 | `--acls` |
| 扩展属性 | 用户自定义属性 | 需要支持 | `--xattrs` |

## 📝 示例输出

```bash
$ ./sync.sh -f test.txt -v

当前配置:
  远程主机: root@server.com:22
  远程路径: ~/backup
  私钥文件: ~/.ssh/id_rsa
  最大文件大小: 10485760 bytes
  排除模式: .git/ *.tmp *.log .DS_Store
  包含模式:

同步单个文件: test.txt -> root@server.com:/root/backup/test.txt
启用: 保持文件时间戳
启用: 保持文件权限和可执行性
执行命令: rsync -avz --progress --times --perms test.txt root@server.com:/root/backup/
上传完成: test.txt -> root@server.com:/root/backup/test.txt
```

## 🤝 贡献

欢迎提交Issue和Pull Request来改进这个脚本！

## 📄 许可证

本项目采用MIT许可证。