Files
gitea-daily-backup/docs/agent/ARCHITECTURE.md
T
2026-11-08 17:06:04 +03:00

4.9 KiB
Raw Blame History

Архитектура

Обзор

Один процесс 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).

pip install -e .
python -m unittest discover -s tests -v