mirror of
https://github.com/CodeSeeed/sbackup.git
synced 2026-10-02 18:32:58 +08:00
v2.0.0: 多目标备份 + S3云存储 + 完整性校验 + 9语言国际化
feat: v2.0.0 — 多目标备份 + S3云存储 + 审计日志 + 9语言国际化
This commit is contained in:
xiatianxuan authored and GitHub committed
1 parent
c8c704a9c6
commit
8f2bcdf8fa
89 files changed
+37677
-1387
No files matched your search
@@ -0,0 +1,665 @@
|
||||
# Sbackup
|
||||
|
||||
[](https://www.python.org/)
|
||||
[](../../LICENSE)
|
||||
[](https://pypi.org/project/sbackup-cli/)
|
||||
[](../../.github/workflows/ci.yml)
|
||||
[]()
|
||||
|
||||
> Leichtgewichtiges, effizientes Ordner-Backup-Tool mit Kommandozeilenunterstuetzung zur einfachen Verwaltung Ihrer Backup-Strategien.
|
||||
|
||||
[English](../../README.md) | [Deutsch](README_de.md) | [Espanol](README_es.md) | [Francais](README_fr.md) | [Portugues](README_pt.md) | [Pycckuu](README_ru.md) | [日本語](README_ja.md) | [한국어](README_ko.md) | [中文](README_zh.md)
|
||||
|
||||
- [Ueberblick](#ueberblick)
|
||||
- [Funktionen](#funktionen)
|
||||
- [Schnellstart](#schnellstart)
|
||||
- [Installation](#installation)
|
||||
- [Verwendung](#verwendung)
|
||||
- [Konfigurationsdatei](#konfigurationsdatei)
|
||||
- [Konfigurationsbeispiel](#konfigurationsbeispiel)
|
||||
- [SFTP-Remote-Backup](#sftp-remote-backup)
|
||||
- [WebDAV-Remote-Backup](#webdav-remote-backup)
|
||||
- [Funktionsweise](#funktionsweise)
|
||||
- [Entwicklerhandbuch](#entwicklerhandbuch)
|
||||
- [Tests ausfuehren](#tests-ausfuehren)
|
||||
- [Code-Struktur](#code-struktur)
|
||||
- [Haeufig gestellte Fragen](#haeufig-gestellte-fragen)
|
||||
- [Mitwirkungsrichtlinie](#mitwirkungsrichtlinie)
|
||||
- [Lizenz](#lizenz)
|
||||
- [Autor](#autor)
|
||||
|
||||
---
|
||||
|
||||
## Ueberblick
|
||||
|
||||
Sbackup ist ein leichtgewichtiges Ordner-Backup-Tool, mit dem Sie Backup-Strategien ueber die Kommandozeile hinzufuegen, loeschen und anzeigen koennen. Es basiert auf dem letzten Aenderungszeitpunkt eines Ordners, um zu entscheiden, ob ein Backup erforderlich ist, und stellt sicher, dass Ihre Daten stets aktuell bleiben.
|
||||
|
||||
## Funktionen
|
||||
|
||||
- **Inkrementelles Backup**: Nur geaenderte Ordner werden gesichert, was Zeit und Speicherplatz spart
|
||||
- **Mehrere Formate**: Unterstuetzt ZIP, tar, tar.gz, tar.bz2, tar.xz, tar.zst und 7z -- sieben Packformate, global und pro Eintrag unabhaengig konfigurierbar
|
||||
- **SFTP-Remote-Backup**: Basierend auf paramiko, unterstuetzt Passwort-/SSH-Schluessel-Authentifizierung mit automatischer Erkennung des Standardschluessels
|
||||
- **WebDAV-Remote-Backup**: Basierend auf der Standardbibliothek urllib, ohne zusaetzliche Abhaengigkeiten, unterstuetzt Jianguoyun/NextCloud/Synology
|
||||
- **S3-Cloud-Speicher**: Basierend auf minio, unterstuetzt alle S3-kompatiblen Speicher (AWS/MinIO/Alibaba Cloud OSS usw.)
|
||||
- **Parallel-Backup auf mehrere Ziele**: Simultane Sicherung auf lokale und mehrere Remote-Ziele, unabhaengig voneinander
|
||||
- **Backup-Wiederherstellung**: Entpacken und Wiederherstellen aus Backup-Dateien in ein angegebenes Verzeichnis, mit selektiver Wiederherstellung
|
||||
- **Backup-Bereinigung**: Automatisches Loeschen alter Backups mit Strategien nach Anzahl/Zeit taeglicher Aufbewahrung
|
||||
- **Verschluesselte Backups**: Passwortverschluesselung fuer 7z-Format und PBKDF2-Verschluesselung fuer alle Formate
|
||||
- **Zeitgesteuerte Backups**: Intervallgesteuerte automatische Ausfuehrung, unterstuetzt Echtzeit-Dateiueberwachung (watchdog)
|
||||
- **Backup-Verlauf**: Protokollierung von Zeitpunkt, Groesse und SHA256-Pruefsumme jedes Backups zur Nachverfolgung
|
||||
- **Audit-Protokoll**: Protokollierung aller Backup-/Wiederherstellungsereignisse
|
||||
- **Pre-/Post-Hooks**: Ausfuehren von benutzerdefinierten Befehlen vor und nach dem Backup
|
||||
- **Konfigurationsprofile**: Speichern, Umschalten, Importieren und Exportieren mehrerer Konfigurationen
|
||||
- **Suche ueber Archive hinweg**: Dateinamenssuche in mehreren Backup-Dateien
|
||||
- **Datenintegritaet**: SHA256-Pruefsummen-Erzeugung und -Verifizierung, Reed-Solomon-Fehlerkorrektur
|
||||
- **Konfigurationsvalidierung**: Automatische Pruefung der Konfigurationsparameter, Erkennung von Manipulationen
|
||||
- **Aufgabenwarteschlange**: Verwaltung von Backup-Aufgaben mit Hinzufuegen, Ausfuehren und Abbrechen
|
||||
- **Komprimierungs-Benchmark**: Vergleich der Komprimierungsleistung verschiedener Formate und Stufen
|
||||
- **Speicherplatz-Schaetzung**: Backup-Groessenschaetzung nach Dateityp, Pruefung des Zielplatzes
|
||||
- **Internationalisierung**: Unterstuetzt Chinesisch, Englisch, Franzoesisch, Spanisch, Russisch, Deutsch, Japanisch, Portugiesisch und Koreanisch
|
||||
- **Shell-Autovervollstaendigung**: Unterstuetzt bash/zsh/fish/powershell
|
||||
- **Leichtgewichtig und effizient**: Kleine Dateigroesse, schneller Start, geringer Ressourcenverbrauch
|
||||
- **Plattformuebergreifend**: Unterstuetzt Windows, macOS und Linux
|
||||
|
||||
## Schnellstart
|
||||
|
||||
### Installation
|
||||
|
||||
#### Installation mit pip
|
||||
|
||||
```bash
|
||||
pip install sbackup-cli
|
||||
```
|
||||
|
||||
Nach der Installation verwenden Sie den Befehl `sbackup` (PyPI-Paketname: `sbackup-cli`, CLI-Befehl: `sbackup`).
|
||||
|
||||
#### Installation aus dem Quellcode
|
||||
|
||||
```bash
|
||||
git clone https://github.com/xiatianxuan/sbackup.git
|
||||
cd sbackup
|
||||
uv sync
|
||||
```
|
||||
|
||||
### Verwendung
|
||||
|
||||
#### Grundlegende Syntax
|
||||
|
||||
```bash
|
||||
uv run python main.py <command> [options]
|
||||
```
|
||||
|
||||
#### Verfuegbare Befehle
|
||||
|
||||
| Befehl | Beschreibung |
|
||||
|--------|--------------|
|
||||
| `add` | Backup-Strategie hinzufuegen |
|
||||
| `rm` / `remove` | Backup-Strategie loeschen |
|
||||
| `edit` | Vorhandene Backup-Strategie bearbeiten |
|
||||
| `all` | Alle Backup-Strategien anzeigen |
|
||||
| `save` | Backup ausfuehren |
|
||||
| `watch` | Backup zeitgesteuert ausfuehren |
|
||||
| `restore` | Aus Backup-Datei wiederherstellen |
|
||||
| `info` | Details einer Backup-Datei anzeigen |
|
||||
| `diff` | Quellverzeichnis mit Backup vergleichen |
|
||||
| `verify` | Integritaet der Backup-Datei pruefen |
|
||||
| `search` | Dateien im Backup suchen |
|
||||
| `xsearch` | Suche ueber mehrere Backup-Archive |
|
||||
| `versions` | Backup-Versionsverlauf anzeigen |
|
||||
| `sftp` | SFTP-Remote-Backup verwalten |
|
||||
| `webdav` | WebDAV-Remote-Backup verwalten |
|
||||
| `remote` | Remote-Dateiverwaltung (list/rm) |
|
||||
| `task` | Backup-Aufgabenwarteschlange verwalten |
|
||||
| `audit` | Audit-Protokoll abfragen |
|
||||
| `hooks` | Pre-/Post-Hooks manuell ausfuehren |
|
||||
| `profile` | Konfigurationsprofile verwalten |
|
||||
| `rotate` | Backup-Rotation und Bereinigung |
|
||||
| `clean` | Alte Backups bereinigen |
|
||||
| `diskcheck` | Speicherplatz-Schaetzung |
|
||||
| `benchmark` | Komprimierungsformat-Benchmark |
|
||||
| `integrity` | Integritaetspruefung des Backup-Verzeichnisses |
|
||||
| `dry-run` | Vorschau der Backup-Dateiauswahl |
|
||||
| `export` / `import` | Backup-Strategien exportieren/importieren |
|
||||
| `ignore` | .sbackupignore-Datei erstellen |
|
||||
| `schedule` | Zeitgesteuerte Konfiguration exportieren |
|
||||
| `webhook` | Webhook-Voreinstellungen konfigurieren |
|
||||
| `config` | Konfiguration verschluesseln/pruefen |
|
||||
| `report` | Backup-Bericht erstellen |
|
||||
| `completion` | Shell-Autovervollstaendigungsskript erzeugen |
|
||||
| `wizard` | Interaktiver Konfigurationsassistent |
|
||||
| `status` | Backup-Status-Dashboard |
|
||||
| `version` | Versionsinformationen anzeigen |
|
||||
| `help` | Hilfe anzeigen |
|
||||
|
||||
#### Globale Parameter
|
||||
|
||||
| Parameter | Beschreibung |
|
||||
|-----------|--------------|
|
||||
| `--lang zh_CN` / `en_US` / `fr_FR` / `es_ES` / `ru_RU` / `de_DE` / `ja_JP` / `pt_BR` / `ko_KR` | Oberflaechensprache festlegen (wird in config.json gespeichert) |
|
||||
| `--format zip` / `tar` / `tar.gz` / `tar.bz2` / `tar.xz` / `tar.zst` / `7z` | Packformat festlegen (wird in config.json gespeichert) |
|
||||
| `--debug` | Debug-Protokollierung aktivieren |
|
||||
|
||||
#### Backup-Strategie hinzufuegen
|
||||
|
||||
```bash
|
||||
uv run python main.py add <source> <dest> [-i ignore_patterns]
|
||||
```
|
||||
|
||||
Parameter:
|
||||
- **source**: Pfad des zu sichernden Quellordners
|
||||
- **dest**: Pfad fuer die Ablage der Backup-Dateien
|
||||
- **-i, --ignore**: Zu ignorierende Datei- oder Ordnernamen, kommagetrennt (Standard: `.git,__pycache__`)
|
||||
- **--format**: Packformat pro Eintrag (gilt nur fuer diese Strategie, Standardwert wird verwendet, wenn nicht angegeben): `zip` / `tar` / `tar.gz` / `tar.bz2` / `tar.xz` / `tar.zst` / `7z`
|
||||
|
||||
Beispiele:
|
||||
```bash
|
||||
# Strategie mit globalem Standardformat hinzufuegen
|
||||
uv run python main.py add F:/my_folder F:/backup -i node_modules,.git
|
||||
|
||||
# Tar.gz-Format fuer diese Strategie festlegen (jedes Backup dieses Ordners verwendet tar.gz)
|
||||
uv run python main.py add F:/my_folder F:/backup --format tar.gz
|
||||
|
||||
# 7z-Format festlegen (nur fuer diesen Ordner)
|
||||
uv run python main.py add F:/my_folder F:/backup --format 7z
|
||||
```
|
||||
|
||||
#### Backup-Strategie loeschen
|
||||
|
||||
```bash
|
||||
uv run python main.py rm <path>
|
||||
```
|
||||
|
||||
Parameter:
|
||||
- **path**: Pfad des Quellordners, dessen Backup-Strategie geloescht werden soll
|
||||
|
||||
Beispiel:
|
||||
```bash
|
||||
uv run python main.py rm F:/my_folder
|
||||
```
|
||||
|
||||
#### Alle Backup-Strategien anzeigen
|
||||
|
||||
```bash
|
||||
uv run python main.py all
|
||||
```
|
||||
|
||||
Zeigt alle aktuell konfigurierten Backup-Strategien an.
|
||||
|
||||
#### Backup ausfuehren
|
||||
|
||||
```bash
|
||||
# Mit Standardformat (ZIP)
|
||||
uv run python main.py save
|
||||
|
||||
# Mit tar.gz-Format
|
||||
uv run python main.py --format tar.gz save
|
||||
|
||||
# Die letzten 5 Backup-Dateien aufbewahren, alte automatisch bereinigen
|
||||
uv run python main.py save --keep 5
|
||||
|
||||
# Mit 7z-Format und Verschluesselung
|
||||
uv run python main.py --format 7z save --password mysecret
|
||||
|
||||
# Englische Oberflaeche + tar.xz-Format
|
||||
uv run python main.py --lang en_US --format tar.xz save
|
||||
```
|
||||
|
||||
**Parameter fuer den Befehl save:**
|
||||
|
||||
| Parameter | Standardwert | Beschreibung |
|
||||
|-----------|-------------|--------------|
|
||||
| `--keep N` | `0` | Die letzten N Backup-Dateien aufbewahren, 0 bedeutet keine Bereinigung |
|
||||
| `--password PASSWORT` | `""` | Verschluesselungspasswort (nur fuer 7z-Format) |
|
||||
| `--sftp` | `false` | Nach dem Backup auf SFTP-Server hochladen |
|
||||
| `--webdav` | `false` | Nach dem Backup auf WebDAV-Server hochladen |
|
||||
|
||||
Gemaess der Backup-Strategie werden geaenderte Ordner automatisch gesichert.
|
||||
|
||||
#### Zeitgesteuertes Backup
|
||||
|
||||
```bash
|
||||
# Alle 60 Minuten ein Backup ausfuehren
|
||||
uv run python main.py watch --interval 60
|
||||
|
||||
# Alle 2 Stunden mit Aufbewahrung der letzten 10 Dateien
|
||||
uv run python main.py watch --interval 120 --keep 10
|
||||
|
||||
# Zeitgesteuertes Backup + 7z-Verschluesselung
|
||||
uv run python main.py --format 7z watch --interval 60 --password mysecret
|
||||
```
|
||||
|
||||
**Parameter fuer den Befehl watch:**
|
||||
|
||||
| Parameter | Standardwert | Beschreibung |
|
||||
|-----------|-------------|--------------|
|
||||
| `--interval MINUTEN` | `60` | Backup-Intervall in Minuten |
|
||||
| `--keep N` | `0` | Die letzten N Backup-Dateien aufbewahren |
|
||||
| `--password PASSWORT` | `""` | Verschluesselungspasswort (nur fuer 7z-Format) |
|
||||
| `--sftp` | `false` | Nach jedem Backup auf SFTP-Server hochladen |
|
||||
| `--webdav` | `false` | Nach jedem Backup auf WebDAV-Server hochladen |
|
||||
|
||||
Mit `Ctrl+C` wird das zeitgesteuerte Backup gestoppt.
|
||||
|
||||
#### Backup wiederherstellen
|
||||
|
||||
```bash
|
||||
uv run python main.py restore <backup_file> <target_dir>
|
||||
```
|
||||
|
||||
Parameter:
|
||||
- **backup_file**: Pfad zur Backup-Datei (unterstuetzt .zip / .tar / .tar.gz / .tar.bz2 / .tar.xz / .tar.zst / .7z)
|
||||
- **target_dir**: Zielverzeichnis fuer die Wiederherstellung
|
||||
|
||||
Beispiele:
|
||||
```bash
|
||||
uv run python main.py restore F:/backup/my_folder.tar.gz F:/restored
|
||||
uv run python main.py restore F:/backup/my_folder.7z F:/restored
|
||||
uv run python main.py restore F:/backup/my_folder.tar.zst F:/restored
|
||||
```
|
||||
|
||||
#### SFTP-Remote-Backup
|
||||
|
||||
```bash
|
||||
# ============ Schnellstart (empfohlen) ============
|
||||
# 1. SFTP konfigurieren (automatische SSH-Schluessel-Erkennung, keine manuelle Angabe noetig)
|
||||
sbackup sftp config --host 192.168.1.100 --user admin --remote-path /backups
|
||||
|
||||
# 2. Verbindung testen
|
||||
sbackup sftp test
|
||||
|
||||
# 3. Backup ausfuehren und hochladen
|
||||
sbackup save --sftp
|
||||
|
||||
# ============ Authentifizierungsmethoden ============
|
||||
|
||||
# Methode 1: Automatische Schluessel-Erkennung (empfohlen)
|
||||
# Das System versucht automatisch ~/.ssh/id_ed25519 -> id_rsa -> id_ecdsa
|
||||
sbackup sftp config --host 192.168.1.100 --user admin
|
||||
|
||||
# Methode 2: Passwort-Authentifizierung
|
||||
sbackup sftp config --host 192.168.1.100 --user admin --password secret
|
||||
|
||||
# Methode 3: Bestimmten Schluessel angeben
|
||||
sbackup sftp config --host 192.168.1.100 --user admin --key-file ~/.ssh/id_rsa
|
||||
|
||||
# Methode 4: Schluessel + Passphrase (interaktive Eingabe)
|
||||
sbackup sftp config --host 192.168.1.100 --user admin --key-file ~/.ssh/id_rsa
|
||||
|
||||
# Methode 5: Schluessel + Passphrase (Kommandozeile)
|
||||
sbackup sftp config --host 192.168.1.100 --user admin --key-file ~/.ssh/id_rsa --key-passphrase mykeypass
|
||||
|
||||
# ============ Anwendungsszenarien ============
|
||||
|
||||
# Szenario 1: Einmaliges Backup mit Hochladen
|
||||
sbackup save --sftp
|
||||
|
||||
# Szenario 2: Zeitgesteuertes Backup mit automatischem Hochladen (alle 60 Minuten)
|
||||
sbackup watch --interval 60 --sftp
|
||||
|
||||
# Szenario 3: Bestimmtes Format + Hochladen
|
||||
sbackup --format tar.gz save --sftp
|
||||
|
||||
# Szenario 4: Verschluesseltes Backup + Hochladen
|
||||
sbackup --format 7z save --password mysecret --sftp
|
||||
|
||||
# Szenario 5: Aufbewahrung der letzten 5 Backups + Hochladen
|
||||
sbackup save --keep 5 --sftp
|
||||
|
||||
# ============ Erweiterte Verwendung ============
|
||||
|
||||
# Interaktive Konfiguration (alle Parameter schrittweise eingeben)
|
||||
sbackup sftp config
|
||||
|
||||
# Nicht-interaktive Konfiguration (alle Parameter in der Kommandozeile)
|
||||
sbackup sftp config --host 192.168.1.100 --port 22 --user admin --password secret --remote-path /backups
|
||||
|
||||
# Verbindung testen mit detailliertem Protokoll
|
||||
sbackup --debug sftp test
|
||||
```
|
||||
|
||||
**sftp-Unterbefehle:**
|
||||
|
||||
| Unterbefehl | Beschreibung | Beispiel |
|
||||
|-------------|--------------|----------|
|
||||
| `sftp config` | SFTP-Verbindungsparameter konfigurieren (host/port/user/password/key_file/key_passphrase/remote_path) | `sbackup sftp config --host 192.168.1.100 --user admin` |
|
||||
| `sftp test` | SFTP-Verbindung testen | `sbackup sftp test` |
|
||||
|
||||
**Authentifizierungsmethoden:**
|
||||
|
||||
| Methode | Parameter | Beschreibung | Beispiel |
|
||||
|---------|-----------|--------------|----------|
|
||||
| **Automatische Erkennung** | Keine Authentifizierungsparameter angeben | Versucht automatisch `~/.ssh/id_ed25519` -> `id_rsa` -> `id_ecdsa` (empfohlen) | `sbackup sftp config --host ... --user ...` |
|
||||
| Passwort | `--password` | Direkt mit Passwort anmelden | `sbackup sftp config --host ... --user ... --password secret` |
|
||||
| Schluessel | `--key-file` | Mit angegebenem SSH-Schluessel anmelden | `sbackup sftp config --host ... --user ... --key-file ~/.ssh/id_rsa` |
|
||||
| Schluessel + Passphrase | `--key-file` + `--key-passphrase` | Wenn der Schluessel eine Passphrase hat | `sbackup sftp config --host ... --user ... --key-file ~/.ssh/id_rsa --key-passphrase mypass` |
|
||||
|
||||
Unterstuetzte Schluesselformate: RSA, Ed25519, ECDSA.
|
||||
|
||||
**Plattformuebergreifende Pfadunterstuetzung:**
|
||||
|
||||
| Plattform | Beispiel Schluesselpfad | Beschreibung |
|
||||
|-----------|------------------------|--------------|
|
||||
| Linux/macOS | `~/.ssh/id_rsa` | Wird automatisch zu `/home/user/.ssh/id_rsa` aufgeloest |
|
||||
| Windows | `~/.ssh/id_rsa` | Wird automatisch zu `C:\Users\username\.ssh\id_rsa` aufgeloest |
|
||||
| Alle Plattformen | Absoluter Pfad | Vollstaendiger Pfad wird direkt verwendet |
|
||||
|
||||
Die SFTP-Konfiguration wird im Feld `sftp` der Datei `config.json` gespeichert und unterstuetzt Kommandozeilenparameter oder interaktive Eingabe.
|
||||
|
||||
#### Versionsinformationen anzeigen
|
||||
|
||||
```bash
|
||||
sbackup version
|
||||
```
|
||||
|
||||
## Konfigurationsdatei
|
||||
|
||||
Sbackup unterstuetzt benutzerdefinierte Konfiguration ueber die Datei `config.json`. Die Konfigurationsdatei liegt im Projektstammverzeichnis.
|
||||
|
||||
### Konfigurationsparameter
|
||||
|
||||
```json
|
||||
{
|
||||
"compression_format": "ZIP",
|
||||
"compression": {
|
||||
"algorithm": "ZIP_DEFLATED",
|
||||
"level": 6
|
||||
},
|
||||
"skip_patterns": [".git", "__pycache__"],
|
||||
"data_file": "sbackup.json",
|
||||
"lang": "zh_CN",
|
||||
"password": "",
|
||||
"sftp": {
|
||||
"host": "",
|
||||
"port": 22,
|
||||
"user": "",
|
||||
"password": "",
|
||||
"key_file": "",
|
||||
"key_passphrase": "",
|
||||
"remote_path": "/",
|
||||
"enabled": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| Parameter | Typ | Standardwert | Beschreibung |
|
||||
|-----------|-----|-------------|--------------|
|
||||
| `compression_format` | string | `"ZIP"` | Packformat, Auswahl: `ZIP`, `TAR`, `TAR_GZ`, `TAR_BZ2`, `TAR_XZ`, `TAR_ZST`, `7Z` |
|
||||
| `compression.algorithm` | string | `"ZIP_DEFLATED"` | ZIP-Komprimierungsalgorithmus, Auswahl: `ZIP_DEFLATED`, `ZIP_STORED`, `ZIP_BZIP2`, `ZIP_LZMA` |
|
||||
| `compression.level` | int | `6` | Komprimierungsstufe, Bereich 0-9 (0 = keine Komprimierung, 9 = hoechste Komprimierung) |
|
||||
| `skip_patterns` | list | `[".git", "__pycache__"]` | Zu ignorierende Datei-/Ordnermuster (unterstuetzt fnmatch-Platzhalter und Pfadabgleich) |
|
||||
| `data_file` | string | Plattform-Standardpfad | Pfad zur Datei mit den Backup-Strategien |
|
||||
| `lang` | string | `"zh_CN"` | Oberflaechensprache, Auswahl: `zh_CN`, `en_US`, `fr_FR`, `es_ES`, `ru_RU`, `de_DE`, `ja_JP`, `pt_BR`, `ko_KR` |
|
||||
| `password` | string | `""` | Verschluesselungspasswort fuer 7z |
|
||||
| `sftp.host` | string | `""` | SFTP-Serveradresse |
|
||||
| `sftp.port` | int | `22` | SFTP-Port |
|
||||
| `sftp.user` | string | `""` | SFTP-Benutzername |
|
||||
| `sftp.password` | string | `""` | SFTP-Passwort (fuer Passwort-Authentifizierung) |
|
||||
| `sftp.key_file` | string | `""` | Pfad zur SSH-Schluesseldatei (fuer Schluessel-Authentifizierung, empfohlen) |
|
||||
| `sftp.key_passphrase` | string | `""` | Schluessel-Passphrase (falls vorhanden) |
|
||||
| `sftp.remote_path` | string | `"/"` | Remote-Zielpfad |
|
||||
| `sftp.enabled` | bool | `false` | SFTP aktivieren oder nicht |
|
||||
|
||||
### Konfigurationsbeispiel
|
||||
|
||||
Backup mit dem tar.bz2-Format und hoher Komprimierung:
|
||||
|
||||
```json
|
||||
{
|
||||
"compression_format": "TAR_BZ2",
|
||||
"compression_level": 9,
|
||||
"skip_patterns": [".git", "__pycache__", "node_modules", "*.log"],
|
||||
"data_file": "backup_strategies.json",
|
||||
"lang": "de_DE"
|
||||
}
|
||||
```
|
||||
|
||||
### Vergleich der Packformate
|
||||
|
||||
| Format | Dateiendung | Komprimierung | Geschwindigkeit | Abhaengigkeit | Anwendungsfall |
|
||||
|--------|-------------|---------------|-----------------|---------------|----------------|
|
||||
| ZIP | .zip | Mittel | Schnell | Standardbibliothek | Universell, beste Windows-Kompatibilitaet |
|
||||
| tar | .tar | Keine | Sehr schnell | Standardbibliothek | Reines Archiv, fuer externe Komprimierung |
|
||||
| tar.gz | .tar.gz | Mittel | Schnell | Standardbibliothek | Linux/macOS Standard |
|
||||
| tar.bz2 | .tar.bz2 | Hoch | Mittel | Standardbibliothek | Hochkomprimierte Archive |
|
||||
| tar.xz | .tar.xz | Am hoechsten | Langsam | Standardbibliothek | Langzeitarchivierung, platzsparend |
|
||||
| tar.zst | .tar.zst | Mittel-hoch | Sehr schnell | zstandard | Modern, gute Balance zwischen Geschwindigkeit und Kompression |
|
||||
| 7z | .7z | Sehr hoch | Langsam | py7zr | Hoechste Kompression, unterstuetzt Verschluesselung |
|
||||
|
||||
#### WebDAV-Remote-Backup
|
||||
|
||||
WebDAV ist ein HTTP-basiertes Dateiprotokoll, das Jianguoyun, NextCloud, Synology und andere gaengige Cloud-Speicher unterstuetzt. Verwendet die Python-Standardbibliothek `urllib` -- **keine zusaetzlichen Abhaengigkeiten**.
|
||||
|
||||
```bash
|
||||
# ============ Schnellstart ============
|
||||
# 1. WebDAV konfigurieren
|
||||
sbackup webdav config --url https://dav.jianguoyun.com/dav/ --user user@example.com --password secret
|
||||
|
||||
# 2. Verbindung testen
|
||||
sbackup webdav test
|
||||
|
||||
# 3. Backup ausfuehren und hochladen
|
||||
sbackup save --webdav
|
||||
|
||||
# ============ Anwendungsszenarien ============
|
||||
|
||||
# Szenario 1: Einmaliges Backup mit Hochladen
|
||||
sbackup save --webdav
|
||||
|
||||
# Szenario 2: Zeitgesteuertes Backup mit automatischem Hochladen (alle 60 Minuten)
|
||||
sbackup watch --interval 60 --webdav
|
||||
|
||||
# Szenario 3: Remote-Unterverzeichnis angeben
|
||||
sbackup webdav config --url https://dav.jianguoyun.com/dav/ --user user@example.com --remote-path /backups/sbackup
|
||||
|
||||
# Szenario 4: Simultanes Hochladen auf SFTP und WebDAV
|
||||
sbackup save --sftp --webdav
|
||||
|
||||
# ============ Gaengige WebDAV-Adressen ============
|
||||
# Jianguoyun: https://dav.jianguoyun.com/dav/
|
||||
# NextCloud: https://your-server/remote.php/dav/files/username/
|
||||
# Synology: https://your-synology:5006/webdav/
|
||||
```
|
||||
|
||||
**webdav-Unterbefehle:**
|
||||
|
||||
| Unterbefehl | Beschreibung | Beispiel |
|
||||
|-------------|--------------|----------|
|
||||
| `webdav config` | WebDAV-Verbindungsparameter konfigurieren (url/user/password/remote_path) | `sbackup webdav config --url ... --user ...` |
|
||||
| `webdav test` | WebDAV-Verbindung testen | `sbackup webdav test` |
|
||||
|
||||
| Parameter | Standardwert | Beschreibung |
|
||||
|-----------|-------------|--------------|
|
||||
| `--url URL` | `""` | WebDAV-Serveradresse (z.B. `https://dav.jianguoyun.com/dav/`) |
|
||||
| `--user BENUTZER` | `""` | WebDAV-Benutzername (in der Regel E-Mail-Adresse) |
|
||||
| `--password PASSWORT` | `""` | WebDAV-Passwort (fuer Jianguoyun muss in den Einstellungen ein App-Passwort generiert werden) |
|
||||
| `--remote-path PFAD` | `/` | Remote-Zielpfad |
|
||||
|
||||
## Funktionsweise
|
||||
|
||||
Sbackup realisiert die Backup-Funktionalitaet auf folgende Weise:
|
||||
|
||||
1. **Backup-Strategie-Speicherung**: Backup-Strategien werden in einer JSON-Datei gespeichert, die Ordnerpfade, letzte Aenderungszeiten, Zielpfade, Ignoriermuster und packformat pro Eintrag enthaelt.
|
||||
2. **Inkrementelles Backup**: Durch Vergleich des letzten Aenderungszeitpunkts eines Ordners werden nur geaenderte Ordner gesichert.
|
||||
3. **Multiformat-Komprimierung**: Verwendet Pythons eingebaute `zipfile`- und `tarfile`-Module sowie die Drittanbieter-Bibliotheken `zstandard` und `py7zr` fuer sieben Packformate.
|
||||
4. **Format pro Eintrag**: Jede Backup-Strategie kann ein eigenes Packformat angeben (`add --format`), das Vorrang vor dem globalen `--format` hat. Ohne Angabe wird der globale Standard verwendet.
|
||||
5. **Backup-Bereinigung**: Nach erfolgreichem Backup wird das Zielverzeichnis automatisch gescannt, nach Aenderungszeitpunkt sortiert und alte Dateien werden ueber die Aufbewahrungsanzahl hinaus geloescht.
|
||||
6. **Verschluesseltes Backup**: Das 7z-Format unterstuetzt LZMA2-Verschluesselung ueber den `--password`-Parameter oder die `config.json`-Konfiguration.
|
||||
7. **Zeitgesteuertes Backup**: Der `watch`-Befehl fuehrt in einer Schleife in angegebenen Intervallen Backups aus. `Ctrl+C` beendet sicher.
|
||||
8. **Backup-Verlauf**: Nach jedem Backup werden Zeitstempel, Dateigroesse und Dateianzahl protokolliert. Es werden die letzten 100 Eintraege aufbewahrt.
|
||||
9. **SFTP-Remote-Backup**: Basierend auf der paramiko-Bibliothek als SFTP-Client, unterstuetzt Verbindungstests, automatische Erstellung von Remote-Verzeichnissen und Datei-Upload mit Fortschrittsanzeige.
|
||||
|
||||
### Datenformat der Datei
|
||||
|
||||
```json
|
||||
{
|
||||
"/path/to/source/folder": [
|
||||
1719235200.0,
|
||||
"/path/to/target/folder",
|
||||
[".git", "__pycache__"],
|
||||
""
|
||||
],
|
||||
"/path/to/another/folder": [
|
||||
1719235200.0,
|
||||
"/path/to/another/target",
|
||||
[".git"],
|
||||
"TAR_GZ"
|
||||
],
|
||||
"_history": [
|
||||
{
|
||||
"time": "2026-05-01T12:00:00",
|
||||
"source": "/path/to/source/folder",
|
||||
"size_mb": 12.5,
|
||||
"files_count": 150
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Jeder Backup-Strategie-Eintrag ist eine 4-Element-Liste: `[mtime, target, skip_patterns, compression_format]`
|
||||
|
||||
| Feld | Beschreibung |
|
||||
|------|--------------|
|
||||
| `mtime` | Letzter Aenderungszeitpunkt des Quellordners (fuer inkrementelle Backup-Entscheidung) |
|
||||
| `target` | Zielpfad fuer die Backup-Dateien |
|
||||
| `skip_patterns` | Liste der zu ignorierenden Datei-/Ordnermuster |
|
||||
| `compression_format` | Packformat pro Eintrag (leerer String bedeutet globaler Standard) |
|
||||
|
||||
## Entwicklerhandbuch
|
||||
|
||||
### Tests ausfuehren
|
||||
|
||||
```bash
|
||||
uv run coverage run -m unittest discover -s tests -t . && uv run coverage report -m
|
||||
```
|
||||
|
||||
### Code-Struktur
|
||||
|
||||
```
|
||||
sbackup/
|
||||
├── main.py # Programmeinstieg
|
||||
├── sbackup/
|
||||
│ ├── __init__.py # Export der Kernfunktionen
|
||||
│ ├── __main__.py # python -m sbackup Einstieg
|
||||
│ ├── cli.py # CLI-Argument-Parser und Befehlsverteilung (30+ Befehle)
|
||||
│ ├── config.py # Konfigurationslade, Verschluesselung, Webhook-/SMTP-Konfiguration
|
||||
│ ├── auto_save.py # BackupManager Kern-Engine
|
||||
│ ├── compression.py # Komprimierung/Dekomprimierung fuer 7 Formate
|
||||
│ ├── i18n.py # Internationalisierung (9 Sprachen)
|
||||
│ ├── sftp.py # SFTP-Remote-Backup-Client (paramiko)
|
||||
│ ├── webdav.py # WebDAV-Remote-Backup-Client (ohne Abhaengigkeiten)
|
||||
│ ├── cloud_storage.py # S3-Cloud-Speicher-Client (minio)
|
||||
│ ├── multi_dest.py # Parallel-Backup auf mehrere Ziele
|
||||
│ ├── handlers.py # SFTP-/WebDAV-/Remote-/Schedule-Befehlsverarbeitung
|
||||
│ ├── hooks.py # Pre-/Post-Hook-Ausfuehrung
|
||||
│ ├── audit.py # Audit-Protokollsystem
|
||||
│ ├── profile.py # Konfigurationsprofil-Verwaltung
|
||||
│ ├── selective.py # Selektive Wiederherstellung
|
||||
│ ├── cross_search.py | Suche ueber Archive hinweg
|
||||
│ ├── integrity.py # SHA256-Pruefsumme
|
||||
│ ├── rotation.py # Backup-Rotationsstrategie
|
||||
│ ├── dryrun.py # Dry-run-Vorschau
|
||||
│ ├── diskcheck.py # Speicherplatz-Schaetzung
|
||||
│ ├── task_queue.py # Aufgabenwarteschlangensystem
|
||||
│ ├── schema.py # Konfigurationsvalidierer
|
||||
│ ├── benchmark.py # Komprimierungs-Benchmark
|
||||
│ ├── chunked_backup.py# Blockweise inkrementelle Sicherung
|
||||
│ ├── dedup.py # Dateiweise SHA256-Deduplizierung
|
||||
│ ├── export.py # Metadaten-Export (CSV/JSON)
|
||||
│ ├── monitor.py # watchdog Dateisystemueberwachung
|
||||
│ ├── lock.py # Plattformuebergreifende Prozesssperre
|
||||
│ ├── retry.py | Exponentielle Wiederholung mit Backoff
|
||||
│ ├── ratelimiter.py # Token-Bucket-Ratenbegrenzung
|
||||
│ ├── keychain.py # System-Keychain-Integration
|
||||
│ ├── parity.py # Reed-Solomon-Fehlerkorrektur
|
||||
│ ├── completion.py # Shell-Autovervollstaendigung
|
||||
│ ├── wizard.py # Interaktiver Konfigurationsassistent
|
||||
│ └── locales/ # Uebersetzungsdateien fuer 9 Sprachen
|
||||
└── tests/
|
||||
└── sbackup/
|
||||
└── test_*.py # 30 Testdateien, alle Module abdeckend
|
||||
```
|
||||
|
||||
### Neue Funktionen hinzufuegen
|
||||
|
||||
1. Erstellen Sie eine neue Moduldatei im `sbackup/`-Verzeichnis
|
||||
2. Importieren Sie die neuen Funktionen in `sbackup/__init__.py`
|
||||
3. Fuegen Sie die Verarbeitungslogik fuer den neuen Befehl in der `run()`-Funktion hinzu
|
||||
4. Erstellen Sie die entsprechende Testdatei im `tests/`-Verzeichnis
|
||||
|
||||
## Haeufig gestellte Fragen
|
||||
|
||||
### Q: Was passiert, wenn die Backup-Strategie-Datei versehentlich geloescht wird?
|
||||
|
||||
A: Die Backup-Strategien werden in der Datendatei gespeichert. Bei versehentlicher Loeschung koennen die Strategien mit dem `add`-Befehl erneut hinzugefuegt werden.
|
||||
|
||||
### Q: Wie kann eine vorhandene Backup-Strategie geaendert werden?
|
||||
|
||||
A: Verwenden Sie den Befehl `sbackup edit`: `sbackup edit <source> --dest <new_dest> --ignore <patterns> --format <fmt>`.
|
||||
|
||||
### Q: Werden Remote-Backups unterstuetzt?
|
||||
|
||||
A: Ja! Es werden drei Remote-Backup-Methoden angeboten:
|
||||
- **SFTP**: `sbackup sftp config` konfigurieren, `sbackup save --sftp` hochladen
|
||||
- **WebDAV**: `sbackup webdav config` konfigurieren, `sbackup save --webdav` hochladen (unterstuetzt Jianguoyun/NextCloud/Synology)
|
||||
- **S3-Cloud-Speicher**: Das Feld `cloud` in `config.json` konfigurieren, `sbackup save --cloud` hochladen
|
||||
- Mehrere Methoden gleichzeitig: `sbackup save --sftp --webdav --cloud`
|
||||
|
||||
### Q: Was ist der Unterschied zwischen tar.gz und ZIP?
|
||||
|
||||
A: tar.gz wird auf Linux/macOS haeufiger verwendet und bietet eine etwas bessere Kompression. ZIP ist auf Windows gaengiger und hat die beste Kompatibilitaet. tar.bz2 und tar.xz bieten hoehere Kompression, sind aber langsamer. tar.zst ist ein moderner Algorithmus mit sehr hoher Geschwindigkeit und guter Kompression. 7z bietet die hoechste Kompression und unterstuetzt Verschluesselung.
|
||||
|
||||
### Q: Wie werden Backups verschluesselt?
|
||||
|
||||
A: Verwenden Sie das 7z-Format mit Passwort: `uv run python main.py --format 7z save --password yourpassword`. Das Passwort kann auch im Feld `password` der `config.json` hinterlegt werden.
|
||||
|
||||
### Q: Wie werden alte Backups automatisch bereinigt?
|
||||
|
||||
A: Verwenden Sie den Parameter `--keep`: `uv run python main.py save --keep 5` bewahrt nur die letzten 5 Backup-Dateien auf. Bei zeitgesteuerten Backups ebenfalls unterstuetzt: `uv run python main.py watch --interval 60 --keep 10`.
|
||||
|
||||
### Q: Wie richtet man zeitgesteuerte Backups ein?
|
||||
|
||||
A: Verwenden Sie den Befehl `watch`: `uv run python main.py watch --interval 60` fuehrt alle 60 Minuten ein Backup aus. Mit `Ctrl+C` wird gestoppt.
|
||||
|
||||
### Q: Ist die Passwortspeicherung sicher?
|
||||
|
||||
A: Die SFTP-Passwoerter und 7z-Verschluesselungspasswoerter in `config.json` werden im **Klartext** gespeichert. Stellen Sie sicher, dass der Zugriff auf die Datei `config.json` auf vertrauenswuerdige Benutzer beschraenkt ist (z.B. `chmod 600 config.json`). Fuegen Sie eine `config.json` mit Passwoertern nicht in ein Versionskontrollsystem ein.
|
||||
|
||||
## Mitwirkungsrichtlinie
|
||||
|
||||
Issues und Pull Requests sind willkommen!
|
||||
|
||||
1. Forken Sie dieses Repository
|
||||
2. Erstellen Sie Ihren Feature-Branch (`git checkout -b feature/AmazingFeature`)
|
||||
3. Committen Sie Ihre Aenderungen (`git commit -m 'Add some AmazingFeature'`)
|
||||
4. Pushen Sie auf den Branch (`git push origin feature/AmazingFeature`)
|
||||
5. Erstellen Sie einen Pull Request
|
||||
|
||||
### Codestil
|
||||
|
||||
Dieses Projekt folgt PEP 8 und dem Google Python Style Guide. Bitte stellen Sie sicher, dass Ihr Code:
|
||||
- Typannotationen verwendet
|
||||
- Google-stile Docstrings einhaelt
|
||||
- Alle Tests besteht
|
||||
|
||||
## Lizenz
|
||||
|
||||
Dieses Projekt steht unter der GNU GPL v3.0-Lizenz. Einzelheiten finden Sie in der Datei [LICENSE](../../LICENSE).
|
||||
|
||||
## Autor
|
||||
|
||||
**xiatianxuan** (CodeSeed)
|
||||
|
||||
- [Gitee](https://gitee.com/xiatianxuan)
|
||||
- [Webseite](https://xnors-codeseed.pages.dev/)
|
||||
|
||||
## Besonderer Dank
|
||||
|
||||
- [Xnors Studio](https://xnors.github.io/)
|
||||
|
||||
## Kontakt
|
||||
|
||||
Bei Fragen oder Anregungen senden Sie bitte eine E-Mail an: xiatianxuan2025@163.com
|
||||
|
||||
---
|
||||
|
||||
*Letzte Aktualisierung: 19. Juni 2026*
|
||||
@@ -0,0 +1,665 @@
|
||||
# Sbackup
|
||||
|
||||
[](https://www.python.org/)
|
||||
[](../../LICENSE)
|
||||
[](https://pypi.org/project/sbackup-cli/)
|
||||
[](../../.github/workflows/ci.yml)
|
||||
[]()
|
||||
|
||||
> Herramienta ligera y eficiente para copias de seguridad de carpetas, con soporte de linea de comandos para gestionar tus estrategias de backup sin esfuerzo.
|
||||
|
||||
[English](../../README.md) | [Deutsch](README_de.md) | [Espanol](README_es.md) | [Francais](README_fr.md) | [Portugues](README_pt.md) | [Pycckuu](README_ru.md) | [日本語](README_ja.md) | [한국어](README_ko.md) | [中文](README_zh.md)
|
||||
|
||||
- [Introduccion](#introduccion)
|
||||
- [Caracteristicas](#caracteristicas)
|
||||
- [Inicio rapido](#inicio-rapido)
|
||||
- [Instalacion](#instalacion)
|
||||
- [Uso](#uso)
|
||||
- [Archivo de configuracion](#archivo-de-configuracion)
|
||||
- [Ejemplo de configuracion](#ejemplo-de-configuracion)
|
||||
- [Copia de seguridad remota por SFTP](#copia-de-seguridad-remota-por-sftp)
|
||||
- [Copia de seguridad remota por WebDAV](#copia-de-seguridad-remota-por-webdav)
|
||||
- [Principio de funcionamiento](#principio-de-funcionamiento)
|
||||
- [Guia de desarrollo](#guia-de-desarrollo)
|
||||
- [Ejecutar pruebas](#ejecutar-pruebas)
|
||||
- [Estructura del codigo](#estructura-del-codigo)
|
||||
- [Preguntas frecuentes](#preguntas-frecuentes)
|
||||
- [Guia de contribucion](#guia-de-contribucion)
|
||||
- [Licencia](#licencia)
|
||||
- [Autor](#autor)
|
||||
|
||||
---
|
||||
|
||||
## Introduccion
|
||||
|
||||
Sbackup es una herramienta ligera de copias de seguridad de carpetas que permite agregar, eliminar y consultar estrategias de backup desde la linea de comandos. Se basa en la ultima fecha de modificacion de las carpetas para determinar si es necesario realizar una copia de seguridad, asegurando que tus datos permanezcan siempre actualizados.
|
||||
|
||||
## Caracteristicas
|
||||
|
||||
- **Copia de seguridad incremental**: Solo respalda las carpetas que han cambiado, ahorrando tiempo y espacio de almacenamiento.
|
||||
- **Soporte de multiples formatos**: Compatible con siete formatos de empaquetado: ZIP, tar, tar.gz, tar.bz2, tar.xz, tar.zst y 7z. Tanto el formato global como el de cada entrada pueden configurarse de forma independiente.
|
||||
- **Copia de seguridad remota por SFTP**: Basado en la biblioteca paramiko, soporta autenticacion por contrasena o clave privada SSH, con deteccion automatica de la clave privada predeterminada.
|
||||
- **Copia de seguridad remota por WebDAV**: Basado en urllib de la biblioteca estandar, sin dependencias adicionales. Compatible con Jianguoyun, NextCloud y Synology.
|
||||
- **Almacenamiento en la nube S3**: Basado en la biblioteca minio, compatible con todo almacenamiento compatible con S3 (AWS, MinIO, Alibaba Cloud OSS, etc.).
|
||||
- **Backup paralelo a multiples destinos**: Copia simultanea a almacenamiento local y multiples destinos remotos, sin interferencias entre ellos.
|
||||
- **Restauracion de backups**: Permite descomprimir y restaurar archivos de backup en el directorio especificado, con soporte de restauracion selectiva.
|
||||
- **Limpieza de backups**: Eliminacion automatica de backups antiguos, con politicas por cantidad, tiempo o retencion diaria.
|
||||
- **Cifrado de backups**: Soporta cifrado con contrasena en formato 7z mas cifrado PBKDF2 para todos los formatos.
|
||||
- **Copia de seguridad programada**: Ejecucion automatica a intervalos definidos, con soporte de monitoreo de archivos en tiempo real (watchdog).
|
||||
- **Historial de backups**: Registro de la fecha, tamano y suma de verificacion SHA256 de cada backup para facilitar el seguimiento.
|
||||
- **Registro de auditoria**: Registro de todos los eventos de auditoria de operaciones de backup y restauracion.
|
||||
- **Hooks pre/post**: Ejecucion de comandos personalizados antes y despues del backup.
|
||||
- **Perfiles de configuracion**: Soporte para guardar, cambiar, importar y exportar multiples esquemas de configuracion.
|
||||
- **Busqueda entre archivos**: Busqueda de nombres de archivo coincidentes en multiples archivos de backup.
|
||||
- **Integridad de datos**: Generacion y verificacion de sumas de verificacion SHA256, codigos de correccion de errores Reed-Solomon.
|
||||
- **Validacion de configuracion**: Verificacion automatica de la validez de los parametros de configuracion y deteccion de manipulaciones.
|
||||
- **Cola de tareas**: Gestion de la cola de tareas de backup, con soporte para agregar, ejecutar y cancelar.
|
||||
- **Benchmark de compresion**: Comparacion del rendimiento de compresion entre diferentes formatos y niveles.
|
||||
- **Estimacion de espacio en disco**: Estimacion del tamano del backup por tipo de archivo y verificacion del espacio en el destino.
|
||||
- **Internacionalizacion**: Soporte para nueve idiomas: chino, ingles, frances, espanol, ruso, aleman, japones, portugues y coreano.
|
||||
- **Autocompletado de shell**: Soporte de autocompletado automatico para bash, zsh, fish y powershell.
|
||||
- **Ligero y eficiente**: Tamano reducido, inicio rapido y bajo consumo de recursos.
|
||||
- **Soporte multiplataforma**: Compatible con Windows, macOS y Linux.
|
||||
|
||||
## Inicio rapido
|
||||
|
||||
### Instalacion
|
||||
|
||||
#### Instalacion con pip
|
||||
|
||||
```bash
|
||||
pip install sbackup-cli
|
||||
```
|
||||
|
||||
Despues de la instalacion, usa el comando `sbackup` (el nombre del paquete en PyPI es `sbackup-cli`, el comando CLI es `sbackup`).
|
||||
|
||||
#### Instalacion desde el codigo fuente
|
||||
|
||||
```bash
|
||||
git clone https://github.com/xiatianxuan/sbackup.git
|
||||
cd sbackup
|
||||
uv sync
|
||||
```
|
||||
|
||||
### Uso
|
||||
|
||||
#### Sintaxis basica
|
||||
|
||||
```bash
|
||||
uv run python main.py <command> [options]
|
||||
```
|
||||
|
||||
#### Comandos disponibles
|
||||
|
||||
| Comando | Descripcion |
|
||||
|---------|-------------|
|
||||
| `add` | Agregar una estrategia de backup |
|
||||
| `rm` / `remove` | Eliminar una estrategia de backup |
|
||||
| `edit` | Editar una estrategia de backup existente |
|
||||
| `all` | Ver todas las estrategias de backup |
|
||||
| `save` | Ejecutar el backup |
|
||||
| `watch` | Ejecutar backups programados |
|
||||
| `restore` | Restaurar desde un archivo de backup |
|
||||
| `info` | Ver detalles del archivo de backup |
|
||||
| `diff` | Comparar diferencias entre el directorio origen y el backup |
|
||||
| `verify` | Verificar la integridad del archivo de backup |
|
||||
| `search` | Buscar archivos dentro de un backup |
|
||||
| `xsearch` | Buscar entre multiples archivos de backup |
|
||||
| `versions` | Ver el historial de versiones del backup |
|
||||
| `sftp` | Gestion de backups remotos por SFTP |
|
||||
| `webdav` | Gestion de backups remotos por WebDAV |
|
||||
| `remote` | Gestion de archivos remotos (list/rm) |
|
||||
| `task` | Gestion de la cola de tareas de backup |
|
||||
| `audit` | Consulta del registro de auditoria |
|
||||
| `hooks` | Ejecucion manual de hooks pre/post |
|
||||
| `profile` | Gestion de perfiles de configuracion |
|
||||
| `rotate` | Limpieza por rotacion de backups |
|
||||
| `clean` | Limpieza de backups antiguos |
|
||||
| `diskcheck` | Estimacion de espacio en disco |
|
||||
| `benchmark` | Benchmark de formatos de compresion |
|
||||
| `integrity` | Verificacion de integridad del directorio de backups |
|
||||
| `dry-run` | Vista previa de la seleccion de archivos de backup |
|
||||
| `export` / `import` | Exportar/importar estrategias de backup |
|
||||
| `ignore` | Generar archivo .sbackupignore |
|
||||
| `schedule` | Exportar configuracion de programacion |
|
||||
| `webhook` | Configurar preajustes de webhook |
|
||||
| `config` | Configuracion de cifrado/verificacion |
|
||||
| `report` | Generar informe de backups |
|
||||
| `completion` | Generar scripts de autocompletado de shell |
|
||||
| `wizard` | Asistente de configuracion interactivo |
|
||||
| `status` | Panel de estado del backup |
|
||||
| `version` | Ver informacion de version |
|
||||
| `help` | Ver ayuda |
|
||||
|
||||
#### Parametros globales
|
||||
|
||||
| Parametro | Descripcion |
|
||||
|-----------|-------------|
|
||||
| `--lang zh_CN` / `en_US` / `fr_FR` / `es_ES` / `ru_RU` / `de_DE` / `ja_JP` / `pt_BR` / `ko_KR` | Establecer el idioma de la interfaz (persistente en config.json) |
|
||||
| `--format zip` / `tar` / `tar.gz` / `tar.bz2` / `tar.xz` / `tar.zst` / `7z` | Establecer el formato de empaquetado (persistente en config.json) |
|
||||
| `--debug` | Activar el registro de depuracion |
|
||||
|
||||
#### Agregar una estrategia de backup
|
||||
|
||||
```bash
|
||||
uv run python main.py add <source> <dest> [-i ignore_patterns]
|
||||
```
|
||||
|
||||
Parametros:
|
||||
- **source**: Ruta de la carpeta de origen a respaldar
|
||||
- **dest**: Ruta de destino donde se almacenara el backup
|
||||
- **-i, --ignore**: Nombres de archivos o carpetas a ignorar, separados por comas (por defecto: `.git,__pycache__`)
|
||||
- **--format**: Formato de empaquetado a nivel de entrada (solo afecta a esta estrategia de backup; si no se especifica, se usa el formato global): `zip` / `tar` / `tar.gz` / `tar.bz2` / `tar.xz` / `tar.zst` / `7z`
|
||||
|
||||
Ejemplos:
|
||||
```bash
|
||||
# Agregar estrategia usando el formato global por defecto
|
||||
uv run python main.py add F:/my_folder F:/backup -i node_modules,.git
|
||||
|
||||
# Especificar formato tar.gz para esta estrategia (cada backup de esta carpeta usara tar.gz)
|
||||
uv run python main.py add F:/my_folder F:/backup --format tar.gz
|
||||
|
||||
# Especificar formato 7z (solo para esta carpeta)
|
||||
uv run python main.py add F:/my_folder F:/backup --format 7z
|
||||
```
|
||||
|
||||
#### Eliminar una estrategia de backup
|
||||
|
||||
```bash
|
||||
uv run python main.py rm <path>
|
||||
```
|
||||
|
||||
Parametros:
|
||||
- **path**: Ruta de la carpeta de origen cuya estrategia de backup se va a eliminar
|
||||
|
||||
Ejemplo:
|
||||
```bash
|
||||
uv run python main.py rm F:/my_folder
|
||||
```
|
||||
|
||||
#### Ver todas las estrategias de backup
|
||||
|
||||
```bash
|
||||
uv run python main.py all
|
||||
```
|
||||
|
||||
Muestra todas las estrategias de backup configuradas actualmente.
|
||||
|
||||
#### Ejecutar backup
|
||||
|
||||
```bash
|
||||
# Usar formato por defecto (ZIP)
|
||||
uv run python main.py save
|
||||
|
||||
# Usar formato tar.gz
|
||||
uv run python main.py --format tar.gz save
|
||||
|
||||
# Conservar los 5 backups mas recientes, limpiando automaticamente los antiguos
|
||||
uv run python main.py save --keep 5
|
||||
|
||||
# Usar formato 7z con cifrado
|
||||
uv run python main.py --format 7z save --password mysecret
|
||||
|
||||
# Interfaz en ingles + formato tar.xz
|
||||
uv run python main.py --lang en_US --format tar.xz save
|
||||
```
|
||||
|
||||
**Parametros del comando save:**
|
||||
|
||||
| Parametro | Valor por defecto | Descripcion |
|
||||
|-----------|-------------------|-------------|
|
||||
| `--keep N` | `0` | Conservar los N backups mas recientes; 0 significa sin limpieza |
|
||||
| `--password PASSWORD` | `""` | Contrasena de cifrado (solo formato 7z) |
|
||||
| `--sftp` | `false` | Subir al servidor SFTP despues del backup |
|
||||
| `--webdav` | `false` | Subir al servidor WebDAV despues del backup |
|
||||
|
||||
Segun la estrategia de backup configurada, respalda automaticamente las carpetas que hayan cambiado.
|
||||
|
||||
#### Backup programado
|
||||
|
||||
```bash
|
||||
# Ejecutar backup cada 60 minutos
|
||||
uv run python main.py watch --interval 60
|
||||
|
||||
# Backup cada 2 horas, conservando los 10 archivos mas recientes
|
||||
uv run python main.py watch --interval 120 --keep 10
|
||||
|
||||
# Backup programado + cifrado 7z
|
||||
uv run python main.py --format 7z watch --interval 60 --password mysecret
|
||||
```
|
||||
|
||||
**Parametros del comando watch:**
|
||||
|
||||
| Parametro | Valor por defecto | Descripcion |
|
||||
|-----------|-------------------|-------------|
|
||||
| `--interval MINUTES` | `60` | Intervalo de backup (en minutos) |
|
||||
| `--keep N` | `0` | Conservar los N backups mas recientes |
|
||||
| `--password PASSWORD` | `""` | Contrasena de cifrado (solo formato 7z) |
|
||||
| `--sftp` | `false` | Subir al servidor SFTP despues de cada backup |
|
||||
| `--webdav` | `false` | Subir al servidor WebDAV despues de cada backup |
|
||||
|
||||
Pulsa `Ctrl+C` para detener el backup programado.
|
||||
|
||||
#### Restaurar backup
|
||||
|
||||
```bash
|
||||
uv run python main.py restore <backup_file> <target_dir>
|
||||
```
|
||||
|
||||
Parametros:
|
||||
- **backup_file**: Ruta del archivo de backup (compatible con .zip / .tar / .tar.gz / .tar.bz2 / .tar.xz / .tar.zst / .7z)
|
||||
- **target_dir**: Directorio de destino para la restauracion
|
||||
|
||||
Ejemplos:
|
||||
```bash
|
||||
uv run python main.py restore F:/backup/my_folder.tar.gz F:/restored
|
||||
uv run python main.py restore F:/backup/my_folder.7z F:/restored
|
||||
uv run python main.py restore F:/backup/my_folder.tar.zst F:/restored
|
||||
```
|
||||
|
||||
#### Copia de seguridad remota por SFTP
|
||||
|
||||
```bash
|
||||
# ============ Inicio rapido (recomendado) ============
|
||||
# 1. Configurar SFTP (deteccion automatica de clave privada SSH, sin necesidad de especificar manualmente)
|
||||
sbackup sftp config --host 192.168.1.100 --user admin --remote-path /backups
|
||||
|
||||
# 2. Probar conexion
|
||||
sbackup sftp test
|
||||
|
||||
# 3. Ejecutar backup y subir
|
||||
sbackup save --sftp
|
||||
|
||||
# ============ Metodos de autenticacion ============
|
||||
|
||||
# Metodo 1: Deteccion automatica de clave privada (recomendado)
|
||||
# El sistema intenta automaticamente ~/.ssh/id_ed25519 -> id_rsa -> id_ecdsa
|
||||
sbackup sftp config --host 192.168.1.100 --user admin
|
||||
|
||||
# Metodo 2: Autenticacion por contrasena
|
||||
sbackup sftp config --host 192.168.1.100 --user admin --password secret
|
||||
|
||||
# Metodo 3: Especificar clave privada
|
||||
sbackup sftp config --host 192.168.1.100 --user admin --key-file ~/.ssh/id_rsa
|
||||
|
||||
# Metodo 4: Clave privada + frase de paso (entrada interactiva)
|
||||
sbackup sftp config --host 192.168.1.100 --user admin --key-file ~/.ssh/id_rsa
|
||||
|
||||
# Metodo 5: Clave privada + frase de paso (especificada en linea de comandos)
|
||||
sbackup sftp config --host 192.168.1.100 --user admin --key-file ~/.ssh/id_rsa --key-passphrase mykeypass
|
||||
|
||||
# ============ Casos de uso ============
|
||||
|
||||
# Caso 1: Backup unico y subida
|
||||
sbackup save --sftp
|
||||
|
||||
# Caso 2: Backup programado con subida automatica (cada 60 minutos)
|
||||
sbackup watch --interval 60 --sftp
|
||||
|
||||
# Caso 3: Backup con formato especifico + subida
|
||||
sbackup --format tar.gz save --sftp
|
||||
|
||||
# Caso 4: Backup cifrado + subida
|
||||
sbackup --format 7z save --password mysecret --sftp
|
||||
|
||||
# Caso 5: Conservar los 5 backups mas recientes + subida
|
||||
sbackup save --keep 5 --sftp
|
||||
|
||||
# ============ Uso avanzado ============
|
||||
|
||||
# Configuracion interactiva (introducir todos los parametros paso a paso)
|
||||
sbackup sftp config
|
||||
|
||||
# Configuracion no interactiva (todos los parametros en la linea de comandos)
|
||||
sbackup sftp config --host 192.168.1.100 --port 22 --user admin --password secret --remote-path /backups
|
||||
|
||||
# Probar conexion y ver registro detallado
|
||||
sbackup --debug sftp test
|
||||
```
|
||||
|
||||
**Subcomandos de sftp:**
|
||||
|
||||
| Subcomando | Descripcion | Ejemplo |
|
||||
|------------|-------------|---------|
|
||||
| `sftp config` | Configurar parametros de conexion SFTP (host/port/user/password/key_file/key_passphrase/remote_path) | `sbackup sftp config --host 192.168.1.100 --user admin` |
|
||||
| `sftp test` | Probar si la conexion SFTP esta disponible | `sbackup sftp test` |
|
||||
|
||||
**Metodos de autenticacion:**
|
||||
|
||||
| Metodo | Parametros | Descripcion | Ejemplo |
|
||||
|--------|------------|-------------|---------|
|
||||
| **Deteccion automatica** | Sin parametros de autenticacion | Intenta automaticamente `~/.ssh/id_ed25519` -> `id_rsa` -> `id_ecdsa` (recomendado) | `sbackup sftp config --host ... --user ...` |
|
||||
| Contrasena | `--password` | Acceso directo con contrasena | `sbackup sftp config --host ... --user ... --password secret` |
|
||||
| Clave privada | `--key-file` | Acceso con clave privada SSH especificada | `sbackup sftp config --host ... --user ... --key-file ~/.ssh/id_rsa` |
|
||||
| Clave privada + frase de paso | `--key-file` + `--key-passphrase` | Para claves privadas con frase de paso | `sbackup sftp config --host ... --user ... --key-file ~/.ssh/id_rsa --key-passphrase mypass` |
|
||||
|
||||
Formatos de clave privada compatibles: RSA, Ed25519, ECDSA.
|
||||
|
||||
**Soporte de rutas multiplataforma:**
|
||||
|
||||
| Plataforma | Ejemplo de ruta de clave privada | Descripcion |
|
||||
|------------|----------------------------------|-------------|
|
||||
| Linux/macOS | `~/.ssh/id_rsa` | Se expande automaticamente a `/home/user/.ssh/id_rsa` |
|
||||
| Windows | `~/.ssh/id_rsa` | Se expande automaticamente a `C:\Users\username\.ssh\id_rsa` |
|
||||
| Todas | Ruta absoluta | Se usa directamente la ruta completa |
|
||||
|
||||
La configuracion de SFTP se guarda en el campo `sftp` de `config.json` y admite parametros de linea de comandos o entrada interactiva.
|
||||
|
||||
#### Ver informacion de version
|
||||
|
||||
```bash
|
||||
sbackup version
|
||||
```
|
||||
|
||||
## Archivo de configuracion
|
||||
|
||||
Sbackup permite la personalizacion mediante el archivo `config.json`. El archivo de configuracion debe ubicarse en el directorio raiz del proyecto.
|
||||
|
||||
### Descripcion de las opciones de configuracion
|
||||
|
||||
```json
|
||||
{
|
||||
"compression_format": "ZIP",
|
||||
"compression": {
|
||||
"algorithm": "ZIP_DEFLATED",
|
||||
"level": 6
|
||||
},
|
||||
"skip_patterns": [".git", "__pycache__"],
|
||||
"data_file": "sbackup.json",
|
||||
"lang": "zh_CN",
|
||||
"password": "",
|
||||
"sftp": {
|
||||
"host": "",
|
||||
"port": 22,
|
||||
"user": "",
|
||||
"password": "",
|
||||
"key_file": "",
|
||||
"key_passphrase": "",
|
||||
"remote_path": "/",
|
||||
"enabled": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| Opcion | Tipo | Valor por defecto | Descripcion |
|
||||
|--------|------|-------------------|-------------|
|
||||
| `compression_format` | string | `"ZIP"` | Formato de empaquetado. Valores posibles: `ZIP`, `TAR`, `TAR_GZ`, `TAR_BZ2`, `TAR_XZ`, `TAR_ZST`, `7Z` |
|
||||
| `compression.algorithm` | string | `"ZIP_DEFLATED"` | Algoritmo de compresion ZIP. Valores posibles: `ZIP_DEFLATED`, `ZIP_STORED`, `ZIP_BZIP2`, `ZIP_LZMA` |
|
||||
| `compression.level` | int | `6` | Nivel de compresion, rango 0-9 (0 = sin compresion, 9 = maxima compresion) |
|
||||
| `skip_patterns` | list | `[".git", "__pycache__"]` | Patrones de archivos o carpetas a ignorar (compatible con comodines fnmatch y coincidencia de rutas) |
|
||||
| `data_file` | string | Ruta predeterminada de la plataforma | Ruta del archivo de datos de estrategias de backup |
|
||||
| `lang` | string | `"zh_CN"` | Idioma de la interfaz. Valores posibles: `zh_CN`, `en_US`, `fr_FR`, `es_ES`, `ru_RU`, `de_DE`, `ja_JP`, `pt_BR`, `ko_KR` |
|
||||
| `password` | string | `""` | Contrasena de cifrado para 7z |
|
||||
| `sftp.host` | string | `""` | Direccion del servidor SFTP |
|
||||
| `sftp.port` | int | `22` | Puerto SFTP |
|
||||
| `sftp.user` | string | `""` | Nombre de usuario SFTP |
|
||||
| `sftp.password` | string | `""` | Contrasena SFTP (para autenticacion por contrasena) |
|
||||
| `sftp.key_file` | string | `""` | Ruta del archivo de clave privada SSH (para autenticacion por clave privada, recomendado) |
|
||||
| `sftp.key_passphrase` | string | `""` | Frase de paso de la clave privada (si aplica) |
|
||||
| `sftp.remote_path` | string | `"/"` | Ruta de destino remoto |
|
||||
| `sftp.enabled` | bool | `false` | Habilitar o deshabilitar SFTP |
|
||||
|
||||
### Ejemplo de configuracion
|
||||
|
||||
Usar formato tar.bz2 para backups con alta tasa de compresion:
|
||||
|
||||
```json
|
||||
{
|
||||
"compression_format": "TAR_BZ2",
|
||||
"compression_level": 9,
|
||||
"skip_patterns": [".git", "__pycache__", "node_modules", "*.log"],
|
||||
"data_file": "backup_strategies.json",
|
||||
"lang": "es_ES"
|
||||
}
|
||||
```
|
||||
|
||||
### Comparacion de formatos de empaquetado
|
||||
|
||||
| Formato | Extension | Compresion | Velocidad | Dependencias | Caso de uso |
|
||||
|---------|-----------|------------|-----------|--------------|-------------|
|
||||
| ZIP | .zip | Media | Rapida | Biblioteca estandar | Uso general, mejor compatibilidad con Windows |
|
||||
| tar | .tar | Ninguna | Muy rapida | Biblioteca estandar | Archivado puro, compresion externa |
|
||||
| tar.gz | .tar.gz | Media | Rapida | Biblioteca estandar | Uso general en Linux/macOS |
|
||||
| tar.bz2 | .tar.bz2 | Alta | Media | Biblioteca estandar | Archivado con alta compresion |
|
||||
| tar.xz | .tar.xz | Maxima | Lenta | Biblioteca estandar | Archivado a largo plazo, sensible al espacio |
|
||||
| tar.zst | .tar.zst | Media-alta | Muy rapida | zstandard | Casos modernos, equilibrio entre velocidad y compresion |
|
||||
| 7z | .7z | Muy alta | Lenta | py7zr | Maxima compresion, soporte de cifrado |
|
||||
|
||||
#### Copia de seguridad remota por WebDAV
|
||||
|
||||
WebDAV es un protocolo de archivos basado en HTTP, compatible con los principales servicios en la nube como Jianguoyun, NextCloud y Synology. Utiliza `urllib` de la biblioteca estandar de Python, **sin dependencias adicionales**.
|
||||
|
||||
```bash
|
||||
# ============ Inicio rapido ============
|
||||
# 1. Configurar WebDAV
|
||||
sbackup webdav config --url https://dav.jianguoyun.com/dav/ --user user@example.com --password secret
|
||||
|
||||
# 2. Probar conexion
|
||||
sbackup webdav test
|
||||
|
||||
# 3. Ejecutar backup y subir
|
||||
sbackup save --webdav
|
||||
|
||||
# ============ Casos de uso ============
|
||||
|
||||
# Caso 1: Backup unico y subida
|
||||
sbackup save --webdav
|
||||
|
||||
# Caso 2: Backup programado con subida automatica (cada 60 minutos)
|
||||
sbackup watch --interval 60 --webdav
|
||||
|
||||
# Caso 3: Especificar subdirectorio remoto
|
||||
sbackup webdav config --url https://dav.jianguoyun.com/dav/ --user user@example.com --remote-path /backups/sbackup
|
||||
|
||||
# Caso 4: Subir simultaneamente a SFTP y WebDAV
|
||||
sbackup save --sftp --webdav
|
||||
|
||||
# ============ Direcciones comunes de servicios WebDAV ============
|
||||
# Jianguoyun: https://dav.jianguoyun.com/dav/
|
||||
# NextCloud: https://your-server/remote.php/dav/files/username/
|
||||
# Synology: https://your-synology:5006/webdav/
|
||||
```
|
||||
|
||||
**Subcomandos de webdav:**
|
||||
|
||||
| Subcomando | Descripcion | Ejemplo |
|
||||
|------------|-------------|---------|
|
||||
| `webdav config` | Configurar parametros de conexion WebDAV (url/user/password/remote_path) | `sbackup webdav config --url ... --user ...` |
|
||||
| `webdav test` | Probar si la conexion WebDAV esta disponible | `sbackup webdav test` |
|
||||
|
||||
| Parametro | Valor por defecto | Descripcion |
|
||||
|-----------|-------------------|-------------|
|
||||
| `--url URL` | `""` | Direccion del servidor WebDAV (ej. `https://dav.jianguoyun.com/dav/`) |
|
||||
| `--user USER` | `""` | Nombre de usuario de WebDAV (normalmente un correo electronico) |
|
||||
| `--password PASS` | `""` | Contrasena de WebDAV (para Jianguoyun, genera una contrasena de aplicacion en la configuracion) |
|
||||
| `--remote-path PATH` | `/` | Ruta de destino remoto |
|
||||
|
||||
## Principio de funcionamiento
|
||||
|
||||
Sbackup implementa sus funciones de backup de la siguiente manera:
|
||||
|
||||
1. **Almacenamiento de estrategias**: Las estrategias de backup se almacenan en un archivo JSON que contiene las rutas de las carpetas, la ultima fecha de modificacion, las rutas de destino, los patrones de exclusion y el formato de empaquetado a nivel de entrada.
|
||||
2. **Backup incremental**: Al comparar la ultima fecha de modificacion de las carpetas, solo se respaldan las carpetas que hayan cambiado.
|
||||
3. **Compresion multi-formato**: Utiliza los modulos integrados `zipfile` y `tarfile` de Python, junto con las bibliotecas de terceros `zstandard` y `py7zr`, para soportar siete formatos de empaquetado.
|
||||
4. **Formato a nivel de entrada**: Cada estrategia de backup puede especificar su propio formato de empaquetado (`add --format`), que tiene prioridad sobre la configuracion global `--format`. Si no se especifica, se usa el formato global por defecto.
|
||||
5. **Limpieza de backups**: Despues de un backup exitoso, se escanea automaticamente el directorio de destino, se ordena por fecha de modificacion y se eliminan los archivos antiguos que excedan la cantidad de retencion.
|
||||
6. **Cifrado**: El formato 7z soporta cifrado LZMA2, configurable mediante el parametro `--password` o en `config.json`.
|
||||
7. **Backup programado**: El comando `watch` ejecuta backups en bucle a intervalos especificados; se sale de forma segura con `Ctrl+C`.
|
||||
8. **Historial de backups**: Despues de cada backup se registra la marca de tiempo, el tamano del archivo y la cantidad de archivos, conservando los ultimos 100 registros.
|
||||
9. **Backup remoto por SFTP**: Implementado con la biblioteca paramiko, soporta prueba de conexion, creacion automatica de directorios remotos y subida de archivos con barra de progreso.
|
||||
|
||||
### Formato del archivo de datos
|
||||
|
||||
```json
|
||||
{
|
||||
"/path/to/source/folder": [
|
||||
1719235200.0,
|
||||
"/path/to/target/folder",
|
||||
[".git", "__pycache__"],
|
||||
""
|
||||
],
|
||||
"/path/to/another/folder": [
|
||||
1719235200.0,
|
||||
"/path/to/another/target",
|
||||
[".git"],
|
||||
"TAR_GZ"
|
||||
],
|
||||
"_history": [
|
||||
{
|
||||
"time": "2026-05-01T12:00:00",
|
||||
"source": "/path/to/source/folder",
|
||||
"size_mb": 12.5,
|
||||
"files_count": 150
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Cada entrada de estrategia de backup es una lista de 4 elementos: `[mtime, target, skip_patterns, compression_format]`
|
||||
|
||||
| Campo | Descripcion |
|
||||
|-------|-------------|
|
||||
| `mtime` | Ultima fecha de modificacion de la carpeta de origen (para determinar si se necesita backup incremental) |
|
||||
| `target` | Ruta de destino donde se almacenara el archivo de backup |
|
||||
| `skip_patterns` | Lista de patrones de archivos/carpetas a ignorar |
|
||||
| `compression_format` | Formato de empaquetado a nivel de entrada (cadena vacia = usar formato global por defecto) |
|
||||
|
||||
## Guia de desarrollo
|
||||
|
||||
### Ejecutar pruebas
|
||||
|
||||
```bash
|
||||
uv run coverage run -m unittest discover -s tests -t . && uv run coverage report -m
|
||||
```
|
||||
|
||||
### Estructura del codigo
|
||||
|
||||
```
|
||||
sbackup/
|
||||
├── main.py # Punto de entrada del programa
|
||||
├── sbackup/
|
||||
│ ├── __init__.py # Exportacion de funciones principales
|
||||
│ ├── __main__.py # Punto de entrada para python -m sbackup
|
||||
│ ├── cli.py # Analisis de argumentos CLI y distribucion de comandos (30+ comandos)
|
||||
│ ├── config.py # Carga de configuracion, cifrado, configuracion Webhook/SMTP
|
||||
│ ├── auto_save.py # Motor principal BackupManager
|
||||
│ ├── compression.py # Motor de compresion/descompresion de 7 formatos
|
||||
│ ├── i18n.py # Internacionalizacion (9 idiomas)
|
||||
│ ├── sftp.py # Cliente de backup remoto SFTP (paramiko)
|
||||
│ ├── webdav.py # Cliente de backup remoto WebDAV (sin dependencias)
|
||||
│ ├── cloud_storage.py # Cliente de almacenamiento en la nube S3 (minio)
|
||||
│ ├── multi_dest.py # Backup paralelo a multiples destinos
|
||||
│ ├── handlers.py # Manejadores de comandos SFTP/WebDAV/Remote/Schedule
|
||||
│ ├── hooks.py # Ejecucion de hooks pre/post
|
||||
│ ├── audit.py # Sistema de registro de auditoria
|
||||
│ ├── profile.py # Gestion de perfiles de configuracion
|
||||
│ ├── selective.py # Restauracion selectiva
|
||||
│ ├── cross_search.py # Busqueda entre archivos
|
||||
│ ├── integrity.py # Sumas de verificacion SHA256
|
||||
│ ├── rotation.py # Politicas de rotacion de backups
|
||||
│ ├── dryrun.py # Vista previa de dry-run
|
||||
│ ├── diskcheck.py # Estimacion de espacio en disco
|
||||
│ ├── task_queue.py # Sistema de cola de tareas
|
||||
│ ├── schema.py # Validador de configuracion
|
||||
│ ├── benchmark.py # Benchmark de compresion
|
||||
│ ├── chunked_backup.py# Backup incremental a nivel de bloque
|
||||
│ ├── dedup.py # Deduplicacion a nivel de archivo con SHA256
|
||||
│ ├── export.py # Exportacion de metadatos (CSV/JSON)
|
||||
│ ├── monitor.py # Monitoreo de sistema de archivos con watchdog
|
||||
│ ├── lock.py # Bloqueo de proceso multiplataforma
|
||||
│ ├── retry.py # Reintentos con retroceso exponencial
|
||||
│ ├── ratelimiter.py # Limitador de velocidad con cubeta de tokens
|
||||
│ ├── keychain.py # Integracion con el llavero del sistema
|
||||
│ ├── parity.py # Codigos de correccion de errores Reed-Solomon
|
||||
│ ├── completion.py # Autocompletado de shell
|
||||
│ ├── wizard.py # Asistente de configuracion interactivo
|
||||
│ └── locales/ # Archivos de traduccion en 9 idiomas
|
||||
└── tests/
|
||||
└── sbackup/
|
||||
└── test_*.py # 30 archivos de prueba que cubren todos los modulos
|
||||
```
|
||||
|
||||
### Agregar nuevas funcionalidades
|
||||
|
||||
1. Crear un nuevo archivo de modulo en el directorio `sbackup/`
|
||||
2. Importar las funciones de la nueva funcionalidad en `sbackup/__init__.py`
|
||||
3. Agregar la logica de manejo del nuevo comando en la funcion `run()`
|
||||
4. Agregar el archivo de prueba correspondiente en el directorio `tests/`
|
||||
|
||||
## Preguntas frecuentes
|
||||
|
||||
### P: Que pasa si elimino accidentalmente el archivo de estrategias de backup?
|
||||
|
||||
R: Las estrategias de backup se almacenan en el archivo de datos. Si se elimina accidentalmente, puedes volver a agregar las estrategias ejecutando el comando `add` nuevamente.
|
||||
|
||||
### P: Como puedo modificar una estrategia de backup ya agregada?
|
||||
|
||||
R: Usa el comando `sbackup edit`: `sbackup edit <source> --dest <new_dest> --ignore <patterns> --format <fmt>`.
|
||||
|
||||
### P: Soporta backups remotos?
|
||||
|
||||
R: Si. Se ofrecen tres metodos de backup remoto:
|
||||
- **SFTP**: Configurar con `sbackup sftp config`, subir con `sbackup save --sftp`
|
||||
- **WebDAV**: Configurar con `sbackup webdav config`, subir con `sbackup save --webdav` (compatible con Jianguoyun, NextCloud, Synology)
|
||||
- **Almacenamiento S3**: Configurar el campo `cloud` en `config.json`, subir con `sbackup save --cloud`
|
||||
- Se pueden usar varios a la vez: `sbackup save --sftp --webdav --cloud`
|
||||
|
||||
### P: Cual es la diferencia entre tar.gz y ZIP?
|
||||
|
||||
R: tar.gz se usa mas comunmente en Linux/macOS y ofrece una tasa de compresion ligeramente superior; ZIP es mas universal en Windows y tiene la mejor compatibilidad. tar.bz2 y tar.xz ofrecen mayor compresion pero son mas lentos. tar.zst es un algoritmo moderno con velocidad excelente y buena compresion. 7z ofrece la mayor compresion y soporta cifrado.
|
||||
|
||||
### P: Como puedo cifrar un backup?
|
||||
|
||||
R: Usa el formato 7z y establece una contrasena: `uv run python main.py --format 7z save --password yourpassword`. La contrasena tambien puede escribirse en el campo `password` de `config.json`.
|
||||
|
||||
### P: Como puedo limpiar automaticamente los backups antiguos?
|
||||
|
||||
R: Usa el parametro `--keep`: `uv run python main.py save --keep 5` conserva solo los 5 backups mas recientes. Tambien funciona con backups programados: `uv run python main.py watch --interval 60 --keep 10`.
|
||||
|
||||
### P: Como puedo configurar backups programados?
|
||||
|
||||
R: Usa el comando `watch`: `uv run python main.py watch --interval 60` ejecuta un backup cada 60 minutos. Pulsa `Ctrl+C` para detener.
|
||||
|
||||
### P: Es seguro almacenar las contrasenas?
|
||||
|
||||
R: Las contrasenas de SFTP y de cifrado 7z en `config.json` se almacenan en **texto plano**. Asegurate de que los permisos de acceso al archivo `config.json` esten restringidos a usuarios de confianza (por ejemplo, `chmod 600 config.json`). No incluyas el archivo `config.json` con contrasenas en el sistema de control de versiones.
|
||||
|
||||
## Guia de contribucion
|
||||
|
||||
Se agradecen los Issues y Pull Requests.
|
||||
|
||||
1. Haz fork de este repositorio
|
||||
2. Crea tu rama de funcionalidad (`git checkout -b feature/AmazingFeature`)
|
||||
3. Realiza tus cambios (`git commit -m 'Add some AmazingFeature'`)
|
||||
4. Sube a tu rama (`git push origin feature/AmazingFeature`)
|
||||
5. Envia el Pull Request
|
||||
|
||||
### Estilo de codigo
|
||||
|
||||
Este proyecto sigue PEP 8 y Google Python Style Guide. Asegurate de que tu codigo:
|
||||
- Use anotaciones de tipo
|
||||
- Siga la convencion de docstrings de Google
|
||||
- Pase todas las pruebas unitarias
|
||||
|
||||
## Licencia
|
||||
|
||||
Este proyecto esta licenciado bajo la licencia GNU GPL v3.0. Consulta el archivo [LICENSE](../../LICENSE) para mas detalles.
|
||||
|
||||
## Autor
|
||||
|
||||
**xiatianxuan** (CodeSeed)
|
||||
|
||||
- [Gitee](https://gitee.com/xiatianxuan)
|
||||
- [Pagina personal](https://xnors-codeseed.pages.dev/)
|
||||
|
||||
## Agradecimientos especiales
|
||||
|
||||
- [Xnors Studio](https://xnors.github.io/)
|
||||
|
||||
## Contacto
|
||||
|
||||
Si tienes preguntas o sugerencias, envia un correo a: xiatianxuan2025@163.com
|
||||
|
||||
---
|
||||
|
||||
*Ultima actualizacion: 19 de junio de 2026*
|
||||
@@ -0,0 +1,665 @@
|
||||
# Sbackup
|
||||
|
||||
[](https://www.python.org/)
|
||||
[](../../LICENSE)
|
||||
[](https://pypi.org/project/sbackup-cli/)
|
||||
[](../../.github/workflows/ci.yml)
|
||||
[]()
|
||||
|
||||
> Outil de sauvegarde de dossiers léger et efficace, fonctionnant en ligne de commande, pour gérer vos stratégies de sauvegarde en toute simplicité.
|
||||
|
||||
[English](../../README.md) | [Deutsch](README_de.md) | [Espanol](README_es.md) | [Francais](README_fr.md) | [Portugues](README_pt.md) | [Pycckuu](README_ru.md) | [日本語](README_ja.md) | [한국어](README_ko.md) | [中文](README_zh.md)
|
||||
|
||||
- [Introduction](#introduction)
|
||||
- [Fonctionnalites](#fonctionnalites)
|
||||
- [Demarrage rapide](#demarrage-rapide)
|
||||
- [Installation](#installation)
|
||||
- [Utilisation](#utilisation)
|
||||
- [Fichier de configuration](#fichier-de-configuration)
|
||||
- [Exemple de configuration](#exemple-de-configuration)
|
||||
- [Sauvegarde SFTP distante](#sauvegarde-sftp-distante)
|
||||
- [Sauvegarde WebDAV distante](#sauvegarde-webdav-distante)
|
||||
- [Principe de fonctionnement](#principe-de-fonctionnement)
|
||||
- [Guide de developpement](#guide-de-developpement)
|
||||
- [Executer les tests](#executer-les-tests)
|
||||
- [Structure du code](#structure-du-code)
|
||||
- [Questions frequentes](#questions-frequentes)
|
||||
- [Guide de contribution](#guide-de-contribution)
|
||||
- [Licence](#licence)
|
||||
- [Auteur](#auteur)
|
||||
|
||||
---
|
||||
|
||||
## Introduction
|
||||
|
||||
Sbackup est un outil de sauvegarde de dossiers léger qui permet d'ajouter, supprimer et consulter des stratégies de sauvegarde via la ligne de commande. Il se base sur la date de dernière modification des dossiers pour déterminer si une sauvegarde est nécessaire, garantissant ainsi que vos données sont toujours à jour.
|
||||
|
||||
## Fonctionnalites
|
||||
|
||||
- **Sauvegarde incrémentielle** : ne sauvegarde que les dossiers modifiés, économisant temps et espace de stockage
|
||||
- **Multi-format** : prend en charge sept formats d'archivage — ZIP, tar, tar.gz, tar.bz2, tar.xz, tar.zst, 7z — configurables globalement ou par entrée
|
||||
- **Sauvegarde SFTP distante** : basée sur la bibliothèque paramiko, authentification par mot de passe ou clé SSH privée, détection automatique de la clé par défaut
|
||||
- **Sauvegarde WebDAV distante** : basée sur la bibliothèque standard urllib, sans aucune dépendance supplémentaire, compatible avec Jianguoyun / NextCloud / Synology
|
||||
- **Stockage cloud S3** : basé sur la bibliothèque minio, compatible avec tous les stockages S3 (AWS / MinIO / Alibaba Cloud OSS, etc.)
|
||||
- **Sauvegarde multi-destinations en parallèle** : sauvegarde simultanée vers le local et plusieurs destinations distantes, sans interférence mutuelle
|
||||
- **Restauration de sauvegarde** : extraction et restauration depuis un fichier de sauvegarde vers un répertoire cible, avec restauration sélective possible
|
||||
- **Nettoyage de sauvegardes** : suppression automatique des anciennes sauvegardes, avec stratégies par nombre / durée / conservation quotidienne
|
||||
- **Sauvegarde chiffrée** : chiffrement par mot de passe pour le format 7z + chiffrement PBKDF2 pour tous les formats
|
||||
- **Sauvegarde planifiée** : exécution automatique à intervalles réguliers, surveillance en temps réel des fichiers (watchdog)
|
||||
- **Historique de sauvegarde** : enregistrement de l'heure, de la taille et de la somme de contrôle SHA256 de chaque sauvegarde, pour un suivi facile
|
||||
- **Journal d'audit** : enregistrement des événements d'audit pour toutes les opérations de sauvegarde et de restauration
|
||||
- **Hooks Pre/Post** : exécution de commandes personnalisées avant et après la sauvegarde
|
||||
- **Profils de configuration** : sauvegarde, basculement, import/export de plusieurs jeux de configuration
|
||||
- **Recherche inter-archives** : recherche de noms de fichiers correspondants dans plusieurs fichiers de sauvegarde
|
||||
- **Intégrité des données** : génération et vérification de sommes de contrôle SHA256, codes correcteurs d'erreurs Reed-Solomon
|
||||
- **Validation de configuration** : vérification automatique de la validité des paramètres, détection des modifications non autorisées
|
||||
- **File d'attente de tâches** : gestion de la file d'attente des tâches de sauvegarde, avec ajout, exécution et annulation
|
||||
- **Benchmark de compression** : comparaison des performances de compression selon les différents formats et niveaux
|
||||
- **Estimation d'espace disque** : estimation de la taille de sauvegarde par type de fichier, vérification de l'espace disponible sur la destination
|
||||
- **Internationalisation** : support de neuf langues — chinois, anglais, français, espagnol, russe, allemand, japonais, portugais, coréen
|
||||
- **Complétion shell** : auto-complétion pour bash / zsh / fish / powershell
|
||||
- **Léger et efficace** : faible encombrement, démarrage rapide, consommation de ressources minimale
|
||||
- **Multiplateforme** : compatible avec Windows, macOS et Linux
|
||||
|
||||
## Demarrage rapide
|
||||
|
||||
### Installation
|
||||
|
||||
#### Installation via pip
|
||||
|
||||
```bash
|
||||
pip install sbackup-cli
|
||||
```
|
||||
|
||||
Après l'installation, utilisez la commande `sbackup` (le nom du paquet PyPI est `sbackup-cli`, la commande CLI est `sbackup`).
|
||||
|
||||
#### Installation depuis les sources
|
||||
|
||||
```bash
|
||||
git clone https://github.com/xiatianxuan/sbackup.git
|
||||
cd sbackup
|
||||
uv sync
|
||||
```
|
||||
|
||||
### Utilisation
|
||||
|
||||
#### Syntaxe de base
|
||||
|
||||
```bash
|
||||
uv run python main.py <commande> [options]
|
||||
```
|
||||
|
||||
#### Commandes disponibles
|
||||
|
||||
| Commande | Description |
|
||||
|----------|-------------|
|
||||
| `add` | Ajouter une stratégie de sauvegarde |
|
||||
| `rm` / `remove` | Supprimer une stratégie de sauvegarde |
|
||||
| `edit` | Modifier une stratégie de sauvegarde existante |
|
||||
| `all` | Afficher toutes les stratégies de sauvegarde |
|
||||
| `save` | Exécuter la sauvegarde |
|
||||
| `watch` | Sauvegarde planifiée à intervalles réguliers |
|
||||
| `restore` | Restaurer depuis un fichier de sauvegarde |
|
||||
| `info` | Afficher les détails d'un fichier de sauvegarde |
|
||||
| `diff` | Comparer les différences entre le répertoire source et la sauvegarde |
|
||||
| `verify` | Vérifier l'intégrité d'un fichier de sauvegarde |
|
||||
| `search` | Rechercher des fichiers dans une sauvegarde |
|
||||
| `xsearch` | Rechercher dans plusieurs archives de sauvegarde |
|
||||
| `versions` | Afficher l'historique des versions de sauvegarde |
|
||||
| `sftp` | Gestion des sauvegardes SFTP distantes |
|
||||
| `webdav` | Gestion des sauvegardes WebDAV distantes |
|
||||
| `remote` | Gestion des fichiers distants (list/rm) |
|
||||
| `task` | Gestion de la file d'attente des tâches |
|
||||
| `audit` | Consultation du journal d'audit |
|
||||
| `hooks` | Exécution manuelle des hooks Pre/Post |
|
||||
| `profile` | Gestion des profils de configuration |
|
||||
| `rotate` | Rotation et nettoyage des sauvegardes |
|
||||
| `clean` | Nettoyage des anciennes sauvegardes |
|
||||
| `diskcheck` | Estimation de l'espace disque |
|
||||
| `benchmark` | Benchmark des formats de compression |
|
||||
| `integrity` | Vérification d'intégrité du répertoire de sauvegarde |
|
||||
| `dry-run` | Aperçu de la sélection des fichiers de sauvegarde |
|
||||
| `export` / `import` | Exporter / Importer les stratégies de sauvegarde |
|
||||
| `ignore` | Générer un fichier .sbackupignore |
|
||||
| `schedule` | Exporter la configuration de planification |
|
||||
| `webhook` | Configurer des préréglages de webhook |
|
||||
| `config` | Configuration du chiffrement / validation |
|
||||
| `report` | Générer un rapport de sauvegarde |
|
||||
| `completion` | Générer les scripts de complétion shell |
|
||||
| `wizard` | Assistant de configuration interactif |
|
||||
| `status` | Tableau de bord de l'état des sauvegardes |
|
||||
| `version` | Afficher les informations de version |
|
||||
| `help` | Afficher l'aide |
|
||||
|
||||
#### Paramètres globaux
|
||||
|
||||
| Paramètre | Description |
|
||||
|-----------|-------------|
|
||||
| `--lang zh_CN` / `en_US` / `fr_FR` / `es_ES` / `ru_RU` / `de_DE` / `ja_JP` / `pt_BR` / `ko_KR` | Définir la langue de l'interface (persisté dans config.json) |
|
||||
| `--format zip` / `tar` / `tar.gz` / `tar.bz2` / `tar.xz` / `tar.zst` / `7z` | Définir le format d'archivage (persisté dans config.json) |
|
||||
| `--debug` | Activer le journal de débogage |
|
||||
|
||||
#### Ajouter une stratégie de sauvegarde
|
||||
|
||||
```bash
|
||||
uv run python main.py add <source> <dest> [-i ignore_patterns]
|
||||
```
|
||||
|
||||
Description des paramètres :
|
||||
- **source** : chemin du dossier source à sauvegarder
|
||||
- **dest** : chemin de destination pour le fichier de sauvegarde
|
||||
- **-i, --ignore** : noms de fichiers ou dossiers à ignorer, séparés par des virgules (par défaut : `.git,__pycache__`)
|
||||
- **--format** : format d'archivage au niveau de l'entrée (s'applique uniquement à cette stratégie, utilise la valeur globale par défaut si non spécifié) : `zip` / `tar` / `tar.gz` / `tar.bz2` / `tar.xz` / `tar.zst` / `7z`
|
||||
|
||||
Exemples :
|
||||
```bash
|
||||
# Ajouter une stratégie avec le format par défaut global
|
||||
uv run python main.py add F:/my_folder F:/backup -i node_modules,.git
|
||||
|
||||
# Spécifier le format tar.gz pour cette stratégie (chaque sauvegarde de ce dossier utilisera tar.gz)
|
||||
uv run python main.py add F:/my_folder F:/backup --format tar.gz
|
||||
|
||||
# Spécifier le format 7z (uniquement pour ce dossier)
|
||||
uv run python main.py add F:/my_folder F:/backup --format 7z
|
||||
```
|
||||
|
||||
#### Supprimer une stratégie de sauvegarde
|
||||
|
||||
```bash
|
||||
uv run python main.py rm <path>
|
||||
```
|
||||
|
||||
Description des paramètres :
|
||||
- **path** : chemin du dossier source dont la stratégie de sauvegarde doit être supprimée
|
||||
|
||||
Exemple :
|
||||
```bash
|
||||
uv run python main.py rm F:/my_folder
|
||||
```
|
||||
|
||||
#### Afficher toutes les stratégies de sauvegarde
|
||||
|
||||
```bash
|
||||
uv run python main.py all
|
||||
```
|
||||
|
||||
Affiche toutes les stratégies de sauvegarde actuellement configurées.
|
||||
|
||||
#### Exécuter la sauvegarde
|
||||
|
||||
```bash
|
||||
# Utiliser le format par défaut (ZIP)
|
||||
uv run python main.py save
|
||||
|
||||
# Utiliser le format tar.gz
|
||||
uv run python main.py --format tar.gz save
|
||||
|
||||
# Conserver les 5 derniers fichiers de sauvegarde, nettoyer automatiquement les anciens
|
||||
uv run python main.py save --keep 5
|
||||
|
||||
# Utiliser le format 7z avec chiffrement
|
||||
uv run python main.py --format 7z save --password mysecret
|
||||
|
||||
# Interface en anglais + format tar.xz
|
||||
uv run python main.py --lang en_US --format tar.xz save
|
||||
```
|
||||
|
||||
**Paramètres de la commande save :**
|
||||
|
||||
| Paramètre | Valeur par défaut | Description |
|
||||
|-----------|-------------------|-------------|
|
||||
| `--keep N` | `0` | Conserver les N fichiers de sauvegarde les plus récents, 0 signifie aucun nettoyage |
|
||||
| `--password PASSWORD` | `""` | Mot de passe de chiffrement (uniquement pour le format 7z) |
|
||||
| `--sftp` | `false` | Télécharger vers le serveur SFTP après la sauvegarde |
|
||||
| `--webdav` | `false` | Télécharger vers le serveur WebDAV après la sauvegarde |
|
||||
|
||||
Sauvegarde automatiquement les dossiers modifiés selon les stratégies configurées.
|
||||
|
||||
#### Sauvegarde planifiée
|
||||
|
||||
```bash
|
||||
# Exécuter la sauvegarde toutes les 60 minutes
|
||||
uv run python main.py watch --interval 60
|
||||
|
||||
# Sauvegarder toutes les 2 heures, conserver les 10 derniers fichiers
|
||||
uv run python main.py watch --interval 120 --keep 10
|
||||
|
||||
# Sauvegarde planifiée + chiffrement 7z
|
||||
uv run python main.py --format 7z watch --interval 60 --password mysecret
|
||||
```
|
||||
|
||||
**Paramètres de la commande watch :**
|
||||
|
||||
| Paramètre | Valeur par défaut | Description |
|
||||
|-----------|-------------------|-------------|
|
||||
| `--interval MINUTES` | `60` | Intervalle de sauvegarde (en minutes) |
|
||||
| `--keep N` | `0` | Conserver les N fichiers de sauvegarde les plus récents |
|
||||
| `--password PASSWORD` | `""` | Mot de passe de chiffrement (uniquement pour le format 7z) |
|
||||
| `--sftp` | `false` | Télécharger vers le serveur SFTP après chaque sauvegarde |
|
||||
| `--webdav` | `false` | Télécharger vers le serveur WebDAV après chaque sauvegarde |
|
||||
|
||||
Appuyez sur `Ctrl+C` pour arrêter la sauvegarde planifiée.
|
||||
|
||||
#### Restaurer une sauvegarde
|
||||
|
||||
```bash
|
||||
uv run python main.py restore <backup_file> <target_dir>
|
||||
```
|
||||
|
||||
Description des paramètres :
|
||||
- **backup_file** : chemin du fichier de sauvegarde (compatible .zip / .tar / .tar.gz / .tar.bz2 / .tar.xz / .tar.zst / .7z)
|
||||
- **target_dir** : répertoire cible de la restauration
|
||||
|
||||
Exemples :
|
||||
```bash
|
||||
uv run python main.py restore F:/backup/my_folder.tar.gz F:/restored
|
||||
uv run python main.py restore F:/backup/my_folder.7z F:/restored
|
||||
uv run python main.py restore F:/backup/my_folder.tar.zst F:/restored
|
||||
```
|
||||
|
||||
#### Sauvegarde SFTP distante
|
||||
|
||||
```bash
|
||||
# ============ Demarrage rapide (recommande) ============
|
||||
# 1. Configurer le SFTP (détection automatique de la clé SSH privée, aucune spécification manuelle nécessaire)
|
||||
sbackup sftp config --host 192.168.1.100 --user admin --remote-path /backups
|
||||
|
||||
# 2. Tester la connexion
|
||||
sbackup sftp test
|
||||
|
||||
# 3. Exécuter la sauvegarde et télécharger
|
||||
sbackup save --sftp
|
||||
|
||||
# ============ Modes d'authentification ============
|
||||
|
||||
# Mode 1 : Détection automatique de la clé privée (recommandé)
|
||||
# Le système tente automatiquement ~/.ssh/id_ed25519 → id_rsa → id_ecdsa
|
||||
sbackup sftp config --host 192.168.1.100 --user admin
|
||||
|
||||
# Mode 2 : Authentification par mot de passe
|
||||
sbackup sftp config --host 192.168.1.100 --user admin --password secret
|
||||
|
||||
# Mode 3 : Spécifier une clé privée
|
||||
sbackup sftp config --host 192.168.1.100 --user admin --key-file ~/.ssh/id_rsa
|
||||
|
||||
# Mode 4 : Clé privée + phrase secrète (saisie interactive)
|
||||
sbackup sftp config --host 192.168.1.100 --user admin --key-file ~/.ssh/id_rsa
|
||||
|
||||
# Mode 5 : Clé privée + phrase secrète (spécifiée en ligne de commande)
|
||||
sbackup sftp config --host 192.168.1.100 --user admin --key-file ~/.ssh/id_rsa --key-passphrase mykeypass
|
||||
|
||||
# ============ Scenarios d'utilisation ============
|
||||
|
||||
# Scénario 1 : Sauvegarde unique avec téléchargement
|
||||
sbackup save --sftp
|
||||
|
||||
# Scénario 2 : Sauvegarde planifiée avec téléchargement automatique (toutes les 60 minutes)
|
||||
sbackup watch --interval 60 --sftp
|
||||
|
||||
# Scénario 3 : Sauvegarde dans un format spécifié + téléchargement
|
||||
sbackup --format tar.gz save --sftp
|
||||
|
||||
# Scénario 4 : Sauvegarde chiffrée + téléchargement
|
||||
sbackup --format 7z save --password mysecret --sftp
|
||||
|
||||
# Scénario 5 : Conserver les 5 dernières sauvegardes + téléchargement
|
||||
sbackup save --keep 5 --sftp
|
||||
|
||||
# ============ Utilisation avancee ============
|
||||
|
||||
# Configuration interactive (saisie de tous les paramètres étape par étape)
|
||||
sbackup sftp config
|
||||
|
||||
# Configuration non interactive (tous les paramètres spécifiés en ligne de commande)
|
||||
sbackup sftp config --host 192.168.1.100 --port 22 --user admin --password secret --remote-path /backups
|
||||
|
||||
# Tester la connexion avec journal détaillé
|
||||
sbackup --debug sftp test
|
||||
```
|
||||
|
||||
**Sous-commandes sftp :**
|
||||
|
||||
| Sous-commande | Description | Exemple |
|
||||
|---------------|-------------|---------|
|
||||
| `sftp config` | Configurer les paramètres de connexion SFTP (host/port/user/password/key_file/key_passphrase/remote_path) | `sbackup sftp config --host 192.168.1.100 --user admin` |
|
||||
| `sftp test` | Tester si la connexion SFTP est disponible | `sbackup sftp test` |
|
||||
|
||||
**Modes d'authentification :**
|
||||
|
||||
| Mode | Paramètres | Description | Exemple |
|
||||
|------|------------|-------------|---------|
|
||||
| **Détection automatique** | Aucun paramètre d'authentification | Tente automatiquement `~/.ssh/id_ed25519` → `id_rsa` → `id_ecdsa` (recommandé) | `sbackup sftp config --host ... --user ...` |
|
||||
| Mot de passe | `--password` | Connexion directe par mot de passe | `sbackup sftp config --host ... --user ... --password secret` |
|
||||
| Clé privée | `--key-file` | Connexion avec une clé SSH privée spécifiée | `sbackup sftp config --host ... --user ... --key-file ~/.ssh/id_rsa` |
|
||||
| Clé privée + phrase | `--key-file` + `--key-passphrase` | Lorsque la clé privée est protégée par une phrase secrète | `sbackup sftp config --host ... --user ... --key-file ~/.ssh/id_rsa --key-passphrase mypass` |
|
||||
|
||||
Formats de clés privées pris en charge : RSA, Ed25519, ECDSA.
|
||||
|
||||
**Support des chemins multiplateforme :**
|
||||
|
||||
| Plateforme | Exemple de chemin de clé privée | Description |
|
||||
|------------|--------------------------------|-------------|
|
||||
| Linux/macOS | `~/.ssh/id_rsa` | Développement automatiquement en `/home/user/.ssh/id_rsa` |
|
||||
| Windows | `~/.ssh/id_rsa` | Développement automatiquement en `C:\Users\username\.ssh\id_rsa` |
|
||||
| Toutes plateformes | Chemin absolu | Utilisation directe du chemin complet |
|
||||
|
||||
La configuration SFTP est enregistrée dans le champ `sftp` du fichier `config.json`, configurable via les paramètres de ligne de commande ou en mode interactif.
|
||||
|
||||
#### Afficher les informations de version
|
||||
|
||||
```bash
|
||||
sbackup version
|
||||
```
|
||||
|
||||
## Fichier de configuration
|
||||
|
||||
Sbackup prend en charge la personnalisation via un fichier `config.json`. Le fichier de configuration doit être placé à la racine du projet.
|
||||
|
||||
### Description des paramètres de configuration
|
||||
|
||||
```json
|
||||
{
|
||||
"compression_format": "ZIP",
|
||||
"compression": {
|
||||
"algorithm": "ZIP_DEFLATED",
|
||||
"level": 6
|
||||
},
|
||||
"skip_patterns": [".git", "__pycache__"],
|
||||
"data_file": "sbackup.json",
|
||||
"lang": "zh_CN",
|
||||
"password": "",
|
||||
"sftp": {
|
||||
"host": "",
|
||||
"port": 22,
|
||||
"user": "",
|
||||
"password": "",
|
||||
"key_file": "",
|
||||
"key_passphrase": "",
|
||||
"remote_path": "/",
|
||||
"enabled": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| Paramètre | Type | Valeur par défaut | Description |
|
||||
|-----------|------|-------------------|-------------|
|
||||
| `compression_format` | string | `"ZIP"` | Format d'archivage, valeurs possibles : `ZIP`, `TAR`, `TAR_GZ`, `TAR_BZ2`, `TAR_XZ`, `TAR_ZST`, `7Z` |
|
||||
| `compression.algorithm` | string | `"ZIP_DEFLATED"` | Algorithme de compression ZIP, valeurs possibles : `ZIP_DEFLATED`, `ZIP_STORED`, `ZIP_BZIP2`, `ZIP_LZMA` |
|
||||
| `compression.level` | int | `6` | Niveau de compression, de 0 à 9 (0 = pas de compression, 9 = compression maximale) |
|
||||
| `skip_patterns` | list | `[".git", "__pycache__"]` | Motifs de fichiers ou dossiers à ignorer (supporte les jokers fnmatch et la correspondance de chemins) |
|
||||
| `data_file` | string | Chemin par défaut de la plateforme | Chemin du fichier de données des stratégies de sauvegarde |
|
||||
| `lang` | string | `"zh_CN"` | Langue de l'interface, valeurs possibles : `zh_CN`, `en_US`, `fr_FR`, `es_ES`, `ru_RU`, `de_DE`, `ja_JP`, `pt_BR`, `ko_KR` |
|
||||
| `password` | string | `""` | Mot de passe de chiffrement 7z |
|
||||
| `sftp.host` | string | `""` | Adresse du serveur SFTP |
|
||||
| `sftp.port` | int | `22` | Port SFTP |
|
||||
| `sftp.user` | string | `""` | Nom d'utilisateur SFTP |
|
||||
| `sftp.password` | string | `""` | Mot de passe SFTP (utilisé pour l'authentification par mot de passe) |
|
||||
| `sftp.key_file` | string | `""` | Chemin du fichier de clé SSH privée (utilisé pour l'authentification par clé, recommandé) |
|
||||
| `sftp.key_passphrase` | string | `""` | Phrase secrète de la clé privée (le cas échéant) |
|
||||
| `sftp.remote_path` | string | `"/"` | Chemin de destination distant |
|
||||
| `sftp.enabled` | bool | `false` | Activer ou non le SFTP |
|
||||
|
||||
### Exemple de configuration
|
||||
|
||||
Utiliser le format tar.bz2 pour une sauvegarde à taux de compression élevé :
|
||||
|
||||
```json
|
||||
{
|
||||
"compression_format": "TAR_BZ2",
|
||||
"compression_level": 9,
|
||||
"skip_patterns": [".git", "__pycache__", "node_modules", "*.log"],
|
||||
"data_file": "backup_strategies.json",
|
||||
"lang": "zh_CN"
|
||||
}
|
||||
```
|
||||
|
||||
### Comparaison des formats d'archivage
|
||||
|
||||
| Format | Extension | Taux de compression | Vitesse | Dépendance | Cas d'utilisation |
|
||||
|--------|-----------|---------------------|---------|------------|-------------------|
|
||||
| ZIP | .zip | Moyen | Rapide | Bibliothèque standard | Universel, meilleure compatibilité sous Windows |
|
||||
| tar | .tar | Aucun | Très rapide | Bibliothèque standard | Archivage pur, à combiner avec une compression externe |
|
||||
| tar.gz | .tar.gz | Moyen | Rapide | Bibliothèque standard | Courant sous Linux/macOS |
|
||||
| tar.bz2 | .tar.bz2 | Élevé | Moyen | Bibliothèque standard | Archivage à taux de compression élevé |
|
||||
| tar.xz | .tar.xz | Le plus élevé | Lent | Bibliothèque standard | Archivage à long terme, espace limité |
|
||||
| tar.zst | .tar.zst | Moyen-élevé | Très rapide | zstandard | Usage moderne, bon équilibre vitesse/compression |
|
||||
| 7z | .7z | Très élevé | Lent | py7zr | Compression maximale, support du chiffrement |
|
||||
|
||||
#### Sauvegarde WebDAV distante
|
||||
|
||||
WebDAV est un protocole de fichiers basé sur HTTP, compatible avec les principaux services cloud comme Jianguoyun, NextCloud et Synology. Utilise la bibliothèque standard Python `urllib`, **sans aucune dépendance supplémentaire**.
|
||||
|
||||
```bash
|
||||
# ============ Demarrage rapide ============
|
||||
# 1. Configurer le WebDAV
|
||||
sbackup webdav config --url https://dav.jianguoyun.com/dav/ --user user@example.com --password secret
|
||||
|
||||
# 2. Tester la connexion
|
||||
sbackup webdav test
|
||||
|
||||
# 3. Exécuter la sauvegarde et télécharger
|
||||
sbackup save --webdav
|
||||
|
||||
# ============ Scenarios d'utilisation ============
|
||||
|
||||
# Scénario 1 : Sauvegarde unique avec téléchargement
|
||||
sbackup save --webdav
|
||||
|
||||
# Scénario 2 : Sauvegarde planifiée avec téléchargement automatique (toutes les 60 minutes)
|
||||
sbackup watch --interval 60 --webdav
|
||||
|
||||
# Scénario 3 : Spécifier un sous-répertoire distant
|
||||
sbackup webdav config --url https://dav.jianguoyun.com/dav/ --user user@example.com --remote-path /backups/sbackup
|
||||
|
||||
# Scénario 4 : Télécharger simultanément vers SFTP et WebDAV
|
||||
sbackup save --sftp --webdav
|
||||
|
||||
# ============ Adresses de services WebDAV courants ============
|
||||
# Jianguoyun: https://dav.jianguoyun.com/dav/
|
||||
# NextCloud: https://your-server/remote.php/dav/files/username/
|
||||
# Synology: https://your-synology:5006/webdav/
|
||||
```
|
||||
|
||||
**Sous-commandes webdav :**
|
||||
|
||||
| Sous-commande | Description | Exemple |
|
||||
|---------------|-------------|---------|
|
||||
| `webdav config` | Configurer les paramètres de connexion WebDAV (url/user/password/remote_path) | `sbackup webdav config --url ... --user ...` |
|
||||
| `webdav test` | Tester si la connexion WebDAV est disponible | `sbackup webdav test` |
|
||||
|
||||
| Paramètre | Valeur par défaut | Description |
|
||||
|-----------|-------------------|-------------|
|
||||
| `--url URL` | `""` | Adresse du serveur WebDAV (par ex. `https://dav.jianguoyun.com/dav/`) |
|
||||
| `--user USER` | `""` | Nom d'utilisateur WebDAV (généralement une adresse e-mail) |
|
||||
| `--password PASS` | `""` | Mot de passe WebDAV (pour Jianguoyun, générez un mot de passe d'application dans les paramètres) |
|
||||
| `--remote-path PATH` | `/` | Chemin de destination distant |
|
||||
|
||||
## Principe de fonctionnement
|
||||
|
||||
Sbackup implémente les fonctionnalités de sauvegarde de la manière suivante :
|
||||
|
||||
1. **Stockage des stratégies** : les stratégies de sauvegarde sont enregistrées dans un fichier JSON, contenant les chemins des dossiers, les dates de dernière modification, les chemins de destination, les motifs d'exclusion et les formats d'archivage par entrée.
|
||||
2. **Sauvegarde incrémentielle** : en comparant les dates de dernière modification des dossiers, seuls les dossiers modifiés sont sauvegardés.
|
||||
3. **Compression multi-format** : utilisation des modules Python intégrés `zipfile` et `tarfile`, ainsi que des bibliothèques tierces `zstandard` et `py7zr`, pour prendre en charge sept formats d'archivage.
|
||||
4. **Format par entrée** : chaque stratégie de sauvegarde peut spécifier un format d'archivage indépendant (`add --format`), prioritaire sur le paramètre global `--format` ; la valeur globale est utilisée si aucune n'est spécifiée.
|
||||
5. **Nettoyage des sauvegardes** : après une sauvegarde réussie, le répertoire cible est analysé, trié par date de modification, et les fichiers dépassant le nombre de rétention sont supprimés.
|
||||
6. **Sauvegarde chiffrée** : le format 7z supporte le chiffrement LZMA2, configurable via le paramètre `--password` ou le fichier `config.json`.
|
||||
7. **Sauvegarde planifiée** : la commande `watch` exécute la sauvegarde en boucle à l'intervalle spécifié, arrêt sécurisé avec `Ctrl+C`.
|
||||
8. **Historique de sauvegarde** : après chaque sauvegarde, l'horodatage, la taille du fichier et le nombre de fichiers sont enregistrés, avec conservation des 100 dernières entrées.
|
||||
9. **Sauvegarde SFTP distante** : implémentation d'un client SFTP basée sur la bibliothèque paramiko, avec test de connexion, création automatique de répertoires distants et upload avec barre de progression.
|
||||
|
||||
### Format du fichier de données
|
||||
|
||||
```json
|
||||
{
|
||||
"/path/to/source/folder": [
|
||||
1719235200.0,
|
||||
"/path/to/target/folder",
|
||||
[".git", "__pycache__"],
|
||||
""
|
||||
],
|
||||
"/path/to/another/folder": [
|
||||
1719235200.0,
|
||||
"/path/to/another/target",
|
||||
[".git"],
|
||||
"TAR_GZ"
|
||||
],
|
||||
"_history": [
|
||||
{
|
||||
"time": "2026-05-01T12:00:00",
|
||||
"source": "/path/to/source/folder",
|
||||
"size_mb": 12.5,
|
||||
"files_count": 150
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Chaque entrée de stratégie de sauvegarde est une liste de 4 éléments : `[mtime, target, skip_patterns, compression_format]`
|
||||
|
||||
| Champ | Description |
|
||||
|-------|-------------|
|
||||
| `mtime` | Date de dernière modification du dossier source (utilisée pour la décision de sauvegarde incrémentielle) |
|
||||
| `target` | Chemin de destination pour le fichier de sauvegarde |
|
||||
| `skip_patterns` | Liste des motifs de fichiers/dossiers à ignorer |
|
||||
| `compression_format` | Format d'archivage au niveau de l'entrée (chaîne vide = utilisation de la valeur globale par défaut) |
|
||||
|
||||
## Guide de developpement
|
||||
|
||||
### Executer les tests
|
||||
|
||||
```bash
|
||||
uv run coverage run -m unittest discover -s tests -t . && uv run coverage report -m
|
||||
```
|
||||
|
||||
### Structure du code
|
||||
|
||||
```
|
||||
sbackup/
|
||||
├── main.py # Point d'entrée du programme
|
||||
├── sbackup/
|
||||
│ ├── __init__.py # Export des fonctions principales
|
||||
│ ├── __main__.py # Point d'entrée python -m sbackup
|
||||
│ ├── cli.py # Analyse des arguments CLI et dispatch des commandes (30+ commandes)
|
||||
│ ├── config.py # Chargement de la configuration, chiffrement, configuration Webhook/SMTP
|
||||
│ ├── auto_save.py # Moteur principal BackupManager
|
||||
│ ├── compression.py # Moteur de compression/décompression pour 7 formats
|
||||
│ ├── i18n.py # Internationalisation (9 langues)
|
||||
│ ├── sftp.py # Client de sauvegarde SFTP distant (paramiko)
|
||||
│ ├── webdav.py # Client de sauvegarde WebDAV distant (sans dépendance)
|
||||
│ ├── cloud_storage.py # Client de stockage cloud S3 (minio)
|
||||
│ ├── multi_dest.py # Sauvegarde multi-destinations en parallèle
|
||||
│ ├── handlers.py # Gestionnaires de commandes SFTP/WebDAV/Remote/Schedule
|
||||
│ ├── hooks.py # Exécution des hooks Pre/Post
|
||||
│ ├── audit.py # Système de journal d'audit
|
||||
│ ├── profile.py # Gestion des profils de configuration
|
||||
│ ├── selective.py # Restauration sélective
|
||||
│ ├── cross_search.py # Recherche inter-archives
|
||||
│ ├── integrity.py # Sommes de contrôle SHA256
|
||||
│ ├── rotation.py # Stratégies de rotation des sauvegardes
|
||||
│ ├── dryrun.py # Aperçu en mode dry-run
|
||||
│ ├── diskcheck.py # Estimation de l'espace disque
|
||||
│ ├── task_queue.py # Système de file d'attente de tâches
|
||||
│ ├── schema.py # Validateur de configuration
|
||||
│ ├── benchmark.py # Benchmark de compression
|
||||
│ ├── chunked_backup.py# Sauvegarde incrémentielle par blocs
|
||||
│ ├── dedup.py # Dédoublonnage par fichier SHA256
|
||||
│ ├── export.py # Export des métadonnées (CSV/JSON)
|
||||
│ ├── monitor.py # Surveillance du système de fichiers (watchdog)
|
||||
│ ├── lock.py # Verrouillage de processus multiplateforme
|
||||
│ ├── retry.py # Réessai avec backoff exponentiel
|
||||
│ ├── ratelimiter.py # Limiteur de débit par jeton
|
||||
│ ├── keychain.py # Intégration du trousseau système
|
||||
│ ├── parity.py # Codes correcteurs d'erreurs Reed-Solomon
|
||||
│ ├── completion.py # Auto-complétion shell
|
||||
│ ├── wizard.py # Assistant de configuration interactif
|
||||
│ └── locales/ # Fichiers de traduction pour 9 langues
|
||||
└── tests/
|
||||
└── sbackup/
|
||||
└── test_*.py # 30 fichiers de test couvrant tous les modules
|
||||
```
|
||||
|
||||
### Ajouter une nouvelle fonctionnalité
|
||||
|
||||
1. Créer un nouveau fichier module dans le répertoire `sbackup/`
|
||||
2. Importer les fonctions de la nouvelle fonctionnalité dans `sbackup/__init__.py`
|
||||
3. Ajouter la logique de gestion de la nouvelle commande dans la fonction `run()`
|
||||
4. Ajouter le fichier de test correspondant dans le répertoire `tests/`
|
||||
|
||||
## Questions frequentes
|
||||
|
||||
### Q : Que faire si le fichier de stratégie de sauvegarde est supprimé par erreur ?
|
||||
|
||||
R : Les stratégies de sauvegarde sont stockées dans le fichier de données. En cas de suppression accidentelle, vous pouvez les recréer en réexécutant la commande `add`.
|
||||
|
||||
### Q : Comment modifier une stratégie de sauvegarde déjà ajoutée ?
|
||||
|
||||
R : Utilisez la commande `sbackup edit` : `sbackup edit <source> --dest <new_dest> --ignore <patterns> --format <fmt>`.
|
||||
|
||||
### Q : La sauvegarde distante est-elle prise en charge ?
|
||||
|
||||
R : Oui ! Trois méthodes de sauvegarde distante sont disponibles :
|
||||
- **SFTP** : configuration avec `sbackup sftp config`, téléchargement avec `sbackup save --sftp`
|
||||
- **WebDAV** : configuration avec `sbackup webdav config`, téléchargement avec `sbackup save --webdav` (compatible Jianguoyun / NextCloud / Synology)
|
||||
- **Stockage cloud S3** : configurer le champ `cloud` dans `config.json`, téléchargement avec `sbackup save --cloud`
|
||||
- Activation simultanée de plusieurs méthodes : `sbackup save --sftp --webdav --cloud`
|
||||
|
||||
### Q : Quelle est la différence entre tar.gz et ZIP ?
|
||||
|
||||
R : tar.gz est plus courant sous Linux/macOS avec un taux de compression légèrement supérieur ; ZIP est plus universel sous Windows avec la meilleure compatibilité. tar.bz2 et tar.xz offrent des taux de compression plus élevés mais sont plus lents. tar.zst est un algorithme moderne, extrêmement rapide avec un bon taux de compression. 7z offre le taux de compression le plus élevé et supporte le chiffrement.
|
||||
|
||||
### Q : Comment chiffrer une sauvegarde ?
|
||||
|
||||
R : Utilisez le format 7z avec un mot de passe : `uv run python main.py --format 7z save --password yourpassword`. Le mot de passe peut également être enregistré dans le champ `password` du fichier `config.json`.
|
||||
|
||||
### Q : Comment nettoyer automatiquement les anciennes sauvegardes ?
|
||||
|
||||
R : Utilisez le paramètre `--keep` : `uv run python main.py save --keep 5` ne conserve que les 5 fichiers de sauvegarde les plus récents. La sauvegarde planifiée le supporte également : `uv run python main.py watch --interval 60 --keep 10`.
|
||||
|
||||
### Q : Comment configurer une sauvegarde planifiée ?
|
||||
|
||||
R : Utilisez la commande `watch` : `uv run python main.py watch --interval 60` pour sauvegarder toutes les 60 minutes. Appuyez sur `Ctrl+C` pour arrêter.
|
||||
|
||||
### Q : Le stockage des mots de passe est-il sécurisé ?
|
||||
|
||||
R : Les mots de passe SFTP et de chiffrement 7z dans `config.json` sont stockés en **clair**. Veuillez vous assurer que l'accès au fichier `config.json` est limité aux utilisateurs de confiance (par exemple, `chmod 600 config.json`). Ne commitez pas un fichier `config.json` contenant des mots de passe dans un système de contrôle de version.
|
||||
|
||||
## Guide de contribution
|
||||
|
||||
Les Issues et Pull Requests sont les bienvenus !
|
||||
|
||||
1. Forker ce dépôt
|
||||
2. Créer votre branche de fonctionnalité (`git checkout -b feature/AmazingFeature`)
|
||||
3. Valider vos modifications (`git commit -m 'Add some AmazingFeature'`)
|
||||
4. Pousser vers la branche (`git push origin feature/AmazingFeature`)
|
||||
5. Soumettre une Pull Request
|
||||
|
||||
### Style de code
|
||||
|
||||
Ce projet suit les conventions PEP 8 et le Google Python Style Guide. Veuillez vous assurer que votre code :
|
||||
- Utilise des annotations de type
|
||||
- Suit les docstrings au format Google
|
||||
- Passe tous les tests unitaires
|
||||
|
||||
## Licence
|
||||
|
||||
Ce projet est sous licence GNU GPL v3.0. Pour plus de détails, consultez le fichier [LICENSE](../../LICENSE).
|
||||
|
||||
## Auteur
|
||||
|
||||
**xiatianxuan** (CodeSeed)
|
||||
|
||||
- [Gitee](https://gitee.com/xiatianxuan)
|
||||
- [Page personnelle](https://xnors-codeseed.pages.dev/)
|
||||
|
||||
## Remerciements
|
||||
|
||||
- [Xnors Studio](https://xnors.github.io/)
|
||||
|
||||
## Nous contacter
|
||||
|
||||
Pour toute question ou suggestion, envoyez un e-mail à : xiatianxuan2025@163.com
|
||||
|
||||
---
|
||||
|
||||
*Dernière mise à jour : 19 juin 2026*
|
||||
@@ -0,0 +1,665 @@
|
||||
# Sbackup
|
||||
|
||||
[](https://www.python.org/)
|
||||
[](../../LICENSE)
|
||||
[](https://pypi.org/project/sbackup-cli/)
|
||||
[](../../.github/workflows/ci.yml)
|
||||
[]()
|
||||
|
||||
> 軽量で高効率なフォルダバックアップツール。コマンドラインでバックアップ戦略を簡単に管理できます。
|
||||
|
||||
[English](../../README.md) | [Deutsch](README_de.md) | [Espanol](README_es.md) | [Francais](README_fr.md) | [Portugues](README_pt.md) | [Pycckuu](README_ru.md) | [日本語](README_ja.md) | [한국어](README_ko.md) | [中文](README_zh.md)
|
||||
|
||||
- [はじめに](#はじめに)
|
||||
- [機能一覧](#機能一覧)
|
||||
- [クイックスタート](#クイックスタート)
|
||||
- [インストール](#インストール)
|
||||
- [使い方](#使い方)
|
||||
- [設定ファイル](#設定ファイル)
|
||||
- [設定例](#設定例)
|
||||
- [SFTP リモートバックアップ](#sftp-リモートバックアップ)
|
||||
- [WebDAV リモートバックアップ](#webdav-リモートバックアップ)
|
||||
- [仕組み](#仕組み)
|
||||
- [開発ガイド](#開発ガイド)
|
||||
- [テスト実行](#テスト実行)
|
||||
- [コード構造](#コード構造)
|
||||
- [よくある質問](#よくある質問)
|
||||
- [コントリビューションガイド](#コントリビューションガイド)
|
||||
- [ライセンス](#ライセンス)
|
||||
- [著者](#著者)
|
||||
|
||||
---
|
||||
|
||||
## はじめに
|
||||
|
||||
Sbackup は軽量なフォルダバックアップツールです。コマンドラインからバックアップ戦略の追加、削除、表示が可能です。フォルダの最終更新日時を基にバックアップが必要かどうかを判断し、データを常に最新の状態に保ちます。
|
||||
|
||||
## 機能一覧
|
||||
|
||||
- **増分バックアップ**: 変更されたフォルダのみをバックアップし、時間とストレージを節約
|
||||
- **多形式対応**: ZIP、tar、tar.gz、tar.bz2、tar.xz、tar.zst、7z の 7 種類のアーカイブ形式に対応。グローバルおよびエントリ単位で個別に指定可能
|
||||
- **SFTP リモートバックアップ**: paramiko ベース。パスワード/SSH 秘密鍵認証、デフォルト秘密鍵の自動検出に対応
|
||||
- **WebDAV リモートバックアップ**: Python 標準ライブラリ urllib ベース。追加依存なし。Jianguoyun/NextCloud/Synology 対応
|
||||
- **S3 クラウドストレージ**: minio ベース。すべての S3 互換ストレージ（AWS/MinIO/Alibaba Cloud OSS 等）に対応
|
||||
- **マルチターゲット並列バックアップ**: ローカルと複数のリモートターゲットへ同時にバックアップ。互いに影響しない
|
||||
- **バックアップ復元**: バックアップファイルからの解凍・復元に対応。選択的な復元も可能
|
||||
- **バックアップクリーンアップ**: 古いバックアップの自動削除。数量/日数/日別保持ポリシーに対応
|
||||
- **暗号化バックアップ**: 7z 形式のパスワード暗号化と全形式 PBKDF2 暗号化に対応
|
||||
- **定期バックアップ**: 指定間隔での自動実行。リアルタイムファイル監視（watchdog）に対応
|
||||
- **バックアップ履歴**: 各バックアップの時刻、サイズ、SHA256 チェックサムを記録し、追跡を容易に
|
||||
- **監査ログ**: すべてのバックアップ/復元操作の監査イベントを記録
|
||||
- **Pre/Post Hook**: バックアップ前後にカスタムコマンドを実行
|
||||
- **設定 Profile**: 複数の設定プロファイルの保存、切替、インポート/エクスポート
|
||||
- **クロスアーカイブ検索**: 複数のバックアップファイルにわたるファイル名検索
|
||||
- **データ整合性**: SHA256 チェックサムの生成と検証、Reed-Solomon 誤り訂正符号
|
||||
- **設定バリデーション**: 設定パラメータの自動検証、改ざん検出
|
||||
- **タスクキュー**: バックアップタスクキューの管理。追加、実行、キャンセルに対応
|
||||
- **圧縮ベンチマーク**: 異なる形式/圧縮レベルのパフォーマンス比較
|
||||
- **ディスク容量見積もり**: ファイルタイプ別のバックアップサイズ見積もり、ターゲット空き容量チェック
|
||||
- **国際化**: 中国語、英語、フランス語、スペイン語、ロシア語、ドイツ語、日本語、ポルトガル語、韓国語の 9 言語に対応
|
||||
- **Shell 補完**: bash/zsh/fish/powershell での自動補完に対応
|
||||
- **軽量高効率**: 小さなサイズ、高速起動、リソース消費が低い
|
||||
- **クロスプラットフォーム対応**: Windows、macOS、Linux に対応
|
||||
|
||||
## クイックスタート
|
||||
|
||||
### インストール
|
||||
|
||||
#### pip でのインストール
|
||||
|
||||
```bash
|
||||
pip install sbackup-cli
|
||||
```
|
||||
|
||||
インストール後、`sbackup` コマンドが使用可能になります（PyPI パッケージ名は `sbackup-cli`、CLI コマンドは `sbackup`）。
|
||||
|
||||
#### ソースからのインストール
|
||||
|
||||
```bash
|
||||
git clone https://github.com/xiatianxuan/sbackup.git
|
||||
cd sbackup
|
||||
uv sync
|
||||
```
|
||||
|
||||
### 使い方
|
||||
|
||||
#### 基本構文
|
||||
|
||||
```bash
|
||||
uv run python main.py <command> [options]
|
||||
```
|
||||
|
||||
#### 利用可能なコマンド
|
||||
|
||||
| コマンド | 説明 |
|
||||
|----------|------|
|
||||
| `add` | バックアップ戦略を追加 |
|
||||
| `rm` / `remove` | バックアップ戦略を削除 |
|
||||
| `edit` | 既存のバックアップ戦略を編集 |
|
||||
| `all` | すべてのバックアップ戦略を表示 |
|
||||
| `save` | バックアップを実行 |
|
||||
| `watch` | 定期バックアップを実行 |
|
||||
| `restore` | バックアップファイルから復元 |
|
||||
| `info` | バックアップファイルの詳細を表示 |
|
||||
| `diff` | ソースディレクトリとバックアップの差分を比較 |
|
||||
| `verify` | バックアップファイルの整合性を検証 |
|
||||
| `search` | バックアップ内をファイル検索 |
|
||||
| `xsearch` | 複数のバックアップアーカイブを横断検索 |
|
||||
| `versions` | バックアップバージョン履歴を表示 |
|
||||
| `sftp` | SFTP リモートバックアップ管理 |
|
||||
| `webdav` | WebDAV リモートバックアップ管理 |
|
||||
| `remote` | リモートファイル管理（list/rm） |
|
||||
| `task` | バックアップタスクキュー管理 |
|
||||
| `audit` | 監査ログ照会 |
|
||||
| `hooks` | Pre/Post Hook を手動実行 |
|
||||
| `profile` | 設定 Profile 管理 |
|
||||
| `rotate` | バックアップローテーションクリーンアップ |
|
||||
| `clean` | 古いバックアップをクリーンアップ |
|
||||
| `diskcheck` | ディスク容量見積もり |
|
||||
| `benchmark` | 圧縮形式ベンチマーク |
|
||||
| `integrity` | バックアップディレクトリ整合性検証 |
|
||||
| `dry-run` | バックアップファイル選択のプレビュー |
|
||||
| `export` / `import` | バックアップ戦略のエクスポート/インポート |
|
||||
| `ignore` | .sbackupignore ファイルを生成 |
|
||||
| `schedule` | 定期スケジュール設定をエクスポート |
|
||||
| `webhook` | Webhook プリセットを設定 |
|
||||
| `config` | 暗号化/検証の設定 |
|
||||
| `report` | バックアップレポートを生成 |
|
||||
| `completion` | Shell 補完スクリプトを生成 |
|
||||
| `wizard` | インタラクティブ設定ウィザード |
|
||||
| `status` | バックアップステータスダッシュボード |
|
||||
| `version` | バージョン情報を表示 |
|
||||
| `help` | ヘルプを表示 |
|
||||
|
||||
#### グローバルオプション
|
||||
|
||||
| オプション | 説明 |
|
||||
|-----------|------|
|
||||
| `--lang zh_CN` / `en_US` / `fr_FR` / `es_ES` / `ru_RU` / `de_DE` / `ja_JP` / `pt_BR` / `ko_KR` | UI 言語を設定（config.json に永続化） |
|
||||
| `--format zip` / `tar` / `tar.gz` / `tar.bz2` / `tar.xz` / `tar.zst` / `7z` | アーカイブ形式を設定（config.json に永続化） |
|
||||
| `--debug` | デバッグログを有効化 |
|
||||
|
||||
#### バックアップ戦略の追加
|
||||
|
||||
```bash
|
||||
uv run python main.py add <source> <dest> [-i ignore_patterns]
|
||||
```
|
||||
|
||||
パラメータ説明:
|
||||
- **source**: バックアップ対象のソースフォルダパス
|
||||
- **dest**: バックアップファイルの保存先パス
|
||||
- **-i, --ignore**: 無視するファイルまたはフォルダ名（カンマ区切り。デフォルト: `.git,__pycache__`）
|
||||
- **--format**: エントリ単位のアーカイブ形式（このバックアップ戦略のみに適用。未指定時はグローバルデフォルトを使用）: `zip` / `tar` / `tar.gz` / `tar.bz2` / `tar.xz` / `tar.zst` / `7z`
|
||||
|
||||
例:
|
||||
```bash
|
||||
# グローバルデフォルト形式で戦略を追加
|
||||
uv run python main.py add F:/my_folder F:/backup -i node_modules,.git
|
||||
|
||||
# この戦略に tar.gz 形式を指定（このフォルダのバックアップは常に tar.gz）
|
||||
uv run python main.py add F:/my_folder F:/backup --format tar.gz
|
||||
|
||||
# 7z 形式を指定（このフォルダのみ）
|
||||
uv run python main.py add F:/my_folder F:/backup --format 7z
|
||||
```
|
||||
|
||||
#### バックアップ戦略の削除
|
||||
|
||||
```bash
|
||||
uv run python main.py rm <path>
|
||||
```
|
||||
|
||||
パラメータ説明:
|
||||
- **path**: バックアップ戦略を削除するソースフォルダのパス
|
||||
|
||||
例:
|
||||
```bash
|
||||
uv run python main.py rm F:/my_folder
|
||||
```
|
||||
|
||||
#### すべてのバックアップ戦略を表示
|
||||
|
||||
```bash
|
||||
uv run python main.py all
|
||||
```
|
||||
|
||||
現在設定されているすべてのバックアップ戦略を表示します。
|
||||
|
||||
#### バックアップの実行
|
||||
|
||||
```bash
|
||||
# デフォルト形式（ZIP）を使用
|
||||
uv run python main.py save
|
||||
|
||||
# tar.gz 形式を使用
|
||||
uv run python main.py --format tar.gz save
|
||||
|
||||
# 直近 5 件のバックアップを保持し、古いものを自動クリーンアップ
|
||||
uv run python main.py save --keep 5
|
||||
|
||||
# 7z 形式で暗号化
|
||||
uv run python main.py --format 7z save --password mysecret
|
||||
|
||||
# 英語 UI + tar.xz 形式
|
||||
uv run python main.py --lang en_US --format tar.xz save
|
||||
```
|
||||
|
||||
**save コマンドのオプション:**
|
||||
|
||||
| オプション | デフォルト値 | 説明 |
|
||||
|-----------|-------------|------|
|
||||
| `--keep N` | `0` | 直近 N 件のバックアップファイルを保持。0 はクリーンアップなし |
|
||||
| `--password PASSWORD` | `""` | 暗号化パスワード（7z 形式のみ対応） |
|
||||
| `--sftp` | `false` | バックアップ完了後に SFTP サーバーへアップロード |
|
||||
| `--webdav` | `false` | バックアップ完了後に WebDAV サーバーへアップロード |
|
||||
|
||||
バックアップ戦略に基づき、変更されたフォルダを自動的にバックアップします。
|
||||
|
||||
#### 定期バックアップ
|
||||
|
||||
```bash
|
||||
# 60 分ごとにバックアップを実行
|
||||
uv run python main.py watch --interval 60
|
||||
|
||||
# 2 時間ごとにバックアップ、直近 10 ファイルを保持
|
||||
uv run python main.py watch --interval 120 --keep 10
|
||||
|
||||
# 定期バックアップ + 7z 暗号化
|
||||
uv run python main.py --format 7z watch --interval 60 --password mysecret
|
||||
```
|
||||
|
||||
**watch コマンドのオプション:**
|
||||
|
||||
| オプション | デフォルト値 | 説明 |
|
||||
|-----------|-------------|------|
|
||||
| `--interval MINUTES` | `60` | バックアップ間隔（分） |
|
||||
| `--keep N` | `0` | 直近 N 件のバックアップファイルを保持 |
|
||||
| `--password PASSWORD` | `""` | 暗号化パスワード（7z 形式のみ対応） |
|
||||
| `--sftp` | `false` | バックアップ後に SFTP サーバーへアップロード |
|
||||
| `--webdav` | `false` | バックアップ後に WebDAV サーバーへアップロード |
|
||||
|
||||
`Ctrl+C` で定期バックアップを停止できます。
|
||||
|
||||
#### バックアップの復元
|
||||
|
||||
```bash
|
||||
uv run python main.py restore <backup_file> <target_dir>
|
||||
```
|
||||
|
||||
パラメータ説明:
|
||||
- **backup_file**: バックアップファイルのパス（.zip / .tar / .tar.gz / .tar.bz2 / .tar.xz / .tar.zst / .7z 対応）
|
||||
- **target_dir**: 復元先ディレクトリ
|
||||
|
||||
例:
|
||||
```bash
|
||||
uv run python main.py restore F:/backup/my_folder.tar.gz F:/restored
|
||||
uv run python main.py restore F:/backup/my_folder.7z F:/restored
|
||||
uv run python main.py restore F:/backup/my_folder.tar.zst F:/restored
|
||||
```
|
||||
|
||||
#### SFTP リモートバックアップ
|
||||
|
||||
```bash
|
||||
# ============ クイックスタート（推奨） ============
|
||||
# 1. SFTP を設定（SSH 秘密鍵を自動検出、手動指定不要）
|
||||
sbackup sftp config --host 192.168.1.100 --user admin --remote-path /backups
|
||||
|
||||
# 2. 接続テスト
|
||||
sbackup sftp test
|
||||
|
||||
# 3. バックアップ実行とアップロード
|
||||
sbackup save --sftp
|
||||
|
||||
# ============ 認証方式 ============
|
||||
|
||||
# 方式 1: 秘密鍵の自動検出（推奨）
|
||||
# ~/.ssh/id_ed25519 → id_rsa → id_ecdsa を自動的に試行
|
||||
sbackup sftp config --host 192.168.1.100 --user admin
|
||||
|
||||
# 方式 2: パスワード認証
|
||||
sbackup sftp config --host 192.168.1.100 --user admin --password secret
|
||||
|
||||
# 方式 3: 秘密鍵を指定
|
||||
sbackup sftp config --host 192.168.1.100 --user admin --key-file ~/.ssh/id_rsa
|
||||
|
||||
# 方式 4: 秘密鍵 + パスフレーズ（対話的入力）
|
||||
sbackup sftp config --host 192.168.1.100 --user admin --key-file ~/.ssh/id_rsa
|
||||
|
||||
# 方式 5: 秘密鍵 + パスフレーズ（コマンドラインで指定）
|
||||
sbackup sftp config --host 192.168.1.100 --user admin --key-file ~/.ssh/id_rsa --key-passphrase mykeypass
|
||||
|
||||
# ============ 使用シーン ============
|
||||
|
||||
# シーン 1: 1 回限りのバックアップとアップロード
|
||||
sbackup save --sftp
|
||||
|
||||
# シーン 2: 定期バックアップと自動アップロード（60 分ごと）
|
||||
sbackup watch --interval 60 --sftp
|
||||
|
||||
# シーン 3: 形式を指定してバックアップ + アップロード
|
||||
sbackup --format tar.gz save --sftp
|
||||
|
||||
# シーン 4: 暗号化バックアップ + アップロード
|
||||
sbackup --format 7z save --password mysecret --sftp
|
||||
|
||||
# シーン 5: 直近 5 件を保持 + アップロード
|
||||
sbackup save --keep 5 --sftp
|
||||
|
||||
# ============ 高度な使い方 ============
|
||||
|
||||
# インタラクティブ設定（すべてのパラメータを順に入力）
|
||||
sbackup sftp config
|
||||
|
||||
# 非インタラクティブ設定（すべてのパラメータをコマンドラインで指定）
|
||||
sbackup sftp config --host 192.168.1.100 --port 22 --user admin --password secret --remote-path /backups
|
||||
|
||||
# 接続テストと詳細ログ表示
|
||||
sbackup --debug sftp test
|
||||
```
|
||||
|
||||
**sftp サブコマンド:**
|
||||
|
||||
| サブコマンド | 説明 | 例 |
|
||||
|-------------|------|-----|
|
||||
| `sftp config` | SFTP 接続パラメータを設定（host/port/user/password/key_file/key_passphrase/remote_path） | `sbackup sftp config --host 192.168.1.100 --user admin` |
|
||||
| `sftp test` | SFTP 接続のテスト | `sbackup sftp test` |
|
||||
|
||||
**認証方式:**
|
||||
|
||||
| 方式 | パラメータ | 説明 | 例 |
|
||||
|------|-----------|------|-----|
|
||||
| **自動検出** | 認証パラメータを指定しない | `~/.ssh/id_ed25519` → `id_rsa` → `id_ecdsa` を自動的に試行（推奨） | `sbackup sftp config --host ... --user ...` |
|
||||
| パスワード認証 | `--password` | パスワードで直接ログイン | `sbackup sftp config --host ... --user ... --password secret` |
|
||||
| 秘密鍵認証 | `--key-file` | 指定した SSH 秘密鍵でログイン | `sbackup sftp config --host ... --user ... --key-file ~/.ssh/id_rsa` |
|
||||
| 秘密鍵+パスフレーズ | `--key-file` + `--key-passphrase` | 秘密鍵にパスフレーズがある場合に使用 | `sbackup sftp config --host ... --user ... --key-file ~/.ssh/id_rsa --key-passphrase mypass` |
|
||||
|
||||
対応する秘密鍵形式: RSA、Ed25519、ECDSA。
|
||||
|
||||
**クロスプラットフォームパス対応:**
|
||||
|
||||
| プラットフォーム | 秘密鍵パスの例 | 説明 |
|
||||
|-----------------|----------------|------|
|
||||
| Linux/macOS | `~/.ssh/id_rsa` | `/home/user/.ssh/id_rsa` に自動展開 |
|
||||
| Windows | `~/.ssh/id_rsa` | `C:\Users\username\.ssh\id_rsa` に自動展開 |
|
||||
| 全プラットフォーム | 絶対パス | 完全なパスを直接使用 |
|
||||
|
||||
SFTP 設定は `config.json` の `sftp` フィールドに保存されます。コマンドライン引数または対話的入力で設定できます。
|
||||
|
||||
#### バージョン情報の表示
|
||||
|
||||
```bash
|
||||
sbackup version
|
||||
```
|
||||
|
||||
## 設定ファイル
|
||||
|
||||
Sbackup は `config.json` ファイルによるカスタマイズ設定に対応しています。設定ファイルはプロジェクトルートディレクトリに配置してください。
|
||||
|
||||
### 設定項目の説明
|
||||
|
||||
```json
|
||||
{
|
||||
"compression_format": "ZIP",
|
||||
"compression": {
|
||||
"algorithm": "ZIP_DEFLATED",
|
||||
"level": 6
|
||||
},
|
||||
"skip_patterns": [".git", "__pycache__"],
|
||||
"data_file": "sbackup.json",
|
||||
"lang": "zh_CN",
|
||||
"password": "",
|
||||
"sftp": {
|
||||
"host": "",
|
||||
"port": 22,
|
||||
"user": "",
|
||||
"password": "",
|
||||
"key_file": "",
|
||||
"key_passphrase": "",
|
||||
"remote_path": "/",
|
||||
"enabled": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| 設定項目 | 型 | デフォルト値 | 説明 |
|
||||
|---------|-----|------------|------|
|
||||
| `compression_format` | string | `"ZIP"` | アーカイブ形式。選択肢: `ZIP`, `TAR`, `TAR_GZ`, `TAR_BZ2`, `TAR_XZ`, `TAR_ZST`, `7Z` |
|
||||
| `compression.algorithm` | string | `"ZIP_DEFLATED"` | ZIP 圧縮アルゴリズム。選択肢: `ZIP_DEFLATED`, `ZIP_STORED`, `ZIP_BZIP2`, `ZIP_LZMA` |
|
||||
| `compression.level` | int | `6` | 圧縮レベル（0-9）。0 は無圧縮、9 が最高圧縮 |
|
||||
| `skip_patterns` | list | `[".git", "__pycache__"]` | 無視するファイルまたはフォルダのパターン（fnmatch ワイルドカードとパスマッチに対応） |
|
||||
| `data_file` | string | プラットフォームのデフォルトパス | バックアップ戦略データファイルの保存先 |
|
||||
| `lang` | string | `"zh_CN"` | UI 言語。選択肢: `zh_CN`, `en_US`, `fr_FR`, `es_ES`, `ru_RU`, `de_DE`, `ja_JP`, `pt_BR`, `ko_KR` |
|
||||
| `password` | string | `""` | 7z 暗号化パスワード |
|
||||
| `sftp.host` | string | `""` | SFTP サーバーアドレス |
|
||||
| `sftp.port` | int | `22` | SFTP ポート |
|
||||
| `sftp.user` | string | `""` | SFTP ユーザー名 |
|
||||
| `sftp.password` | string | `""` | SFTP パスワード（パスワード認証時に使用） |
|
||||
| `sftp.key_file` | string | `""` | SSH 秘密鍵ファイルのパス（秘密鍵認証時に使用。推奨） |
|
||||
| `sftp.key_passphrase` | string | `""` | 秘密鍵のパスフレーズ（必要な場合） |
|
||||
| `sftp.remote_path` | string | `"/"` | リモートターゲットパス |
|
||||
| `sftp.enabled` | bool | `false` | SFTP を有効にするか |
|
||||
|
||||
### 設定例
|
||||
|
||||
tar.bz2 形式で高圧縮率バックアップを行う場合:
|
||||
|
||||
```json
|
||||
{
|
||||
"compression_format": "TAR_BZ2",
|
||||
"compression_level": 9,
|
||||
"skip_patterns": [".git", "__pycache__", "node_modules", "*.log"],
|
||||
"data_file": "backup_strategies.json",
|
||||
"lang": "zh_CN"
|
||||
}
|
||||
```
|
||||
|
||||
### アーカイブ形式の比較
|
||||
|
||||
| 形式 | 拡張子 | 圧縮率 | 速度 | 依存関係 | 適用シーン |
|
||||
|------|--------|--------|------|---------|-----------|
|
||||
| ZIP | .zip | 中 | 高速 | 標準ライブラリ | 汎用。Windows での互換性が最も高い |
|
||||
| tar | .tar | なし | 超高速 | 標準ライブラリ | アーカイブのみ。外部圧縮と組み合わせ |
|
||||
| tar.gz | .tar.gz | 中 | 高速 | 標準ライブラリ | Linux/macOS で一般的 |
|
||||
| tar.bz2 | .tar.bz2 | 高 | 中 | 標準ライブラリ | 高圧縮率アーカイブ |
|
||||
| tar.xz | .tar.xz | 最高 | 低速 | 標準ライブラリ | 長期保存。容量制限が厳しい場合 |
|
||||
| tar.zst | .tar.zst | 中高 | 超高速 | zstandard | モダンな用途。速度と圧縮率のバランス |
|
||||
| 7z | .7z | 極高 | 低速 | py7zr | 最高圧縮率。暗号化対応 |
|
||||
|
||||
#### WebDAV リモートバックアップ
|
||||
|
||||
WebDAV は HTTP ベースのファイルプロトコルで、Jianguoyun（坚果云）、NextCloud、Synology（群晖）などの主要クラウドストレージに対応しています。Python 標準ライブラリ `urllib` を使用するため、**追加の依存は不要**です。
|
||||
|
||||
```bash
|
||||
# ============ クイックスタート ============
|
||||
# 1. WebDAV を設定
|
||||
sbackup webdav config --url https://dav.jianguoyun.com/dav/ --user user@example.com --password secret
|
||||
|
||||
# 2. 接続テスト
|
||||
sbackup webdav test
|
||||
|
||||
# 3. バックアップ実行とアップロード
|
||||
sbackup save --webdav
|
||||
|
||||
# ============ 使用シーン ============
|
||||
|
||||
# シーン 1: 1 回限りのバックアップとアップロード
|
||||
sbackup save --webdav
|
||||
|
||||
# シーン 2: 定期バックアップと自動アップロード（60 分ごと）
|
||||
sbackup watch --interval 60 --webdav
|
||||
|
||||
# シーン 3: リモートサブディレクトリを指定
|
||||
sbackup webdav config --url https://dav.jianguoyun.com/dav/ --user user@example.com --remote-path /backups/sbackup
|
||||
|
||||
# シーン 4: SFTP と WebDAV へ同時にアップロード
|
||||
sbackup save --sftp --webdav
|
||||
|
||||
# ============ 主要な WebDAV サービスのアドレス ============
|
||||
# 坚果云: https://dav.jianguoyun.com/dav/
|
||||
# NextCloud: https://your-server/remote.php/dav/files/username/
|
||||
# 群晖: https://your-synology:5006/webdav/
|
||||
```
|
||||
|
||||
**webdav サブコマンド:**
|
||||
|
||||
| サブコマンド | 説明 | 例 |
|
||||
|-------------|------|-----|
|
||||
| `webdav config` | WebDAV 接続パラメータを設定（url/user/password/remote_path） | `sbackup webdav config --url ... --user ...` |
|
||||
| `webdav test` | WebDAV 接続のテスト | `sbackup webdav test` |
|
||||
|
||||
| パラメータ | デフォルト値 | 説明 |
|
||||
|-----------|-------------|------|
|
||||
| `--url URL` | `""` | WebDAV サーバーアドレス（例: `https://dav.jianguoyun.com/dav/`） |
|
||||
| `--user USER` | `""` | WebDAV ユーザー名（通常はメールアドレス） |
|
||||
| `--password PASS` | `""` | WebDAV パスワード（Jianguoyun では設定画面でアプリパスワードを生成） |
|
||||
| `--remote-path PATH` | `/` | リモートターゲットパス |
|
||||
|
||||
## 仕組み
|
||||
|
||||
Sbackup は以下の方法でバックアップ機能を実現しています。
|
||||
|
||||
1. **バックアップ戦略の保存**: バックアップ戦略は JSON ファイルに保存されます。フォルダパス、最終更新日時、ターゲットパス、無視パターン、エントリ単位のアーカイブ形式を含みます。
|
||||
2. **増分バックアップ**: フォルダの最終更新日時を比較し、変更されたフォルダのみをバックアップします。
|
||||
3. **マルチ形式圧縮**: Python 組み込みの `zipfile` および `tarfile` モジュールに加え、`zstandard` と `py7zr` のサードパーティライブラリを使用し、7 種類のアーカイブ形式に対応しています。
|
||||
4. **エントリ単位の形式**: 各バックアップ戦略は個別のアーカイブ形式を指定できます（`add --format`）。グローバルの `--format` 設定より優先されます。未指定の場合はグローバルデフォルトを使用します。
|
||||
5. **バックアップクリーンアップ**: バックアップ成功後、ターゲットディレクトリをスキャンし、更新日時順にソートして、保持数を超える古いファイルを削除します。
|
||||
6. **暗号化バックアップ**: 7z 形式は LZMA2 暗号化に対応。`--password` パラメータまたは `config.json` で設定します。
|
||||
7. **定期バックアップ**: `watch` コマンドは指定された間隔でバックアップをループ実行します。`Ctrl+C` で安全に終了できます。
|
||||
8. **バックアップ履歴**: 各バックアップ後にタイムスタンプ、ファイルサイズ、ファイル数を記録し、直近 100 件のレコードを保持します。
|
||||
9. **SFTP リモートバックアップ**: paramiko ベースの SFTP クライアントを実装。接続テスト、リモートディレクトリの自動作成、プログレスバー付きファイルアップロードに対応。
|
||||
|
||||
### データファイルの形式
|
||||
|
||||
```json
|
||||
{
|
||||
"/path/to/source/folder": [
|
||||
1719235200.0,
|
||||
"/path/to/target/folder",
|
||||
[".git", "__pycache__"],
|
||||
""
|
||||
],
|
||||
"/path/to/another/folder": [
|
||||
1719235200.0,
|
||||
"/path/to/another/target",
|
||||
[".git"],
|
||||
"TAR_GZ"
|
||||
],
|
||||
"_history": [
|
||||
{
|
||||
"time": "2026-05-01T12:00:00",
|
||||
"source": "/path/to/source/folder",
|
||||
"size_mb": 12.5,
|
||||
"files_count": 150
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
各バックアップ戦略エントリは 4 要素のリストです: `[mtime, target, skip_patterns, compression_format]`
|
||||
|
||||
| フィールド | 説明 |
|
||||
|-----------|------|
|
||||
| `mtime` | ソースフォルダの最終更新日時（増分バックアップの判定に使用） |
|
||||
| `target` | バックアップファイルの保存先パス |
|
||||
| `skip_patterns` | 無視するファイル/フォルダパターンのリスト |
|
||||
| `compression_format` | エントリ単位のアーカイブ形式（空文字列はグローバルデフォルトを使用） |
|
||||
|
||||
## 開発ガイド
|
||||
|
||||
### テスト実行
|
||||
|
||||
```bash
|
||||
uv run coverage run -m unittest discover -s tests -t . && uv run coverage report -m
|
||||
```
|
||||
|
||||
### コード構造
|
||||
|
||||
```
|
||||
sbackup/
|
||||
├── main.py # プログラムエントリポイント
|
||||
├── sbackup/
|
||||
│ ├── __init__.py # コア関数をエクスポート
|
||||
│ ├── __main__.py # python -m sbackup エントリポイント
|
||||
│ ├── cli.py # CLI 引数解析とコマンドディスパッチ（30 以上のコマンド）
|
||||
│ ├── config.py # 設定読み込み、暗号化、Webhook/SMTP 設定
|
||||
│ ├── auto_save.py # BackupManager コアエンジン
|
||||
│ ├── compression.py # 7 形式の圧縮/解凍エンジン
|
||||
│ ├── i18n.py # 国際化（9 言語）
|
||||
│ ├── sftp.py # SFTP リモートバックアップクライアント（paramiko）
|
||||
│ ├── webdav.py # WebDAV リモートバックアップクライアント（依存なし）
|
||||
│ ├── cloud_storage.py # S3 クラウドストレージクライアント（minio）
|
||||
│ ├── multi_dest.py # マルチターゲット並列バックアップ
|
||||
│ ├── handlers.py # SFTP/WebDAV/Remote/Schedule コマンドハンドラ
|
||||
│ ├── hooks.py # Pre/Post Hook 実行
|
||||
│ ├── audit.py # 監査ログシステム
|
||||
│ ├── profile.py # 設定 Profile 管理
|
||||
│ ├── selective.py # 選択的復元
|
||||
│ ├── cross_search.py # クロスアーカイブ検索
|
||||
│ ├── integrity.py # SHA256 チェックサム
|
||||
│ ├── rotation.py # バックアップローテーションポリシー
|
||||
│ ├── dryrun.py # Dry-run プレビュー
|
||||
│ ├── diskcheck.py # ディスク容量見積もり
|
||||
│ ├── task_queue.py # タスクキューシステム
|
||||
│ ├── schema.py # 設定バリデーター
|
||||
│ ├── benchmark.py # 圧縮ベンチマーク
|
||||
│ ├── chunked_backup.py# ブロックレベル増分バックアップ
|
||||
│ ├── dedup.py # ファイルレベル SHA256 重複排除
|
||||
│ ├── export.py # メタデータエクスポート（CSV/JSON）
|
||||
│ ├── monitor.py # watchdog ファイルシステム監視
|
||||
│ ├── lock.py # クロスプラットフォームプロセスロック
|
||||
│ ├── retry.py # 指数バックオフリトライ
|
||||
│ ├── ratelimiter.py # トークンバケットレートリミッター
|
||||
│ ├── keychain.py # システムキーチェーン統合
|
||||
│ ├── parity.py # Reed-Solomon 誤り訂正符号
|
||||
│ ├── completion.py # Shell 自動補完
|
||||
│ ├── wizard.py # インタラクティブ設定ウィザード
|
||||
│ └── locales/ # 9 言語の翻訳ファイル
|
||||
└── tests/
|
||||
└── sbackup/
|
||||
└── test_*.py # 30 個のテストファイル。すべてのモジュールをカバー
|
||||
```
|
||||
|
||||
### 新機能の追加
|
||||
|
||||
1. `sbackup/` ディレクトリに新しいモジュールファイルを作成
|
||||
2. `sbackup/__init__.py` で新機能の関数をインポート
|
||||
3. `run()` 関数に新しいコマンドラインコマンドの処理ロジックを追加
|
||||
4. `tests/` ディレクトリに対応するテストファイルを追加
|
||||
|
||||
## よくある質問
|
||||
|
||||
### Q: バックアップ戦略ファイルを誤って削除してしまいました。どうすればよいですか？
|
||||
|
||||
A: バックアップ戦略はデータファイルに保存されています。誤って削除した場合は、`add` コマンドを再実行してバックアップ戦略を再追加してください。
|
||||
|
||||
### Q: 追加済みのバックアップ戦略を変更するにはどうすればよいですか？
|
||||
|
||||
A: `sbackup edit` コマンドを使用してください: `sbackup edit <source> --dest <new_dest> --ignore <patterns> --format <fmt>`。
|
||||
|
||||
### Q: リモートバックアップは対応していますか？
|
||||
|
||||
A: 対応しています。3 種類のリモートバックアップ方式があります:
|
||||
- **SFTP**: `sbackup sftp config` で設定、`sbackup save --sftp` でアップロード
|
||||
- **WebDAV**: `sbackup webdav config` で設定、`sbackup save --webdav` でアップロード（Jianguoyun/NextCloud/Synology 対応）
|
||||
- **S3 クラウドストレージ**: `config.json` の `cloud` フィールドで設定、`sbackup save --cloud` でアップロード
|
||||
- 複数を同時に有効化可能: `sbackup save --sftp --webdav --cloud`
|
||||
|
||||
### Q: tar.gz と ZIP の違いは何ですか？
|
||||
|
||||
A: tar.gz は Linux/macOS で一般的に使用され、圧縮率がやや高いです。ZIP は Windows で汎用的で互換性が最も高いです。tar.bz2 と tar.xz はさらに高い圧縮率を持ちますが速度は遅くなります。tar.zst はモダンなアルゴリズムで、高速かつ良好な圧縮率を備えています。7z は最高の圧縮率を持ち、暗号化にも対応しています。
|
||||
|
||||
### Q: バックアップを暗号化するにはどうすればよいですか？
|
||||
|
||||
A: 7z 形式を使用しパスワードを設定してください: `uv run python main.py --format 7z save --password yourpassword`。パスワードは `config.json` の `password` フィールドに記載することもできます。
|
||||
|
||||
### Q: 古いバックアップを自動的にクリーンアップするにはどうすればよいですか？
|
||||
|
||||
A: `--keep` パラメータを使用してください: `uv run python main.py save --keep 5` で直近 5 件のバックアップファイルのみを保持します。定期バックアップ時も同様に対応しています: `uv run python main.py watch --interval 60 --keep 10`。
|
||||
|
||||
### Q: 定期バックアップを設定するにはどうすればよいですか？
|
||||
|
||||
A: `watch` コマンドを使用してください: `uv run python main.py watch --interval 60` で 60 分ごとにバックアップを実行します。`Ctrl+C` で停止できます。
|
||||
|
||||
### Q: パスワードの保存は安全ですか？
|
||||
|
||||
A: `config.json` に保存される SFTP パスワードと 7z 暗号化パスワードは**プレーンテキスト**で保存されます。`config.json` ファイルへのアクセス権限を信頼できるユーザーのみに制限してください（例: `chmod 600 config.json`）。パスワードを含む `config.json` をバージョン管理システムにコミ밋しないでください。
|
||||
|
||||
## コントリビューションガイド
|
||||
|
||||
Issue と Pull Request の提出を歓迎します。
|
||||
|
||||
1. 本リポジトリを Fork
|
||||
2. 機能ブランチを作成 (`git checkout -b feature/AmazingFeature`)
|
||||
3. 変更をコミット (`git commit -m 'Add some AmazingFeature'`)
|
||||
4. ブランチにプッシュ (`git push origin feature/AmazingFeature`)
|
||||
5. Pull Request を提出
|
||||
|
||||
### コードスタイル
|
||||
|
||||
本プロジェクトは PEP 8 および Google Python Style Guide に準拠しています。以下の点を確認してください:
|
||||
- 型アノテーションを使用すること
|
||||
- Google スタイルの docstrings に従うこと
|
||||
- すべての単体テストに合格すること
|
||||
|
||||
## ライセンス
|
||||
|
||||
本プロジェクトは GNU GPL v3.0 ライセンスの下で提供されています。詳細は [LICENSE](../../LICENSE) ファイルを参照してください。
|
||||
|
||||
## 著者
|
||||
|
||||
**xiatianxuan** (CodeSeed)
|
||||
|
||||
- [Gitee](https://gitee.com/xiatianxuan)
|
||||
- [個人ページ](https://xnors-codeseed.pages.dev/)
|
||||
|
||||
## 謝辞
|
||||
|
||||
- [Xnors Studio](https://xnors.github.io/)
|
||||
|
||||
## お問い合わせ
|
||||
|
||||
ご質問やご提案がございましたら、以下のメールアドレスまでお問い合わせください: xiatianxuan2025@163.com
|
||||
|
||||
---
|
||||
|
||||
*最終更新: 2026年6月19日*
|
||||
@@ -0,0 +1,665 @@
|
||||
# Sbackup
|
||||
|
||||
[](https://www.python.org/)
|
||||
[](../../LICENSE)
|
||||
[](https://pypi.org/project/sbackup-cli/)
|
||||
[](../../.github/workflows/ci.yml)
|
||||
[]()
|
||||
|
||||
> 가볍고 효율적인 폴더 백업 도구로, CLI를 통해 백업 전략을 손쉽게 관리할 수 있습니다.
|
||||
|
||||
[English](../../README.md) | [Deutsch](README_de.md) | [Espanol](README_es.md) | [Francais](README_fr.md) | [Portugues](README_pt.md) | [Pycckuu](README_ru.md) | [日本語](README_ja.md) | [한국어](README_ko.md) | [中文](README_zh.md)
|
||||
|
||||
- [소개](#소개)
|
||||
- [주요 기능](#주요-기능)
|
||||
- [빠른 시작](#빠른-시작)
|
||||
- [설치](#설치)
|
||||
- [사용 방법](#사용-방법)
|
||||
- [설정 파일](#설정-파일)
|
||||
- [설정 예시](#설정-예시)
|
||||
- [SFTP 원격 백업](#sftp-원격-백업)
|
||||
- [WebDAV 원격 백업](#webdav-원격-백업)
|
||||
- [구현 원리](#구현-원리)
|
||||
- [개발 가이드](#개발-가이드)
|
||||
- [테스트 실행](#테스트-실행)
|
||||
- [코드 구조](#코드-구조)
|
||||
- [자주 묻는 질문](#자주-묻는-질문)
|
||||
- [기여 가이드](#기여-가이드)
|
||||
- [라이선스](#라이선스)
|
||||
- [저자](#저자)
|
||||
|
||||
---
|
||||
|
||||
## 소개
|
||||
|
||||
Sbackup는 CLI를 통해 백업 전략을 추가, 삭제, 조회할 수 있는 가벼운 폴더 백업 도구입니다. 폴더의 최종 수정 시간을 기준으로 백업이 필요한지 판단하여 데이터를 항상 최신 상태로 유지합니다.
|
||||
|
||||
## 주요 기능
|
||||
|
||||
- **증분 백업**: 변경된 폴더만 백업하여 시간과 저장 공간을 절약
|
||||
- **다중 포맷 지원**: ZIP, tar, tar.gz, tar.bz2, tar.xz, tar.zst, 7z 등 7가지 압축 포맷을 전략별 및 전역 수준에서 독립 지정 가능
|
||||
- **SFTP 원격 백업**: paramiko 기반, 비밀번호/SSH 개인키 인증 및 기본 개인키 자동 감지 지원
|
||||
- **WebDAV 원격 백업**: 표준 라이브러리 urllib 기반, 추가 의존성 없이 견과云/NextCloud/시놀로지 지원
|
||||
- **S3 클라우드 저장소**: minio 기반, 모든 S3 호환 저장소(AWS/MinIO/Alibaba Cloud OSS 등) 지원
|
||||
- **다중 대상 병렬 백업**: 로컬 + 여러 원격 대상에 동시에 백업, 상호 간섭 없음
|
||||
- **백업 복원**: 백업 파일에서 지정 디렉토리로 압축 해제 및 복원, 선택적 복원 지원
|
||||
- **백업 정리**: 오래된 백업 자동 삭제, 수량/시간/일별 보존 전략 지원
|
||||
- **암호화 백업**: 7z 포맷 비밀번호 암호화 + 전체 포맷 PBKDF2 암호화
|
||||
- **예약 백업**: 간격 기반 자동 실행, 실시간 파일 감시(watchdog) 지원
|
||||
- **백업 이력**: 각 백업의 시간, 크기, SHA256 체크섬 기록으로 추적 용이
|
||||
- **감사 로그**: 모든 백업/복원 작업의 감사 이벤트 기록
|
||||
- **Pre/Post Hook**: 백업 전후 사용자 정의 명령 실행
|
||||
- **설정 Profile**: 다중 설정 프로필의 저장, 전환, 가져오기/내보내기 지원
|
||||
- **크로스 아카이브 검색**: 여러 백업 파일에서 일치하는 파일명 검색
|
||||
- **데이터 무결성**: SHA256 체크섬 생성 및 검증, Reed-Solomon 오류 정정 코드
|
||||
- **설정 검증**: 설정 매개변수 유효성 자동 검증, 변조 감지
|
||||
- **작업 큐**: 백업 작업 큐 관리, 추가/실행/취소 지원
|
||||
- **압축 벤치마크**: 다양한 포맷/레벨의 압축 성능 비교
|
||||
- **디스크 공간 예측**: 파일 유형별 백업 크기 추정, 대상 공간 확인
|
||||
- **국제화**: 한국어, 영어, 중국어, 프랑스어, 스페인어, 러시아어, 독일어, 일본어, 포르투갈어 9개 언어 지원
|
||||
- **Shell 자동 완성**: bash/zsh/fish/powershell 자동 완성 지원
|
||||
- **가볍고 효율적**: 작은 용량, 빠른 시작 속도, 낮은 리소스 사용량
|
||||
- **크로스 플랫폼 지원**: Windows, macOS, Linux 지원
|
||||
|
||||
## 빠른 시작
|
||||
|
||||
### 설치
|
||||
|
||||
#### pip으로 설치
|
||||
|
||||
```bash
|
||||
pip install sbackup-cli
|
||||
```
|
||||
|
||||
설치 후 `sbackup` 명령을 사용합니다 (PyPI 패키지명: `sbackup-cli`, CLI 명령: `sbackup`).
|
||||
|
||||
#### 소스에서 설치
|
||||
|
||||
```bash
|
||||
git clone https://github.com/xiatianxuan/sbackup.git
|
||||
cd sbackup
|
||||
uv sync
|
||||
```
|
||||
|
||||
### 사용 방법
|
||||
|
||||
#### 기본 구문
|
||||
|
||||
```bash
|
||||
uv run python main.py <command> [options]
|
||||
```
|
||||
|
||||
#### 사용 가능한 명령
|
||||
|
||||
| 명령 | 설명 |
|
||||
|------|------|
|
||||
| `add` | 백업 전략 추가 |
|
||||
| `rm` / `remove` | 백업 전략 삭제 |
|
||||
| `edit` | 기존 백업 전략 편집 |
|
||||
| `all` | 모든 백업 전략 조회 |
|
||||
| `save` | 백업 실행 |
|
||||
| `watch` | 예약 백업 실행 |
|
||||
| `restore` | 백업 파일에서 복원 |
|
||||
| `info` | 백업 파일 상세 정보 조회 |
|
||||
| `diff` | 원본 디렉토리와 백업 간 차이 비교 |
|
||||
| `verify` | 백업 파일 무결성 검증 |
|
||||
| `search` | 백업 내 파일 검색 |
|
||||
| `xsearch` | 여러 백업 아카이브에서 검색 |
|
||||
| `versions` | 백업 버전 이력 조회 |
|
||||
| `sftp` | SFTP 원격 백업 관리 |
|
||||
| `webdav` | WebDAV 원격 백업 관리 |
|
||||
| `remote` | 원격 파일 관리 (list/rm) |
|
||||
| `task` | 백업 작업 큐 관리 |
|
||||
| `audit` | 감사 로그 조회 |
|
||||
| `hooks` | Pre/Post Hook 수동 실행 |
|
||||
| `profile` | 설정 Profile 관리 |
|
||||
| `rotate` | 백업 로테이션 정리 |
|
||||
| `clean` | 오래된 백업 정리 |
|
||||
| `diskcheck` | 디스크 공간 예측 |
|
||||
| `benchmark` | 압축 포맷 벤치마크 |
|
||||
| `integrity` | 백업 디렉토리 무결성 검증 |
|
||||
| `dry-run` | 백업 파일 선택 미리보기 |
|
||||
| `export` / `import` | 백업 전략 내보내기/가져오기 |
|
||||
| `ignore` | .sbackupignore 파일 생성 |
|
||||
| `schedule` | 예약 스케줄 설정 내보내기 |
|
||||
| `webhook` | Webhook 프리셋 설정 |
|
||||
| `config` | 암호화/검증 설정 |
|
||||
| `report` | 백업 보고서 생성 |
|
||||
| `completion` | Shell 자동 완성 스크립트 생성 |
|
||||
| `wizard` | 대화형 설정 마법사 |
|
||||
| `status` | 백업 상태 대시보드 |
|
||||
| `version` | 버전 정보 조회 |
|
||||
| `help` | 도움말 조회 |
|
||||
|
||||
#### 전역 매개변수
|
||||
|
||||
| 매개변수 | 설명 |
|
||||
|----------|------|
|
||||
| `--lang zh_CN` / `en_US` / `fr_FR` / `es_ES` / `ru_RU` / `de_DE` / `ja_JP` / `pt_BR` / `ko_KR` | 인터페이스 언어 설정 (config.json에 영구 저장) |
|
||||
| `--format zip` / `tar` / `tar.gz` / `tar.bz2` / `tar.xz` / `tar.zst` / `7z` | 압축 포맷 설정 (config.json에 영구 저장) |
|
||||
| `--debug` | 디버그 로그 활성화 |
|
||||
|
||||
#### 백업 전략 추가
|
||||
|
||||
```bash
|
||||
uv run python main.py add <source> <dest> [-i ignore_patterns]
|
||||
```
|
||||
|
||||
매개변수 설명:
|
||||
- **source**: 백업할 원본 폴더 경로
|
||||
- **dest**: 백업 파일 저장 대상 경로
|
||||
- **-i, --ignore**: 무시할 파일 또는 폴더 이름, 쉼표로 구분 (기본값: `.git,__pycache__`)
|
||||
- **--format**: 항목별 압축 포맷 (해당 백업 전략에만 적용, 미지정 시 전역 기본값 사용): `zip` / `tar` / `tar.gz` / `tar.bz2` / `tar.xz` / `tar.zst` / `7z`
|
||||
|
||||
예시:
|
||||
```bash
|
||||
# 전역 기본 포맷으로 전략 추가
|
||||
uv run python main.py add F:/my_folder F:/backup -i node_modules,.git
|
||||
|
||||
# 해당 전략에 tar.gz 포맷 지정 (이 폴더 백업 시 항상 tar.gz 사용)
|
||||
uv run python main.py add F:/my_folder F:/backup --format tar.gz
|
||||
|
||||
# 7z 포맷 지정 (해당 폴더만)
|
||||
uv run python main.py add F:/my_folder F:/backup --format 7z
|
||||
```
|
||||
|
||||
#### 백업 전략 삭제
|
||||
|
||||
```bash
|
||||
uv run python main.py rm <path>
|
||||
```
|
||||
|
||||
매개변수 설명:
|
||||
- **path**: 백업 전략을 삭제할 원본 폴더 경로
|
||||
|
||||
예시:
|
||||
```bash
|
||||
uv run python main.py rm F:/my_folder
|
||||
```
|
||||
|
||||
#### 모든 백업 전략 조회
|
||||
|
||||
```bash
|
||||
uv run python main.py all
|
||||
```
|
||||
|
||||
현재 설정된 모든 백업 전략을 표시합니다.
|
||||
|
||||
#### 백업 실행
|
||||
|
||||
```bash
|
||||
# 기본 포맷(ZIP) 사용
|
||||
uv run python main.py save
|
||||
|
||||
# tar.gz 포맷 사용
|
||||
uv run python main.py --format tar.gz save
|
||||
|
||||
# 최근 5개 백업 파일 유지, 오래된 파일 자동 정리
|
||||
uv run python main.py save --keep 5
|
||||
|
||||
# 7z 포맷으로 암호화
|
||||
uv run python main.py --format 7z save --password mysecret
|
||||
|
||||
# 영어 인터페이스 + tar.xz 포맷
|
||||
uv run python main.py --lang en_US --format tar.xz save
|
||||
```
|
||||
|
||||
**save 명령 매개변수:**
|
||||
|
||||
| 매개변수 | 기본값 | 설명 |
|
||||
|----------|--------|------|
|
||||
| `--keep N` | `0` | 최근 N개 백업 파일 유지, 0이면 정리 안 함 |
|
||||
| `--password PASSWORD` | `""` | 암호화 비밀번호 (7z 포맷만 지원) |
|
||||
| `--sftp` | `false` | 백업 완료 후 SFTP 서버에 업로드 |
|
||||
| `--webdav` | `false` | 백업 완료 후 WebDAV 서버에 업로드 |
|
||||
|
||||
백업 전략에 따라 변경된 폴더를 자동 백업합니다.
|
||||
|
||||
#### 예약 백업
|
||||
|
||||
```bash
|
||||
# 60분마다 백업 실행
|
||||
uv run python main.py watch --interval 60
|
||||
|
||||
# 2시간마다 백업, 최근 10개 파일 유지
|
||||
uv run python main.py watch --interval 120 --keep 10
|
||||
|
||||
# 예약 백업 + 7z 암호화
|
||||
uv run python main.py --format 7z watch --interval 60 --password mysecret
|
||||
```
|
||||
|
||||
**watch 명령 매개변수:**
|
||||
|
||||
| 매개변수 | 기본값 | 설명 |
|
||||
|----------|--------|------|
|
||||
| `--interval MINUTES` | `60` | 백업 간격 (분) |
|
||||
| `--keep N` | `0` | 최근 N개 백업 파일 유지 |
|
||||
| `--password PASSWORD` | `""` | 암호화 비밀번호 (7z 포맷만 지원) |
|
||||
| `--sftp` | `false` | 매 백업 후 SFTP 서버에 업로드 |
|
||||
| `--webdav` | `false` | 매 백업 후 WebDAV 서버에 업로드 |
|
||||
|
||||
`Ctrl+C`를 눌러 예약 백업을 중지합니다.
|
||||
|
||||
#### 백업 복원
|
||||
|
||||
```bash
|
||||
uv run python main.py restore <backup_file> <target_dir>
|
||||
```
|
||||
|
||||
매개변수 설명:
|
||||
- **backup_file**: 백업 파일 경로 (.zip / .tar / .tar.gz / .tar.bz2 / .tar.xz / .tar.zst / .7z 지원)
|
||||
- **target_dir**: 복원 대상 디렉토리
|
||||
|
||||
예시:
|
||||
```bash
|
||||
uv run python main.py restore F:/backup/my_folder.tar.gz F:/restored
|
||||
uv run python main.py restore F:/backup/my_folder.7z F:/restored
|
||||
uv run python main.py restore F:/backup/my_folder.tar.zst F:/restored
|
||||
```
|
||||
|
||||
#### SFTP 원격 백업
|
||||
|
||||
```bash
|
||||
# ============ 빠른 시작 (권장) ============
|
||||
# 1. SFTP 설정 (SSH 개인키 자동 감지, 수동 지정 불필요)
|
||||
sbackup sftp config --host 192.168.1.100 --user admin --remote-path /backups
|
||||
|
||||
# 2. 연결 테스트
|
||||
sbackup sftp test
|
||||
|
||||
# 3. 백업 실행 및 업로드
|
||||
sbackup save --sftp
|
||||
|
||||
# ============ 인증 방식 ============
|
||||
|
||||
# 방식 1: 개인키 자동 감지 (권장)
|
||||
# 시스템이 자동으로 ~/.ssh/id_ed25519 -> id_rsa -> id_ecdsa 순서로 시도
|
||||
sbackup sftp config --host 192.168.1.100 --user admin
|
||||
|
||||
# 방식 2: 비밀번호 인증
|
||||
sbackup sftp config --host 192.168.1.100 --user admin --password secret
|
||||
|
||||
# 방식 3: 개인키 지정
|
||||
sbackup sftp config --host 192.168.1.100 --user admin --key-file ~/.ssh/id_rsa
|
||||
|
||||
# 방식 4: 개인키 + 패스프레이즈 (대화형 입력)
|
||||
sbackup sftp config --host 192.168.1.100 --user admin --key-file ~/.ssh/id_rsa
|
||||
|
||||
# 방식 5: 개인키 + 패스프레이즈 (명령줄 지정)
|
||||
sbackup sftp config --host 192.168.1.100 --user admin --key-file ~/.ssh/id_rsa --key-passphrase mykeypass
|
||||
|
||||
# ============ 사용 시나리오 ============
|
||||
|
||||
# 시나리오 1: 일회성 백업 및 업로드
|
||||
sbackup save --sftp
|
||||
|
||||
# 시나리오 2: 예약 백업 및 자동 업로드 (60분마다)
|
||||
sbackup watch --interval 60 --sftp
|
||||
|
||||
# 시나리오 3: 특정 포맷 백업 + 업로드
|
||||
sbackup --format tar.gz save --sftp
|
||||
|
||||
# 시나리오 4: 암호화 백업 + 업로드
|
||||
sbackup --format 7z save --password mysecret --sftp
|
||||
|
||||
# 시나리오 5: 최근 5개 백업 유지 + 업로드
|
||||
sbackup save --keep 5 --sftp
|
||||
|
||||
# ============ 고급 사용법 ============
|
||||
|
||||
# 대화형 설정 (단계별로 모든 매개변수 입력)
|
||||
sbackup sftp config
|
||||
|
||||
# 비대화형 설정 (모든 매개변수를 명령줄에서 지정)
|
||||
sbackup sftp config --host 192.168.1.100 --port 22 --user admin --password secret --remote-path /backups
|
||||
|
||||
# 연결 테스트 및 상세 로그 확인
|
||||
sbackup --debug sftp test
|
||||
```
|
||||
|
||||
**sftp 하위 명령:**
|
||||
|
||||
| 하위 명령 | 설명 | 예시 |
|
||||
|-----------|------|------|
|
||||
| `sftp config` | SFTP 연결 매개변수 설정 (host/port/user/password/key_file/key_passphrase/remote_path) | `sbackup sftp config --host 192.168.1.100 --user admin` |
|
||||
| `sftp test` | SFTP 연결 가능 여부 테스트 | `sbackup sftp test` |
|
||||
|
||||
**인증 방식:**
|
||||
|
||||
| 방식 | 매개변수 | 설명 | 예시 |
|
||||
|------|----------|------|------|
|
||||
| **자동 감지** | 인증 매개변수 미지정 | `~/.ssh/id_ed25519` -> `id_rsa` -> `id_ecdsa` 순서로 자동 시도 (권장) | `sbackup sftp config --host ... --user ...` |
|
||||
| 비밀번호 인증 | `--password` | 비밀번호로 직접 로그인 | `sbackup sftp config --host ... --user ... --password secret` |
|
||||
| 개인키 인증 | `--key-file` | 지정된 SSH 개인키로 로그인 | `sbackup sftp config --host ... --user ... --key-file ~/.ssh/id_rsa` |
|
||||
| 개인키+패스프레이즈 | `--key-file` + `--key-passphrase` | 개인키에 패스프레이즈가 있는 경우 사용 | `sbackup sftp config --host ... --user ... --key-file ~/.ssh/id_rsa --key-passphrase mypass` |
|
||||
|
||||
지원되는 개인키 형식: RSA, Ed25519, ECDSA.
|
||||
|
||||
**크로스 플랫폼 경로 지원:**
|
||||
|
||||
| 플랫폼 | 개인키 경로 예시 | 설명 |
|
||||
|--------|-----------------|------|
|
||||
| Linux/macOS | `~/.ssh/id_rsa` | `/home/user/.ssh/id_rsa`로 자동 확장 |
|
||||
| Windows | `~/.ssh/id_rsa` | `C:\Users\username\.ssh\id_rsa`로 자동 확장 |
|
||||
| 전 플랫폼 | 절대 경로 | 전체 경로를 직접 사용 |
|
||||
|
||||
SFTP 설정은 `config.json`의 `sftp` 필드에 저장되며, 명령줄 매개변수 또는 대화형 입력으로 설정할 수 있습니다.
|
||||
|
||||
#### 버전 정보 조회
|
||||
|
||||
```bash
|
||||
sbackup version
|
||||
```
|
||||
|
||||
## 설정 파일
|
||||
|
||||
Sbackup는 `config.json` 파일을 통해 사용자 정의 설정을 지원합니다. 설정 파일은 프로젝트 루트 디렉토리에 배치해야 합니다.
|
||||
|
||||
### 설정 항목 설명
|
||||
|
||||
```json
|
||||
{
|
||||
"compression_format": "ZIP",
|
||||
"compression": {
|
||||
"algorithm": "ZIP_DEFLATED",
|
||||
"level": 6
|
||||
},
|
||||
"skip_patterns": [".git", "__pycache__"],
|
||||
"data_file": "sbackup.json",
|
||||
"lang": "zh_CN",
|
||||
"password": "",
|
||||
"sftp": {
|
||||
"host": "",
|
||||
"port": 22,
|
||||
"user": "",
|
||||
"password": "",
|
||||
"key_file": "",
|
||||
"key_passphrase": "",
|
||||
"remote_path": "/",
|
||||
"enabled": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| 설정 항목 | 타입 | 기본값 | 설명 |
|
||||
|-----------|------|--------|------|
|
||||
| `compression_format` | string | `"ZIP"` | 압축 포맷, 가능한 값: `ZIP`, `TAR`, `TAR_GZ`, `TAR_BZ2`, `TAR_XZ`, `TAR_ZST`, `7Z` |
|
||||
| `compression.algorithm` | string | `"ZIP_DEFLATED"` | ZIP 압축 알고리즘, 가능한 값: `ZIP_DEFLATED`, `ZIP_STORED`, `ZIP_BZIP2`, `ZIP_LZMA` |
|
||||
| `compression.level` | int | `6` | 압축 레벨, 범위 0-9 (0: 압축 없음, 9: 최대 압축) |
|
||||
| `skip_patterns` | list | `[".git", "__pycache__"]` | 무시할 파일 또는 폴더 패턴 (fnmatch 와일드카드 및 경로 매칭 지원) |
|
||||
| `data_file` | string | 플랫폼 기본 경로 | 백업 전략 데이터 파일 저장 경로 |
|
||||
| `lang` | string | `"zh_CN"` | 인터페이스 언어, 가능한 값: `zh_CN`, `en_US`, `fr_FR`, `es_ES`, `ru_RU`, `de_DE`, `ja_JP`, `pt_BR`, `ko_KR` |
|
||||
| `password` | string | `""` | 7z 암호화 비밀번호 |
|
||||
| `sftp.host` | string | `""` | SFTP 서버 주소 |
|
||||
| `sftp.port` | int | `22` | SFTP 포트 |
|
||||
| `sftp.user` | string | `""` | SFTP 사용자 이름 |
|
||||
| `sftp.password` | string | `""` | SFTP 비밀번호 (비밀번호 인증 시 사용) |
|
||||
| `sftp.key_file` | string | `""` | SSH 개인키 파일 경로 (개인키 인증 시 사용, 권장) |
|
||||
| `sftp.key_passphrase` | string | `""` | 개인키 패스프레이즈 (있는 경우) |
|
||||
| `sftp.remote_path` | string | `"/"` | 원격 대상 경로 |
|
||||
| `sftp.enabled` | bool | `false` | SFTP 활성화 여부 |
|
||||
|
||||
### 설정 예시
|
||||
|
||||
tar.bz2 포맷으로 고압축률 백업:
|
||||
|
||||
```json
|
||||
{
|
||||
"compression_format": "TAR_BZ2",
|
||||
"compression_level": 9,
|
||||
"skip_patterns": [".git", "__pycache__", "node_modules", "*.log"],
|
||||
"data_file": "backup_strategies.json",
|
||||
"lang": "zh_CN"
|
||||
}
|
||||
```
|
||||
|
||||
### 압축 포맷 비교
|
||||
|
||||
| 포맷 | 확장자 | 압축률 | 속도 | 의존성 | 적합한 시나리오 |
|
||||
|------|--------|--------|------|--------|----------------|
|
||||
| ZIP | .zip | 중간 | 빠름 | 표준 라이브러리 | 범용, Windows 호환성 최고 |
|
||||
| tar | .tar | 없음 | 매우 빠름 | 표준 라이브러리 | 순수 아카이브, 외부 압축과 결합 |
|
||||
| tar.gz | .tar.gz | 중간 | 빠름 | 표준 라이브러리 | Linux/macOS 범용 |
|
||||
| tar.bz2 | .tar.bz2 | 높음 | 중간 | 표준 라이브러리 | 고압축률 아카이브 |
|
||||
| tar.xz | .tar.xz | 최고 | 느림 | 표준 라이브러리 | 장기 아카이브, 공간 민감 |
|
||||
| tar.zst | .tar.zst | 중상 | 매우 빠름 | zstandard | 현대 시나리오, 속도와 압축률 균형 |
|
||||
| 7z | .7z | 매우 높음 | 느림 | py7zr | 최대 압축률, 암호화 지원 |
|
||||
|
||||
#### WebDAV 원격 백업
|
||||
|
||||
WebDAV는 HTTP 기반 파일 프로토콜로, 견과云, NextCloud, 시놀로지 등 주요 클라우드 스토리지를 지원합니다. Python 표준 라이브러리 `urllib`을 사용하여 **추가 의존성이 없습니다**.
|
||||
|
||||
```bash
|
||||
# ============ 빠른 시작 ============
|
||||
# 1. WebDAV 설정
|
||||
sbackup webdav config --url https://dav.jianguoyun.com/dav/ --user user@example.com --password secret
|
||||
|
||||
# 2. 연결 테스트
|
||||
sbackup webdav test
|
||||
|
||||
# 3. 백업 실행 및 업로드
|
||||
sbackup save --webdav
|
||||
|
||||
# ============ 사용 시나리오 ============
|
||||
|
||||
# 시나리오 1: 일회성 백업 및 업로드
|
||||
sbackup save --webdav
|
||||
|
||||
# 시나리오 2: 예약 백업 및 자동 업로드 (60분마다)
|
||||
sbackup watch --interval 60 --webdav
|
||||
|
||||
# 시나리오 3: 원격 하위 디렉토리 지정
|
||||
sbackup webdav config --url https://dav.jianguoyun.com/dav/ --user user@example.com --remote-path /backups/sbackup
|
||||
|
||||
# 시나리오 4: SFTP와 WebDAV에 동시 업로드
|
||||
sbackup save --sftp --webdav
|
||||
|
||||
# ============ 일반 WebDAV 서비스 주소 ============
|
||||
# 견과云: https://dav.jianguoyun.com/dav/
|
||||
# NextCloud: https://your-server/remote.php/dav/files/username/
|
||||
# 시놀로지: https://your-synology:5006/webdav/
|
||||
```
|
||||
|
||||
**webdav 하위 명령:**
|
||||
|
||||
| 하위 명령 | 설명 | 예시 |
|
||||
|-----------|------|------|
|
||||
| `webdav config` | WebDAV 연결 매개변수 설정 (url/user/password/remote_path) | `sbackup webdav config --url ... --user ...` |
|
||||
| `webdav test` | WebDAV 연결 가능 여부 테스트 | `sbackup webdav test` |
|
||||
|
||||
| 매개변수 | 기본값 | 설명 |
|
||||
|----------|--------|------|
|
||||
| `--url URL` | `""` | WebDAV 서버 주소 (예: `https://dav.jianguoyun.com/dav/`) |
|
||||
| `--user USER` | `""` | WebDAV 사용자 이름 (일반적으로 이메일) |
|
||||
| `--password PASS` | `""` | WebDAV 비밀번호 (견과云은 설정에서 앱 비밀번호를 생성해야 함) |
|
||||
| `--remote-path PATH` | `/` | 원격 대상 경로 |
|
||||
|
||||
## 구현 원리
|
||||
|
||||
Sbackup는 다음과 같은 방식으로 백업 기능을 구현합니다:
|
||||
|
||||
1. **백업 전략 저장**: 백업 전략은 JSON 파일에 저장되며, 폴더 경로, 최종 수정 시간, 대상 경로, 무시 패턴, 항목별 압축 포맷을 포함합니다.
|
||||
2. **증분 백업**: 폴더의 최종 수정 시간을 비교하여 변경된 폴더만 백업합니다.
|
||||
3. **다중 포맷 압축**: Python 내장 `zipfile` 및 `tarfile` 모듈과 `zstandard`, `py7zr` 서드파티 라이브러리를 사용하여 7가지 압축 포맷을 지원합니다.
|
||||
4. **항목별 포맷**: 각 백업 전략은 독립적인 압축 포맷을 지정할 수 있습니다 (`add --format`). 전역 `--format` 설정보다 우선하며, 미지정 시 전역 기본값을 사용합니다.
|
||||
5. **백업 정리**: 백업 성공 후 대상 디렉토리를 자동 스캔하여 수정 시간순으로 정렬하고, 보존 수량을 초과하는 오래된 파일을 삭제합니다.
|
||||
6. **암호화 백업**: 7z 포맷은 LZMA2 암호화를 지원하며, `--password` 매개변수 또는 `config.json` 설정을 통해 구성합니다.
|
||||
7. **예약 백업**: `watch` 명령은 지정된 간격으로 루프에서 백업을 실행하며, `Ctrl+C`로 안전하게 종료합니다.
|
||||
8. **백업 이력**: 매 백업 후 타임스탬프, 파일 크기, 파일 수를 기록하며, 최근 100개 기록을 유지합니다.
|
||||
9. **SFTP 원격 백업**: paramiko 라이브러리 기반 SFTP 클라이언트를 구현하며, 연결 테스트, 원격 디렉토리 자동 생성, 진행 표시줄이 포함된 파일 업로드를 지원합니다.
|
||||
|
||||
### 데이터 파일 형식
|
||||
|
||||
```json
|
||||
{
|
||||
"/path/to/source/folder": [
|
||||
1719235200.0,
|
||||
"/path/to/target/folder",
|
||||
[".git", "__pycache__"],
|
||||
""
|
||||
],
|
||||
"/path/to/another/folder": [
|
||||
1719235200.0,
|
||||
"/path/to/another/target",
|
||||
[".git"],
|
||||
"TAR_GZ"
|
||||
],
|
||||
"_history": [
|
||||
{
|
||||
"time": "2026-05-01T12:00:00",
|
||||
"source": "/path/to/source/folder",
|
||||
"size_mb": 12.5,
|
||||
"files_count": 150
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
각 백업 전략 항목은 4요소 리스트입니다: `[mtime, target, skip_patterns, compression_format]`
|
||||
|
||||
| 필드 | 설명 |
|
||||
|------|------|
|
||||
| `mtime` | 원본 폴더의 최종 수정 시간 (증분 백업 판단에 사용) |
|
||||
| `target` | 백업 파일 저장 대상 경로 |
|
||||
| `skip_patterns` | 무시할 파일/폴더 패턴 목록 |
|
||||
| `compression_format` | 항목별 압축 포맷 (빈 문자열이면 전역 기본값 사용) |
|
||||
|
||||
## 개발 가이드
|
||||
|
||||
### 테스트 실행
|
||||
|
||||
```bash
|
||||
uv run coverage run -m unittest discover -s tests -t . && uv run coverage report -m
|
||||
```
|
||||
|
||||
### 코드 구조
|
||||
|
||||
```
|
||||
sbackup/
|
||||
├── main.py # 프로그램 진입점
|
||||
├── sbackup/
|
||||
│ ├── __init__.py # 핵심 함수 내보내기
|
||||
│ ├── __main__.py # python -m sbackup 진입점
|
||||
│ ├── cli.py # CLI 매개변수 파싱 및 명령 분배 (30+ 명령)
|
||||
│ ├── config.py # 설정 로드, 암호화, Webhook/SMTP 설정
|
||||
│ ├── auto_save.py # BackupManager 핵심 엔진
|
||||
│ ├── compression.py # 7가지 포맷 압축/해제 엔진
|
||||
│ ├── i18n.py # 국제화 (9개 언어)
|
||||
│ ├── sftp.py # SFTP 원격 백업 클라이언트 (paramiko)
|
||||
│ ├── webdav.py # WebDAV 원격 백업 클라이언트 (무의존성)
|
||||
│ ├── cloud_storage.py # S3 클라우드 저장소 클라이언트 (minio)
|
||||
│ ├── multi_dest.py # 다중 대상 병렬 백업
|
||||
│ ├── handlers.py # SFTP/WebDAV/Remote/Schedule 명령 처리
|
||||
│ ├── hooks.py # Pre/Post Hook 실행
|
||||
│ ├── audit.py # 감사 로그 시스템
|
||||
│ ├── profile.py # 설정 Profile 관리
|
||||
│ ├── selective.py # 선택적 복원
|
||||
│ ├── cross_search.py # 크로스 아카이브 검색
|
||||
│ ├── integrity.py # SHA256 체크섬
|
||||
│ ├── rotation.py # 백업 로테이션 전략
|
||||
│ ├── dryrun.py # Dry-run 미리보기
|
||||
│ ├── diskcheck.py # 디스크 공간 예측
|
||||
│ ├── task_queue.py # 작업 큐 시스템
|
||||
│ ├── schema.py # 설정 검증기
|
||||
│ ├── benchmark.py # 압축 벤치마크
|
||||
│ ├── chunked_backup.py# 블록 단위 증분 백업
|
||||
│ ├── dedup.py # 파일 단위 SHA256 중복 제거
|
||||
│ ├── export.py # 메타데이터 내보내기 (CSV/JSON)
|
||||
│ ├── monitor.py # watchdog 파일 시스템 감시
|
||||
│ ├── lock.py # 크로스 플랫폼 프로세스 잠금
|
||||
│ ├── retry.py # 지수 백오프 재시도
|
||||
│ ├── ratelimiter.py # 토큰 버킷 속도 제한기
|
||||
│ ├── keychain.py # 시스템 키체인 통합
|
||||
│ ├── parity.py # Reed-Solomon 오류 정정 코드
|
||||
│ ├── completion.py # Shell 자동 완성
|
||||
│ ├── wizard.py # 대화형 설정 마법사
|
||||
│ └── locales/ # 9개 언어 번역 파일
|
||||
└── tests/
|
||||
└── sbackup/
|
||||
└── test_*.py # 30개 테스트 파일, 모든 모듈 커버
|
||||
```
|
||||
|
||||
### 새 기능 추가
|
||||
|
||||
1. `sbackup/` 디렉토리에 새 모듈 파일을 생성합니다
|
||||
2. `sbackup/__init__.py`에 새 기능의 함수를 임포트합니다
|
||||
3. `run()` 함수에 새로운 CLI 명령 처리 로직을 추가합니다
|
||||
4. `tests/` 디렉토리에 대응하는 테스트 파일을 추가합니다
|
||||
|
||||
## 자주 묻는 질문
|
||||
|
||||
### Q: 백업 전략 파일을 실수로 삭제하면 어떻게 하나요?
|
||||
|
||||
A: 백업 전략은 데이터 파일에 저장됩니다. 실수로 삭제한 경우 `add` 명령을 다시 실행하여 백업 전략을 다시 추가할 수 있습니다.
|
||||
|
||||
### Q: 이미 추가한 백업 전략을 어떻게 수정하나요?
|
||||
|
||||
A: `sbackup edit` 명령을 사용합니다: `sbackup edit <source> --dest <new_dest> --ignore <patterns> --format <fmt>`.
|
||||
|
||||
### Q: 원격 백업을 지원하나요?
|
||||
|
||||
A: 지원합니다! 세 가지 원격 백업 방식을 제공합니다:
|
||||
- **SFTP**: `sbackup sftp config`로 설정, `sbackup save --sftp`로 업로드
|
||||
- **WebDAV**: `sbackup webdav config`로 설정, `sbackup save --webdav`로 업로드 (견과云/NextCloud/시놀로지 지원)
|
||||
- **S3 클라우드 저장소**: `config.json`에서 `cloud` 필드 설정, `sbackup save --cloud`로 업로드
|
||||
- 동시에 여러 방식 사용 가능: `sbackup save --sftp --webdav --cloud`
|
||||
|
||||
### Q: tar.gz와 ZIP의 차이는 무엇인가요?
|
||||
|
||||
A: tar.gz는 Linux/macOS에서 더 일반적이며 압축률이 약간 높습니다. ZIP은 Windows에서 더 범용적이며 호환성이 가장 좋습니다. tar.bz2와 tar.xz는 더 높은 압축률을 제공하지만 속도가 느립니다. tar.zst는 현대 알고리즘으로 속도가 매우 빠르면서 압축률도 양호합니다. 7z는 압축률이 가장 높고 암호화를 지원합니다.
|
||||
|
||||
### Q: 백업을 어떻게 암호화하나요?
|
||||
|
||||
A: 7z 포맷을 사용하고 비밀번호를 설정합니다: `uv run python main.py --format 7z save --password yourpassword`. 비밀번호를 `config.json`의 `password` 필드에 작성할 수도 있습니다.
|
||||
|
||||
### Q: 오래된 백업을 어떻게 자동 정리하나요?
|
||||
|
||||
A: `--keep` 매개변수를 사용합니다: `uv run python main.py save --keep 5`로 최근 5개 백업 파일만 유지합니다. 예약 백업 시에도同样 지원합니다: `uv run python main.py watch --interval 60 --keep 10`.
|
||||
|
||||
### Q: 예약 백업을 어떻게 설정하나요?
|
||||
|
||||
A: `watch` 명령을 사용합니다: `uv run python main.py watch --interval 60`으로 60분마다 백업합니다. `Ctrl+C`로 중지합니다.
|
||||
|
||||
### Q: 비밀번호 저장이 안전한가요?
|
||||
|
||||
A: `config.json`에 저장된 SFTP 비밀번호와 7z 암호화 비밀번호는 **평문**으로 저장됩니다. `config.json` 파일의 접근 권한을 신뢰할 수 있는 사용자로만 제한하세요 (예: `chmod 600 config.json`). 비밀번호가 포함된 `config.json`을 버전控制系统에 커밋하지 마세요.
|
||||
|
||||
## 기여 가이드
|
||||
|
||||
Issue와 Pull Request를 환영합니다!
|
||||
|
||||
1. 이 저장소를 Fork합니다
|
||||
2. 기능 브랜치를 생성합니다 (`git checkout -b feature/AmazingFeature`)
|
||||
3. 변경사항을 커밋합니다 (`git commit -m 'Add some AmazingFeature'`)
|
||||
4. 브랜치에 푸시합니다 (`git push origin feature/AmazingFeature`)
|
||||
5. Pull Request를 제출합니다
|
||||
|
||||
### 코드 스타일
|
||||
|
||||
이 프로젝트는 PEP 8 및 Google Python Style Guide를 따릅니다. 다음을 준수하세요:
|
||||
- 타입 어노테이션 사용
|
||||
- Google 스타일 docstrings 준수
|
||||
- 모든 단위 테스트 통과
|
||||
|
||||
## 라이선스
|
||||
|
||||
이 프로젝트는 GNU GPL v3.0 라이선스를 따릅니다. 자세한 내용은 [LICENSE](../../LICENSE) 파일을 참조하세요.
|
||||
|
||||
## 저자
|
||||
|
||||
**xiatianxuan** (CodeSeed)
|
||||
|
||||
- [Gitee](https://gitee.com/xiatianxuan)
|
||||
- [홈페이지](https://xnors-codeseed.pages.dev/)
|
||||
|
||||
## 특별 감사
|
||||
|
||||
- [Xnors Studio](https://xnors.github.io/)
|
||||
|
||||
## 문의
|
||||
|
||||
질문이나 제안이 있으시면 이메일로 연락해 주세요: xiatianxuan2025@163.com
|
||||
|
||||
---
|
||||
|
||||
*최종 업데이트: 2026년 6월 19일*
|
||||
@@ -0,0 +1,665 @@
|
||||
# Sbackup
|
||||
|
||||
[](https://www.python.org/)
|
||||
[](../../LICENSE)
|
||||
[](https://pypi.org/project/sbackup-cli/)
|
||||
[](../../.github/workflows/ci.yml)
|
||||
[]()
|
||||
|
||||
> Ferramenta leve e eficiente para backup de pastas via linha de comando, ajudando você a gerenciar facilmente suas estratégias de backup.
|
||||
|
||||
[English](../../README.md) | [Deutsch](README_de.md) | [Espanol](README_es.md) | [Francais](README_fr.md) | [Portugues](README_pt.md) | [Pycckuu](README_ru.md) | [日本語](README_ja.md) | [한국어](README_ko.md) | [中文](README_zh.md)
|
||||
|
||||
- [Introducao](#introducao)
|
||||
- [Recursos](#recursos)
|
||||
- [Inicio Rapido](#inicio-rapido)
|
||||
- [Instalacao](#instalacao)
|
||||
- [Como Usar](#como-usar)
|
||||
- [Arquivo de Configuracao](#arquivo-de-configuracao)
|
||||
- [Exemplo de Configuracao](#exemplo-de-configuracao)
|
||||
- [Backup Remoto via SFTP](#backup-remoto-via-sftp)
|
||||
- [Backup Remoto via WebDAV](#backup-remoto-via-webdav)
|
||||
- [Como Funciona](#como-funciona)
|
||||
- [Guia de Desenvolvimento](#guia-de-desenvolvimento)
|
||||
- [Executando Testes](#executando-testes)
|
||||
- [Estrutura do Codigo](#estrutura-do-codigo)
|
||||
- [Perguntas Frequentes](#perguntas-frequentes)
|
||||
- [Guia de Contribuicao](#guia-de-contribuicao)
|
||||
- [Licenca](#licenca)
|
||||
- [Autor](#autor)
|
||||
|
||||
---
|
||||
|
||||
## Introducao
|
||||
|
||||
Sbackup e uma ferramenta leve de backup de pastas que permite adicionar, remover e visualizar estrategias de backup via linha de comando. Ela utiliza a data de ultima modificacao da pasta para decidir se o backup precisa ser realizado, garantindo que seus dados estejam sempre atualizados.
|
||||
|
||||
## Recursos
|
||||
|
||||
- **Backup incremental**: faz backup apenas das pastas que foram alteradas, economizando tempo e espaco de armazenamento
|
||||
- **Suporte a multiplos formatos**: suporta ZIP, tar, tar.gz, tar.bz2, tar.xz, tar.zst e 7z, com configuracao global e por entrada
|
||||
- **Backup remoto via SFTP**: baseado na biblioteca paramiko, suporta autenticacao por senha/chave SSH com deteccao automatica de chave padrao
|
||||
- **Backup remoto via WebDAV**: baseado na biblioteca padrao urllib, zero dependencias extras, compativel com JianguoCloud/NextCloud/Synology
|
||||
- **Armazenamento em nuvem S3**: baseado na biblioteca minio, suporta todos os armazenamentos compativeis com S3 (AWS/MinIO/Alibaba Cloud OSS, etc.)
|
||||
- **Backup paralelo para multiplos destinos**: faz backup simultaneamente para local + multiplos destinos remotos, sem interferencia entre eles
|
||||
- **Restauracao de backup**: suporta descompactacao e restauracao de arquivos de backup para um diretorio especificado, com restauracao seletiva
|
||||
- **Limpeza de backups**: remove backups antigos automaticamente, com politicas de retencao por quantidade/tempo/diaria
|
||||
- **Backup criptografado**: suporta criptografia por senha no formato 7z + criptografia PBKDF2 para todos os formatos
|
||||
- **Backup agendado**: execucao automatica em intervalos definidos, com monitoramento de arquivos em tempo real (watchdog)
|
||||
- **Historico de backups**: registra o tempo, tamanho e checksum SHA256 de cada backup para rastreabilidade
|
||||
- **Log de auditoria**: registra eventos de auditoria de todas as operacoes de backup/restauracao
|
||||
- **Pre/Post Hook**: executa comandos personalizados antes e depois do backup
|
||||
- **Perfis de configuracao**: suporta salvamento, alternancia, importacao e exportacao de multiplos perfis de configuracao
|
||||
- **Busca entre arquivos**: busca nomes de arquivos correspondentes em multiplos arquivos de backup
|
||||
- **Integridade dos dados**: geracao e verificacao de checksum SHA256, codigos de correcao de erros Reed-Solomon
|
||||
- **Validacao de configuracao**: validacao automatica dos parametros de configuracao, deteccao de adulteracao
|
||||
- **Fila de tarefas**: gerencia a fila de tarefas de backup, com suporte a adicao, execucao e cancelamento
|
||||
- **Benchmark de compressao**: compara o desempenho de compressao entre diferentes formatos/niveis
|
||||
- **Estimativa de espaco em disco**: estima o tamanho do backup por tipo de arquivo e verifica o espaco no destino
|
||||
- **Internacionalizacao**: suporta chines, ingles, frances, espanhol, russo, alemao, japones, portugues e coreano
|
||||
- **Autocompletar no shell**: suporta autocompletar em bash/zsh/fish/powershell
|
||||
- **Leve e eficiente**: tamanho pequeno, inicializacao rapida, baixo consumo de recursos
|
||||
- **Suporte multiplataforma**: suporta Windows, macOS e Linux
|
||||
|
||||
## Inicio Rapido
|
||||
|
||||
### Instalacao
|
||||
|
||||
#### Instalando via pip
|
||||
|
||||
```bash
|
||||
pip install sbackup-cli
|
||||
```
|
||||
|
||||
Apos a instalacao, use o comando `sbackup` (nome do pacote PyPI e `sbackup-cli`, comando CLI e `sbackup`).
|
||||
|
||||
#### Instalando a partir do codigo-fonte
|
||||
|
||||
```bash
|
||||
git clone https://github.com/xiatianxuan/sbackup.git
|
||||
cd sbackup
|
||||
uv sync
|
||||
```
|
||||
|
||||
### Como Usar
|
||||
|
||||
#### Sintaxe basica
|
||||
|
||||
```bash
|
||||
uv run python main.py <comando> [opcoes]
|
||||
```
|
||||
|
||||
#### Comandos disponiveis
|
||||
|
||||
| Comando | Descricao |
|
||||
|---------|-----------|
|
||||
| `add` | Adiciona uma estrategia de backup |
|
||||
| `rm` / `remove` | Remove uma estrategia de backup |
|
||||
| `edit` | Edita uma estrategia de backup existente |
|
||||
| `all` | Exibe todas as estrategias de backup |
|
||||
| `save` | Executa o backup |
|
||||
| `watch` | Executa backups agendados |
|
||||
| `restore` | Restaura a partir de um arquivo de backup |
|
||||
| `info` | Exibe detalhes do arquivo de backup |
|
||||
| `diff` | Compara diferencas entre o diretorio de origem e o backup |
|
||||
| `verify` | Verifica a integridade do arquivo de backup |
|
||||
| `search` | Busca arquivos no backup |
|
||||
| `xsearch` | Busca entre multiplos arquivos de backup |
|
||||
| `versions` | Exibe o historico de versoes do backup |
|
||||
| `sftp` | Gerenciamento de backup remoto via SFTP |
|
||||
| `webdav` | Gerenciamento de backup remoto via WebDAV |
|
||||
| `remote` | Gerenciamento de arquivos remotos (list/rm) |
|
||||
| `task` | Gerenciamento da fila de tarefas de backup |
|
||||
| `audit` | Consulta de logs de auditoria |
|
||||
| `hooks` | Executa Pre/Post Hook manualmente |
|
||||
| `profile` | Gerenciamento de perfis de configuracao |
|
||||
| `rotate` | Limpeza por rotacao de backups |
|
||||
| `clean` | Limpa backups antigos |
|
||||
| `diskcheck` | Estimativa de espaco em disco |
|
||||
| `benchmark` | Benchmark de formatos de compressao |
|
||||
| `integrity` | Verificacao de integridade do diretorio de backup |
|
||||
| `dry-run` | Visualizacao previa da selecao de arquivos de backup |
|
||||
| `export` / `import` | Exporta/importa estrategias de backup |
|
||||
| `ignore` | Gera arquivo .sbackupignore |
|
||||
| `schedule` | Exporta configuracao de agendamento |
|
||||
| `webhook` | Configura predefinicoes de Webhook |
|
||||
| `config` | Configuracao de criptografia/validacao |
|
||||
| `report` | Gera relatorio de backup |
|
||||
| `completion` | Gera scripts de autocompletar para shells |
|
||||
| `wizard` | Assistente de configuracao interativo |
|
||||
| `status` | Painel de status do backup |
|
||||
| `version` | Exibe informacoes de versao |
|
||||
| `help` | Exibe ajuda |
|
||||
|
||||
#### Parametros globais
|
||||
|
||||
| Parametro | Descricao |
|
||||
|-----------|-----------|
|
||||
| `--lang zh_CN` / `en_US` / `fr_FR` / `es_ES` / `ru_RU` / `de_DE` / `ja_JP` / `pt_BR` / `ko_KR` | Define o idioma da interface (persistido no config.json) |
|
||||
| `--format zip` / `tar` / `tar.gz` / `tar.bz2` / `tar.xz` / `tar.zst` / `7z` | Define o formato de empacotamento (persistido no config.json) |
|
||||
| `--debug` | Ativa logs de depuracao |
|
||||
|
||||
#### Adicionando uma estrategia de backup
|
||||
|
||||
```bash
|
||||
uv run python main.py add <origem> <destino> [-i padroes_ignorados]
|
||||
```
|
||||
|
||||
Parametros:
|
||||
- **origem**: caminho da pasta de origem para backup
|
||||
- **destino**: caminho onde os arquivos de backup serao armazenados
|
||||
- **-i, --ignore**: nomes de arquivos ou pastas a serem ignorados, separados por virgula (padrao: `.git,__pycache__`)
|
||||
- **--format**: formato de empacotamento por entrada (apenas para esta estrategia de backup, usa o padrao global se nao especificado): `zip` / `tar` / `tar.gz` / `tar.bz2` / `tar.xz` / `tar.zst` / `7z`
|
||||
|
||||
Exemplos:
|
||||
```bash
|
||||
# Adiciona estrategia usando o formato padrao global
|
||||
uv run python main.py add F:/minha_pasta F:/backup -i node_modules,.git
|
||||
|
||||
# Define formato tar.gz para esta estrategia (cada backup desta pasta usara tar.gz)
|
||||
uv run python main.py add F:/minha_pasta F:/backup --format tar.gz
|
||||
|
||||
# Define formato 7z (apenas para esta pasta)
|
||||
uv run python main.py add F:/minha_pasta F:/backup --format 7z
|
||||
```
|
||||
|
||||
#### Removendo uma estrategia de backup
|
||||
|
||||
```bash
|
||||
uv run python main.py rm <caminho>
|
||||
```
|
||||
|
||||
Parametros:
|
||||
- **caminho**: caminho da pasta de origem da estrategia de backup a ser removida
|
||||
|
||||
Exemplo:
|
||||
```bash
|
||||
uv run python main.py rm F:/minha_pasta
|
||||
```
|
||||
|
||||
#### Visualizando todas as estrategias de backup
|
||||
|
||||
```bash
|
||||
uv run python main.py all
|
||||
```
|
||||
|
||||
Exibe todas as estrategias de backup configuradas atualmente.
|
||||
|
||||
#### Executando o backup
|
||||
|
||||
```bash
|
||||
# Usa o formato padrao (ZIP)
|
||||
uv run python main.py save
|
||||
|
||||
# Usa formato tar.gz
|
||||
uv run python main.py --format tar.gz save
|
||||
|
||||
# Mantem os 5 backups mais recentes, limpa automaticamente os antigos
|
||||
uv run python main.py save --keep 5
|
||||
|
||||
# Usa formato 7z com criptografia
|
||||
uv run python main.py --format 7z save --password mysecret
|
||||
|
||||
# Interface em ingles + formato tar.xz
|
||||
uv run python main.py --lang en_US --format tar.xz save
|
||||
```
|
||||
|
||||
**Parametros do comando save:**
|
||||
|
||||
| Parametro | Padrao | Descricao |
|
||||
|-----------|--------|-----------|
|
||||
| `--keep N` | `0` | Mantem os N backups mais recentes, 0 significa sem limpeza |
|
||||
| `--password SENHA` | `""` | Senha de criptografia (apenas formato 7z) |
|
||||
| `--sftp` | `false` | Envia para servidor SFTP apos o backup |
|
||||
| `--webdav` | `false` | Envia para servidor WebDAV apos o backup |
|
||||
|
||||
De acordo com a estrategia de backup, faz backup automaticamente das pastas que foram alteradas.
|
||||
|
||||
#### Backup agendado
|
||||
|
||||
```bash
|
||||
# Executa backup a cada 60 minutos
|
||||
uv run python main.py watch --interval 60
|
||||
|
||||
# Backup a cada 2 horas, mantem os 10 arquivos mais recentes
|
||||
uv run python main.py watch --interval 120 --keep 10
|
||||
|
||||
# Backup agendado + criptografia 7z
|
||||
uv run python main.py --format 7z watch --interval 60 --password mysecret
|
||||
```
|
||||
|
||||
**Parametros do comando watch:**
|
||||
|
||||
| Parametro | Padrao | Descricao |
|
||||
|-----------|--------|-----------|
|
||||
| `--interval MINUTOS` | `60` | Intervalo entre backups (em minutos) |
|
||||
| `--keep N` | `0` | Mantem os N backups mais recentes |
|
||||
| `--password SENHA` | `""` | Senha de criptografia (apenas formato 7z) |
|
||||
| `--sftp` | `false` | Envia para servidor SFTP apos cada backup |
|
||||
| `--webdav` | `false` | Envia para servidor WebDAV apos cada backup |
|
||||
|
||||
Pressione `Ctrl+C` para parar o backup agendado.
|
||||
|
||||
#### Restaurando backup
|
||||
|
||||
```bash
|
||||
uv run python main.py restore <arquivo_backup> <diretorio_destino>
|
||||
```
|
||||
|
||||
Parametros:
|
||||
- **arquivo_backup**: caminho do arquivo de backup (suporta .zip / .tar / .tar.gz / .tar.bz2 / .tar.xz / .tar.zst / .7z)
|
||||
- **diretorio_destino**: diretorio de destino para restauracao
|
||||
|
||||
Exemplos:
|
||||
```bash
|
||||
uv run python main.py restore F:/backup/minha_pasta.tar.gz F:/restaurado
|
||||
uv run python main.py restore F:/backup/minha_pasta.7z F:/restaurado
|
||||
uv run python main.py restore F:/backup/minha_pasta.tar.zst F:/restaurado
|
||||
```
|
||||
|
||||
#### Backup remoto via SFTP
|
||||
|
||||
```bash
|
||||
# ============ Inicio rapido (recomendado) ============
|
||||
# 1. Configura SFTP (deteccao automatica de chave SSH, sem necessidade de especificar manualmente)
|
||||
sbackup sftp config --host 192.168.1.100 --user admin --remote-path /backups
|
||||
|
||||
# 2. Testa a conexao
|
||||
sbackup sftp test
|
||||
|
||||
# 3. Executa backup e envia
|
||||
sbackup save --sftp
|
||||
|
||||
# ============ Metodos de autenticacao ============
|
||||
|
||||
# Metodo 1: Deteccao automatica de chave privada (recomendado)
|
||||
# O sistema tenta automaticamente ~/.ssh/id_ed25519 -> id_rsa -> id_ecdsa
|
||||
sbackup sftp config --host 192.168.1.100 --user admin
|
||||
|
||||
# Metodo 2: Autenticacao por senha
|
||||
sbackup sftp config --host 192.168.1.100 --user admin --password secret
|
||||
|
||||
# Metodo 3: Especificar chave privada
|
||||
sbackup sftp config --host 192.168.1.100 --user admin --key-file ~/.ssh/id_rsa
|
||||
|
||||
# Metodo 4: Chave privada + frase secreta (entrada interativa)
|
||||
sbackup sftp config --host 192.168.1.100 --user admin --key-file ~/.ssh/id_rsa
|
||||
|
||||
# Metodo 5: Chave privada + frase secreta (especificada na linha de comando)
|
||||
sbackup sftp config --host 192.168.1.100 --user admin --key-file ~/.ssh/id_rsa --key-passphrase mykeypass
|
||||
|
||||
# ============ Cenarios de uso ============
|
||||
|
||||
# Cenario 1: Backup unico e envio
|
||||
sbackup save --sftp
|
||||
|
||||
# Cenario 2: Backup agendado com envio automatico (a cada 60 minutos)
|
||||
sbackup watch --interval 60 --sftp
|
||||
|
||||
# Cenario 3: Backup com formato especifico + envio
|
||||
sbackup --format tar.gz save --sftp
|
||||
|
||||
# Cenario 4: Backup criptografado + envio
|
||||
sbackup --format 7z save --password mysecret --sftp
|
||||
|
||||
# Cenario 5: Manter os 5 backups mais recentes + envio
|
||||
sbackup save --keep 5 --sftp
|
||||
|
||||
# ============ Uso avancado ============
|
||||
|
||||
# Configuracao interativa (insere todos os parametros passo a passo)
|
||||
sbackup sftp config
|
||||
|
||||
# Configuracao nao interativa (todos os parametros na linha de comando)
|
||||
sbackup sftp config --host 192.168.1.100 --port 22 --user admin --password secret --remote-path /backups
|
||||
|
||||
# Testa conexao e exibe log detalhado
|
||||
sbackup --debug sftp test
|
||||
```
|
||||
|
||||
**Subcomandos sftp:**
|
||||
|
||||
| Subcomando | Descricao | Exemplo |
|
||||
|------------|-----------|---------|
|
||||
| `sftp config` | Configura parametros de conexao SFTP (host/port/user/password/key_file/key_passphrase/remote_path) | `sbackup sftp config --host 192.168.1.100 --user admin` |
|
||||
| `sftp test` | Testa se a conexao SFTP esta disponivel | `sbackup sftp test` |
|
||||
|
||||
**Metodos de autenticacao:**
|
||||
|
||||
| Metodo | Parametros | Descricao | Exemplo |
|
||||
|--------|------------|-----------|---------|
|
||||
| **Deteccao automatica** | Sem parametros de autenticacao | Tenta automaticamente `~/.ssh/id_ed25519` -> `id_rsa` -> `id_ecdsa` (recomendado) | `sbackup sftp config --host ... --user ...` |
|
||||
| Senha | `--password` | Login direto com senha | `sbackup sftp config --host ... --user ... --password secret` |
|
||||
| Chave privada | `--key-file` | Login com chave SSH especifica | `sbackup sftp config --host ... --user ... --key-file ~/.ssh/id_rsa` |
|
||||
| Chave privada+frase | `--key-file` + `--key-passphrase` | Usado quando a chave privada possui frase secreta | `sbackup sftp config --host ... --user ... --key-file ~/.ssh/id_rsa --key-passphrase mypass` |
|
||||
|
||||
Formatos de chave privada suportados: RSA, Ed25519, ECDSA.
|
||||
|
||||
**Suporte a caminhos multiplataforma:**
|
||||
|
||||
| Plataforma | Exemplo de caminho da chave privada | Descricao |
|
||||
|------------|-------------------------------------|-----------|
|
||||
| Linux/macOS | `~/.ssh/id_rsa` | Expande automaticamente para `/home/usuario/.ssh/id_rsa` |
|
||||
| Windows | `~/.ssh/id_rsa` | Expande automaticamente para `C:\Users\usuario\.ssh\id_rsa` |
|
||||
| Todas | Caminho absoluto | Usa o caminho completo diretamente |
|
||||
|
||||
A configuracao SFTP e salva no campo `sftp` do `config.json`, suportando parametros via linha de comando ou entrada interativa.
|
||||
|
||||
#### Visualizando informacoes de versao
|
||||
|
||||
```bash
|
||||
sbackup version
|
||||
```
|
||||
|
||||
## Arquivo de Configuracao
|
||||
|
||||
Sbackup suporta configuracao personalizada atraves do arquivo `config.json`. O arquivo de configuracao deve ser colocado no diretorio raiz do projeto.
|
||||
|
||||
### Descricao das configuracoes
|
||||
|
||||
```json
|
||||
{
|
||||
"compression_format": "ZIP",
|
||||
"compression": {
|
||||
"algorithm": "ZIP_DEFLATED",
|
||||
"level": 6
|
||||
},
|
||||
"skip_patterns": [".git", "__pycache__"],
|
||||
"data_file": "sbackup.json",
|
||||
"lang": "pt_BR",
|
||||
"password": "",
|
||||
"sftp": {
|
||||
"host": "",
|
||||
"port": 22,
|
||||
"user": "",
|
||||
"password": "",
|
||||
"key_file": "",
|
||||
"key_passphrase": "",
|
||||
"remote_path": "/",
|
||||
"enabled": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| Configuracao | Tipo | Padrao | Descricao |
|
||||
|--------------|------|--------|-----------|
|
||||
| `compression_format` | string | `"ZIP"` | Formato de empacotamento, valores validos: `ZIP`, `TAR`, `TAR_GZ`, `TAR_BZ2`, `TAR_XZ`, `TAR_ZST`, `7Z` |
|
||||
| `compression.algorithm` | string | `"ZIP_DEFLATED"` | Algoritmo de compressao ZIP, valores validos: `ZIP_DEFLATED`, `ZIP_STORED`, `ZIP_BZIP2`, `ZIP_LZMA` |
|
||||
| `compression.level` | int | `6` | Nivel de compressao, intervalo 0-9 (0 = sem compressao, 9 = compressao maxima) |
|
||||
| `skip_patterns` | list | `[".git", "__pycache__"]` | Padroes de arquivos ou pastas a serem ignorados (suporta curingas fnmatch e correspondencia de caminhos) |
|
||||
| `data_file` | string | Caminho padrao da plataforma | Caminho do arquivo de dados das estrategias de backup |
|
||||
| `lang` | string | `"pt_BR"` | Idioma da interface, valores validos: `zh_CN`, `en_US`, `fr_FR`, `es_ES`, `ru_RU`, `de_DE`, `ja_JP`, `pt_BR`, `ko_KR` |
|
||||
| `password` | string | `""` | Senha de criptografia 7z |
|
||||
| `sftp.host` | string | `""` | Endereco do servidor SFTP |
|
||||
| `sftp.port` | int | `22` | Porta SFTP |
|
||||
| `sftp.user` | string | `""` | Nome de usuario SFTP |
|
||||
| `sftp.password` | string | `""` | Senha SFTP (usada na autenticacao por senha) |
|
||||
| `sftp.key_file` | string | `""` | Caminho do arquivo de chave SSH privada (usado na autenticacao por chave, recomendado) |
|
||||
| `sftp.key_passphrase` | string | `""` | Frase secreta da chave privada (se houver) |
|
||||
| `sftp.remote_path` | string | `"/"` | Caminho do destino remoto |
|
||||
| `sftp.enabled` | bool | `false` | Habilita ou desabilita SFTP |
|
||||
|
||||
### Exemplo de configuracao
|
||||
|
||||
Usando formato tar.bz2 para backup com alta taxa de compressao:
|
||||
|
||||
```json
|
||||
{
|
||||
"compression_format": "TAR_BZ2",
|
||||
"compression_level": 9,
|
||||
"skip_patterns": [".git", "__pycache__", "node_modules", "*.log"],
|
||||
"data_file": "estrategias_backup.json",
|
||||
"lang": "pt_BR"
|
||||
}
|
||||
```
|
||||
|
||||
### Comparacao de formatos de empacotamento
|
||||
|
||||
| Formato | Extensao | Taxa de compressao | Velocidade | Dependencia | Cenario de uso |
|
||||
|---------|----------|-------------------|------------|-------------|----------------|
|
||||
| ZIP | .zip | Media | Rapida | Biblioteca padrao | Uso geral, melhor compatibilidade com Windows |
|
||||
| tar | .tar | Nenhuma | Muito rapida | Biblioteca padrao | Apenas arquivamento, combina com compressao externa |
|
||||
| tar.gz | .tar.gz | Media | Rapida | Biblioteca padrao | Uso geral em Linux/macOS |
|
||||
| tar.bz2 | .tar.bz2 | Alta | Media | Biblioteca padrao | Arquivamento com alta taxa de compressao |
|
||||
| tar.xz | .tar.xz | Muito alta | Lenta | Biblioteca padrao | Arquivamento de longo prazo, sensivel a espaco |
|
||||
| tar.zst | .tar.zst | Media-alta | Muito rapida | zstandard | Cenarios modernos, equilibrio entre velocidade e compressao |
|
||||
| 7z | .7z | Extremamente alta | Lenta | py7zr | Maior taxa de compressao, suporta criptografia |
|
||||
|
||||
#### Backup remoto via WebDAV
|
||||
|
||||
WebDAV e um protocolo de arquivos baseado em HTTP, compativel com JianguoCloud, NextCloud, Synology e outros servicos de armazenamento em nuvem. Usa a biblioteca padrao `urllib` do Python, **zero dependencias extras**.
|
||||
|
||||
```bash
|
||||
# ============ Inicio rapido ============
|
||||
# 1. Configura WebDAV
|
||||
sbackup webdav config --url https://dav.jianguoyun.com/dav/ --user usuario@exemplo.com --password secret
|
||||
|
||||
# 2. Testa a conexao
|
||||
sbackup webdav test
|
||||
|
||||
# 3. Executa backup e envia
|
||||
sbackup save --webdav
|
||||
|
||||
# ============ Cenarios de uso ============
|
||||
|
||||
# Cenario 1: Backup unico e envio
|
||||
sbackup save --webdav
|
||||
|
||||
# Cenario 2: Backup agendado com envio automatico (a cada 60 minutos)
|
||||
sbackup watch --interval 60 --webdav
|
||||
|
||||
# Cenario 3: Especificar subdiretorio remoto
|
||||
sbackup webdav config --url https://dav.jianguoyun.com/dav/ --user usuario@exemplo.com --remote-path /backups/sbackup
|
||||
|
||||
# Cenario 4: Enviar simultaneamente para SFTP e WebDAV
|
||||
sbackup save --sftp --webdav
|
||||
|
||||
# ============ Enderecos comuns de servicos WebDAV ============
|
||||
# JianguoCloud: https://dav.jianguoyun.com/dav/
|
||||
# NextCloud: https://seu-servidor/remote.php/dav/files/usuario/
|
||||
# Synology: https://seu-synology:5006/webdav/
|
||||
```
|
||||
|
||||
**Subcomandos webdav:**
|
||||
|
||||
| Subcomando | Descricao | Exemplo |
|
||||
|------------|-----------|---------|
|
||||
| `webdav config` | Configura parametros de conexao WebDAV (url/user/password/remote_path) | `sbackup webdav config --url ... --user ...` |
|
||||
| `webdav test` | Testa se a conexao WebDAV esta disponivel | `sbackup webdav test` |
|
||||
|
||||
| Parametro | Padrao | Descricao |
|
||||
|-----------|--------|-----------|
|
||||
| `--url URL` | `""` | Endereco do servidor WebDAV (ex: `https://dav.jianguoyun.com/dav/`) |
|
||||
| `--user USUARIO` | `""` | Nome de usuario WebDAV (geralmente o e-mail) |
|
||||
| `--password SENHA` | `""` | Senha WebDAV (JianguoCloud requer geracao de senha de aplicativo nas configuracoes) |
|
||||
| `--remote-path CAMINHO` | `/` | Caminho do destino remoto |
|
||||
|
||||
## Como Funciona
|
||||
|
||||
Sbackup implementa as funcionalidades de backup da seguinte forma:
|
||||
|
||||
1. **Armazenamento de estrategias**: as estrategias de backup sao armazenadas em um arquivo JSON, contendo caminhos de pastas, data de ultima modificacao, caminhos de destino, padroes de ignorancia e formato de empacotamento por entrada.
|
||||
2. **Backup incremental**: comparando a data de ultima modificacao das pastas, faz backup apenas das pastas que foram alteradas.
|
||||
3. **Compressao multi-formato**: usa os modulos `zipfile` e `tarfile` integrados do Python, alem das bibliotecas `zstandard` e `py7zr`, suportando 7 formatos de empacotamento.
|
||||
4. **Formato por entrada**: cada estrategia de backup pode ter seu proprio formato de empacotamento (`add --format`), com prioridade sobre a configuracao global `--format`; quando nao especificado, usa o padrao global.
|
||||
5. **Limpeza de backups**: apos o backup ser bem-sucedido, escaneia automaticamente o diretorio de destino, ordena por data de modificacao e remove arquivos antigos que excedem a quantidade de retencao.
|
||||
6. **Backup criptografado**: o formato 7z suporta criptografia LZMA2, atraves do parametro `--password` ou configuracao no `config.json`.
|
||||
7. **Backup agendado**: o comando `watch` executa backups em loop com intervalos especificados, `Ctrl+C` para saida segura.
|
||||
8. **Historico de backups**: apos cada backup, registra timestamp, tamanho do arquivo e contagem de arquivos, mantendo os ultimos 100 registros.
|
||||
9. **Backup remoto via SFTP**: implementa o cliente SFTP baseado na biblioteca paramiko, com suporte a teste de conexao, criacao automatica de diretorios remotos e upload de arquivos com barra de progresso.
|
||||
|
||||
### Formato do arquivo de dados
|
||||
|
||||
```json
|
||||
{
|
||||
"/caminho/para/pasta/de/origem": [
|
||||
1719235200.0,
|
||||
"/caminho/para/pasta/de/destino",
|
||||
[".git", "__pycache__"],
|
||||
""
|
||||
],
|
||||
"/caminho/para/outra/pasta": [
|
||||
1719235200.0,
|
||||
"/caminho/para/outro/destino",
|
||||
[".git"],
|
||||
"TAR_GZ"
|
||||
],
|
||||
"_history": [
|
||||
{
|
||||
"time": "2026-05-01T12:00:00",
|
||||
"source": "/caminho/para/pasta/de/origem",
|
||||
"size_mb": 12.5,
|
||||
"files_count": 150
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Cada entrada de estrategia de backup e uma lista de 4 elementos: `[mtime, destino, padroes_ignorados, formato_compressao]`
|
||||
|
||||
| Campo | Descricao |
|
||||
|-------|-----------|
|
||||
| `mtime` | Data de ultima modificacao da pasta de origem (usada para decisao de backup incremental) |
|
||||
| `destino` | Caminho de destino onde os arquivos de backup serao armazenados |
|
||||
| `padroes_ignorados` | Lista de padroes de arquivos/pastas a serem ignorados |
|
||||
| `formato_compressao` | Formato de empacotamento por entrada (string vazia significa usar o padrao global) |
|
||||
|
||||
## Guia de Desenvolvimento
|
||||
|
||||
### Executando testes
|
||||
|
||||
```bash
|
||||
uv run coverage run -m unittest discover -s tests -t . && uv run coverage report -m
|
||||
```
|
||||
|
||||
### Estrutura do codigo
|
||||
|
||||
```
|
||||
sbackup/
|
||||
├── main.py # Ponto de entrada do programa
|
||||
├── sbackup/
|
||||
│ ├── __init__.py # Exporta funcoes principais
|
||||
│ ├── __main__.py # Ponto de entrada python -m sbackup
|
||||
│ ├── cli.py # Analise de argumentos CLI e distribuicao de comandos (30+ comandos)
|
||||
│ ├── config.py # Carregamento de configuracao, criptografia, configuracao Webhook/SMTP
|
||||
│ ├── auto_save.py # Motor principal BackupManager
|
||||
│ ├── compression.py # Motor de compressao/descompressao para 7 formatos
|
||||
│ ├── i18n.py # Internacionalizacao (9 idiomas)
|
||||
│ ├── sftp.py # Cliente SFTP de backup remoto (paramiko)
|
||||
│ ├── webdav.py # Cliente WebDAV de backup remoto (zero dependencias)
|
||||
│ ├── cloud_storage.py # Cliente S3 de armazenamento em nuvem (minio)
|
||||
│ ├── multi_dest.py # Backup paralelo para multiplos destinos
|
||||
│ ├── handlers.py # Manipuladores de comandos SFTP/WebDAV/Remote/Schedule
|
||||
│ ├── hooks.py # Execucao de Pre/Post Hook
|
||||
│ ├── audit.py # Sistema de log de auditoria
|
||||
│ ├── profile.py # Gerenciamento de perfis de configuracao
|
||||
│ ├── selective.py # Restauracao seletiva
|
||||
│ ├── cross_search.py # Busca entre arquivos
|
||||
│ ├── integrity.py # Checksum SHA256
|
||||
│ ├── rotation.py # Estrategia de rotacao de backups
|
||||
│ ├── dryrun.py # Visualizacao previa de dry-run
|
||||
│ ├── diskcheck.py # Estimativa de espaco em disco
|
||||
│ ├── task_queue.py # Sistema de fila de tarefas
|
||||
│ ├── schema.py # Validador de configuracao
|
||||
│ ├── benchmark.py # Benchmark de compressao
|
||||
│ ├── chunked_backup.py# Backup incremental por blocos
|
||||
│ ├── dedup.py # Deduplicacao por SHA256 no nivel de arquivo
|
||||
│ ├── export.py # Exportacao de metadados (CSV/JSON)
|
||||
│ ├── monitor.py # Monitoramento de sistema de arquivos com watchdog
|
||||
│ ├── lock.py # Bloqueio de processo multiplataforma
|
||||
│ ├── retry.py | Retry com backoff exponencial
|
||||
│ ├── ratelimiter.py # Limitador de taxa por balde de tokens
|
||||
│ ├── keychain.py # Integracao com chaveiro do sistema
|
||||
│ ├── parity.py # Codigos de correcao de erros Reed-Solomon
|
||||
│ ├── completion.py # Autocompletar para shells
|
||||
│ ├── wizard.py # Assistente de configuracao interativo
|
||||
│ └── locales/ # Arquivos de traducao para 9 idiomas
|
||||
└── tests/
|
||||
└── sbackup/
|
||||
└── test_*.py # 30 arquivos de teste cobrindo todos os modulos
|
||||
```
|
||||
|
||||
### Adicionando novas funcionalidades
|
||||
|
||||
1. Crie um novo arquivo de modulo no diretorio `sbackup/`
|
||||
2. Importe as funcoes da nova funcionalidade em `sbackup/__init__.py`
|
||||
3. Adicione a logica de manipulacao do novo comando na funcao `run()`
|
||||
4. Adicione o arquivo de teste correspondente no diretorio `tests/`
|
||||
|
||||
## Perguntas Frequentes
|
||||
|
||||
### P: E se o arquivo de estrategias de backup for deletado acidentalmente?
|
||||
|
||||
R: As estrategias de backup sao armazenadas no arquivo de dados. Se forem deletadas acidentalmente, voce pode reexecutar o comando `add` para adicionar as estrategias novamente.
|
||||
|
||||
### P: Como modificar uma estrategia de backup ja adicionada?
|
||||
|
||||
R: Use o comando `sbackup edit`: `sbackup edit <origem> --dest <novo_destino> --ignore <padroes> --format <fmt>`.
|
||||
|
||||
### P: Suporta backup remoto?
|
||||
|
||||
R: Sim! Sao fornecidos tres metodos de backup remoto:
|
||||
- **SFTP**: `sbackup sftp config` para configurar, `sbackup save --sftp` para enviar
|
||||
- **WebDAV**: `sbackup webdav config` para configurar, `sbackup save --webdav` para enviar (compativel com JianguoCloud/NextCloud/Synology)
|
||||
- **Armazenamento em nuvem S3**: configure o campo `cloud` no `config.json`, `sbackup save --cloud` para enviar
|
||||
- Pode usar varios simultaneamente: `sbackup save --sftp --webdav --cloud`
|
||||
|
||||
### P: Qual a diferenca entre tar.gz e ZIP?
|
||||
|
||||
R: tar.gz e mais usado em Linux/macOS, com taxa de compressao ligeiramente superior; ZIP e mais universal em Windows, com melhor compatibilidade. tar.bz2 e tar.xz oferecem maior taxa de compressao, mas sao mais lentos. tar.zst e um algoritmo moderno, muito rapido com boa taxa de compressao. 7z tem a maior taxa de compressao e suporta criptografia.
|
||||
|
||||
### P: Como criptografar o backup?
|
||||
|
||||
R: Use o formato 7z e defina uma senha: `uv run python main.py --format 7z save --password suasenha`. A senha tambem pode ser gravada no campo `password` do `config.json`.
|
||||
|
||||
### P: Como limpar backups antigos automaticamente?
|
||||
|
||||
R: Use o parametro `--keep`: `uv run python main.py save --keep 5` mantem apenas os 5 backups mais recentes. O backup agendado tambem suporta: `uv run python main.py watch --interval 60 --keep 10`.
|
||||
|
||||
### P: Como configurar backup agendado?
|
||||
|
||||
R: Use o comando `watch`: `uv run python main.py watch --interval 60` executa backup a cada 60 minutos. Pressione `Ctrl+C` para parar.
|
||||
|
||||
### P: O armazenamento de senhas e seguro?
|
||||
|
||||
R: As senhas SFTP e de criptografia 7z no `config.json` sao armazenadas em **texto plano**. Certifique-se de que as permissoes de acesso ao arquivo `config.json` sejam restritas a usuarios confiaveis (por exemplo, `chmod 600 config.json`). Nao envie o `config.json` com senhas para o sistema de controle de versao.
|
||||
|
||||
## Guia de Contribuicao
|
||||
|
||||
Contribuicoes com Issues e Pull Requests sao bem-vindas!
|
||||
|
||||
1. Fork este repositorio
|
||||
2. Crie sua branch de funcionalidade (`git checkout -b feature/SuaFuncionalidade`)
|
||||
3. Faca seus commits (`git commit -m 'Adiciona SuaFuncionalidade'`)
|
||||
4. Envie para a branch (`git push origin feature/SuaFuncionalidade`)
|
||||
5. Abra um Pull Request
|
||||
|
||||
### Estilo de codigo
|
||||
|
||||
Este projeto segue o PEP 8 e o Google Python Style Guide. Certifique-se de que seu codigo:
|
||||
- Use anotacoes de tipo
|
||||
- Siga docstrings no estilo Google
|
||||
- Passe em todos os testes unitarios
|
||||
|
||||
## Licenca
|
||||
|
||||
Este projeto esta licenciado sob a GNU GPL v3.0. Consulte o arquivo [LICENSE](../../LICENSE) para mais detalhes.
|
||||
|
||||
## Autor
|
||||
|
||||
**xiatianxuan** (CodeSeed)
|
||||
|
||||
- [Gitee](https://gitee.com/xiatianxuan)
|
||||
- [Pagina pessoal](https://xnors-codeseed.pages.dev/)
|
||||
|
||||
## Agradecimentos especiais
|
||||
|
||||
- [Xnors Studio](https://xnors.github.io/)
|
||||
|
||||
## Contato
|
||||
|
||||
Se tiver duvidas ou sugestoes, envie um e-mail para: xiatianxuan2025@163.com
|
||||
|
||||
---
|
||||
|
||||
*Ultima atualizacao: 19 de junho de 2026*
|
||||
@@ -0,0 +1,665 @@
|
||||
# Sbackup
|
||||
|
||||
[](https://www.python.org/)
|
||||
[](../../LICENSE)
|
||||
[](https://pypi.org/project/sbackup-cli/)
|
||||
[](../../.github/workflows/ci.yml)
|
||||
[]()
|
||||
|
||||
> Лёгкий и эффективный инструмент резервного копирования папок с поддержкой командной строки, позволяющий удобно управлять стратегиями бэкапов.
|
||||
|
||||
[English](../../README.md) | [Deutsch](README_de.md) | [Espanol](README_es.md) | [Francais](README_fr.md) | [Portugues](README_pt.md) | [Pycckuu](README_ru.md) | [日本語](README_ja.md) | [한국어](README_ko.md) | [中文](README_zh.md)
|
||||
|
||||
- [Введение](#введение)
|
||||
- [Возможности](#возможности)
|
||||
- [Быстрый старт](#быстрый-старт)
|
||||
- [Установка](#установка)
|
||||
- [Использование](#использование)
|
||||
- [Файл конфигурации](#файл-конфигурации)
|
||||
- [Пример конфигурации](#пример-конфигурации)
|
||||
- [Удалённое резервное копирование через SFTP](#удалённое-резервное-копирование-через-sftp)
|
||||
- [Удалённое резервное копирование через WebDAV](#удалённое-резервное-копирование-через-webdav)
|
||||
- [Принцип работы](#принцип-работы)
|
||||
- [Руководство для разработчиков](#руководство-для-разработчиков)
|
||||
- [Запуск тестов](#запуск-тестов)
|
||||
- [Структура кода](#структура-кода)
|
||||
- [Часто задаваемые вопросы](#часто-задаваемые-вопросы)
|
||||
- [Руководство по участию в разработке](#руководство-по-участию-в-разработке)
|
||||
- [Лицензия](#лицензия)
|
||||
- [Автор](#автор)
|
||||
|
||||
---
|
||||
|
||||
## Введение
|
||||
|
||||
Sbackup -- это лёгкий инструмент резервного копирования папок, позволяющий добавлять, удалять и просматривать стратегии бэкапов через командную строку. Он определяет необходимость резервного копирования на основе времени последнего изменения папки, гарантируя, что ваши данные всегда остаются актуальными.
|
||||
|
||||
## Возможности
|
||||
|
||||
- **Инкрементальное резервное копирование**: копируются только изменённые папки, что экономит время и дисковое пространство
|
||||
- **Поддержка множества форматов**: семь форматов упаковки -- ZIP, tar, tar.gz, tar.bz2, tar.xz, tar.zst, 7z; можно задавать как глобально, так и для каждого элемента отдельно
|
||||
- **Удалённое резервное копирование через SFTP**: на базе библиотеки paramiko, поддержка аутентификации по паролю/SSH-ключу, автоматическое определение ключа по умолчанию
|
||||
- **Удалённое резервное копирование через WebDAV**: на базе стандартной библиотеки urllib, без дополнительных зависимостей; поддержка Jianguoyun/NextCloud/Synology
|
||||
- **Облачное хранилище S3**: на базе библиотеки minio, совместимо со всеми S3-хранилищами (AWS/MinIO/Aliyun OSS и др.)
|
||||
- **Параллельное копирование в несколько направлений**: одновременное резервное копирование на локальный диск и несколько удалённых хранилищ
|
||||
- **Восстановление из бэкапа**: распаковка и восстановление в указанную директорию с возможностью выборочного восстановления
|
||||
- **Очистка старых бэкапов**: автоматическое удаление с поддержкой стратегий по количеству/времени/ежедневному хранению
|
||||
- **Шифрование**: парольное шифрование для формата 7z + шифрование PBKDF2 для всех форматов
|
||||
- **Планирование**: автоматическое выполнение по расписанию, поддержка мониторинга файловой системы в реальном времени (watchdog)
|
||||
- **История резервных копий**: запись времени, размера и контрольной суммы SHA256 каждого бэкапа для удобного отслеживания
|
||||
- **Журнал аудита**: запись всех событий резервного копирования и восстановления
|
||||
- **Pre/Post Hook**: выполнение пользовательских команд до и после резервного копирования
|
||||
- **Профили конфигурации**: сохранение, переключение, импорт и экспорт нескольких конфигураций
|
||||
- **Поиск по архивам**: поиск совпадающих имён файлов в нескольких бэкапах
|
||||
- **Целостность данных**: генерация и проверка контрольных сумм SHA256, корректирующие коды Рида-Соломона
|
||||
- **Валидация конфигурации**: автоматическая проверка параметров конфигурации, обнаружение несанкционированных изменений
|
||||
- **Очередь задач**: управление очередью задач резервного копирования с возможностью добавления, выполнения и отмены
|
||||
- **Бенчмарк сжатия**: сравнение производительности различных форматов и уровней сжатия
|
||||
- **Оценка дискового пространства**: предварительный расчёт размера бэкапа по типам файлов с проверкой места на диске
|
||||
- **Интернационализация**: поддержка девяти языков -- китайский, английский, французский, испанский, русский, немецкий, японский, португальский, корейский
|
||||
- **Автодополнение в оболочке**: bash/zsh/fish/powershell
|
||||
- **Лёгкость и эффективность**: малый размер, быстрый запуск, низкое потребление ресурсов
|
||||
- **Кроссплатформенность**: поддержка Windows, macOS и Linux
|
||||
|
||||
## Быстрый старт
|
||||
|
||||
### Установка
|
||||
|
||||
#### Установка через pip
|
||||
|
||||
```bash
|
||||
pip install sbackup-cli
|
||||
```
|
||||
|
||||
После установки доступна команда `sbackup` (имя пакета на PyPI -- `sbackup-cli`, имя CLI-команды -- `sbackup`).
|
||||
|
||||
#### Установка из исходного кода
|
||||
|
||||
```bash
|
||||
git clone https://github.com/xiatianxuan/sbackup.git
|
||||
cd sbackup
|
||||
uv sync
|
||||
```
|
||||
|
||||
### Использование
|
||||
|
||||
#### Основной синтаксис
|
||||
|
||||
```bash
|
||||
uv run python main.py <command> [options]
|
||||
```
|
||||
|
||||
#### Доступные команды
|
||||
|
||||
| Команда | Описание |
|
||||
|---------|----------|
|
||||
| `add` | Добавить стратегию резервного копирования |
|
||||
| `rm` / `remove` | Удалить стратегию резервного копирования |
|
||||
| `edit` | Редактировать существующую стратегию |
|
||||
| `all` | Показать все стратегии резервного копирования |
|
||||
| `save` | Выполнить резервное копирование |
|
||||
| `watch` | Запустить резервное копирование по расписанию |
|
||||
| `restore` | Восстановить из файла резервной копии |
|
||||
| `info` | Показать подробную информацию о файле резервной копии |
|
||||
| `diff` | Сравнить исходную директорию с резервной копией |
|
||||
| `verify` | Проверить целостность файла резервной копии |
|
||||
| `search` | Поиск файлов в резервной копии |
|
||||
| `xsearch` | Поиск по нескольким архивам резервных копий |
|
||||
| `versions` | Показать историю версий резервных копий |
|
||||
| `sftp` | Управление удалённым резервным копированием через SFTP |
|
||||
| `webdav` | Управление удалённым резервным копированием через WebDAV |
|
||||
| `remote` | Управление удалёнными файлами (list/rm) |
|
||||
| `task` | Управление очередью задач резервного копирования |
|
||||
| `audit` | Запрос журнала аудита |
|
||||
| `hooks` | Ручной запуск Pre/Post Hook |
|
||||
| `profile` | Управление профилями конфигурации |
|
||||
| `rotate` | Ротация резервных копий |
|
||||
| `clean` | Очистка старых резервных копий |
|
||||
| `diskcheck` | Оценка дискового пространства |
|
||||
| `benchmark` | Бенчмарк форматов сжатия |
|
||||
| `integrity` | Проверка целостности директории резервных копий |
|
||||
| `dry-run` | Предварительный просмотр выбора файлов |
|
||||
| `export` / `import` | Экспорт/импорт стратегий резервного копирования |
|
||||
| `ignore` | Генерация файла .sbackupignore |
|
||||
| `schedule` | Экспорт конфигурации планировщика |
|
||||
| `webhook` | Настройка предустановок Webhook |
|
||||
| `config` | Шифрование/проверка конфигурации |
|
||||
| `report` | Генерация отчёта о резервном копировании |
|
||||
| `completion` | Генерация скрипта автодополнения для оболочки |
|
||||
| `wizard` | Интерактивный мастер настройки |
|
||||
| `status` | Панель состояния резервного копирования |
|
||||
| `version` | Показать информацию о версии |
|
||||
| `help` | Показать справку |
|
||||
|
||||
#### Глобальные параметры
|
||||
|
||||
| Параметр | Описание |
|
||||
|----------|----------|
|
||||
| `--lang zh_CN` / `en_US` / `fr_FR` / `es_ES` / `ru_RU` / `de_DE` / `ja_JP` / `pt_BR` / `ko_KR` | Установить язык интерфейса (сохраняется в config.json) |
|
||||
| `--format zip` / `tar` / `tar.gz` / `tar.bz2` / `tar.xz` / `tar.zst` / `7z` | Установить формат упаковки (сохраняется в config.json) |
|
||||
| `--debug` | Включить отладочное логирование |
|
||||
|
||||
#### Добавление стратегии резервного копирования
|
||||
|
||||
```bash
|
||||
uv run python main.py add <source> <dest> [-i ignore_patterns]
|
||||
```
|
||||
|
||||
Параметры:
|
||||
- **source**: путь к исходной папке для резервного копирования
|
||||
- **dest**: путь к директории для хранения резервных копий
|
||||
- **-i, --ignore**: имена файлов или папок, которые следует игнорировать, через запятую (по умолчанию: `.git,__pycache__`)
|
||||
- **--format**: формат упаковки на уровне элемента (применяется только к данной стратегии; если не указан, используется глобальный по умолчанию): `zip` / `tar` / `tar.gz` / `tar.bz2` / `tar.xz` / `tar.zst` / `7z`
|
||||
|
||||
Примеры:
|
||||
```bash
|
||||
# Добавить стратегию с форматом по умолчанию
|
||||
uv run python main.py add F:/my_folder F:/backup -i node_modules,.git
|
||||
|
||||
# Указать формат tar.gz для данной стратегии (каждый бэкап этой папки будет в формате tar.gz)
|
||||
uv run python main.py add F:/my_folder F:/backup --format tar.gz
|
||||
|
||||
# Указать формат 7z (только для этой папки)
|
||||
uv run python main.py add F:/my_folder F:/backup --format 7z
|
||||
```
|
||||
|
||||
#### Удаление стратегии резервного копирования
|
||||
|
||||
```bash
|
||||
uv run python main.py rm <path>
|
||||
```
|
||||
|
||||
Параметры:
|
||||
- **path**: путь к исходной папке, стратегию которой нужно удалить
|
||||
|
||||
Пример:
|
||||
```bash
|
||||
uv run python main.py rm F:/my_folder
|
||||
```
|
||||
|
||||
#### Просмотр всех стратегий резервного копирования
|
||||
|
||||
```bash
|
||||
uv run python main.py all
|
||||
```
|
||||
|
||||
Отображает все текущие настроенные стратегии резервного копирования.
|
||||
|
||||
#### Выполнение резервного копирования
|
||||
|
||||
```bash
|
||||
# С использованием формата по умолчанию (ZIP)
|
||||
uv run python main.py save
|
||||
|
||||
# С использованием формата tar.gz
|
||||
uv run python main.py --format tar.gz save
|
||||
|
||||
# Сохранить последние 5 резервных копий, автоматически удалить старые
|
||||
uv run python main.py save --keep 5
|
||||
|
||||
# Использовать формат 7z с шифрованием
|
||||
uv run python main.py --format 7z save --password mysecret
|
||||
|
||||
# Английский интерфейс + формат tar.xz
|
||||
uv run python main.py --lang en_US --format tar.xz save
|
||||
```
|
||||
|
||||
**Параметры команды save:**
|
||||
|
||||
| Параметр | Значение по умолчанию | Описание |
|
||||
|----------|----------------------|----------|
|
||||
| `--keep N` | `0` | Сохранять N последних резервных копий; 0 -- не удалять старые |
|
||||
| `--password PASSWORD` | `""` | Пароль шифрования (только для формата 7z) |
|
||||
| `--sftp` | `false` | Загрузить на SFTP-сервер после завершения резервного копирования |
|
||||
| `--webdav` | `false` | Загрузить на WebDAV-сервер после завершения резервного копирования |
|
||||
|
||||
Автоматическое резервное копирование изменённых папок в соответствии с настроенными стратегиями.
|
||||
|
||||
#### Планирование резервного копирования
|
||||
|
||||
```bash
|
||||
# Выполнять резервное копирование каждые 60 минут
|
||||
uv run python main.py watch --interval 60
|
||||
|
||||
# Каждые 2 часа, сохранять последние 10 файлов
|
||||
uv run python main.py watch --interval 120 --keep 10
|
||||
|
||||
# Планирование + шифрование 7z
|
||||
uv run python main.py --format 7z watch --interval 60 --password mysecret
|
||||
```
|
||||
|
||||
**Параметры команды watch:**
|
||||
|
||||
| Параметр | Значение по умолчанию | Описание |
|
||||
|----------|----------------------|----------|
|
||||
| `--interval MINUTES` | `60` | Интервал резервного копирования (в минутах) |
|
||||
| `--keep N` | `0` | Сохранять N последних резервных копий |
|
||||
| `--password PASSWORD` | `""` | Пароль шифрования (только для формата 7z) |
|
||||
| `--sftp` | `false` | Загружать на SFTP-сервер после каждого бэкапа |
|
||||
| `--webdav` | `false` | Загружать на WebDAV-сервер после каждого бэкапа |
|
||||
|
||||
Нажмите `Ctrl+C`, чтобы остановить планирование.
|
||||
|
||||
#### Восстановление из резервной копии
|
||||
|
||||
```bash
|
||||
uv run python main.py restore <backup_file> <target_dir>
|
||||
```
|
||||
|
||||
Параметры:
|
||||
- **backup_file**: путь к файлу резервной копии (поддерживаются форматы .zip / .tar / .tar.gz / .tar.bz2 / .tar.xz / .tar.zst / .7z)
|
||||
- **target_dir**: целевая директория для восстановления
|
||||
|
||||
Примеры:
|
||||
```bash
|
||||
uv run python main.py restore F:/backup/my_folder.tar.gz F:/restored
|
||||
uv run python main.py restore F:/backup/my_folder.7z F:/restored
|
||||
uv run python main.py restore F:/backup/my_folder.tar.zst F:/restored
|
||||
```
|
||||
|
||||
#### Удалённое резервное копирование через SFTP
|
||||
|
||||
```bash
|
||||
# ============ Быстрый старт (рекомендуется) ============
|
||||
# 1. Настроить SFTP (автоматическое определение SSH-ключа, без ручного указания)
|
||||
sbackup sftp config --host 192.168.1.100 --user admin --remote-path /backups
|
||||
|
||||
# 2. Проверить соединение
|
||||
sbackup sftp test
|
||||
|
||||
# 3. Выполнить резервное копирование и загрузить
|
||||
sbackup save --sftp
|
||||
|
||||
# ============ Способы аутентификации ============
|
||||
|
||||
# Способ 1: Автоматическое определение ключа (рекомендуется)
|
||||
# Система автоматически проверяет ~/.ssh/id_ed25519 -> id_rsa -> id_ecdsa
|
||||
sbackup sftp config --host 192.168.1.100 --user admin
|
||||
|
||||
# Способ 2: Аутентификация по паролю
|
||||
sbackup sftp config --host 192.168.1.100 --user admin --password secret
|
||||
|
||||
# Способ 3: Указание конкретного ключа
|
||||
sbackup sftp config --host 192.168.1.100 --user admin --key-file ~/.ssh/id_rsa
|
||||
|
||||
# Способ 4: Ключ + парольная фраза (интерактивный ввод)
|
||||
sbackup sftp config --host 192.168.1.100 --user admin --key-file ~/.ssh/id_rsa
|
||||
|
||||
# Способ 5: Ключ + парольная фраза (через командную строку)
|
||||
sbackup sftp config --host 192.168.1.100 --user admin --key-file ~/.ssh/id_rsa --key-passphrase mykeypass
|
||||
|
||||
# ============ Сценарии использования ============
|
||||
|
||||
# Сценарий 1: Разовое резервное копирование с загрузкой
|
||||
sbackup save --sftp
|
||||
|
||||
# Сценарий 2: Планирование с автоматической загрузкой (каждые 60 минут)
|
||||
sbackup watch --interval 60 --sftp
|
||||
|
||||
# Сценарий 3: Указание формата + загрузка
|
||||
sbackup --format tar.gz save --sftp
|
||||
|
||||
# Сценарий 4: Шифрованное резервное копирование + загрузка
|
||||
sbackup --format 7z save --password mysecret --sftp
|
||||
|
||||
# Сценарий 5: Сохранение последних 5 копий + загрузка
|
||||
sbackup save --keep 5 --sftp
|
||||
|
||||
# ============ Расширенное использование ============
|
||||
|
||||
# Интерактивная настройка (пошаговый ввод всех параметров)
|
||||
sbackup sftp config
|
||||
|
||||
# Неинтерактивная настройка (все параметры через командную строку)
|
||||
sbackup sftp config --host 192.168.1.100 --port 22 --user admin --password secret --remote-path /backups
|
||||
|
||||
# Проверка соединения с подробным логом
|
||||
sbackup --debug sftp test
|
||||
```
|
||||
|
||||
**Подкоманды sftp:**
|
||||
|
||||
| Подкоманда | Описание | Пример |
|
||||
|------------|----------|--------|
|
||||
| `sftp config` | Настройка параметров подключения SFTP (host/port/user/password/key_file/key_passphrase/remote_path) | `sbackup sftp config --host 192.168.1.100 --user admin` |
|
||||
| `sftp test` | Проверка доступности SFTP-соединения | `sbackup sftp test` |
|
||||
|
||||
**Способы аутентификации:**
|
||||
|
||||
| Способ | Параметры | Описание | Пример |
|
||||
|--------|-----------|----------|--------|
|
||||
| **Автоопределение** | Без указания параметров аутентификации | Автоматическая проверка `~/.ssh/id_ed25519` -> `id_rsa` -> `id_ecdsa` (рекомендуется) | `sbackup sftp config --host ... --user ...` |
|
||||
| Пароль | `--password` | Вход по паролю | `sbackup sftp config --host ... --user ... --password secret` |
|
||||
| Приватный ключ | `--key-file` | Вход с использованием указанного SSH-ключа | `sbackup sftp config --host ... --user ... --key-file ~/.ssh/id_rsa` |
|
||||
| Ключ + фраза | `--key-file` + `--key-passphrase` | Для ключа с парольной фразой | `sbackup sftp config --host ... --user ... --key-file ~/.ssh/id_rsa --key-passphrase mypass` |
|
||||
|
||||
Поддерживаемые форматы ключей: RSA, Ed25519, ECDSA.
|
||||
|
||||
**Кроссплатформенная поддержка путей:**
|
||||
|
||||
| Платформа | Пример пути к ключу | Описание |
|
||||
|-----------|---------------------|----------|
|
||||
| Linux/macOS | `~/.ssh/id_rsa` | Автоматически раскрывается в `/home/user/.ssh/id_rsa` |
|
||||
| Windows | `~/.ssh/id_rsa` | Автоматически раскрывается в `C:\Users\username\.ssh\id_rsa` |
|
||||
| Все платформы | Абсолютный путь | Используется полный путь напрямую |
|
||||
|
||||
Конфигурация SFTP сохраняется в поле `sftp` файла `config.json`, параметры можно задать через командную строку или интерактивно.
|
||||
|
||||
#### Просмотр информации о версии
|
||||
|
||||
```bash
|
||||
sbackup version
|
||||
```
|
||||
|
||||
## Файл конфигурации
|
||||
|
||||
Sbackup поддерживает пользовательскую настройку через файл `config.json`. Файл конфигурации должен находиться в корневой директории проекта.
|
||||
|
||||
### Описание параметров конфигурации
|
||||
|
||||
```json
|
||||
{
|
||||
"compression_format": "ZIP",
|
||||
"compression": {
|
||||
"algorithm": "ZIP_DEFLATED",
|
||||
"level": 6
|
||||
},
|
||||
"skip_patterns": [".git", "__pycache__"],
|
||||
"data_file": "sbackup.json",
|
||||
"lang": "zh_CN",
|
||||
"password": "",
|
||||
"sftp": {
|
||||
"host": "",
|
||||
"port": 22,
|
||||
"user": "",
|
||||
"password": "",
|
||||
"key_file": "",
|
||||
"key_passphrase": "",
|
||||
"remote_path": "/",
|
||||
"enabled": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| Параметр | Тип | Значение по умолчанию | Описание |
|
||||
|----------|-----|----------------------|----------|
|
||||
| `compression_format` | string | `"ZIP"` | Формат упаковки; допустимые значения: `ZIP`, `TAR`, `TAR_GZ`, `TAR_BZ2`, `TAR_XZ`, `TAR_ZST`, `7Z` |
|
||||
| `compression.algorithm` | string | `"ZIP_DEFLATED"` | Алгоритм сжатия ZIP; допустимые значения: `ZIP_DEFLATED`, `ZIP_STORED`, `ZIP_BZIP2`, `ZIP_LZMA` |
|
||||
| `compression.level` | int | `6` | Уровень сжатия, диапазон 0-9 (0 -- без сжатия, 9 -- максимальное сжатие) |
|
||||
| `skip_patterns` | list | `[".git", "__pycache__"]` | Шаблоны игнорируемых файлов или папок (поддержка fnmatch-подстановок и сопоставления путей) |
|
||||
| `data_file` | string | Путь по умолчанию для платформы | Путь к файлу данных стратегий резервного копирования |
|
||||
| `lang` | string | `"zh_CN"` | Язык интерфейса; допустимые значения: `zh_CN`, `en_US`, `fr_FR`, `es_ES`, `ru_RU`, `de_DE`, `ja_JP`, `pt_BR`, `ko_KR` |
|
||||
| `password` | string | `""` | Пароль шифрования для формата 7z |
|
||||
| `sftp.host` | string | `""` | Адрес SFTP-сервера |
|
||||
| `sftp.port` | int | `22` | Порт SFTP |
|
||||
| `sftp.user` | string | `""` | Имя пользователя SFTP |
|
||||
| `sftp.password` | string | `""` | Пароль SFTP (используется при аутентификации по паролю) |
|
||||
| `sftp.key_file` | string | `""` | Путь к файлу приватного SSH-ключа (используется при аутентификации по ключу, рекомендуется) |
|
||||
| `sftp.key_passphrase` | string | `""` | Парольная фраза ключа (при наличии) |
|
||||
| `sftp.remote_path` | string | `"/"` | Путь к удалённой директории назначения |
|
||||
| `sftp.enabled` | bool | `false` | Включить или отключить SFTP |
|
||||
|
||||
### Пример конфигурации
|
||||
|
||||
Резервное копирование с высокой степенью сжатия в формате tar.bz2:
|
||||
|
||||
```json
|
||||
{
|
||||
"compression_format": "TAR_BZ2",
|
||||
"compression_level": 9,
|
||||
"skip_patterns": [".git", "__pycache__", "node_modules", "*.log"],
|
||||
"data_file": "backup_strategies.json",
|
||||
"lang": "zh_CN"
|
||||
}
|
||||
```
|
||||
|
||||
### Сравнение форматов упаковки
|
||||
|
||||
| Формат | Расширение | Степень сжатия | Скорость | Зависимости | Применение |
|
||||
|--------|------------|----------------|----------|-------------|------------|
|
||||
| ZIP | .zip | Средняя | Высокая | Стандартная библиотека | Универсальный, лучшая совместимость с Windows |
|
||||
| tar | .tar | Нет | Очень высокая | Стандартная библиотека | Чистая архивация, для внешнего сжатия |
|
||||
| tar.gz | .tar.gz | Средняя | Высокая | Стандартная библиотека | Универсальный для Linux/macOS |
|
||||
| tar.bz2 | .tar.bz2 | Высокая | Средняя | Стандартная библиотека | Архивация с высокой степенью сжатия |
|
||||
| tar.xz | .tar.xz | Максимальная | Низкая | Стандартная библиотека | Долгосрочное архивирование, экономия места |
|
||||
| tar.zst | .tar.zst | Средне-высокая | Очень высокая | zstandard | Современный формат, баланс скорости и сжатия |
|
||||
| 7z | .7z | Очень высокая | Низкая | py7zr | Максимальное сжатие, поддержка шифрования |
|
||||
|
||||
#### Удалённое резервное копирование через WebDAV
|
||||
|
||||
WebDAV -- это файловый протокол на основе HTTP, поддерживаемый такими сервисами, как Jianguoyun, NextCloud, Synology и другими. Использует стандартную библиотеку Python `urllib`, **без дополнительных зависимостей**.
|
||||
|
||||
```bash
|
||||
# ============ Быстрый старт ============
|
||||
# 1. Настроить WebDAV
|
||||
sbackup webdav config --url https://dav.jianguoyun.com/dav/ --user user@example.com --password secret
|
||||
|
||||
# 2. Проверить соединение
|
||||
sbackup webdav test
|
||||
|
||||
# 3. Выполнить резервное копирование и загрузить
|
||||
sbackup save --webdav
|
||||
|
||||
# ============ Сценарии использования ============
|
||||
|
||||
# Сценарий 1: Разовое резервное копирование с загрузкой
|
||||
sbackup save --webdav
|
||||
|
||||
# Сценарий 2: Планирование с автоматической загрузкой (каждые 60 минут)
|
||||
sbackup watch --interval 60 --webdav
|
||||
|
||||
# Сценарий 3: Указание удалённой поддиректории
|
||||
sbackup webdav config --url https://dav.jianguoyun.com/dav/ --user user@example.com --remote-path /backups/sbackup
|
||||
|
||||
# Сценарий 4: Одновременная загрузка на SFTP и WebDAV
|
||||
sbackup save --sftp --webdav
|
||||
|
||||
# ============ Типичные адреса WebDAV-сервисов ============
|
||||
# Jianguoyun: https://dav.jianguoyun.com/dav/
|
||||
# NextCloud: https://your-server/remote.php/dav/files/username/
|
||||
# Synology: https://your-synology:5006/webdav/
|
||||
```
|
||||
|
||||
**Подкоманды webdav:**
|
||||
|
||||
| Подкоманда | Описание | Пример |
|
||||
|------------|----------|--------|
|
||||
| `webdav config` | Настройка параметров подключения WebDAV (url/user/password/remote_path) | `sbackup webdav config --url ... --user ...` |
|
||||
| `webdav test` | Проверка доступности WebDAV-соединения | `sbackup webdav test` |
|
||||
|
||||
| Параметр | Значение по умолчанию | Описание |
|
||||
|----------|----------------------|----------|
|
||||
| `--url URL` | `""` | Адрес WebDAV-сервера (например, `https://dav.jianguoyun.com/dav/`) |
|
||||
| `--user USER` | `""` | Имя пользователя WebDAV (обычно адрес электронной почты) |
|
||||
| `--password PASS` | `""` | Пароль WebDAV (для Jianguoyun необходимо сгенерировать пароль приложения в настройках) |
|
||||
| `--remote-path PATH` | `/` | Путь к удалённой директории назначения |
|
||||
|
||||
## Принцип работы
|
||||
|
||||
Sbackup реализует резервное копирование следующим образом:
|
||||
|
||||
1. **Хранение стратегий**: стратегии резервного копирования хранятся в файле JSON и содержат пути к папкам, время последнего изменения, пути назначения, шаблоны игнорирования и формат упаковки на уровне элемента.
|
||||
2. **Инкрементальное копирование**: путём сравнения времени последнего изменения папки копируются только изменённые папки.
|
||||
3. **Множественные форматы сжатия**: используются встроенные модули Python `zipfile` и `tarfile`, а также сторонние библиотеки `zstandard` и `py7zr` для поддержки семи форматов упаковки.
|
||||
4. **Формат на уровне элемента**: каждая стратегия может иметь собственный формат упаковки (`add --format`), который имеет приоритет над глобальным параметром `--format`; при отсутствии используется значение по умолчанию.
|
||||
5. **Очистка бэкапов**: после успешного резервного копирования автоматически сканируется целевая директория, файлы сортируются по времени изменения и удаляются старые копии, превышающие лимит хранения.
|
||||
6. **Шифрование**: формат 7z поддерживает шифрование LZMA2 через параметр `--password` или настройку в `config.json`.
|
||||
7. **Планирование**: команда `watch` выполняет резервное копирование в цикле с указанным интервалом, для безопасного выхода используется `Ctrl+C`.
|
||||
8. **История бэкапов**: после каждого резервного копирования записываются временная метка, размер файла и количество файлов; хранятся последние 100 записей.
|
||||
9. **Удалённое копирование через SFTP**: на базе библиотеки paramiko реализован SFTP-клиент с поддержкой проверки соединения, автоматического создания удалённых директорий и загрузки файлов с индикатором прогресса.
|
||||
|
||||
### Формат файла данных
|
||||
|
||||
```json
|
||||
{
|
||||
"/path/to/source/folder": [
|
||||
1719235200.0,
|
||||
"/path/to/target/folder",
|
||||
[".git", "__pycache__"],
|
||||
""
|
||||
],
|
||||
"/path/to/another/folder": [
|
||||
1719235200.0,
|
||||
"/path/to/another/target",
|
||||
[".git"],
|
||||
"TAR_GZ"
|
||||
],
|
||||
"_history": [
|
||||
{
|
||||
"time": "2026-05-01T12:00:00",
|
||||
"source": "/path/to/source/folder",
|
||||
"size_mb": 12.5,
|
||||
"files_count": 150
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Каждая запись стратегии резервного копирования представляет собой список из 4 элементов: `[mtime, target, skip_patterns, compression_format]`
|
||||
|
||||
| Поле | Описание |
|
||||
|------|----------|
|
||||
| `mtime` | Время последнего изменения исходной папки (для определения необходимости инкрементального копирования) |
|
||||
| `target` | Путь к директории для хранения резервных копий |
|
||||
| `skip_patterns` | Список шаблонов игнорируемых файлов/папок |
|
||||
| `compression_format` | Формат упаковки на уровне элемента (пустая строка означает использование глобального значения по умолчанию) |
|
||||
|
||||
## Руководство для разработчиков
|
||||
|
||||
### Запуск тестов
|
||||
|
||||
```bash
|
||||
uv run coverage run -m unittest discover -s tests -t . && uv run coverage report -m
|
||||
```
|
||||
|
||||
### Структура кода
|
||||
|
||||
```
|
||||
sbackup/
|
||||
├── main.py # Точка входа программы
|
||||
├── sbackup/
|
||||
│ ├── __init__.py # Экспорт основных функций
|
||||
│ ├── __main__.py # Точка входа python -m sbackup
|
||||
│ ├── cli.py # Разбор аргументов CLI и маршрутизация команд (30+ команд)
|
||||
│ ├── config.py # Загрузка конфигурации, шифрование, настройки Webhook/SMTP
|
||||
│ ├── auto_save.py # Основной движок BackupManager
|
||||
│ ├── compression.py # Движок сжатия/распаковки для 7 форматов
|
||||
│ ├── i18n.py # Интернационализация (9 языков)
|
||||
│ ├── sftp.py # SFTP-клиент для удалённого копирования (paramiko)
|
||||
│ ├── webdav.py # WebDAV-клиент для удалённого копирования (без зависимостей)
|
||||
│ ├── cloud_storage.py # S3-клиент для облачного хранилища (minio)
|
||||
│ ├── multi_dest.py # Параллельное копирование в несколько направлений
|
||||
│ ├── handlers.py # Обработчики команд SFTP/WebDAV/Remote/Schedule
|
||||
│ ├── hooks.py # Выполнение Pre/Post Hook
|
||||
│ ├── audit.py # Система журналирования аудита
|
||||
│ ├── profile.py # Управление профилями конфигурации
|
||||
│ ├── selective.py # Выборочное восстановление
|
||||
│ ├── cross_search.py | Поиск по архивам
|
||||
│ ├── integrity.py # Контрольные суммы SHA256
|
||||
│ ├── rotation.py # Стратегии ротации резервных копий
|
||||
│ ├── dryrun.py # Предварительный просмотр (dry-run)
|
||||
│ ├── diskcheck.py # Оценка дискового пространства
|
||||
│ ├── task_queue.py # Система очереди задач
|
||||
│ ├── schema.py # Валидатор конфигурации
|
||||
│ ├── benchmark.py # Бенчмарк сжатия
|
||||
│ ├── chunked_backup.py# Блочное инкрементальное копирование
|
||||
│ ├── dedup.py # Дедупликация файлов по SHA256
|
||||
│ ├── export.py # Экспорт метаданных (CSV/JSON)
|
||||
│ ├── monitor.py # Мониторинг файловой системы (watchdog)
|
||||
│ ├── lock.py # Кроссплатформенная блокировка процессов
|
||||
│ ├── retry.py | Повторные попытки с экспоненциальной задержкой
|
||||
│ ├── ratelimiter.py | Ограничитель скорости (алгоритм токен-ведра)
|
||||
│ ├── keychain.py | Интеграция с системной связкой ключей
|
||||
│ ├── parity.py | Корректирующие коды Рида-Соломона
|
||||
│ ├── completion.py | Автодополнение для оболочки
|
||||
│ ├── wizard.py | Интерактивный мастер настройки
|
||||
│ └── locales/ # Файлы перевода на 9 языков
|
||||
└── tests/
|
||||
└── sbackup/
|
||||
└── test_*.py # 30 тестовых файлов, покрывающих все модули
|
||||
```
|
||||
|
||||
### Добавление нового функционала
|
||||
|
||||
1. Создайте новый файл модуля в директории `sbackup/`
|
||||
2. Импортируйте функции нового модуля в `sbackup/__init__.py`
|
||||
3. Добавьте обработку новой команды в функцию `run()`
|
||||
4. Добавьте соответствующий тестовый файл в директорию `tests/`
|
||||
|
||||
## Часто задаваемые вопросы
|
||||
|
||||
### В: Что делать, если файл стратегий резервного копирования был случайно удалён?
|
||||
|
||||
О: Стратегии хранятся в файле данных. Если файл был удалён, просто заново добавьте стратегии с помощью команды `add`.
|
||||
|
||||
### В: Как изменить ранее добавленную стратегию?
|
||||
|
||||
О: Используйте команду `sbackup edit`: `sbackup edit <source> --dest <new_dest> --ignore <patterns> --format <fmt>`.
|
||||
|
||||
### В: Поддерживается ли удалённое резервное копирование?
|
||||
|
||||
О: Да! Предоставляются три способа удалённого копирования:
|
||||
- **SFTP**: настройка через `sbackup sftp config`, загрузка через `sbackup save --sftp`
|
||||
- **WebDAV**: настройка через `sbackup webdav config`, загрузка через `sbackup save --webdav` (поддержка Jianguoyun/NextCloud/Synology)
|
||||
- **Облачное хранилище S3**: настройка поля `cloud` в `config.json`, загрузка через `sbackup save --cloud`
|
||||
- Можно включить несколько способов одновременно: `sbackup save --sftp --webdav --cloud`
|
||||
|
||||
### В: В чём разница между tar.gz и ZIP?
|
||||
|
||||
О: tar.gz чаще используется в Linux/macOS и обеспечивает немного лучшее сжатие; ZIP более универсален на Windows и обладает лучшей совместимостью. tar.bz2 и tar.xz обеспечивают более высокую степень сжатия, но работают медленнее. tar.zst -- современный алгоритм с высокой скоростью и хорошим сжатием. 7z обеспечивает максимальное сжатие и поддерживает шифрование.
|
||||
|
||||
### В: Как зашифровать резервную копию?
|
||||
|
||||
О: Используйте формат 7z с паролем: `uv run python main.py --format 7z save --password yourpassword`. Пароль также можно указать в поле `password` файла `config.json`.
|
||||
|
||||
### В: Как автоматически очищать старые резервные копии?
|
||||
|
||||
О: Используйте параметр `--keep`: `uv run python main.py save --keep 5` сохранит только 5 последних резервных копий. При планировании тоже поддерживается: `uv run python main.py watch --interval 60 --keep 10`.
|
||||
|
||||
### В: Как настроить автоматическое резервное копирование по расписанию?
|
||||
|
||||
О: Используйте команду `watch`: `uv run python main.py watch --interval 60` -- резервное копирование каждые 60 минут. Нажмите `Ctrl+C` для остановки.
|
||||
|
||||
### В: Безопасно ли хранение паролей?
|
||||
|
||||
О: Пароли SFTP и шифрования 7z в файле `config.json` хранятся в **открытом виде**. Убедитесь, что доступ к файлу `config.json` имеют только доверенные пользователи (например, `chmod 600 config.json`). Не добавляйте файл `config.json`, содержащий пароли, в систему контроля версий.
|
||||
|
||||
## Руководство по участию в разработке
|
||||
|
||||
Приветствуются Issues и Pull Requests!
|
||||
|
||||
1. Сделайте форк репозитория
|
||||
2. Создайте ветку для новой функции (`git checkout -b feature/AmazingFeature`)
|
||||
3. Внесите изменения (`git commit -m 'Add some AmazingFeature'`)
|
||||
4. Отправьте в ветку (`git push origin feature/AmazingFeature`)
|
||||
5. Создайте Pull Request
|
||||
|
||||
### Стиль кодирования
|
||||
|
||||
Проект следует стандартам PEP 8 и Google Python Style Guide. Убедитесь, что ваш код:
|
||||
- Использует аннотации типов
|
||||
- Следует Google-стилю docstrings
|
||||
- Проходит все модульные тесты
|
||||
|
||||
## Лицензия
|
||||
|
||||
Проект распространяется под лицензией GNU GPL v3.0. Подробности см. в файле [LICENSE](../../LICENSE).
|
||||
|
||||
## Автор
|
||||
|
||||
**xiatianxuan** (CodeSeed)
|
||||
|
||||
- [Gitee](https://gitee.com/xiatianxuan)
|
||||
- [Личная страница](https://xnors-codeseed.pages.dev/)
|
||||
|
||||
## Благодарности
|
||||
|
||||
- [Xnors Studio](https://xnors.github.io/)
|
||||
|
||||
## Связь с нами
|
||||
|
||||
По вопросам и предложениям обращайтесь по электронной почте: xiatianxuan2025@163.com
|
||||
|
||||
---
|
||||
|
||||
*Последнее обновление: 19 июня 2026 г.*
|
||||
@@ -0,0 +1,665 @@
|
||||
# Sbackup
|
||||
|
||||
[](https://www.python.org/)
|
||||
[](LICENSE)
|
||||
[](https://pypi.org/project/sbackup-cli/)
|
||||
[](.github/workflows/ci.yml)
|
||||
[]()
|
||||
|
||||
> 轻量、高效的文件夹备份工具，支持命令行操作，帮助你轻松管理备份策略。
|
||||
|
||||
[English](../../README.md) | [Deutsch](README_de.md) | [Espanol](README_es.md) | [Francais](README_fr.md) | [Italiano](README_it.md) | [Portugues](README_pt.md) | [Pycckuu](README_ru.md) | [日本語](README_ja.md) | [한국어](README_ko.md)
|
||||
|
||||
- [简介](#简介)
|
||||
- [功能特性](#功能特性)
|
||||
- [快速开始](#快速开始)
|
||||
- [安装](#安装)
|
||||
- [使用方法](#使用方法)
|
||||
- [配置文件](#配置文件)
|
||||
- [配置示例](#配置示例)
|
||||
- [SFTP 远程备份](#sftp-远程备份)
|
||||
- [WebDAV 远程备份](#webdav-远程备份)
|
||||
- [实现原理](#实现原理)
|
||||
- [开发指南](#开发指南)
|
||||
- [运行测试](#运行测试)
|
||||
- [代码结构](#代码结构)
|
||||
- [常见问题](#常见问题)
|
||||
- [贡献指南](#贡献指南)
|
||||
- [许可证](#许可证)
|
||||
- [作者](#作者)
|
||||
|
||||
---
|
||||
|
||||
## 简介
|
||||
|
||||
Sbackup 是一个轻量级的文件夹备份工具，支持通过命令行添加、删除和查看备份策略。它基于文件夹的最后修改时间来决定是否需要进行备份，确保你的数据始终保持最新状态。
|
||||
|
||||
## 功能特性
|
||||
|
||||
- ✅ **增量备份**：仅备份已更改的文件夹，节省时间和存储空间
|
||||
- ✅ **多格式支持**：支持 ZIP、tar、tar.gz、tar.bz2、tar.xz、tar.zst、7z 七种打包格式，全局和条目级均可独立指定
|
||||
- ✅ **SFTP 远程备份**：基于 paramiko 库，支持密码/SSH 私钥认证、自动检测默认私钥
|
||||
- ✅ **WebDAV 远程备份**：基于标准库 urllib，零额外依赖，支持坚果云/NextCloud/群晖
|
||||
- ✅ **S3 云存储**：基于 minio 库，支持所有 S3 兼容存储（AWS/MinIO/阿里云 OSS 等）
|
||||
- ✅ **多目标并行备份**：同时备份到本地 + 多个远程目标，互不影响
|
||||
- ✅ **备份还原**：支持从备份文件解压还原到指定目录，支持选择性恢复
|
||||
- ✅ **备份清理**：自动删除旧备份，支持按数量/时间/每日保留策略
|
||||
- ✅ **加密备份**：支持 7z 格式密码加密 + 全格式 PBKDF2 加密
|
||||
- ✅ **定时备份**：设置间隔自动执行，支持实时文件监控（watchdog）
|
||||
- ✅ **备份历史**：记录每次备份的时间、大小、SHA256 校验和，方便追溯
|
||||
- ✅ **审计日志**：记录所有备份/恢复操作的审计事件
|
||||
- ✅ **Pre/Post Hook**：备份前后执行自定义命令
|
||||
- ✅ **配置 Profile**：支持多配置方案的保存、切换、导入导出
|
||||
- ✅ **跨档案搜索**：在多个备份文件中搜索匹配的文件名
|
||||
- ✅ **数据完整性**：SHA256 校验和生成与验证，Reed-Solomon 纠错码
|
||||
- ✅ **配置校验**：自动校验配置参数合法性，检测篡改
|
||||
- ✅ **任务队列**：管理备份任务队列，支持添加、执行、取消
|
||||
- ✅ **压缩基准测试**：比较不同格式/级别的压缩性能
|
||||
- ✅ **磁盘空间预估**：按文件类型估算备份大小，检查目标空间
|
||||
- ✅ **国际化**：支持中文、英语、法语、西班牙语、俄语、德语、日语、葡萄牙语、韩语九种语言
|
||||
- ✅ **Shell 补全**：支持 bash/zsh/fish/powershell 自动补全
|
||||
- ✅ **轻量高效**：体积小，启动速度快，资源占用低
|
||||
- ✅ **跨平台支持**：支持 Windows、macOS 和 Linux
|
||||
|
||||
## 快速开始
|
||||
|
||||
### 安装
|
||||
|
||||
#### 使用 pip 安装
|
||||
|
||||
```bash
|
||||
pip install sbackup-cli
|
||||
```
|
||||
|
||||
安装后使用 `sbackup` 命令（PyPI 包名为 `sbackup-cli`，CLI 命令为 `sbackup`）。
|
||||
|
||||
#### 从源码安装
|
||||
|
||||
```bash
|
||||
git clone https://github.com/xiatianxuan/sbackup.git
|
||||
cd sbackup
|
||||
uv sync
|
||||
```
|
||||
|
||||
### 使用方法
|
||||
|
||||
#### 基本语法
|
||||
|
||||
```bash
|
||||
uv run python main.py <command> [options]
|
||||
```
|
||||
|
||||
#### 可用命令
|
||||
|
||||
| 命令 | 描述 |
|
||||
|------|------|
|
||||
| `add` | 添加备份策略 |
|
||||
| `rm` / `remove` | 删除备份策略 |
|
||||
| `edit` | 编辑已有备份策略 |
|
||||
| `all` | 查看所有备份策略 |
|
||||
| `save` | 执行备份 |
|
||||
| `watch` | 定时执行备份 |
|
||||
| `restore` | 从备份文件还原 |
|
||||
| `info` | 查看备份文件详情 |
|
||||
| `diff` | 对比源目录与备份的差异 |
|
||||
| `verify` | 校验备份文件完整性 |
|
||||
| `search` | 在备份中搜索文件 |
|
||||
| `xsearch` | 跨多个备份档案搜索 |
|
||||
| `versions` | 查看备份版本历史 |
|
||||
| `sftp` | SFTP 远程备份管理 |
|
||||
| `webdav` | WebDAV 远程备份管理 |
|
||||
| `remote` | 远程文件管理（list/rm） |
|
||||
| `task` | 备份任务队列管理 |
|
||||
| `audit` | 审计日志查询 |
|
||||
| `hooks` | 手动执行 Pre/Post Hook |
|
||||
| `profile` | 配置 Profile 管理 |
|
||||
| `rotate` | 备份轮转清理 |
|
||||
| `clean` | 清理旧备份 |
|
||||
| `diskcheck` | 磁盘空间预估 |
|
||||
| `benchmark` | 压缩格式基准测试 |
|
||||
| `integrity` | 备份目录完整性校验 |
|
||||
| `dry-run` | 预览备份文件选择 |
|
||||
| `export` / `import` | 导出/导入备份策略 |
|
||||
| `ignore` | 生成 .sbackupignore 文件 |
|
||||
| `schedule` | 导出定时调度配置 |
|
||||
| `webhook` | 配置 Webhook 预设 |
|
||||
| `config` | 配置加密/校验 |
|
||||
| `report` | 生成备份报告 |
|
||||
| `completion` | 生成 Shell 补全脚本 |
|
||||
| `wizard` | 交互式配置向导 |
|
||||
| `status` | 备份状态仪表盘 |
|
||||
| `version` | 查看版本信息 |
|
||||
| `help` | 查看帮助信息 |
|
||||
|
||||
#### 全局参数
|
||||
|
||||
| 参数 | 描述 |
|
||||
|------|------|
|
||||
| `--lang zh_CN` / `en_US` / `fr_FR` / `es_ES` / `ru_RU` / `de_DE` / `ja_JP` / `pt_BR` / `ko_KR` | 设置界面语言（持久化到 config.json） |
|
||||
| `--format zip` / `tar` / `tar.gz` / `tar.bz2` / `tar.xz` / `tar.zst` / `7z` | 设置打包格式（持久化到 config.json） |
|
||||
| `--debug` | 开启调试日志 |
|
||||
|
||||
#### 添加备份策略
|
||||
|
||||
```bash
|
||||
uv run python main.py add <source> <dest> [-i ignore_patterns]
|
||||
```
|
||||
|
||||
参数说明：
|
||||
- **source**：需要备份的源文件夹路径
|
||||
- **dest**：备份文件存放的目标路径
|
||||
- **-i, --ignore**：需要忽略的文件或文件夹名称，使用逗号分隔（默认：`.git,__pycache__`）
|
||||
- **--format**：条目级打包格式（仅作用于该备份策略，不指定则使用全局默认）：`zip` / `tar` / `tar.gz` / `tar.bz2` / `tar.xz` / `tar.zst` / `7z`
|
||||
|
||||
示例：
|
||||
```bash
|
||||
# 使用全局默认格式添加策略
|
||||
uv run python main.py add F:/my_folder F:/backup -i node_modules,.git
|
||||
|
||||
# 为该策略指定 tar.gz 格式（每次备份此文件夹都使用 tar.gz）
|
||||
uv run python main.py add F:/my_folder F:/backup --format tar.gz
|
||||
|
||||
# 指定 7z 格式（仅此文件夹）
|
||||
uv run python main.py add F:/my_folder F:/backup --format 7z
|
||||
```
|
||||
|
||||
#### 删除备份策略
|
||||
|
||||
```bash
|
||||
uv run python main.py rm <path>
|
||||
```
|
||||
|
||||
参数说明：
|
||||
- **path**：需要删除备份策略的源文件夹路径
|
||||
|
||||
示例：
|
||||
```bash
|
||||
uv run python main.py rm F:/my_folder
|
||||
```
|
||||
|
||||
#### 查看所有备份策略
|
||||
|
||||
```bash
|
||||
uv run python main.py all
|
||||
```
|
||||
|
||||
显示当前所有已配置的备份策略。
|
||||
|
||||
#### 执行备份
|
||||
|
||||
```bash
|
||||
# 使用默认格式（ZIP）
|
||||
uv run python main.py save
|
||||
|
||||
# 使用 tar.gz 格式
|
||||
uv run python main.py --format tar.gz save
|
||||
|
||||
# 保留最近 5 个备份文件，自动清理旧的
|
||||
uv run python main.py save --keep 5
|
||||
|
||||
# 使用 7z 格式并加密
|
||||
uv run python main.py --format 7z save --password mysecret
|
||||
|
||||
# 英文界面 + tar.xz 格式
|
||||
uv run python main.py --lang en_US --format tar.xz save
|
||||
```
|
||||
|
||||
**save 命令参数：**
|
||||
|
||||
| 参数 | 默认值 | 描述 |
|
||||
|------|--------|------|
|
||||
| `--keep N` | `0` | 保留最近 N 个备份文件，0 表示不清理 |
|
||||
| `--password PASSWORD` | `""` | 加密密码（仅 7z 格式支持） |
|
||||
| `--sftp` | `false` | 备份完成后上传到 SFTP 服务器 |
|
||||
| `--webdav` | `false` | 备份完成后上传到 WebDAV 服务器 |
|
||||
|
||||
根据备份策略，自动备份已更改的文件夹。
|
||||
|
||||
#### 定时备份
|
||||
|
||||
```bash
|
||||
# 每 60 分钟执行一次备份
|
||||
uv run python main.py watch --interval 60
|
||||
|
||||
# 每 2 小时备份一次，保留最近 10 个文件
|
||||
uv run python main.py watch --interval 120 --keep 10
|
||||
|
||||
# 定时备份 + 7z 加密
|
||||
uv run python main.py --format 7z watch --interval 60 --password mysecret
|
||||
```
|
||||
|
||||
**watch 命令参数：**
|
||||
|
||||
| 参数 | 默认值 | 描述 |
|
||||
|------|--------|------|
|
||||
| `--interval MINUTES` | `60` | 备份间隔（分钟） |
|
||||
| `--keep N` | `0` | 保留最近 N 个备份文件 |
|
||||
| `--password PASSWORD` | `""` | 加密密码（仅 7z 格式支持） |
|
||||
| `--sftp` | `false` | 每次备份后上传到 SFTP 服务器 |
|
||||
| `--webdav` | `false` | 每次备份后上传到 WebDAV 服务器 |
|
||||
|
||||
按 `Ctrl+C` 停止定时备份。
|
||||
|
||||
#### 还原备份
|
||||
|
||||
```bash
|
||||
uv run python main.py restore <backup_file> <target_dir>
|
||||
```
|
||||
|
||||
参数说明：
|
||||
- **backup_file**：备份文件路径（支持 .zip / .tar / .tar.gz / .tar.bz2 / .tar.xz / .tar.zst / .7z）
|
||||
- **target_dir**：还原目标目录
|
||||
|
||||
示例：
|
||||
```bash
|
||||
uv run python main.py restore F:/backup/my_folder.tar.gz F:/restored
|
||||
uv run python main.py restore F:/backup/my_folder.7z F:/restored
|
||||
uv run python main.py restore F:/backup/my_folder.tar.zst F:/restored
|
||||
```
|
||||
|
||||
#### SFTP 远程备份
|
||||
|
||||
```bash
|
||||
# ============ 快速开始（推荐） ============
|
||||
# 1. 配置 SFTP（自动检测 SSH 私钥，无需手动指定）
|
||||
sbackup sftp config --host 192.168.1.100 --user admin --remote-path /backups
|
||||
|
||||
# 2. 测试连接
|
||||
sbackup sftp test
|
||||
|
||||
# 3. 执行备份并上传
|
||||
sbackup save --sftp
|
||||
|
||||
# ============ 认证方式 ============
|
||||
|
||||
# 方式一：自动检测私钥（推荐）
|
||||
# 系统自动尝试 ~/.ssh/id_ed25519 → id_rsa → id_ecdsa
|
||||
sbackup sftp config --host 192.168.1.100 --user admin
|
||||
|
||||
# 方式二：密码认证
|
||||
sbackup sftp config --host 192.168.1.100 --user admin --password secret
|
||||
|
||||
# 方式三：指定私钥
|
||||
sbackup sftp config --host 192.168.1.100 --user admin --key-file ~/.ssh/id_rsa
|
||||
|
||||
# 方式四：私钥 + 密码短语（交互式输入）
|
||||
sbackup sftp config --host 192.168.1.100 --user admin --key-file ~/.ssh/id_rsa
|
||||
|
||||
# 方式五：私钥 + 密码短语（命令行指定）
|
||||
sbackup sftp config --host 192.168.1.100 --user admin --key-file ~/.ssh/id_rsa --key-passphrase mykeypass
|
||||
|
||||
# ============ 使用场景 ============
|
||||
|
||||
# 场景一：一次性备份并上传
|
||||
sbackup save --sftp
|
||||
|
||||
# 场景二：定时备份并自动上传（每 60 分钟）
|
||||
sbackup watch --interval 60 --sftp
|
||||
|
||||
# 场景三：指定格式备份 + 上传
|
||||
sbackup --format tar.gz save --sftp
|
||||
|
||||
# 场景四：加密备份 + 上传
|
||||
sbackup --format 7z save --password mysecret --sftp
|
||||
|
||||
# 场景五：保留最近 5 个备份 + 上传
|
||||
sbackup save --keep 5 --sftp
|
||||
|
||||
# ============ 高级用法 ============
|
||||
|
||||
# 交互式配置（逐步输入所有参数）
|
||||
sbackup sftp config
|
||||
|
||||
# 非交互式配置（全部参数在命令行指定）
|
||||
sbackup sftp config --host 192.168.1.100 --port 22 --user admin --password secret --remote-path /backups
|
||||
|
||||
# 测试连接并查看详细日志
|
||||
sbackup --debug sftp test
|
||||
```
|
||||
|
||||
**sftp 子命令：**
|
||||
|
||||
| 子命令 | 描述 | 示例 |
|
||||
|--------|------|------|
|
||||
| `sftp config` | 配置 SFTP 连接参数（host/port/user/password/key_file/key_passphrase/remote_path） | `sbackup sftp config --host 192.168.1.100 --user admin` |
|
||||
| `sftp test` | 测试 SFTP 连接是否可用 | `sbackup sftp test` |
|
||||
|
||||
**认证方式：**
|
||||
|
||||
| 方式 | 参数 | 说明 | 示例 |
|
||||
|------|------|------|------|
|
||||
| **自动检测** | 不指定认证参数 | 自动尝试 `~/.ssh/id_ed25519` → `id_rsa` → `id_ecdsa`（推荐） | `sbackup sftp config --host ... --user ...` |
|
||||
| 密码认证 | `--password` | 直接使用密码登录 | `sbackup sftp config --host ... --user ... --password secret` |
|
||||
| 私钥认证 | `--key-file` | 使用指定 SSH 私钥登录 | `sbackup sftp config --host ... --user ... --key-file ~/.ssh/id_rsa` |
|
||||
| 私钥+短语 | `--key-file` + `--key-passphrase` | 私钥有密码短语时使用 | `sbackup sftp config --host ... --user ... --key-file ~/.ssh/id_rsa --key-passphrase mypass` |
|
||||
|
||||
支持的私钥格式：RSA、Ed25519、ECDSA。
|
||||
|
||||
**跨平台路径支持：**
|
||||
|
||||
| 平台 | 私钥路径示例 | 说明 |
|
||||
|------|-------------|------|
|
||||
| Linux/mac | `~/.ssh/id_rsa` | 自动展开为 `/home/user/.ssh/id_rsa` |
|
||||
| Windows | `~/.ssh/id_rsa` | 自动展开为 `C:\Users\username\.ssh\id_rsa` |
|
||||
| 全平台 | 绝对路径 | 直接使用完整路径 |
|
||||
|
||||
SFTP 配置保存在 `config.json` 的 `sftp` 字段中，支持命令行参数或交互式输入。
|
||||
|
||||
#### 查看版本信息
|
||||
|
||||
```bash
|
||||
sbackup version
|
||||
```
|
||||
|
||||
## 配置文件
|
||||
|
||||
Sbackup 支持通过 `config.json` 文件进行自定义配置。配置文件应放在项目根目录下。
|
||||
|
||||
### 配置项说明
|
||||
|
||||
```json
|
||||
{
|
||||
"compression_format": "ZIP",
|
||||
"compression": {
|
||||
"algorithm": "ZIP_DEFLATED",
|
||||
"level": 6
|
||||
},
|
||||
"skip_patterns": [".git", "__pycache__"],
|
||||
"data_file": "sbackup.json",
|
||||
"lang": "zh_CN",
|
||||
"password": "",
|
||||
"sftp": {
|
||||
"host": "",
|
||||
"port": 22,
|
||||
"user": "",
|
||||
"password": "",
|
||||
"key_file": "",
|
||||
"key_passphrase": "",
|
||||
"remote_path": "/",
|
||||
"enabled": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| 配置项 | 类型 | 默认值 | 描述 |
|
||||
|--------|------|--------|------|
|
||||
| `compression_format` | string | `"ZIP"` | 打包格式，可选值：`ZIP`, `TAR`, `TAR_GZ`, `TAR_BZ2`, `TAR_XZ`, `TAR_ZST`, `7Z` |
|
||||
| `compression.algorithm` | string | `"ZIP_DEFLATED"` | ZIP 压缩算法，可选值：`ZIP_DEFLATED`, `ZIP_STORED`, `ZIP_BZIP2`, `ZIP_LZMA` |
|
||||
| `compression.level` | int | `6` | 压缩级别，范围 0-9（0 为不压缩，9 为最高压缩） |
|
||||
| `skip_patterns` | list | `[".git", "__pycache__"]` | 需要忽略的文件或文件夹模式（支持 fnmatch 通配符和路径匹配） |
|
||||
| `data_file` | string | 平台默认路径 | 备份策略数据文件的存放路径 |
|
||||
| `lang` | string | `"zh_CN"` | 界面语言，可选值：`zh_CN`, `en_US`, `fr_FR`, `es_ES`, `ru_RU`, `de_DE`, `ja_JP`, `pt_BR`, `ko_KR` |
|
||||
| `password` | string | `""` | 7z 加密密码 |
|
||||
| `sftp.host` | string | `""` | SFTP 服务器地址 |
|
||||
| `sftp.port` | int | `22` | SFTP 端口 |
|
||||
| `sftp.user` | string | `""` | SFTP 用户名 |
|
||||
| `sftp.password` | string | `""` | SFTP 密码（密码认证时使用） |
|
||||
| `sftp.key_file` | string | `""` | SSH 私钥文件路径（私钥认证时使用，推荐） |
|
||||
| `sftp.key_passphrase` | string | `""` | 私钥密码短语（如有） |
|
||||
| `sftp.remote_path` | string | `"/"` | 远程目标路径 |
|
||||
| `sftp.enabled` | bool | `false` | 是否启用 SFTP |
|
||||
|
||||
### 示例配置
|
||||
|
||||
使用 tar.bz2 格式进行高压缩率备份：
|
||||
|
||||
```json
|
||||
{
|
||||
"compression_format": "TAR_BZ2",
|
||||
"compression_level": 9,
|
||||
"skip_patterns": [".git", "__pycache__", "node_modules", "*.log"],
|
||||
"data_file": "backup_strategies.json",
|
||||
"lang": "zh_CN"
|
||||
}
|
||||
```
|
||||
|
||||
### 打包格式对比
|
||||
|
||||
| 格式 | 扩展名 | 压缩率 | 速度 | 依赖 | 适用场景 |
|
||||
|------|--------|--------|------|------|----------|
|
||||
| ZIP | .zip | 中 | 快 | 标准库 | 通用，Windows 兼容性最好 |
|
||||
| tar | .tar | 无 | 极快 | 标准库 | 纯归档，配合外部压缩 |
|
||||
| tar.gz | .tar.gz | 中 | 快 | 标准库 | Linux/macOS 通用 |
|
||||
| tar.bz2 | .tar.bz2 | 高 | 中 | 标准库 | 高压缩率归档 |
|
||||
| tar.xz | .tar.xz | 最高 | 慢 | 标准库 | 长期归档，空间敏感 |
|
||||
| tar.zst | .tar.zst | 中高 | 极快 | zstandard | 现代场景，速度与压缩率平衡 |
|
||||
| 7z | .7z | 极高 | 慢 | py7zr | 最高压缩率，支持加密 |
|
||||
|
||||
#### WebDAV 远程备份
|
||||
|
||||
WebDAV 是基于 HTTP 的文件协议，支持坚果云、NextCloud、群晖等主流网盘。使用 Python 标准库 `urllib`，**零额外依赖**。
|
||||
|
||||
```bash
|
||||
# ============ 快速开始 ============
|
||||
# 1. 配置 WebDAV
|
||||
sbackup webdav config --url https://dav.jianguoyun.com/dav/ --user user@example.com --password secret
|
||||
|
||||
# 2. 测试连接
|
||||
sbackup webdav test
|
||||
|
||||
# 3. 执行备份并上传
|
||||
sbackup save --webdav
|
||||
|
||||
# ============ 使用场景 ============
|
||||
|
||||
# 场景一：一次性备份并上传
|
||||
sbackup save --webdav
|
||||
|
||||
# 场景二：定时备份并自动上传（每 60 分钟）
|
||||
sbackup watch --interval 60 --webdav
|
||||
|
||||
# 场景三：指定远程子目录
|
||||
sbackup webdav config --url https://dav.jianguoyun.com/dav/ --user user@example.com --remote-path /backups/sbackup
|
||||
|
||||
# 场景四：同时上传到 SFTP 和 WebDAV
|
||||
sbackup save --sftp --webdav
|
||||
|
||||
# ============ 常见 WebDAV 服务地址 ============
|
||||
# 坚果云: https://dav.jianguoyun.com/dav/
|
||||
# NextCloud: https://your-server/remote.php/dav/files/username/
|
||||
# 群晖: https://your-synology:5006/webdav/
|
||||
```
|
||||
|
||||
**webdav 子命令：**
|
||||
|
||||
| 子命令 | 描述 | 示例 |
|
||||
|--------|------|------|
|
||||
| `webdav config` | 配置 WebDAV 连接参数（url/user/password/remote_path） | `sbackup webdav config --url ... --user ...` |
|
||||
| `webdav test` | 测试 WebDAV 连接是否可用 | `sbackup webdav test` |
|
||||
|
||||
| 参数 | 默认值 | 描述 |
|
||||
|------|--------|------|
|
||||
| `--url URL` | `""` | WebDAV 服务器地址（如 `https://dav.jianguoyun.com/dav/`） |
|
||||
| `--user USER` | `""` | WebDAV 用户名（通常为邮箱） |
|
||||
| `--password PASS` | `""` | WebDAV 密码（坚果云需在设置中生成应用密码） |
|
||||
| `--remote-path PATH` | `/` | 远程目标路径 |
|
||||
|
||||
## 实现原理
|
||||
|
||||
Sbackup 通过以下方式实现备份功能：
|
||||
|
||||
1. **备份策略存储**：备份策略存储在 JSON 文件中，包含文件夹路径、最后修改时间、目标路径、忽略模式和条目级打包格式。
|
||||
2. **增量备份**：通过比较文件夹的最后修改时间，仅备份已更改的文件夹。
|
||||
3. **多格式压缩**：使用 Python 内置的 `zipfile` 和 `tarfile` 模块，以及 `zstandard` 和 `py7zr` 第三方库，支持 7 种打包格式。
|
||||
4. **条目级格式**：每个备份策略可指定独立的打包格式（`add --format`），优先于全局 `--format` 设置；未指定时使用全局默认。
|
||||
5. **备份清理**：备份成功后自动扫描目标目录，按修改时间排序，删除超出保留数量的旧文件。
|
||||
6. **加密备份**：7z 格式支持 LZMA2 加密，通过 `--password` 参数或 `config.json` 配置。
|
||||
7. **定时备份**：`watch` 命令在循环中按指定间隔执行备份，`Ctrl+C` 安全退出。
|
||||
8. **备份历史**：每次备份后记录时间戳、文件大小和文件数量，保留最近 100 条记录。
|
||||
9. **SFTP 远程备份**：基于 paramiko 库实现 SFTP 客户端，支持连接测试、自动创建远程目录、带进度条的文件上传。
|
||||
|
||||
### 数据文件格式
|
||||
|
||||
```json
|
||||
{
|
||||
"/path/to/source/folder": [
|
||||
1719235200.0,
|
||||
"/path/to/target/folder",
|
||||
[".git", "__pycache__"],
|
||||
""
|
||||
],
|
||||
"/path/to/another/folder": [
|
||||
1719235200.0,
|
||||
"/path/to/another/target",
|
||||
[".git"],
|
||||
"TAR_GZ"
|
||||
],
|
||||
"_history": [
|
||||
{
|
||||
"time": "2026-05-01T12:00:00",
|
||||
"source": "/path/to/source/folder",
|
||||
"size_mb": 12.5,
|
||||
"files_count": 150
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
每个备份策略条目为 4 元素列表：`[mtime, target, skip_patterns, compression_format]`
|
||||
|
||||
| 字段 | 说明 |
|
||||
|------|------|
|
||||
| `mtime` | 源文件夹最后修改时间（用于增量备份判断） |
|
||||
| `target` | 备份文件存放的目标路径 |
|
||||
| `skip_patterns` | 需忽略的文件/文件夹模式列表 |
|
||||
| `compression_format` | 条目级打包格式（空字符串表示使用全局默认） |
|
||||
|
||||
## 开发指南
|
||||
|
||||
### 运行测试
|
||||
|
||||
```bash
|
||||
uv run coverage run -m unittest discover -s tests -t . && uv run coverage report -m
|
||||
```
|
||||
|
||||
### 代码结构
|
||||
|
||||
```
|
||||
sbackup/
|
||||
├── main.py # 程序入口
|
||||
├── sbackup/
|
||||
│ ├── __init__.py # 导出核心函数
|
||||
│ ├── __main__.py # python -m sbackup 入口
|
||||
│ ├── cli.py # CLI 参数解析和命令分发（30+ 命令）
|
||||
│ ├── config.py # 配置加载、加密、Webhook/SMTP 配置
|
||||
│ ├── auto_save.py # BackupManager 核心引擎
|
||||
│ ├── compression.py # 7 种格式压缩/解压引擎
|
||||
│ ├── i18n.py # 国际化（9 种语言）
|
||||
│ ├── sftp.py # SFTP 远程备份客户端（paramiko）
|
||||
│ ├── webdav.py # WebDAV 远程备份客户端（零依赖）
|
||||
│ ├── cloud_storage.py # S3 云存储客户端（minio）
|
||||
│ ├── multi_dest.py # 多目标并行备份
|
||||
│ ├── handlers.py # SFTP/WebDAV/Remote/Schedule 命令处理
|
||||
│ ├── hooks.py # Pre/Post Hook 执行
|
||||
│ ├── audit.py # 审计日志系统
|
||||
│ ├── profile.py # 配置 Profile 管理
|
||||
│ ├── selective.py # 选择性恢复
|
||||
│ ├── cross_search.py # 跨档案搜索
|
||||
│ ├── integrity.py # SHA256 校验和
|
||||
│ ├── rotation.py # 备份轮转策略
|
||||
│ ├── dryrun.py # Dry-run 预览
|
||||
│ ├── diskcheck.py # 磁盘空间预估
|
||||
│ ├── task_queue.py # 任务队列系统
|
||||
│ ├── schema.py # 配置校验器
|
||||
│ ├── benchmark.py # 压缩基准测试
|
||||
│ ├── chunked_backup.py# 块级增量备份
|
||||
│ ├── dedup.py # 文件级 SHA256 去重
|
||||
│ ├── export.py # 元数据导出（CSV/JSON）
|
||||
│ ├── monitor.py # watchdog 文件系统监控
|
||||
│ ├── lock.py # 跨平台进程锁
|
||||
│ ├── retry.py # 指数退避重试
|
||||
│ ├── ratelimiter.py # 令牌桶限速器
|
||||
│ ├── keychain.py # 系统密钥链集成
|
||||
│ ├── parity.py # Reed-Solomon 纠错码
|
||||
│ ├── completion.py # Shell 自动补全
|
||||
│ ├── wizard.py # 交互式配置向导
|
||||
│ └── locales/ # 9 种语言翻译文件
|
||||
└── tests/
|
||||
└── sbackup/
|
||||
└── test_*.py # 30 个测试文件，覆盖所有模块
|
||||
```
|
||||
|
||||
### 添加新功能
|
||||
|
||||
1. 在 `sbackup/` 目录下创建新的模块文件
|
||||
2. 在 `sbackup/__init__.py` 中导入新功能的函数
|
||||
3. 在 `run()` 函数中添加新的命令行命令处理逻辑
|
||||
4. 在 `tests/` 目录下添加对应的测试文件
|
||||
|
||||
## 常见问题
|
||||
|
||||
### Q: 备份策略文件被误删了怎么办？
|
||||
|
||||
A: 备份策略存储在数据文件中。如果误删，可以通过重新运行 `add` 命令重新添加备份策略。
|
||||
|
||||
### Q: 如何修改已添加的备份策略？
|
||||
|
||||
A: 使用 `sbackup edit` 命令：`sbackup edit <source> --dest <new_dest> --ignore <patterns> --format <fmt>`。
|
||||
|
||||
### Q: 支持远程备份吗？
|
||||
|
||||
A: 支持！提供三种远程备份方式：
|
||||
- **SFTP**：`sbackup sftp config` 配置，`sbackup save --sftp` 上传
|
||||
- **WebDAV**：`sbackup webdav config` 配置，`sbackup save --webdav` 上传（支持坚果云/NextCloud/群晖）
|
||||
- **S3 云存储**：在 `config.json` 中配置 `cloud` 字段，`sbackup save --cloud` 上传
|
||||
- 可同时启用多种：`sbackup save --sftp --webdav --cloud`
|
||||
|
||||
### Q: tar.gz 和 ZIP 有什么区别？
|
||||
|
||||
A: tar.gz 在 Linux/macOS 上更常用，压缩率略高；ZIP 在 Windows 上更通用，兼容性最好。tar.bz2 和 tar.xz 提供更高的压缩率但速度较慢。tar.zst 是现代算法，速度极快且压缩率不错。7z 压缩率最高且支持加密。
|
||||
|
||||
### Q: 如何加密备份？
|
||||
|
||||
A: 使用 7z 格式并设置密码：`uv run python main.py --format 7z save --password yourpassword`。密码也可以写入 `config.json` 的 `password` 字段。
|
||||
|
||||
### Q: 如何自动清理旧备份？
|
||||
|
||||
A: 使用 `--keep` 参数：`uv run python main.py save --keep 5` 只保留最近 5 个备份文件。定时备份时同样支持：`uv run python main.py watch --interval 60 --keep 10`。
|
||||
|
||||
### Q: 如何设置定时备份？
|
||||
|
||||
A: 使用 `watch` 命令：`uv run python main.py watch --interval 60` 每 60 分钟备份一次。按 `Ctrl+C` 停止。
|
||||
|
||||
### Q: 密码存储安全吗？
|
||||
|
||||
A: `config.json` 中的 SFTP 密码和 7z 加密密码均以**明文**存储。请确保 `config.json` 文件的访问权限仅限于可信用户（例如 `chmod 600 config.json`）。不要将包含密码的 `config.json` 提交到版本控制系统。
|
||||
|
||||
## 贡献指南
|
||||
|
||||
欢迎提交 Issue 和 Pull Request！
|
||||
|
||||
1. Fork 本仓库
|
||||
2. 创建你的特性分支 (`git checkout -b feature/AmazingFeature`)
|
||||
3. 提交你的更改 (`git commit -m 'Add some AmazingFeature'`)
|
||||
4. 推送到分支 (`git push origin feature/AmazingFeature`)
|
||||
5. 提交 Pull Request
|
||||
|
||||
### 代码风格
|
||||
|
||||
本项目遵循 PEP 8 和 Google Python Style Guide。请确保你的代码：
|
||||
- 使用类型注解
|
||||
- 遵循 Google 风格的 docstrings
|
||||
- 通过所有单元测试
|
||||
|
||||
## 许可证
|
||||
|
||||
本项目采用 GNU GPL v3.0 许可证。详情请参阅 [LICENSE](LICENSE) 文件。
|
||||
|
||||
## 作者
|
||||
|
||||
**xiatianxuan** (CodeSeed)
|
||||
|
||||
- [Gitee](https://gitee.com/xiatianxuan)
|
||||
- [个人主页](https://xnors-codeseed.pages.dev/)
|
||||
|
||||
## 特别鸣谢
|
||||
|
||||
- [Xnors Studio](https://xnors.github.io/)
|
||||
|
||||
## 联系我们
|
||||
|
||||
如有问题或建议，请发送邮件至：xiatianxuan2025@163.com
|
||||
|
||||
---
|
||||
|
||||
*最后更新：2026年6月19日*
|
||||
Reference in new issue
Block a user