Files
2026-11-08 17:06:04 +03:00

111 lines
4.9 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Архитектура
## Обзор
Один процесс Python. Нет БД, нет веб-сервера, нет очередей.
```
Gitea API (192.168.1.9)
│ token
▼
gitea-backup (list / run / schedule)
│
├─ git clone --mirror → BACKUP_DIR/mirrors/<owner>/<repo>.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; рядом `<repo>.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:<token>@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
```