4.9 KiB
Архитектура
Обзор
Один процесс 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
load_config()—.envиз cwd или корня репо (src/gitea_backup→ parents[2]). ОтносительныйBACKUP_DIRрезолвится от каталога.env. ФлагGITEA_BACKUP_SKIP_DOTENV=1для тестов.- Flock
BACKUP_DIR/.backup.lock. GET /api/v1/version, затемlist_repos().- Для каждого репо: mirror или fetch; рядом
<repo>.git.meta.json. - Wiki, если
BACKUP_INCLUDE_WIKIиhas_wiki. Ошибка «репозитория wiki нет» — не фейл прогона. - Снимок hardlink, prune старше
BACKUP_KEEP_DAYS. status.json. Код выхода 1, если хотя бы один git-репозиторий (не wiki) упал.
list_repos объединяет:
GET /api/v1/repos/search?q=&private=trueGET /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).
pip install -e .
python -m unittest discover -s tests -v