111 lines
4.9 KiB
Markdown
111 lines
4.9 KiB
Markdown
# Архитектура
|
||
|
||
## Обзор
|
||
|
||
Один процесс 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
|
||
```
|