# backFile

**Repository Path**: lxedgar/back-file

## Basic Information

- **Project Name**: backFile
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: EPL-1.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-26
- **Last Updated**: 2026-01-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 文件备份工具库 (File Backup Library)

[![Java](https://img.shields.io/badge/Java-1.8-orange.svg)](https://www.oracle.com/java/)
[![Spring Boot](https://img.shields.io/badge/Spring%20Boot-2.7.15-brightgreen.svg)](https://spring.io/projects/spring-boot)
[![Maven](https://img.shields.io/badge/Maven-3.8+-blue.svg)](https://maven.apache.org/)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

一个基于 Spring Boot 的文件备份工具库，可以作为 Maven 依赖集成到其他 Spring Boot 项目中。支持文件备份、备份历史管理、配置管理等功能，并提供可选的 Web 管理界面。

## ✨ 功能特性

- ✅ **Maven 库支持**：可作为依赖库集成到其他 Spring Boot 项目
- ✅ **Spring Boot 自动配置**：开箱即用，自动配置相关 Bean
- ✅ **灵活配置**：支持 `application.yml` 和 `application.properties` 两种配置方式
- ✅ **文件备份**：支持自定义源文件路径和备份路径
- ✅ **备份历史**：自动记录备份历史，支持查看、下载、删除
- ✅ **自动清理**：支持配置备份保留次数，自动清理旧备份
- ✅ **可选 Web 界面**：通过配置控制是否启用 Web 管理界面
- ✅ **跨平台支持**：支持 Windows、Linux、Mac OS 等操作系统
- ✅ **数据库备份路径**：支持独立的数据库备份路径配置

## 📋 环境要求

- JDK 1.8+
- Maven 3.8+
- Spring Boot 2.7.15

## 🚀 快速开始

### 1. 安装到本地 Maven 仓库

在项目根目录执行：

```bash
mvn clean install
```

### 2. 在项目中使用

#### 2.1 添加 Maven 依赖

在目标项目的 `pom.xml` 中添加依赖：

```xml
<dependency>
    <groupId>cn.segasoft</groupId>
    <artifactId>file-backup</artifactId>
    <version>1.0.1</version>
</dependency>
```

如果使用 Web 界面功能，还需要添加 JSP 支持依赖：

```xml
<!-- Tomcat Embed Jasper for JSP support -->
<dependency>
    <groupId>org.apache.tomcat.embed</groupId>
    <artifactId>tomcat-embed-jasper</artifactId>
</dependency>

<!-- JSTL -->
<dependency>
    <groupId>javax.servlet</groupId>
    <artifactId>jstl</artifactId>
</dependency>
```

#### 2.2 配置（可选）

在项目的 `application.yml` 或 `application.properties` 中配置：

**application.yml:**

```yaml
file:
  backup:
    # 是否启用Web界面（默认false）
    web:
      enabled: true
    
    # 源文件路径（可选）
    source-path: D:/data/source
    
    # 备份路径（可选）
    backup-path: D:/data/backups/files
    
    # 数据库备份路径（可选）
    db-backup-path: D:/data/backups/db
    
    # 备份保留次数（可选，默认5）
    retention: 10
```

**application.properties:**

```properties
# 是否启用Web界面（默认false）
file.backup.web.enabled=true

# 源文件路径（可选）
file.backup.source-path=D:/data/source

# 备份路径（可选）
file.backup.backup-path=D:/data/backups/files

# 数据库备份路径（可选）
file.backup.db-backup-path=D:/data/backups/db

# 备份保留次数（可选，默认5）
file.backup.retention=10
```

#### 2.3 在代码中使用

**方式一：通过依赖注入使用（推荐）**

```java
@RestController
public class MyController {
    
    @Autowired
    private FileBackupManager fileBackupManager;
    
    @GetMapping("/backup")
    public String backup() {
        try {
            String backupPath = fileBackupManager.backupFiles();
            return "备份成功: " + backupPath;
        } catch (Exception e) {
            return "备份失败: " + e.getMessage();
        }
    }
    
    @GetMapping("/history")
    public List<String> getHistory() {
        return fileBackupManager.getBackupHistory();
    }
}
```

**方式二：直接创建实例使用**

```java
FileBackupManager backupManager = new FileBackupManager();
ConfigManager configManager = backupManager.getConfigManager();

// 设置配置
configManager.setSourcePath("/path/to/source");
configManager.setBackupPath("/path/to/backup");
configManager.setDbBackupPath("/path/to/db/backup");
configManager.setBackupRetention(10);

// 执行备份
String backupPath = backupManager.backupFiles();
```

#### 2.4 启用 Web 界面（可选）

如果需要使用 Web 界面管理备份，在配置文件中设置：

```yaml
file:
  backup:
    web:
      enabled: true
```

并在 Spring Boot 主类中添加组件扫描：

```java
@SpringBootApplication
@ComponentScan(basePackages = {"your.package", "cn.segasoft.fileback.controller"})
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}
```

然后访问：
- 主页: `http://localhost:8080/home` 或 `http://localhost:8080/`
- 配置: `http://localhost:8080/config`
- 备份历史: `http://localhost:8080/history`
- 执行备份: `http://localhost:8080/backup`

## 📖 配置说明

### 配置项列表

| 配置项 | 说明 | 类型 | 默认值 | 是否必需 |
|-------|------|------|-------|---------|
| `file.backup.web.enabled` | 是否启用Web界面 | Boolean | false | 否 |
| `file.backup.source-path` | 源文件路径 | String | 当前工作目录 | 否 |
| `file.backup.backup-path` | 备份路径 | String | 当前工作目录 + /backups/files | 否 |
| `file.backup.db-backup-path` | 数据库备份路径 | String | 当前工作目录 + /backups/db | 否 |
| `file.backup.retention` | 备份保留次数 | Integer | 5 | 否 |

### 配置文件加载优先级

1. **Spring Boot 配置**：优先从 `application.properties` 或 `application.yml` 加载配置
2. **backup-config.properties**：从 classpath 或当前目录加载 `backup-config.properties` 文件
3. **默认配置**：如果以上位置都不存在，则使用代码中的默认值

### 零配置使用

库支持"零配置"使用模式，无需修改任何配置即可集成：

- **默认配置**：自动使用相对路径作为默认配置
- **配置文件自动生成**：首次运行时自动生成 `backup-config.properties` 配置文件
- **多级加载**：从多个位置加载配置文件，适应不同部署环境

## 🔧 API 使用

### FileBackupManager

主要方法：

- `String backupFiles()` - 执行备份操作，返回备份文件路径
- `List<String> getBackupHistory()` - 获取备份历史记录，按时间倒序排列
- `boolean deleteBackup(String filePath)` - 删除备份文件和历史记录
- `ConfigManager getConfigManager()` - 获取配置管理器

### ConfigManager

主要方法：

- `String getSourcePath()` - 获取源文件路径
- `void setSourcePath(String path)` - 设置源文件路径
- `String getBackupPath()` - 获取备份路径
- `void setBackupPath(String path)` - 设置备份路径
- `String getDbBackupPath()` - 获取数据库备份路径
- `void setDbBackupPath(String path)` - 设置数据库备份路径
- `int getBackupRetention()` - 获取备份保留次数
- `void setBackupRetention(int retention)` - 设置备份保留次数

### 使用示例

```java
@Autowired
private FileBackupManager fileBackupManager;

// 执行备份
String backupPath = fileBackupManager.backupFiles();
System.out.println("备份完成：" + backupPath);

// 获取备份历史
List<String> history = fileBackupManager.getBackupHistory();
for (String record : history) {
    System.out.println(record);
}

// 删除备份
boolean success = fileBackupManager.deleteBackup(backupPath);
System.out.println("删除结果：" + success);

// 配置管理
ConfigManager configManager = fileBackupManager.getConfigManager();
configManager.setSourcePath("/path/to/source");
configManager.setBackupPath("/path/to/backup");
configManager.setBackupRetention(10);
```

## 🌐 Web 界面功能

当启用 Web 界面后（`file.backup.web.enabled=true`），提供以下功能：

### 主页面 (`/home` 或 `/`)

- 显示当前配置信息（源文件路径、备份路径、保留次数等）
- 执行备份按钮
- 备份历史列表（支持下载和删除）
- 文件夹内容浏览与下载

### 配置管理 (`/config`)

- 修改源文件路径
- 修改备份路径
- 修改数据库备份路径
- 修改保留备份次数

### 备份历史 (`/history`)

- 查看所有备份记录
- 按时间倒序排列
- 支持下载备份文件
- 支持删除备份文件

## 📁 项目结构

```
file-backup/
├── src/
│   └── main/
│       ├── java/
│       │   └── cn/segasoft/fileback/
│       │       ├── config/
│       │       │   ├── FileBackupAutoConfiguration.java  # 自动配置类
│       │       │   └── FileBackupProperties.java          # 配置属性类
│       │       ├── controller/
│       │       │   └── BackupController.java            # Web控制器（可选）
│       │       └── util/
│       │           ├── ConfigManager.java                # 配置管理器
│       │           └── FileBackupManager.java            # 备份管理器
│       ├── resources/
│       │   └── META-INF/
│       │       └── spring.factories                      # 自动配置注册
│       └── webapp/
│           └── WEB-INF/
│               └── views/
│                   └── home.jsp                          # Web界面视图
├── example-project/                                      # 使用示例项目
└── pom.xml
```

## 🔍 示例项目

项目根目录下的 `example-project` 文件夹包含了一个完整的使用示例，可以参考该示例了解如何使用。

运行示例项目：

```bash
# 1. 先安装库到本地仓库
mvn clean install

# 2. 运行示例项目
cd example-project
mvn spring-boot:run
```

## ❓ 常见问题

### 1. 备份失败

**可能原因**：
- 源文件路径不存在
- 备份路径无写入权限
- 源文件路径为空

**解决方法**：
- 检查源文件路径是否正确
- 确保备份路径有写入权限
- 在配置中设置有效的源文件路径

### 2. Web 界面 404 错误

**可能原因**：
- 未启用 Web 界面（`file.backup.web.enabled=false`）
- 未添加组件扫描
- 未添加 JSP 支持依赖

**解决方法**：
- 确保配置文件中 `file.backup.web.enabled=true`
- 在主类中添加 `@ComponentScan` 扫描 `cn.segasoft.fileback.controller` 包
- 添加 `tomcat-embed-jasper` 和 `jstl` 依赖

### 3. 配置文件不生效

**可能原因**：
- 配置项名称错误（注意 YAML 格式的层级）
- 配置文件位置不正确

**解决方法**：
- 检查配置项名称，YAML 格式应为 `file.backup.web.enabled`（注意层级）
- 确保配置文件在 `src/main/resources/` 目录下

### 4. 中文乱码

**可能原因**：
- 字符编码设置不正确

**解决方法**：
- 确保项目编码设置为 UTF-8
- 确保 JVM 启动参数包含 `-Dfile.encoding=UTF-8`

## 📝 注意事项

1. **备份文件大小**：
   - 建议不要备份过大的文件或目录，以免占用过多存储空间
   - 对于大型文件，考虑使用增量备份策略

2. **备份路径权限**：
   - 确保备份路径有足够的写入权限
   - 定期清理过期备份，避免存储空间不足

3. **配置文件**：
   - 配置文件会在首次运行时自动创建
   - 手动修改配置文件后需要重启应用才能生效

4. **跨系统兼容性**：
   - 支持 Windows、Linux、Mac OS 等操作系统
   - 文件路径会自动适配不同系统的路径分隔符

## 📄 版本历史

### v1.0.1

- ✅ 支持作为 Maven 依赖库使用
- ✅ Spring Boot 自动配置
- ✅ 支持 application.yml 和 application.properties 配置
- ✅ 可选 Web 界面功能
- ✅ 文件备份和备份历史管理
- ✅ 自动清理旧备份
- ✅ 跨平台支持

## 📞 联系方式

如有问题或建议，欢迎联系项目维护者。

---

**© 2024 文件备份工具库团队**