Metadata-Version: 2.5
Name: edgevault
Version: 0.6.0
Summary: Encrypted backups for your project: Postgres, SQLite, files and secrets to S3, Google Drive, Yandex Disk, SFTP — with Telegram alerts
Project-URL: Homepage, https://github.com/Vasiliynemix/EdgeVault
Project-URL: Changelog, https://github.com/Vasiliynemix/EdgeVault/blob/main/CHANGELOG.md
Author: Vasiliynemix
License-Expression: MIT
License-File: LICENSE
Keywords: age,backup,encryption,pg_dump,postgres,s3,sqlite,telegram
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Natural Language :: Russian
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Database
Classifier: Topic :: System :: Archiving :: Backup
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: cryptography>=42
Description-Content-Type: text/markdown

# edgevault

*Encrypted backups for Python projects: Postgres, SQLite, files and secrets → S3,
Google Drive, Yandex Disk, SFTP, with Telegram alerts. Docs are in Russian.*

Зашифрованные бэкапы для проекта: Postgres, SQLite, папки, секреты. Подключается
к бэкенду как обычная библиотека, настраивается его же settings, запускается
вместе с проектом. О сбое приходит сообщение в Telegram: какой проект, какой
сервер, что сломалось и что делать.

Базы edgevault не меняет: подключения к Postgres только на чтение (запись
отклонит сам сервер), SQLite открывается только на чтение, удаляет edgevault
только свои старые копии. Места на диске не хватит — прогон пропустит и скажет,
а не переполнит диск под базой.

## В проект за три шага

**1. Зависимость**

```bash
uv add edgevault        # или pip install edgevault
```

**2. Файл `app/backup.py`** — всё, что нужно знать о бэкапе проекта:

```python
from edgevault import Postgres, S3, Secrets, Telegram, Vault

from app.config import settings

vault = Vault(
    "my-project",
    recipients=settings.BACKUP_AGE_KEY,  # открытый ключ age1…
    sources=[
        Postgres(settings.DATABASE_URL),  # можно postgresql+asyncpg://…
        Secrets(env=["SECRET_KEY", "FERNET_KEY"]),  # ключи, без которых дамп не прочитать
    ],
    targets=[S3(settings.BACKUP_S3_URL)],  # https://KEY:SECRET@host/bucket/папка
    notify=Telegram(settings.BOT_TOKEN, settings.ADMIN_CHAT_ID),
    every="1h",  # или schedule=["04:00"]
    verify_days=7,  # раз в неделю — пробное восстановление
    store="/backups",
)

if __name__ == "__main__":
    vault.cli()  # python -m app.backup [daemon|run|check|test-notify]
```

**3. Запуск** — как удобно:

| Как | Что написать |
|---|---|
| Отдельный сервис рядом (рекомендую) | в `docker-compose.yml` — сервис ниже |
| Внутри приложения, фоном | `vault.start()` при старте, `vault.stop()` при остановке |
| Один раз | `python -m app.backup run`, или `vault.run()` из своего кода |

```yaml
  backup:
    build: .                        # тот же образ, что у бэкенда
    command: python -m app.backup
    env_file: .env
    volumes: ["backups:/backups"]
    restart: unless-stopped
```

Внутри приложения — например, FastAPI:

```python
@asynccontextmanager
async def lifespan(app):
    vault.start()  # расписание в своём потоке, приложению не мешает
    yield
    vault.stop()
```

Несколько воркеров uvicorn с одной папкой копий — не страшно: прогон делает
один, остальные молча пропускают. Но если API масштабируется на несколько
машин, берите отдельный сервис.

### Sync или async — без разницы, и проект он не ломает

- `start()` возвращается сразу. Проверки, сеть, pg_dump — в своём потоке с
  пониженным приоритетом: цикл событий asyncio и потоки приложения не ждут.
- Async-код: `async with vault:` или `vault.start()` … `await vault.astop()`,
  разовый прогон — `await vault.arun()`. Sync-код (Django, Flask, скрипты):
  `with vault:` или `start()`/`stop()`, разовый — `vault.run()`.
- Ошибка в окружении (пустой `BACKUP_AGE_KEY`, опечатка в ключе) не роняет
  импорт и старт приложения: бэкап выключается и говорит почему — в журнал,
  в `check` и в чат. Выключить явно, например в dev: `Vault(..., enabled=settings.IS_PROD)`.
- `run()` и прогоны по расписанию не бросают исключений: всё — в отчёт и в чат.
- Запускайте `start()` в процессе воркера (lifespan, `on_startup`), а не при
  импорте: с `gunicorn --preload` поток, запущенный до fork, в воркеры не попадёт.

