init repo
This commit is contained in:
commit
6c63a20d8d
24 files changed
+2010
No files matched your search
@@ -0,0 +1,110 @@
|
||||
# Архитектура
|
||||
|
||||
## Обзор
|
||||
|
||||
Один процесс 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
|
||||
```
|
||||
Reference in new issue
Block a user