# Архитектура ## Обзор Один процесс Python. Нет БД, нет веб-сервера, нет очередей. ``` Gitea API (192.168.1.9) │ token ▼ gitea-backup (list / run / schedule) │ ├─ git clone --mirror → BACKUP_DIR/mirrors//.git ├─ git fetch --all → те же зеркала (инкремент) ├─ git lfs fetch --all ├─ опционально *.wiki.git └─ cp -al mirrors/ → snapshots/ГГГГ-ММ-ДД/ ``` Точка входа: `gitea_backup.__main__:main` → CLI `gitea-backup`. В Docker: `ENTRYPOINT gitea-backup`, `CMD schedule`. ## Карта файлов ``` src/gitea_backup/ __main__.py CLI: run [--dry-run] | schedule | list config.py env + .env (dotenv), пути, TZ client.py Gitea HTTP API, пагинация, token в clone URL gitops.py git clone --mirror / fetch, LFS, маскировка токена backup.py оркестрация, lock, meta.json, snapshots, status.json scheduler.py сон до BACKUP_AT, опционально прогон на старте install.sh venv без Docker, --cron, --systemd --user docker-up.sh на Ubuntu/WSL: движок Docker + docker build/run (не compose) docker-compose.yml прод-путь: сеть host, том ./backups, BACKUP_DIR=/backups Dockerfile python:3.12-alpine + git, git-lfs, coreutils (нужен GNU cp -al) systemd/ oneshot + timer (шаблон под /opt/gitea-backup) tests/ unittest, без живого Gitea .env.example шаблон; реальный .env в gitignore ``` ## Поток `gitea-backup run` 1. `load_config()` — `.env` из cwd или корня репо (`src/gitea_backup` → parents[2]). Относительный `BACKUP_DIR` резолвится от каталога `.env`. Флаг `GITEA_BACKUP_SKIP_DOTENV=1` для тестов. 2. Flock `BACKUP_DIR/.backup.lock`. 3. `GET /api/v1/version`, затем `list_repos()`. 4. Для каждого репо: mirror или fetch; рядом `.git.meta.json`. 5. Wiki, если `BACKUP_INCLUDE_WIKI` и `has_wiki`. Ошибка «репозитория wiki нет» — не фейл прогона. 6. Снимок hardlink, prune старше `BACKUP_KEEP_DAYS`. 7. `status.json`. Код выхода 1, если хотя бы один git-репозиторий (не wiki) упал. `list_repos` объединяет: - `GET /api/v1/repos/search?q=&private=true` - `GET /api/v1/user/repos` - орги и их репы - если токен админа: `/api/v1/admin/users` + репы пользователей Без админского токена бэкапятся только репозитории, видимые этому пользователю. Это важно объяснить пользователю. Clone URL: поле `clone_url` из API + `oauth2:@host`. Не логировать сырой URL: `gitops.redact`. ## Хранение ``` BACKUP_DIR/ # в Docker: /backups ← том ./backups mirrors/ Owner/repo.git Owner/repo.git.meta.json Owner/repo.wiki.git # если получилось snapshots/YYYY-MM-DD/ # hardlink-копия mirrors status.json .backup.lock ``` Зеркало — bare/mirror. Объекты обычно только в `objects/pack/*.pack`. Восстановление: `git clone backups/mirrors/Owner/repo.git restored`. `cp -al` — GNU coreutils. В Alpine в образ специально добавлен пакет `coreutils`. Если `cp -al` нет, fallback — полная `shutil.copytree` (дорого по месту). ## Конфиг (env) | Переменная | По умолчанию | Смысл | |---|---|---| | `GITEA_URL` | `http://192.168.1.9:3000` | API | | `GITEA_TOKEN` | пусто, обязателен | API + git HTTP | | `BACKUP_DIR` | `./backups` | в compose принудительно `/backups` | | `BACKUP_AT` | `03:00` | ежедневный слот демона | | `TZ` | `Europe/Moscow` | | | `RUN_ON_START` | true | первый прогон сразу в `schedule` | | `BACKUP_SNAPSHOTS` | true | | | `BACKUP_KEEP_DAYS` | 30 | | | `BACKUP_INCLUDE_WIKI` | true | | | `BACKUP_INCLUDE_LFS` | true | | Compose **перебивает** `BACKUP_DIR` на `/backups`, даже если в `.env` стоит `./backups`. Так и надо: том смонтирован в `/backups`. ## Зависимости Python ≥ 3.11. Пакеты: `httpx`, `python-dotenv`. Git и желательно git-lfs на хосте (в образе есть оба). ## Тесты Моки API и FakeGit. Живой Gitea из CI/агентской среды недоступен (частный LAN). ```bash pip install -e . python -m unittest discover -s tests -v ```