## Ключ — один раз, на своём компьютере

```bash
uv tool install edgevault
edgevault keygen          # age-key.txt — в менеджер паролей; age1… — в BACKUP_AGE_KEY
```

На сервер кладут только открытый `age1…`: украденная копия без закрытого ключа
бесполезна. Программа `age` не нужна — шифрование встроено, но копии
расшифровывает и обычный `age -d`.

## До старта скажет, чего не хватает

`python -m app.backup check` (и сам `start()`/`daemon` при запуске — в журнал и
сообщением) проверяет всё, что можно проверить, ничего не делая:

```
  ✗ Программа pg_dump: не установлена, а нужна, чтобы снимать Postgres по адресу
    → Добавьте в Dockerfile образа: RUN apt-get update && apt-get install -y --no-install-recommends postgresql-client
  ✗ Программа pg_dump: версии 17, а сервер Postgres 18: старый pg_dump новую базу не снимет
  ✗ Отправка → s3://storage.yandexcloud.net/backups: HTTP 403 SignatureDoesNotMatch …
    → Ключи S3 неверны или у них нет прав на бакет
```

Команда установки — под систему образа (Debian, Alpine) или машины. Внешние
программы нужны не всегда:

| Что в конфиге | Что нужно поставить |
|---|---|
| `Postgres(url)` | `postgresql-client` той же версии, что сервер, или новее |
| `S3`, `Folder`, `Sqlite`, `Files`, `Secrets`, шифрование | ничего |
| `Rclone("gdrive:…")` — Google/Яндекс Диск, SFTP | `rclone` |
| Postgres в соседних контейнерах (`container`, `discover`) | `docker` и смонтированный `docker.sock` |

## Что сохранять

```python
Postgres(settings.DATABASE_URL)  # по адресу; база из адреса
Postgres(host="db", user="app", password=..., databases=["app", "auth"])
Postgres(container="app-db")  # pg_dump внутри контейнера базы
Postgres(discover=True, compose_project="app")  # все базы своего compose-проекта
Sqlite("data/*.sqlite3")  # согласованная копия, даже если пишут
Files("uploads", exclude=["cache/*"])  # папка архивом
Secrets(env=["SECRET_KEY"])  # переменные окружения
Secrets(root=".", patterns=[".env", "config.py"])  # или файлы
```

## Куда отправлять

```python
S3("https://KEY:SECRET@s3.ru-1.storage.selcloud.ru/bucket/my-project")
S3(
    endpoint="https://storage.yandexcloud.net",
    bucket="b",
    prefix="app",
    access_key=...,
    secret_key=...,
    region="ru-central1",
)
Folder("/mnt/backup-disk/my-project")  # другой диск, NFS, volume
Rclone("gdrive:Backups/my-project", {"type": "drive", "token": settings.GDRIVE_TOKEN})
Rclone("yadisk:Backups/my-project", {"type": "yandex", "token": settings.YADISK_TOKEN})
Rclone(
    "box:/backups",
    {
        "type": "sftp",
        "host": "backup.example.ru",
        "user": "b",
        "key_file": "/run/secrets/backup_key",
    },
)
```

Мест можно несколько: не дошло в одно — остальные всё равно получают копию.
Хотя бы одно — у другого провайдера, не там, где сервер. Без мест копии лежат
только в `store`; их можно забирать к себе: `edgevault pull`.

Токен Google/Яндекс Диска: `edgevault authorize gdrive` (или `yandex`) на своём
компьютере — откроется вход в браузере. У Google Диска доступ только к файлам,
которые положил сам edgevault.

## Как часто и сколько хранить

`schedule=["03:30", "15:30"]` — в эти часы, `every="1h"` — каждый час (`30m`,
`2h`, `6h`…). Между бэкапами данные могут потеряться — это окно и задаёт
расписание: при `every="1h"` теряется не больше часа.

Хранение — `keep=Keep(...)`:

| | По умолчанию | Что это |
|---|---|---|
| `local_days` | 3 | сколько дней копии лежат в `store` |
| `daily_days` | 14 | сколько дней — в местах хранения |
| `monthly_days` | 365 | копия первого числа — год |
| `all_runs_days` | 2 | все прогоны дня — за последние 2 дня, раньше — последний прогон дня |

Так `every="1h"` не превращается в сотни копий: сутки-двое — каждый час, дальше —
по одной на день, месячные — год.

`min_free_gb=1` — сколько места должно остаться на диске после бэкапа (и не
меньше 5% диска). Не хватает — прогон пропускается с сообщением.

## Пробное восстановление

