commit 6c63a20d8dea31fd53133493d48fc4271e694040 Author: SheinovM Date: Sun Nov 8 17:06:04 2026 +0300 init repo diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..1e98c2d --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,14 @@ +# Для агента + +Это рабочий бэкап всех git-репозиториев локального Gitea, не платформа и не веб-приложение. + +**Сначала прочитай** [`docs/agent/README.md`](docs/agent/README.md) — там оглавление, текущее состояние и история решений. + +Краткие правила этой кодовой базы: + +- Язык общения с пользователем и **сообщения коммитов — русский**. Формат: `feat: …` / `fix: …`. +- Не открывать PR, пока пользователь явно не попросил. +- Не добавлять auth, БД и лишние сервисы без запроса. +- Секреты только в `.env` (gitignored). В логах токен маскируется как `oauth2:***`. +- Проверка: `python -m unittest discover -s tests -v` (нужен `pip install -e .`). +- Образ Docker — **Alpine**, не Debian. На RedOS Debian-apt падает на GPG из-за `libseccomp`. diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000..fc550c3 --- /dev/null +++ b/Dockerfile @@ -0,0 +1,19 @@ +# Alpine, не Debian: на RedOS/RHEL старый libseccomp ломает apt GPG +# («At least one invalid signature was encountered»). +FROM python:3.12-alpine + +RUN apk add --no-cache git git-lfs tzdata ca-certificates coreutils \ + && git lfs install --system + +WORKDIR /app +COPY pyproject.toml README.md ./ +COPY src ./src +RUN pip install --no-cache-dir . + +ENV BACKUP_DIR=/backups \ + PYTHONUNBUFFERED=1 \ + TZ=Europe/Moscow + +VOLUME ["/backups"] +ENTRYPOINT ["gitea-backup"] +CMD ["schedule"] diff --git a/README.md b/README.md new file mode 100644 index 0000000..95df3cf --- /dev/null +++ b/README.md @@ -0,0 +1,229 @@ +# Бэкап репозиториев Gitea + +Каждый день забирает **все доступные репозитории** с вашего Gitea (`http://192.168.1.9:3000` по умолчанию) и хранит их как git-зеркала плюс компактные ежедневные снимки. + +Для другого агента или передачи контекста: каталог [`docs/agent/`](docs/agent/README.md) (оглавление, архитектура, прод, грабли). Короткий указатель в корне: [`AGENTS.md`](AGENTS.md). + +**Docker не нужен.** Достаточно Python 3.11+ и Git. + +Что попадает в бэкап: + +- все ветки и теги (`git clone --mirror`); +- wiki, если она включена у репозитория; +- объекты Git LFS; +- короткий JSON с описанием репозитория. + +Что **не** входит: тикеты, PR, пользователи и настройки инстанса. Это лежит в БД Gitea — для полного дампа на самом сервере есть `gitea dump`. + +## Быстрый старт (без Docker) + +На машине в той же сети, что и Gitea (чтобы открывался `192.168.1.9`): + +```bash +sudo apt install python3 python3-venv python3-pip git git-lfs +git lfs install + +./install.sh +nano .env # впишите GITEA_TOKEN +.venv/bin/gitea-backup list +.venv/bin/gitea-backup run +``` + +Ежедневно в 03:00: + +```bash +./install.sh --cron +``` + +Если cron в WSL не запущен: `sudo apt install cron && sudo service cron start`. + +Альтернативы расписанию: + +```bash +./install.sh --systemd # пользовательский systemd-таймер +.venv/bin/gitea-backup schedule # демон в текущем терминале +``` + +Зеркала появятся в `./backups/mirrors`, снимки — в `./backups/snapshots/ГГГГ-ММ-ДД`, отчёт о последнем прогоне — в `./backups/status.json`. + +Запускайте бэкап на машине, которая включена ночью (сам сервер Gitea или всегда включённый ПК). Сессия WSL без окон часто засыпает — тогда cron внутри WSL не сработает. + +## Токен Gitea + +1. Войдите в Gitea под **администратором сайта** — иначе бэкапятся только репозитории, которые видит обычный пользователь. +2. **Настройки → Приложения → Создать токен**. +3. Права: `read:repository`, `read:user`, `read:organization`. +4. Вставьте токен в `.env` как `GITEA_TOKEN`. + +Если Gitea слушает не `:3000`, поправьте `GITEA_URL`. + +## Docker + +Пакет `docker.io` ставит только `docker`. Команда `docker compose` — это **отдельный плагин**. Без него `docker compose up -d` ломается с ошибкой `unknown shorthand flag: 'd' in -d`. + +```bash +sudo apt update +sudo apt install -y docker.io docker-compose-v2 +sudo service docker start +sudo usermod -aG docker "$USER" +# закройте терминал и откройте новый, чтобы группа docker применилась + +docker compose version # должно быть: Docker Compose version v2.x + +cp .env.example .env # если ещё нет; впишите GITEA_TOKEN +docker compose up -d --build +``` + +Если видите `permission denied ... docker.sock` — демон запущен, но ваш пользователь не в группе `docker`. Сейчас можно так: + +```bash +sudo docker compose up -d --build +``` + +Навсегда (один раз): + +```bash +sudo usermod -aG docker "$USER" +newgrp docker +docker compose up -d --build +``` + +`newgrp` действует только в этом терминале. Чтобы группа работала везде — закройте сессию и зайдите снова. + +Если `docker info` показывает Client, но Server пишет `no such file or directory` / `Is the docker daemon running?` — есть только клиент, **движка нет**. То же самое, если `sudo service docker start` отвечает `unrecognized service` и нет `/etc/init.d/docker`. + +Поставьте движок и запустите его: + +```bash +sudo apt update +sudo apt install -y docker.io containerd +which dockerd # должен быть /usr/bin/dockerd +``` + +Дальше — как получится в вашей системе: + +```bash +# если есть systemd +sudo systemctl enable --now docker + +# если service есть +sudo service docker start + +# типичный WSL без systemd: запустить демон вручную +sudo dockerd +``` + +`sudo dockerd` оставьте в одном терминале, в другом: + +```bash +sudo docker info +sudo docker compose up -d --build +``` + +Чтобы демон поднимался сам при старте WSL, в `/etc/wsl.conf`: + +```ini +[boot] +systemd=true +``` + +Затем из Windows: `wsl --shutdown`, снова откройте Ubuntu и выполните `sudo systemctl enable --now docker`. + +Если Docker ставили через **Docker Desktop** на Windows — apt-клиент в WSL к нему не подключится, пока Desktop не запущен. Откройте Docker Desktop и в Settings → Resources → WSL integration включите свой дистрибутив. + +Либо одной командой из репозитория: `./docker-up.sh --install-engine`, затем `./docker-up.sh`. + +Если плагин v2 недоступен в репозиториях: + +```bash +sudo apt install -y docker-compose +docker-compose up -d --build +``` + +Контейнер сразу делает первый бэкап и дальше каждый день в `03:00` (таймзона `Europe/Moscow`). Каталог на хосте: `./backups`. + +```bash +docker compose logs -f +docker compose exec gitea-backup gitea-backup list +docker compose exec gitea-backup gitea-backup run --dry-run +docker compose exec gitea-backup gitea-backup run +docker compose down +``` + +Если `docker compose up` падает с `No such container: ac8d23cfcfca…` — это сломанное состояние Compose после перезапуска `dockerd`. **Образ уже собран**, Compose лучше не использовать. Запустите контейнер напрямую: + +```bash +sudo docker rm -f gitea-backup 2>/dev/null || true +sudo docker run -d \ + --name gitea-backup \ + --network host \ + --restart unless-stopped \ + --env-file .env \ + -e BACKUP_DIR=/backups \ + -v "$PWD/backups:/backups" \ + gitea-daily-backup-gitea-backup:latest + +sudo docker logs -f gitea-backup +sudo docker exec gitea-backup gitea-backup list +``` + +Или из репозитория после `git pull`: `./docker-up.sh` (он собирает образ и делает `docker run`, без Compose). + +Предупреждение `build using Bake, but buildx isn't installed` на запуск не влияет. + +Если на **RedOS / CentOS / RHEL** сборка Debian-образа падает с `At least one invalid signature was encountered` — это не подпись репозитория, а хост: старый `libseccomp` или неверные часы. Образ переведён на Alpine, поэтому после обновления кода: + +```bash +git pull +date # время должно быть близко к реальному; иначе: timedatectl set-ntp true +sudo docker compose build --no-cache +sudo docker compose up -d +``` + +Если Alpine тоже не качается, обновите seccomp на хосте: `sudo dnf update libseccomp` (или `yum`). + +## Как устроено хранение + +``` +backups/ + mirrors/ # актуальные зеркала, каждый день git fetch + alice/app.git + alice/app.git.meta.json + alice/app.wiki.git + snapshots/ # hardlink-копии mirrors на дату (почти не едят место) + 2026-09-07/ + 2026-09-08/ + status.json +``` + +Снимки старше `BACKUP_KEEP_DAYS` (по умолчанию 30) удаляются. Живые зеркала всегда можно клонировать обратно: + +```bash +git clone --bare backups/mirrors/alice/app.git +# или +git clone backups/mirrors/alice/app.git restored-app +``` + +## Переменные окружения + +| Переменная | По умолчанию | Смысл | +|---|---|---| +| `GITEA_URL` | `http://192.168.1.9:3000` | Адрес Gitea | +| `GITEA_TOKEN` | — | Обязательный токен API | +| `BACKUP_DIR` | `./backups` | Корень бэкапов | +| `BACKUP_AT` | `03:00` | Время ежедневного запуска | +| `TZ` | `Europe/Moscow` | Таймзона планировщика | +| `RUN_ON_START` | `true` | Бэкап сразу при старте демона `schedule` | +| `BACKUP_SNAPSHOTS` | `true` | Делать датированные снимки | +| `BACKUP_KEEP_DAYS` | `30` | Сколько дней хранить снимки | +| `BACKUP_INCLUDE_WIKI` | `true` | Бэкап wiki | +| `BACKUP_INCLUDE_LFS` | `true` | `git lfs fetch --all` | + +## Тесты + +```bash +python3 -m venv .venv +source .venv/bin/activate +pip install -e . +python -m unittest discover -s tests -v +``` diff --git a/docker-compose.yml b/docker-compose.yml new file mode 100644 index 0000000..6739ab3 --- /dev/null +++ b/docker-compose.yml @@ -0,0 +1,16 @@ +name: gitea-daily-backup + +services: + gitea-backup: + container_name: gitea-backup + build: . + restart: unless-stopped + env_file: + - .env + environment: + # Том с хоста, не значение BACKUP_DIR из .env (там ./backups для запуска без Docker). + BACKUP_DIR: /backups + volumes: + - ./backups:/backups + # Хост-сеть, чтобы контейнер видел Gitea в LAN (192.168.1.9). + network_mode: host diff --git a/docker-up.sh b/docker-up.sh new file mode 100755 index 0000000..ceb08dc --- /dev/null +++ b/docker-up.sh @@ -0,0 +1,225 @@ +#!/usr/bin/env bash +# Сборка и запуск ежедневного бэкапа Gitea в Docker. +set -euo pipefail + +ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +cd "$ROOT" + +usage() { + cat <<'EOF' +Запуск бэкапа через Docker. + + ./docker-up.sh собрать образ и запустить контейнер (docker run) + ./docker-up.sh --install-engine установить Docker и плагин Compose + ./docker-up.sh --help +EOF +} + +install_engine() { + if ! command -v apt-get >/dev/null 2>&1; then + echo "Автоустановка рассчитана на Ubuntu/Debian. Поставьте Docker вручную." >&2 + exit 1 + fi + echo "Ставлю движок Docker (docker.io), CLI и плагин Compose..." + sudo apt-get update + sudo apt-get install -y docker.io docker-compose-v2 containerd runc + start_engine || true + sudo usermod -aG docker "$USER" || true + echo + echo "Проверка: docker compose version" + sudo docker compose version || true + echo + echo "Если docker без sudo не работает — закройте терминал, откройте новый" + echo "и снова выполните ./docker-up.sh" +} + +docker_bin() { + if docker info >/dev/null 2>&1; then + echo docker + return + fi + local err + err="$(docker info 2>&1 || true)" + if printf '%s' "$err" | grep -qi 'permission denied'; then + echo "sudo docker" + return + fi + echo docker +} + +compose_v2_works() { + local d="$1" + $d compose version >/dev/null 2>&1 +} + +print_compose_missing() { + cat <<'EOF' >&2 +Установлен Docker, но нет команды «docker compose» (плагин Compose). +Из‑за этого флаг -d уходит в сам docker и появляется ошибка: + unknown shorthand flag: 'd' in -d + +Поставьте плагин и проверьте: + + sudo apt update + sudo apt install -y docker-compose-v2 + sudo service docker start + docker compose version + +Должно напечатать что-то вроде «Docker Compose version v2.x». +Потом: + + docker compose up -d --build + +Запасной вариант (старый бинарь через дефис): + + sudo apt install -y docker-compose + docker-compose up -d --build +EOF +} + +run_docker() { + local d + d="$(docker_bin)" + # shellcheck disable=SC2086 + $d "$@" +} + +run_compose() { + local d + d="$(docker_bin)" + if compose_v2_works "$d"; then + # shellcheck disable=SC2086 + $d compose "$@" + return + fi + if command -v docker-compose >/dev/null 2>&1; then + if [[ "$d" == "sudo docker" ]]; then + sudo docker-compose "$@" + else + docker-compose "$@" + fi + return + fi + print_compose_missing + exit 1 +} + +IMAGE_TAG="gitea-backup:latest" +CONTAINER_NAME="gitea-backup" + +run_container() { + mkdir -p "$ROOT/backups" + run_docker rm -f "$CONTAINER_NAME" >/dev/null 2>&1 || true + run_docker run -d \ + --name "$CONTAINER_NAME" \ + --network host \ + --restart unless-stopped \ + --env-file "$ROOT/.env" \ + -e BACKUP_DIR=/backups \ + -v "$ROOT/backups:/backups" \ + "$IMAGE_TAG" +} + +start_engine() { + if command -v systemctl >/dev/null 2>&1 && sudo systemctl start docker 2>/dev/null; then + return 0 + fi + if command -v service >/dev/null 2>&1 && sudo service docker start 2>/dev/null; then + return 0 + fi + if ! command -v dockerd >/dev/null 2>&1; then + echo "Нет бинаря dockerd — установлен только клиент Docker, без движка." >&2 + echo "Поставьте движок: sudo apt install -y docker.io containerd" >&2 + echo "Или запустите Docker Desktop на Windows (с интеграцией WSL)." >&2 + return 1 + fi + echo "systemd/service docker нет (так бывает в WSL). Запускаю dockerd напрямую..." + if pgrep -x dockerd >/dev/null 2>&1; then + return 0 + fi + sudo mkdir -p /run/docker /var/run + sudo nohup dockerd >/tmp/dockerd.log 2>&1 & + local i + for i in $(seq 1 20); do + if sudo docker info >/dev/null 2>&1; then + return 0 + fi + sleep 0.4 + done + echo "dockerd не поднялся. Лог: /tmp/dockerd.log" >&2 + tail -n 30 /tmp/dockerd.log >&2 || true + return 1 +} + +ensure_daemon() { + if docker info >/dev/null 2>&1; then + return + fi + local err + err="$(docker info 2>&1 || true)" + if printf '%s' "$err" | grep -qi 'permission denied'; then + return + fi + start_engine +} + +token_ok() { + python3 - <<'PY' +from pathlib import Path +text = Path(".env").read_text(encoding="utf-8") +for line in text.splitlines(): + s = line.strip() + if not s or s.startswith("#") or not s.startswith("GITEA_TOKEN="): + continue + value = s.split("=", 1)[1].strip().strip("'").strip('"') + raise SystemExit(0 if value else 1) +raise SystemExit(1) +PY +} + +start_stack() { + if ! command -v docker >/dev/null 2>&1; then + cat <<'EOF' >&2 +Команда docker не найдена. + + ./docker-up.sh --install-engine + +Либо вручную: + sudo apt update + sudo apt install -y docker.io docker-compose-v2 + sudo service docker start + sudo usermod -aG docker "$USER" +EOF + exit 1 + fi + + ensure_daemon + + if [[ ! -f .env ]]; then + cp .env.example .env + echo "Создан .env — впишите GITEA_TOKEN и снова запустите ./docker-up.sh" >&2 + exit 1 + fi + if ! token_ok; then + echo "В .env пустой GITEA_TOKEN. Откройте файл и вставьте токен из Gitea." >&2 + exit 1 + fi + + mkdir -p backups + echo "Собираю образ (без Compose — у Docker 29 в WSL он часто ломается на старых ID)..." + run_docker build -t "$IMAGE_TAG" . + echo "Запускаю контейнер $CONTAINER_NAME..." + run_container + echo + echo "Контейнер работает. Первый бэкап идёт сразу, дальше каждый день в 03:00." + echo "Логи: sudo docker logs -f $CONTAINER_NAME" + echo "Репозитории: sudo docker exec $CONTAINER_NAME gitea-backup list" + echo "Каталог: $ROOT/backups" +} + +case "${1:-}" in + --help|-h) usage ;; + --install-engine) install_engine ;; + "") start_stack ;; + *) usage >&2; exit 1 ;; +esac diff --git a/docs/agent/ARCHITECTURE.md b/docs/agent/ARCHITECTURE.md new file mode 100644 index 0000000..9f80773 --- /dev/null +++ b/docs/agent/ARCHITECTURE.md @@ -0,0 +1,110 @@ +# Архитектура + +## Обзор + +Один процесс Python. Нет БД, нет веб-сервера, нет очередей. + +``` +Gitea API (192.168.1.9) + │ token + ▼ + gitea-backup (list / run / schedule) + │ + ├─ git clone --mirror → BACKUP_DIR/mirrors//.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; рядом `.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:@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 +``` diff --git a/docs/agent/HANDOFF.md b/docs/agent/HANDOFF.md new file mode 100644 index 0000000..36ca10b --- /dev/null +++ b/docs/agent/HANDOFF.md @@ -0,0 +1,72 @@ +# Handoff: gitea-daily-backup + +Дата снимка: 2026-10-31 (Europe/Moscow). Ветка: `main` (последний коммит `fix: не пугаю WARNING, если wiki в Gitea ещё не создана`). + +## Задача пользователя + +Есть локальный Gitea на `192.168.1.9`. Нужен **ежедневный бэкап всех репозиториев**. + +Это сделано. Проект — Python-CLI `gitea-backup` + Docker (Alpine) / venv+cron / systemd. + +## Кто и где это крутит + +- Пользователь: Max Pro. Десктоп Windows, сначала пробовал в **WSL** (`max@SheinovM:~/gitea-daily-backup`). +- Потом **перенёс на сервер RedOS** (`root@redos`) и там поднял `docker compose`. Это текущий прод, насколько известно из чата. +- Gitea в LAN: `192.168.1.9`. В `.env.example` порт `:3000`, но в боевых логах clone URL без порта (`http://oauth2:***@192.168.1.9/Matvey/ChatService.git`) — на проде Gitea, скорее всего, на 80 (nginx) или в `GITEA_URL` указан хост без порта. Главное: **clone с того URL, что отдаёт API, работает**. + +Публичное имя репозитория кода: `max-pro/gitea-daily-backup` (Origin, private). +Страница: https://cursor.com/codebase/max-pro/gitea-daily-backup + +## Что считается «готово» + +- Список репозиториев через Gitea API (search + user + orgs + admin users, без дублей). +- `git clone --mirror` / дальше `git fetch --all --prune --tags`. +- Git LFS (`git lfs fetch --all`), если включено. +- Wiki (`.wiki.git`), если Gitea отдала `has_wiki` **и** git-репозиторий wiki реально существует. +- Ежедневные снимки `cp -al` (hardlink) с хранением `BACKUP_KEEP_DAYS` (сейчас 30). +- `status.json` после прогона, flock чтобы два бэкапа не пересеклись. +- Демон `gitea-backup schedule`: сразу при старте (`RUN_ON_START=true`) и каждый день в `BACKUP_AT` (03:00, `TZ=Europe/Moscow`). +- Docker-образ `CMD ["schedule"]`. + +## Чего в бэкапе нет (и это сознательно) + +Тикеты, PR, пользователи, настройки инстанса — это БД Gitea. Для полного дампа на самом сервере Gitea: `gitea dump`. Пользователь просил репозитории. + +## Последний подтверждённый прогон + +Лог с RedOS (контейнер `gitea-backup`), репозиторий `Matvey/ChatService`: + +- `fetch --all --prune --tags` — зеркало уже было, инкремент ок. +- `lfs fetch --all` — ок. +- Клон `ChatService.wiki.git` упал: wiki в настройках включена, git-репо wiki не создано (нет страниц). Код это **пропускает**, пишет «Готово: Matvey/ChatService». +- Пользователь спросил, нормально ли это. Ответ: да, код в порядке. После этого смягчили лог (INFO вместо WARNING для «wiki ещё нет»). На проде этот коммит мог быть ещё не задеплоен — если виден старый WARNING, это тот же самый безобидный случай. + +Проверка зеркала: + +```bash +git -C backups/mirrors//.git rev-list --all --count +git -C backups/mirrors//.git fsck +``` + +В `objects/` у зеркала часто только `info/` и `pack/` — так и должно быть у `--mirror`. + +## На чём остановились + +1. Прод на RedOS через Docker работает, бэкап репозиториев идёт. +2. Пользователь попросил **документацию для следующего агента** (этот каталог). Других фич в очереди нет. +3. WSL-путь с Docker у пользователя был мучительный (нет демона, нет compose-плагина, permission denied, призрак контейнера). На RedOS compose уже собрал Alpine-образ. Предпочитать то, что работает на текущей машине. +4. Не делали: алерты, UI, бэкап БД Gitea, restore-playbook сверх `git clone` из зеркала, CI. + +## Если продолжать работу — разумные следующие шаги (не запрошены) + +- Убедиться, что на RedOS после `git pull` пересобран Alpine-образ (`docker compose build --no-cache` один раз после смены Dockerfile). +- Если wiki не нужны: `BACKUP_INCLUDE_WIKI=false`. +- Restore-инструкция / проверка `status.json` после ночного прогона. +- Если понадобится полный инстанс: документировать `gitea dump` на 192.168.1.9, это другой инструмент. + +## Правила репозитория + +- Коммиты на русском, формат `тип: описание`. +- PR не создавать, пока пользователь не попросил. +- Отвечать пользователю по-русски. +- Не коммитить `.env` и `backups/`. diff --git a/docs/agent/HISTORY.md b/docs/agent/HISTORY.md new file mode 100644 index 0000000..b979929 --- /dev/null +++ b/docs/agent/HISTORY.md @@ -0,0 +1,58 @@ +# История работы (для контекста, не для повторения) + +Проект создан с нуля в пустом репозитории. Пользователь с самого начала на русском, коммиты тоже. + +## Хронология + +1. **Запрос:** ежедневный бэкап всех репозиториев Gitea `192.168.1.9`. + Сделан Python-пакет: API → mirror → снимки, Docker Compose, systemd, README. + +2. **`.env.example`:** `BACKUP_KEEP_DAYS` 14 → 30 (правка пользователя в diff-tab). + +3. **«docker: command not found»** в WSL. + Добавлены `install.sh` (venv/cron) и запуск без Docker как основной путь в README. `BACKUP_DIR` по умолчанию `./backups`. + +4. Пользователь всё же захотел Docker. Дальше серия чисто инфраструктурных сбоев на Ubuntu/WSL, не багов бэкапа: + + - нет плагина Compose (`-d` уходит в `docker`); + - нет прав на `docker.sock`; + - нет `dockerd` / `service docker unrecognized`; + - README.md выкинут `.dockerignore`; + - призрак контейнера Compose после ручного `dockerd`. + + `docker-up.sh` в итоге **не полагается на compose up**: `docker build` + `docker run`. + +5. Проект **перенесён на RedOS**. Сборка Debian-slim упала на GPG apt. Dockerfile сменён на Alpine. + +6. Пользователь прислал лог успешного fetch `Matvey/ChatService` и WARNING wiki. Подтверждено, что это норма; лог wiki смягчён. + +7. Запрос: описание проекта/архитектуры для другого агента → этот каталог `docs/agent/`. + +## Решения, которые нельзя откатывать без причины + +| Решение | Почему | +|---|---| +| Mirror, не `gitea dump` | Просили репозитории, не всю инстанцию | +| Token в URL `oauth2:token@host` | HTTP clone приватных реп | +| `network_mode: host` | Gitea в LAN, не в Docker-сети | +| Alpine-образ | Debian apt на RedOS/старом seccomp лжёт про подписи | +| `coreutils` в Alpine | `cp -al` для дешёвых снимков | +| Wiki-ошибка ≠ fail backup | `has_wiki` не значит, что `.wiki.git` существует | +| Не веб-UI | Это джоба, не продукт с экраном | + +## Коммиты на `main` (порядок) + +``` +feat: добавил ежедневный бэкап всех репозиториев Gitea +chore: увеличил срок хранения снимков до 30 дней +feat: добавил запуск бэкапа без Docker +fix: починил запуск через Docker Compose +docs: описал ошибку permission denied к docker.sock +fix: вернул README.md в Docker-контекст +docs: описал запуск демона Docker в WSL +fix: ставим и запускаем dockerd, а не только CLI +fix: пересоздаю контейнер после перезапуска dockerd +fix: запускаю бэкап через docker run, минуя сломанный Compose +fix: собираю образ на Alpine вместо Debian +fix: не пугаю WARNING, если wiki в Gitea ещё не создана +``` diff --git a/docs/agent/OPS.md b/docs/agent/OPS.md new file mode 100644 index 0000000..2b9da71 --- /dev/null +++ b/docs/agent/OPS.md @@ -0,0 +1,90 @@ +# Эксплуатация и грабли + +## Предпочитаемые способы запуска + +На **RedOS-сервере** (текущий прод пользователя): Docker Compose, образ Alpine. + +```bash +# .env с GITEA_TOKEN и верным GITEA_URL +sudo docker compose build --no-cache # после смены Dockerfile +sudo docker compose up -d +sudo docker compose logs -f +sudo docker exec gitea-backup gitea-backup list +``` + +Сеть контейнера: `network_mode: host`, чтобы достучаться до `192.168.1.9`. + +На **машине без Docker**: `./install.sh`, токен в `.env`, `.venv/bin/gitea-backup run`, ежедневно `./install.sh --cron`. + +На **Ubuntu/WSL**, если Compose болеет: `./docker-up.sh` делает `docker build` + `docker run` (имя контейнера `gitea-backup`, образ `gitea-backup:latest`). Не путать с именем образа, которое даёт compose: `gitea-daily-backup-gitea-backup:latest`. + +## Docker: что уже ломалось у этого пользователя + +Идти по списку сверху вниз, не ставить всё подряд. + +1. **`unknown shorthand flag: 'd' in -d`** + Есть `docker`, нет плагина Compose. + `sudo apt install docker-compose-v2` + Проверка: `docker compose version` → `Docker Compose version v2.x`. + Запас: пакет `docker-compose` и команда через дефис. + +2. **`permission denied ... docker.sock`** + Демон жив, пользователь не в группе `docker`. + Сейчас: `sudo docker compose …` + Навсегда: `sudo usermod -aG docker "$USER"` и новая сессия / `newgrp docker`. + +3. **`Cannot connect to the Docker daemon` + `service docker: unrecognized service`** + Установлен только CLI, нет `dockerd`. + `sudo apt install docker.io containerd` + В WSL без systemd: в одном терминале `sudo dockerd`, в другом compose/run. + Docker Desktop на Windows — отдельный движок: его надо запустить и включить WSL integration. + +4. **Сборка ок, `No such container: ac8d23cfcfca…`** + Compose помнит ID после рестарта `dockerd`. `compose down` / `--force-recreate` у пользователя **не помогли**. Обход: не compose, а `docker run` с уже собранным образом (см. README и `docker-up.sh`). + +5. **`.dockerignore` и `*.md`** + Раньше `COPY README.md` падал: README не попадал в контекст. Правило `*.md` из dockerignore убрано. Не возвращать. + +6. **Debian bookworm: `At least one invalid signature was encountered`** + На RedOS/RHEL это почти всегда старый `libseccomp` (syscall `faccessat2`) или кривые часы хоста, не «Debian unsigned». + **Решение в коде:** Dockerfile на `python:3.12-alpine` + `coreutils`. + После pull: `docker compose build --no-cache`. + Если Alpine тоже не качается: `dnf update libseccomp`, проверить `date`. + +7. **Bake / buildx warning** + Можно игнорировать. `COMPOSE_BAKE=false` отключает. + +8. **`git rev-parse --is-inside-work-tree` при сборке** + Каталог без `.git` (копия файлов). Безвредно. + +## Wiki в логах + +Gitea часто отдаёт `has_wiki: true` до первой страницы. Клон `owner/repo.wiki.git` тогда: + +``` +fatal: Could not read from remote repository. +``` + +Это не фейл git-репозитория. Код продолжает и пишет «Готово». С коммита про смягчение лога — уровень INFO, не WARNING. Отключить wiki: `BACKUP_INCLUDE_WIKI=false`. + +## Токен + +Gitea → Настройки → Приложения. Для **всех** реп, включая чужие приватные, нужен **админ сайта**. Права: `read:repository`, `read:user`, `read:organization`. + +## WSL и ночной бэкап + +Сессия WSL без окон часто засыпает. Cron внутри WSL ночью может не сработать. Прод логичнее держать на всегда включённом сервере (у пользователя — RedOS) или на самой машине Gitea. + +## systemd + +Юниты в `systemd/` заточены под `/opt/gitea-backup`. `install.sh --systemd` пишет user-units с реальными путями к текущему клону. На WSL user-systemd часто нет. + +## Проверки после изменений + +```bash +python -m unittest discover -s tests -v +# на проде: +docker compose logs --tail 100 +# или +cat backups/status.json +``` diff --git a/docs/agent/README.md b/docs/agent/README.md new file mode 100644 index 0000000..2d4f973 --- /dev/null +++ b/docs/agent/README.md @@ -0,0 +1,12 @@ +# Документация для агента + +Читать в таком порядке: + +| Файл | Зачем | +|---|---| +| [HANDOFF.md](HANDOFF.md) | **На чём остановились.** Цель, прод, открытые хвосты. | +| [ARCHITECTURE.md](ARCHITECTURE.md) | Как устроен код, поток данных, конфиг, хранение. | +| [OPS.md](OPS.md) | Как запускать, типичные поломки Docker/WSL/RedOS. | +| [HISTORY.md](HISTORY.md) | Что делали по шагам и почему приняли решения. | + +Пользовательский README: [`../../README.md`](../../README.md). diff --git a/install.sh b/install.sh new file mode 100755 index 0000000..2c0414b --- /dev/null +++ b/install.sh @@ -0,0 +1,162 @@ +#!/usr/bin/env bash +# Установка и ежедневный запуск бэкапа Gitea без Docker. +set -euo pipefail + +ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +cd "$ROOT" + +usage() { + cat <<'EOF' +Установка бэкапа Gitea без Docker. Нужны Python 3.11+ и Git. + + ./install.sh создать venv и поставить программу + ./install.sh --cron то же + ежедневный cron на 03:00 + ./install.sh --systemd то же + пользовательский systemd-таймер + ./install.sh --help +EOF +} + +need_cmd() { + local cmd="$1" + local apt_hint="$2" + if ! command -v "$cmd" >/dev/null 2>&1; then + echo "Не найден ${cmd}. Установите: sudo apt install ${apt_hint}" >&2 + exit 1 + fi +} + +python_ok() { + python3 - <<'PY' +import sys +raise SystemExit(0 if sys.version_info >= (3, 11) else 1) +PY +} + +setup_venv() { + need_cmd python3 "python3 python3-venv python3-pip" + need_cmd git git + if ! python_ok; then + echo "Нужен Python 3.11 или новее. Сейчас: $(python3 --version)" >&2 + exit 1 + fi + + if [[ ! -d .venv ]]; then + python3 -m venv .venv + fi + .venv/bin/pip install -U pip + .venv/bin/pip install -e "$ROOT" + + if [[ ! -f .env ]]; then + cp .env.example .env + echo "Создан файл .env — впишите в него GITEA_TOKEN." + fi + mkdir -p backups + + if ! command -v git-lfs >/dev/null 2>&1; then + echo "Предупреждение: git-lfs не установлен, объекты LFS не попадут в бэкап." + echo " sudo apt install git-lfs && git lfs install" + fi + + cat </dev/null 2>&1 && systemctl is-active --quiet cron 2>/dev/null; then + return 0 + fi + if command -v service >/dev/null 2>&1 && service cron status >/dev/null 2>&1; then + return 0 + fi + return 1 +} + +install_cron() { + setup_venv + local bin="$ROOT/.venv/bin/gitea-backup" + local log="$ROOT/backups/backup.log" + mkdir -p "$ROOT/backups" + local line="0 3 * * * cd \"$ROOT\" && \"$bin\" run >> \"$log\" 2>&1" + local current + current="$(crontab -l 2>/dev/null || true)" + if printf '%s\n' "$current" | grep -F "$bin" >/dev/null 2>&1; then + echo "Cron-задача для gitea-backup уже установлена." + else + { printf '%s\n' "$current"; printf '%s\n' "$line"; } | crontab - + echo "Добавлена cron-задача: каждый день в 03:00." + fi + + if cron_running; then + echo "Служба cron запущена." + else + echo "Служба cron сейчас не запущена. В Ubuntu/WSL:" + echo " sudo apt install cron" + echo " sudo service cron start" + fi +} + +install_systemd() { + setup_venv + if ! command -v systemctl >/dev/null 2>&1; then + echo "systemctl не найден. Используйте: ./install.sh --cron" >&2 + exit 1 + fi + if ! systemctl --user show-environment >/dev/null 2>&1; then + echo "Пользовательский systemd недоступен (часто так в WSL)." >&2 + echo "Включите systemd в /etc/wsl.conf или выполните: ./install.sh --cron" >&2 + exit 1 + fi + + local dir="${XDG_CONFIG_HOME:-$HOME/.config}/systemd/user" + mkdir -p "$dir" + cat >"$dir/gitea-backup.service" <"$dir/gitea-backup.timer" <&2; exit 1 ;; +esac diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 0000000..7d4766f --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,23 @@ +[project] +name = "gitea-backup" +version = "1.0.0" +description = "Ежедневный бэкап всех репозиториев Gitea" +readme = "README.md" +requires-python = ">=3.11" +dependencies = [ + "httpx>=0.27,<1", + "python-dotenv>=1.0,<2", +] + +[project.scripts] +gitea-backup = "gitea_backup.__main__:main" + +[build-system] +requires = ["setuptools>=68"] +build-backend = "setuptools.build_meta" + +[tool.setuptools.packages.find] +where = ["src"] + +[tool.setuptools.package-dir] +"" = "src" diff --git a/src/gitea_backup/__init__.py b/src/gitea_backup/__init__.py new file mode 100644 index 0000000..a41a30a --- /dev/null +++ b/src/gitea_backup/__init__.py @@ -0,0 +1,3 @@ +"""Ежедневный бэкап репозиториев Gitea.""" + +__version__ = "1.0.0" diff --git a/src/gitea_backup/__main__.py b/src/gitea_backup/__main__.py new file mode 100644 index 0000000..bc4277f --- /dev/null +++ b/src/gitea_backup/__main__.py @@ -0,0 +1,92 @@ +from __future__ import annotations + +import argparse +import logging +import sys +from typing import Sequence + +from gitea_backup.backup import run_backup +from gitea_backup.scheduler import run_scheduler +from gitea_backup.client import GiteaClient, GiteaError +from gitea_backup.config import load_config + +log = logging.getLogger("gitea_backup") + + +def _setup_logging() -> None: + logging.basicConfig( + level=logging.INFO, + format="%(asctime)s %(levelname)s %(message)s", + datefmt="%Y-%m-%d %H:%M:%S", + ) + + +def build_parser() -> argparse.ArgumentParser: + parser = argparse.ArgumentParser( + prog="gitea-backup", + description="Ежедневный бэкап всех репозиториев Gitea (git mirror + снимки).", + ) + sub = parser.add_subparsers(dest="command", required=True) + + run_p = sub.add_parser("run", help="Сделать бэкап один раз и выйти") + run_p.add_argument( + "--dry-run", + action="store_true", + help="Только показать список репозиториев, ничего не клонировать", + ) + + sub.add_parser("schedule", help="Демон: бэкап каждый день в BACKUP_AT") + sub.add_parser("list", help="Показать репозитории, доступные токену") + return parser + + +def main(argv: Sequence[str] | None = None) -> int: + _setup_logging() + args = build_parser().parse_args(argv) + + try: + config = load_config() + except ValueError as exc: + log.error("%s", exc) + return 2 + + if not config.token: + log.error( + "Не задан GITEA_TOKEN. Скопируйте .env.example в .env и укажите токен " + "(Gitea → Настройки → Приложения)." + ) + return 2 + + try: + if args.command == "list": + with GiteaClient(config.gitea_url, config.token) as client: + version = client.ping() + repos = client.list_repos() + print(f"Gitea {version} — {config.gitea_url}") + print(f"Репозиториев: {len(repos)}") + for repo in repos: + flag = "private" if repo.get("private") else "public" + print(f" {repo.get('full_name')} ({flag})") + return 0 + + if args.command == "run": + status = run_backup(config, dry_run=args.dry_run) + if status.get("repos_failed"): + return 1 + return 0 + + if args.command == "schedule": + run_scheduler(config) + return 0 + except GiteaError as exc: + log.error("%s", exc) + return 1 + except KeyboardInterrupt: + log.info("Остановлено") + return 130 + + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/src/gitea_backup/backup.py b/src/gitea_backup/backup.py new file mode 100644 index 0000000..7c28d65 --- /dev/null +++ b/src/gitea_backup/backup.py @@ -0,0 +1,242 @@ +from __future__ import annotations + +import json +import logging +import shutil +import subprocess +from datetime import datetime, timedelta, timezone +from pathlib import Path +from typing import Any, Callable +from zoneinfo import ZoneInfo + +from gitea_backup.client import GiteaClient, GiteaError, wiki_clone_url +from gitea_backup.config import Config +from gitea_backup.gitops import Git, GitError, mirror_path + +log = logging.getLogger("gitea_backup") + + +def _now(tz: ZoneInfo) -> datetime: + return datetime.now(tz) + + +def lock_file(path: Path): + """Контекстный менеджер flock, чтобы два бэкапа не пересеклись.""" + path.parent.mkdir(parents=True, exist_ok=True) + handle = path.open("a+") + try: + import fcntl + + fcntl.flock(handle.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB) + except BlockingIOError as exc: + handle.close() + raise RuntimeError("Бэкап уже выполняется (lock-файл занят).") from exc + except ImportError: + pass + return handle + + +def _unlock(handle: Any) -> None: + try: + import fcntl + + fcntl.flock(handle.fileno(), fcntl.LOCK_UN) + except Exception: + pass + handle.close() + + +def make_hardlink_snapshot(src: Path, dest: Path) -> None: + if dest.exists(): + shutil.rmtree(dest) + dest.parent.mkdir(parents=True, exist_ok=True) + result = subprocess.run( + ["cp", "-al", str(src), str(dest)], + capture_output=True, + text=True, + ) + if result.returncode == 0: + return + log.warning("cp -al недоступен (%s), копирую целиком", result.stderr.strip()) + shutil.copytree(src, dest, dirs_exist_ok=False) + + +def prune_snapshots(snapshots_dir: Path, keep_days: int, now: datetime) -> list[str]: + if not snapshots_dir.exists(): + return [] + cutoff = (now - timedelta(days=keep_days)).date() + removed: list[str] = [] + for child in sorted(snapshots_dir.iterdir()): + if not child.is_dir(): + continue + try: + day = datetime.strptime(child.name, "%Y-%m-%d").date() + except ValueError: + continue + if day < cutoff: + shutil.rmtree(child) + removed.append(child.name) + log.info("Удалён старый снимок %s", child.name) + return removed + + +def write_status(path: Path, payload: dict[str, Any]) -> None: + path.parent.mkdir(parents=True, exist_ok=True) + tmp = path.with_suffix(".json.tmp") + tmp.write_text(json.dumps(payload, ensure_ascii=False, indent=2) + "\n", encoding="utf-8") + tmp.replace(path) + + +def run_backup( + config: Config, + *, + dry_run: bool = False, + client_factory: Callable[[Config], GiteaClient] | None = None, + git: Git | None = None, +) -> dict[str, Any]: + tz = config.zoneinfo() + started = _now(tz) + lock_handle = None + if not dry_run: + lock_handle = lock_file(config.backup_dir / ".backup.lock") + + status: dict[str, Any] = { + "started_at": started.isoformat(), + "gitea_url": config.gitea_url, + "dry_run": dry_run, + "ok": False, + "gitea_version": None, + "repos_total": 0, + "repos_ok": 0, + "repos_failed": [], + "snapshot": None, + "pruned_snapshots": [], + "finished_at": None, + "error": None, + } + + make_client = client_factory or (lambda cfg: GiteaClient(cfg.gitea_url, cfg.token)) + worker = git or Git(config.token, include_lfs=config.include_lfs) + + try: + with make_client(config) as client: + version = client.ping() + status["gitea_version"] = version + log.info("Gitea %s (%s)", version, config.gitea_url) + repos = client.list_repos() + status["repos_total"] = len(repos) + log.info("Найдено репозиториев: %s", len(repos)) + + if not repos: + log.warning("Репозитории не найдены. Проверьте токен и его права.") + + for repo in repos: + full_name = str(repo.get("full_name", "")) + try: + _backup_one(config, client, worker, repo, dry_run=dry_run) + status["repos_ok"] += 1 + log.info("Готово: %s", full_name) + except (GiteaError, GitError, OSError) as exc: + log.error("Ошибка %s: %s", full_name, exc) + status["repos_failed"].append({"repo": full_name, "error": str(exc)}) + + if ( + not dry_run + and config.snapshots + and config.mirrors_dir.exists() + and any(config.mirrors_dir.iterdir()) + ): + stamp = started.date().isoformat() + dest = config.snapshots_dir / stamp + log.info("Снимок %s", dest) + make_hardlink_snapshot(config.mirrors_dir, dest) + status["snapshot"] = stamp + status["pruned_snapshots"] = prune_snapshots( + config.snapshots_dir, config.keep_days, started + ) + + status["ok"] = not status["repos_failed"] + if status["repos_failed"] and status["repos_ok"]: + status["ok"] = False + log.warning( + "Бэкап завершён частично: %s ок, %s ошибок", + status["repos_ok"], + len(status["repos_failed"]), + ) + elif status["ok"]: + log.info("Бэкап завершён успешно: %s репозиториев", status["repos_ok"]) + return status + except Exception as exc: + status["error"] = str(exc) + log.exception("Бэкап прерван: %s", exc) + raise + finally: + status["finished_at"] = _now(tz).isoformat() + if not dry_run: + write_status(config.status_path, status) + if lock_handle is not None: + _unlock(lock_handle) + + +def _backup_one( + config: Config, + client: GiteaClient, + git: Git, + repo: dict[str, Any], + *, + dry_run: bool, +) -> None: + full_name = str(repo.get("full_name", "")) + if not full_name: + raise GiteaError("Репозиторий без full_name") + + dest = mirror_path(config.mirrors_dir, full_name) + clone_url = client.clone_url(repo) + if dry_run: + log.info("[dry-run] %s → %s", full_name, dest) + else: + git.mirror_or_fetch(clone_url, dest) + meta = { + "full_name": full_name, + "private": repo.get("private"), + "empty": repo.get("empty"), + "default_branch": repo.get("default_branch"), + "description": repo.get("description"), + "updated_at": repo.get("updated_at"), + "clone_url": repo.get("clone_url"), + "backed_up_at": datetime.now(timezone.utc).isoformat(), + } + (dest.parent / f"{dest.name}.meta.json").write_text( + json.dumps(meta, ensure_ascii=False, indent=2) + "\n", + encoding="utf-8", + ) + + if config.include_wiki and repo.get("has_wiki"): + wiki_dest = mirror_path(config.mirrors_dir, full_name, wiki=True) + wiki_url = wiki_clone_url(clone_url) + if dry_run: + log.info("[dry-run] wiki %s → %s", full_name, wiki_dest) + return + try: + git.mirror_or_fetch(wiki_url, wiki_dest) + except GitError as exc: + text = str(exc).lower() + missing = any( + needle in text + for needle in ( + "could not read from remote", + "repository not found", + "not found", + "correct access rights", + "does not exist", + ) + ) + if missing: + log.info( + "Wiki %s не создана на сервере (флаг wiki включён, страниц ещё нет) — пропуск", + full_name, + ) + else: + log.warning("Wiki %s пропущена: %s", full_name, exc) + + diff --git a/src/gitea_backup/client.py b/src/gitea_backup/client.py new file mode 100644 index 0000000..558fee2 --- /dev/null +++ b/src/gitea_backup/client.py @@ -0,0 +1,141 @@ +from __future__ import annotations + +from typing import Any, Iterator +from urllib.parse import quote, urlparse, urlunparse + +import httpx + + +PAGE_SIZE = 50 + + +class GiteaError(RuntimeError): + pass + + +def inject_token(clone_url: str, token: str) -> str: + """Вставляет токен в clone URL, не ломая порт и путь.""" + parsed = urlparse(clone_url) + if not parsed.hostname: + raise GiteaError(f"Некорректный clone_url: {clone_url!r}") + netloc = f"oauth2:{quote(token, safe='')}@{parsed.hostname}" + if parsed.port: + netloc += f":{parsed.port}" + return urlunparse(parsed._replace(netloc=netloc)) + + +def wiki_clone_url(clone_url: str) -> str: + if clone_url.endswith(".wiki.git"): + return clone_url + if clone_url.endswith(".git"): + return clone_url[: -len(".git")] + ".wiki.git" + return clone_url + ".wiki.git" + + +def username_of(user: dict[str, Any]) -> str: + return str(user.get("username") or user.get("login") or "") + + +class GiteaClient: + def __init__(self, base_url: str, token: str, timeout: float = 60.0) -> None: + if not token: + raise GiteaError( + "Не задан GITEA_TOKEN. Создайте токен в Gitea: " + "Настройки → Приложения → Создать токен." + ) + self.base_url = base_url.rstrip("/") + self.token = token + self._client = httpx.Client( + base_url=self.base_url, + headers={ + "Authorization": f"token {token}", + "Accept": "application/json", + }, + timeout=timeout, + follow_redirects=True, + ) + + def close(self) -> None: + self._client.close() + + def __enter__(self) -> GiteaClient: + return self + + def __exit__(self, *args: object) -> None: + self.close() + + def _get(self, path: str, params: dict[str, Any] | None = None) -> httpx.Response: + try: + response = self._client.get(path, params=params) + response.raise_for_status() + return response + except httpx.HTTPStatusError as exc: + raise GiteaError( + f"Gitea {exc.response.status_code} {path}: {exc.response.text[:300]}" + ) from exc + except httpx.RequestError as exc: + raise GiteaError( + f"Не удалось подключиться к {self.base_url}: {exc}" + ) from exc + + def ping(self) -> str: + data = self._get("/api/v1/version").json() + return str(data.get("version", "unknown")) + + def paginate(self, path: str, params: dict[str, Any] | None = None) -> Iterator[Any]: + page = 1 + while True: + query = dict(params or {}) + query.update(page=page, limit=PAGE_SIZE) + payload = self._get(path, params=query).json() + items = payload.get("data", payload) if isinstance(payload, dict) else payload + if not items: + break + yield from items + if len(items) < PAGE_SIZE: + break + page += 1 + + def _try_paginate(self, path: str, params: dict[str, Any] | None = None) -> list[Any]: + try: + return list(self.paginate(path, params)) + except GiteaError: + return [] + + def list_repos(self) -> list[dict[str, Any]]: + """Собирает все доступные репозитории, без дублей.""" + seen: dict[str, dict[str, Any]] = {} + + def add(repo: dict[str, Any]) -> None: + name = repo.get("full_name") + if name: + seen[str(name)] = repo + + for repo in self.paginate("/api/v1/repos/search", {"q": "", "private": True}): + add(repo) + for repo in self._try_paginate("/api/v1/user/repos"): + add(repo) + + for org in self._try_paginate("/api/v1/orgs"): + org_name = username_of(org) + if org_name: + for repo in self._try_paginate(f"/api/v1/orgs/{org_name}/repos"): + add(repo) + + admin_users = self._try_paginate("/api/v1/admin/users") + for user in admin_users: + name = username_of(user) + if name: + for repo in self._try_paginate(f"/api/v1/users/{name}/repos"): + add(repo) + + return sorted(seen.values(), key=lambda r: str(r.get("full_name", ""))) + + def clone_url(self, repo: dict[str, Any]) -> str: + url = repo.get("clone_url") or repo.get("html_url") + if not url: + full_name = repo.get("full_name") + if not full_name: + raise GiteaError(f"У репозитория нет clone_url: {repo!r}") + url = f"{self.base_url}/{full_name}.git" + return inject_token(str(url), self.token) diff --git a/src/gitea_backup/config.py b/src/gitea_backup/config.py new file mode 100644 index 0000000..2a5a00e --- /dev/null +++ b/src/gitea_backup/config.py @@ -0,0 +1,114 @@ +from __future__ import annotations + +import os +from dataclasses import dataclass +from pathlib import Path +from urllib.parse import urlparse +from zoneinfo import ZoneInfo, ZoneInfoNotFoundError + +from dotenv import load_dotenv + + +def _bool(name: str, default: bool) -> bool: + raw = os.environ.get(name) + if raw is None: + return default + return raw.strip().lower() in {"1", "true", "yes", "on"} + + +def _int(name: str, default: int) -> int: + raw = os.environ.get(name) + if raw is None or not raw.strip(): + return default + return int(raw) + + +@dataclass(frozen=True) +class Config: + gitea_url: str + token: str + backup_dir: Path + backup_at: str + timezone: str + run_on_start: bool + snapshots: bool + keep_days: int + include_wiki: bool + include_lfs: bool + + @property + def mirrors_dir(self) -> Path: + return self.backup_dir / "mirrors" + + @property + def snapshots_dir(self) -> Path: + return self.backup_dir / "snapshots" + + @property + def status_path(self) -> Path: + return self.backup_dir / "status.json" + + def zoneinfo(self) -> ZoneInfo: + try: + return ZoneInfo(self.timezone) + except ZoneInfoNotFoundError as exc: + raise ValueError(f"Неизвестная таймзона TZ={self.timezone!r}") from exc + + def schedule_hm(self) -> tuple[int, int]: + parts = self.backup_at.strip().split(":") + if len(parts) != 2: + raise ValueError(f"BACKUP_AT должен быть в формате ЧЧ:ММ, получено {self.backup_at!r}") + hour, minute = int(parts[0]), int(parts[1]) + if not (0 <= hour <= 23 and 0 <= minute <= 59): + raise ValueError(f"Некорректное время BACKUP_AT={self.backup_at!r}") + return hour, minute + + +def _repo_root() -> Path: + return Path(__file__).resolve().parents[2] + + +def _find_dotenv() -> Path | None: + for candidate in (Path.cwd() / ".env", _repo_root() / ".env"): + if candidate.is_file(): + return candidate + return None + + +def _resolve_backup_dir(raw: str, dotenv_path: Path | None) -> Path: + path = Path(raw).expanduser() + if path.is_absolute(): + return path + base = dotenv_path.parent if dotenv_path is not None else Path.cwd() + return (base / path).resolve() + + +def load_config() -> Config: + dotenv_path = None + if os.environ.get("GITEA_BACKUP_SKIP_DOTENV") != "1": + dotenv_path = _find_dotenv() + if dotenv_path is not None: + load_dotenv(dotenv_path) + else: + load_dotenv() + + url = os.environ.get("GITEA_URL", "http://192.168.1.9:3000").rstrip("/") + parsed = urlparse(url) + if parsed.scheme not in {"http", "https"} or not parsed.netloc: + raise ValueError(f"GITEA_URL должен быть http(s)-адресом, получено {url!r}") + + token = os.environ.get("GITEA_TOKEN", "").strip() + backup_dir = _resolve_backup_dir(os.environ.get("BACKUP_DIR", "./backups"), dotenv_path) + + return Config( + gitea_url=url, + token=token, + backup_dir=backup_dir, + backup_at=os.environ.get("BACKUP_AT", "03:00"), + timezone=os.environ.get("TZ", "Europe/Moscow"), + run_on_start=_bool("RUN_ON_START", True), + snapshots=_bool("BACKUP_SNAPSHOTS", True), + keep_days=max(1, _int("BACKUP_KEEP_DAYS", 30)), + include_wiki=_bool("BACKUP_INCLUDE_WIKI", True), + include_lfs=_bool("BACKUP_INCLUDE_LFS", True), + ) diff --git a/src/gitea_backup/gitops.py b/src/gitea_backup/gitops.py new file mode 100644 index 0000000..690e16b --- /dev/null +++ b/src/gitea_backup/gitops.py @@ -0,0 +1,73 @@ +from __future__ import annotations + +import logging +import shutil +import subprocess +from pathlib import Path + +log = logging.getLogger("gitea_backup") + + +def redact(value: str, token: str) -> str: + if token and token in value: + return value.replace(token, "***") + return value + + +def mirror_path(mirrors_dir: Path, full_name: str, wiki: bool = False) -> Path: + owner, _, name = full_name.partition("/") + suffix = ".wiki.git" if wiki else ".git" + return mirrors_dir / owner / f"{name}{suffix}" + + +class GitError(RuntimeError): + pass + + +class Git: + def __init__(self, token: str, include_lfs: bool = True) -> None: + self.token = token + self.include_lfs = include_lfs + + def _run(self, args: list[str], cwd: Path | None = None) -> None: + logged = [redact(arg, self.token) for arg in args] + log.info("git: %s", " ".join(logged)) + try: + subprocess.run( + args, + cwd=cwd, + check=True, + capture_output=True, + text=True, + ) + except FileNotFoundError as exc: + raise GitError("git не найден в PATH. Установите Git.") from exc + except subprocess.CalledProcessError as exc: + err = redact((exc.stderr or exc.stdout or "").strip(), self.token) + raise GitError(err or f"команда завершилась с кодом {exc.returncode}") from exc + + def mirror_or_fetch(self, clone_url: str, dest: Path) -> None: + dest.parent.mkdir(parents=True, exist_ok=True) + if (dest / "HEAD").exists() or (dest / "packed-refs").exists(): + self._run(["git", "-C", str(dest), "remote", "set-url", "origin", clone_url]) + self._run(["git", "-C", str(dest), "fetch", "--all", "--prune", "--tags"]) + else: + if dest.exists(): + shutil.rmtree(dest) + self._run(["git", "clone", "--mirror", clone_url, str(dest)]) + if self.include_lfs: + self._fetch_lfs(dest) + + def _fetch_lfs(self, dest: Path) -> None: + try: + self._run(["git", "-C", str(dest), "lfs", "fetch", "--all"]) + except GitError as exc: + message = str(exc).lower() + if "not a git command" in message or ("lfs" in message and "not found" in message): + log.warning("git-lfs недоступен, объекты LFS пропущены: %s", dest) + return + # Пустой репозиторий / нет LFS-указателей — не считаем ошибкой. + if "not a valid" in message or "no such" in message or "not found" in message: + log.debug("LFS пропущен для %s: %s", dest, exc) + return + log.warning("LFS для %s: %s", dest, exc) diff --git a/src/gitea_backup/scheduler.py b/src/gitea_backup/scheduler.py new file mode 100644 index 0000000..2a0d265 --- /dev/null +++ b/src/gitea_backup/scheduler.py @@ -0,0 +1,56 @@ +from __future__ import annotations + +import logging +import time +from datetime import datetime, timedelta +from typing import Any, Callable +from zoneinfo import ZoneInfo + +from gitea_backup.backup import run_backup +from gitea_backup.config import Config + +log = logging.getLogger("gitea_backup") + + +def parse_hm(backup_at: str) -> tuple[int, int]: + parts = backup_at.strip().split(":") + if len(parts) != 2: + raise ValueError(f"BACKUP_AT должен быть ЧЧ:ММ, получено {backup_at!r}") + hour, minute = int(parts[0]), int(parts[1]) + if not (0 <= hour <= 23 and 0 <= minute <= 59): + raise ValueError(f"Некорректное время BACKUP_AT={backup_at!r}") + return hour, minute + + +def seconds_until_next(backup_at: str, tz: ZoneInfo, now: datetime | None = None) -> float: + hour, minute = parse_hm(backup_at) + current = now or datetime.now(tz) + target = current.replace(hour=hour, minute=minute, second=0, microsecond=0) + if current >= target: + target += timedelta(days=1) + return max(1.0, (target - current).total_seconds()) + + +def run_scheduler( + config: Config, + sleeper: Callable[[float], None] | None = None, + backup_fn: Callable[[Config], Any] | None = None, +) -> None: + sleep = sleeper or time.sleep + do_backup = backup_fn or (lambda cfg: run_backup(cfg)) + tz = config.zoneinfo() + log.info( + "Планировщик: каждый день в %s (%s), каталог %s", + config.backup_at, + config.timezone, + config.backup_dir, + ) + if config.run_on_start: + log.info("Первый бэкап сразу после старта") + do_backup(config) + + while True: + wait = seconds_until_next(config.backup_at, tz) + log.info("Следующий бэкап через %.1f ч (в %s)", wait / 3600, config.backup_at) + sleep(wait) + do_backup(config) diff --git a/systemd/gitea-backup.service b/systemd/gitea-backup.service new file mode 100644 index 0000000..edea941 --- /dev/null +++ b/systemd/gitea-backup.service @@ -0,0 +1,14 @@ +[Unit] +Description=Бэкап всех репозиториев Gitea +After=network-online.target +Wants=network-online.target + +[Service] +Type=oneshot +WorkingDirectory=/opt/gitea-backup +EnvironmentFile=/opt/gitea-backup/.env +ExecStart=/opt/gitea-backup/.venv/bin/gitea-backup run +Nice=10 + +[Install] +WantedBy=multi-user.target diff --git a/systemd/gitea-backup.timer b/systemd/gitea-backup.timer new file mode 100644 index 0000000..5a83bfc --- /dev/null +++ b/systemd/gitea-backup.timer @@ -0,0 +1,10 @@ +[Unit] +Description=Ежедневный бэкап репозиториев Gitea + +[Timer] +OnCalendar=*-*-* 03:00:00 +Persistent=true +RandomizedDelaySec=5m + +[Install] +WantedBy=timers.target diff --git a/tests/test_backup.py b/tests/test_backup.py new file mode 100644 index 0000000..e2ecf19 --- /dev/null +++ b/tests/test_backup.py @@ -0,0 +1,129 @@ +from __future__ import annotations + +import json +import tempfile +import unittest +from datetime import datetime +from pathlib import Path +from zoneinfo import ZoneInfo + +from gitea_backup.backup import prune_snapshots, run_backup +from gitea_backup.config import Config +from gitea_backup.scheduler import seconds_until_next + + +class FakeGit: + def __init__(self) -> None: + self.calls: list[tuple[str, Path]] = [] + + def mirror_or_fetch(self, clone_url: str, dest: Path) -> None: + dest.mkdir(parents=True, exist_ok=True) + (dest / "HEAD").write_text("ref: refs/heads/main\n", encoding="utf-8") + self.calls.append((clone_url, dest)) + + +class FakeClient: + def __init__(self, repos: list[dict]) -> None: + self._repos = repos + self.token = "tok" + + def __enter__(self) -> FakeClient: + return self + + def __exit__(self, *args: object) -> None: + return None + + def ping(self) -> str: + return "1.22.0" + + def list_repos(self) -> list[dict]: + return self._repos + + def clone_url(self, repo: dict) -> str: + return f"http://oauth2:tok@192.168.1.9:3000/{repo['full_name']}.git" + + +def _config(root: Path, **kwargs) -> Config: + values = dict( + gitea_url="http://192.168.1.9:3000", + token="tok", + backup_dir=root, + backup_at="03:00", + timezone="Europe/Moscow", + run_on_start=True, + snapshots=True, + keep_days=7, + include_wiki=True, + include_lfs=False, + ) + values.update(kwargs) + return Config(**values) + + +class SnapshotPruneTest(unittest.TestCase): + def test_removes_old_dated_dirs(self) -> None: + with tempfile.TemporaryDirectory() as tmp: + root = Path(tmp) + (root / "2026-08-01").mkdir() + (root / "2026-09-07").mkdir() + (root / "notes.txt").write_text("skip", encoding="utf-8") + now = datetime(2026, 9, 8, tzinfo=ZoneInfo("Europe/Moscow")) + removed = prune_snapshots(root, keep_days=7, now=now) + self.assertEqual(removed, ["2026-08-01"]) + self.assertTrue((root / "2026-09-07").is_dir()) + + +class SchedulerTest(unittest.TestCase): + def test_waits_until_tomorrow_if_time_passed(self) -> None: + tz = ZoneInfo("Europe/Moscow") + now = datetime(2026, 9, 8, 4, 0, tzinfo=tz) + wait = seconds_until_next("03:00", tz, now=now) + self.assertGreater(wait, 22 * 3600) + self.assertLess(wait, 24 * 3600) + + def test_waits_same_day_if_upcoming(self) -> None: + tz = ZoneInfo("Europe/Moscow") + now = datetime(2026, 9, 8, 1, 0, tzinfo=tz) + wait = seconds_until_next("03:00", tz, now=now) + self.assertAlmostEqual(wait, 2 * 3600, delta=1) + + +class RunBackupTest(unittest.TestCase): + def test_mirrors_repos_and_writes_status(self) -> None: + with tempfile.TemporaryDirectory() as tmp: + root = Path(tmp) + cfg = _config(root) + git = FakeGit() + repos = [ + { + "full_name": "alice/app", + "clone_url": "http://192.168.1.9:3000/alice/app.git", + "has_wiki": True, + "private": True, + }, + { + "full_name": "bob/lib", + "clone_url": "http://192.168.1.9:3000/bob/lib.git", + "has_wiki": False, + "private": False, + }, + ] + status = run_backup( + cfg, + client_factory=lambda _c: FakeClient(repos), + git=git, # type: ignore[arg-type] + ) + self.assertTrue(status["ok"]) + self.assertEqual(status["repos_ok"], 2) + self.assertEqual(status["gitea_version"], "1.22.0") + names = [Path(dest).name for _url, dest in git.calls] + self.assertIn("app.git", names) + self.assertIn("app.wiki.git", names) + self.assertIn("lib.git", names) + saved = json.loads((root / "status.json").read_text(encoding="utf-8")) + self.assertEqual(saved["repos_total"], 2) + self.assertTrue((root / "mirrors" / "alice" / "app.git.meta.json").exists()) + + +if __name__ == "__main__": + unittest.main() diff --git a/tests/test_client.py b/tests/test_client.py new file mode 100644 index 0000000..90844da --- /dev/null +++ b/tests/test_client.py @@ -0,0 +1,59 @@ +from __future__ import annotations + +import unittest +from unittest.mock import MagicMock + +from gitea_backup.client import GiteaClient, inject_token, wiki_clone_url + + +class UrlHelpersTest(unittest.TestCase): + def test_inject_token_keeps_port(self) -> None: + url = inject_token("http://192.168.1.9:3000/alice/app.git", "s3cret") + self.assertEqual(url, "http://oauth2:s3cret@192.168.1.9:3000/alice/app.git") + + def test_wiki_url(self) -> None: + self.assertEqual( + wiki_clone_url("http://gitea/alice/app.git"), + "http://gitea/alice/app.wiki.git", + ) + + +class ListReposTest(unittest.TestCase): + def test_deduplicates_and_paginates(self) -> None: + client = GiteaClient.__new__(GiteaClient) + client.base_url = "http://192.168.1.9:3000" + client.token = "t" + calls: list[tuple[str, dict]] = [] + + def fake_get(path: str, params: dict | None = None): + calls.append((path, dict(params or {}))) + response = MagicMock() + page = int((params or {}).get("page", 1)) + if path == "/api/v1/repos/search": + if page == 1: + response.json.return_value = { + "data": [ + {"full_name": "alice/app", "clone_url": "http://g/alice/app.git"}, + {"full_name": "bob/lib", "clone_url": "http://g/bob/lib.git"}, + ] + } + else: + response.json.return_value = {"data": []} + elif path == "/api/v1/user/repos": + response.json.return_value = [ + {"full_name": "alice/app", "clone_url": "http://g/alice/app.git"}, + ] + else: + response.json.return_value = [] + return response + + client._get = fake_get # type: ignore[method-assign] + repos = client.list_repos() + names = [r["full_name"] for r in repos] + self.assertEqual(names, ["alice/app", "bob/lib"]) + search_pages = [p for path, p in calls if path == "/api/v1/repos/search"] + self.assertGreaterEqual(len(search_pages), 1) + + +if __name__ == "__main__": + unittest.main() diff --git a/tests/test_config.py b/tests/test_config.py new file mode 100644 index 0000000..c765c5e --- /dev/null +++ b/tests/test_config.py @@ -0,0 +1,47 @@ +from __future__ import annotations + +import os +import tempfile +import unittest +from pathlib import Path +from unittest.mock import patch + +from gitea_backup.config import load_config + + +class LoadConfigTest(unittest.TestCase): + def test_defaults_point_to_local_gitea(self) -> None: + env = { + "GITEA_TOKEN": "abc", + "BACKUP_DIR": "/tmp/gitea-backups", + "GITEA_BACKUP_SKIP_DOTENV": "1", + } + with patch.dict(os.environ, env, clear=True): + cfg = load_config() + self.assertEqual(cfg.gitea_url, "http://192.168.1.9:3000") + self.assertEqual(cfg.backup_at, "03:00") + self.assertTrue(cfg.snapshots) + self.assertEqual(cfg.keep_days, 30) + self.assertEqual(cfg.backup_dir, Path("/tmp/gitea-backups")) + + def test_relative_backup_dir_is_resolved(self) -> None: + with tempfile.TemporaryDirectory() as tmp: + env = { + "GITEA_TOKEN": "abc", + "BACKUP_DIR": "./backups", + "GITEA_BACKUP_SKIP_DOTENV": "1", + } + with patch.dict(os.environ, env, clear=True): + with patch("gitea_backup.config.Path.cwd", return_value=Path(tmp)): + cfg = load_config() + self.assertEqual(cfg.backup_dir, (Path(tmp) / "backups").resolve()) + + def test_rejects_bad_url(self) -> None: + env = { + "GITEA_URL": "192.168.1.9", + "GITEA_TOKEN": "x", + "GITEA_BACKUP_SKIP_DOTENV": "1", + } + with patch.dict(os.environ, env, clear=True): + with self.assertRaises(ValueError): + load_config()