sbackup/docs/readme/README_ru.md

# Sbackup

[![Python](https://img.shields.io/badge/Python-3.10+-3776AB?logo=python&logoColor=white)](https://www.python.org/)
[![License](https://img.shields.io/badge/License-GPL--3.0-green)](../../LICENSE)
[![PyPI](https://img.shields.io/pypi/v/sbackup-cli?color=blue)](https://pypi.org/project/sbackup-cli/)
[![Tests](https://img.shields.io/badge/tests-940%20passed-brightgreen)](../../.github/workflows/ci.yml)
[![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey)]()

> Лёгкий и эффективный инструмент резервного копирования папок с поддержкой командной строки, позволяющий удобно управлять стратегиями бэкапов.

[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 г.*