То, что дамп читается, ещё не значит, что он восстановится. С `verify_days=7` раз
в неделю edgevault разворачивает свежий дамп во временный Postgres, смотрит, что
все таблицы на месте, и удаляет его:

```
· восстановление app-db / app проверено: 42 таблиц, ~1830000 строк, 38 с
```

- Рабочую базу не трогает: временный Postgres — отдельный контейнер без сети, на
  одном ядре, сравнение — с оглавлением самого дампа.
- Образ — тот же, что у базы (с её расширениями: PostGIS, pgvector), для базы по
  адресу — `postgres` той же версии, что в дампе. Свой — `verify_image="…"`.
- Нужен Docker: в сервисе бэкапа — смонтированный `/var/run/docker.sock`. Без
  него `check` скажет об этом, а бэкапы идут как обычно.
- Не прошла — сообщение с причиной и повтор через сутки.
- SQLite проверяется каждый раз сам: копия — это готовая база, и
  `integrity_check` проходит по ней целиком.

## Сообщения

```
🟠 my-project · бэкап с проблемами
prod-1 · 07.11.2026 04:00

Что не так (1):
• Отправка → s3://storage.yandexcloud.net/backups
  HTTP 403 SignatureDoesNotMatch
  💡 Ключи S3 неверны или у них нет прав на бакет

Копии: 2 · 8,9 МБ
Места хранения: s3://storage.yandexcloud.net/backups ✗
```

🔴 — копий нет, 🟠 — часть не сделана, ✅ — снова в порядке. Параметры `Vault`:
`on_success` (сообщать и об успехах, без звука), `on_recovery` (по умолчанию да),
`remind_hours` (тот же сбой — не чаще раза в N часов), `server` (имя сервера в
сообщении). `Telegram(token, "-100…, @ops", thread=42)` — несколько чатов и тема
форума; `Webhook(url)` — JSON со всеми полями. Проверить: `python -m app.backup test-notify`.

### Через прокси

Если с сервера Telegram доступен только через VPN или прокси, задайте его только
для сообщений, бэкапы через него не пойдут:

```python
notify = Telegram(settings.BOT_TOKEN, settings.ADMIN_CHAT_ID, proxy="http://vpn:1080")
Webhook("https://hooks.example/backup", proxy="http://user:pass@proxy:3128")
```

В edgevault.toml: `telegram_proxy` и `webhook_proxy` в `[notify]`. Поддерживаются
только http(s)-прокси, socks — нет: такой адрес будет ошибкой сразу, а не в день
аварии. Пароль прокси и токен бота в журналах и выводе заменяются на `***`.
`test-notify` пишет, через какой прокси ушло сообщение.

Без `proxy` сообщения идут, как настроена система (`HTTPS_PROXY`, `NO_PROXY`).
Встроенный S3 и `Folder` прокси из окружения не читают, а rclone читает:
`HTTPS_PROXY` на весь процесс погонит через прокси и копии в Google/Яндекс Диск.

## Восстановление

```bash
edgevault decrypt app__app.dump.age -k age-key.txt        # → app__app.dump
createdb app_restore && pg_restore -d app_restore --no-owner app__app.dump   # сначала — в новую базу
edgevault decrypt secrets.tar.gz.age -k age-key.txt && tar xzf secrets.tar.gz
```

Раскладка копий везде одна: `daily/ГГГГ-ММ-ДД/ЧЧММ/<копия>.age`,
`monthly/ГГГГ-ММ/<копия>.age`.

## Без кода: edgevault.toml

Для проектов, в код которых лезть не хочется, — отдельная программа и один
конфиг: `edgevault init` в папке проекта напишет его сам (найдёт Postgres в
compose-файлах, SQLite, `.env`), справочник — [`examples/edgevault.toml`](examples/edgevault.toml).
Запуск — `edgevault daemon`, таймером `sudo edgevault systemd --install` или
образом `ghcr.io/vasiliynemix/edgevault:0.5` рядом с проектом.

## Обновление

[semver](https://semver.org/lang/ru/), что изменилось — в [CHANGELOG.md](CHANGELOG.md).

- в проекте: `uv add edgevault@latest` (или поднять версию в зависимостях) и `uv lock`;
- программа: `uv tool upgrade edgevault`;
- образ: тег `0.5` сам указывает на последнее исправление — `docker compose pull`.

После обновления — `check`.

## Разработка

```bash
uv sync
uv run pytest && uv run ruff check . && uv run ruff format --check . && uv run mypy edgevault
scripts/release.sh 0.5.1     # выпуск: проверки → версия → коммит, тег, push → CI → PyPI
```
