init repo

This commit is contained in:
SheinovM committed 2026-11-08 17:06:04 +03:00
commit 6c63a20d8d
24 files changed
+2010

No files matched your search

+14
View File
@@ -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`.
+19
View File
@@ -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"]
+229
View File
@@ -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
```
+16
View File
@@ -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
Executable
+225
View File
@@ -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
+110
View File
@@ -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
```
+72
View File
@@ -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/<owner>/<repo>.git rev-list --all --count
git -C backups/mirrors/<owner>/<repo>.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/`.
+58
View File
@@ -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 ещё не создана
```
+90
View File
@@ -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
```
+12
View File
@@ -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).
Executable
+162
View File
@@ -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 <<EOF
Готово. Дальше:
1. nano .env
вставьте токен (Gitea → Настройки → Приложения)
2. $ROOT/.venv/bin/gitea-backup list
3. $ROOT/.venv/bin/gitea-backup run
Ежедневно без Docker:
./install.sh --cron
./install.sh --systemd
$ROOT/.venv/bin/gitea-backup schedule
EOF
}
cron_running() {
if command -v systemctl >/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" <<EOF
[Unit]
Description=Бэкап всех репозиториев Gitea
After=network-online.target
[Service]
Type=oneshot
WorkingDirectory=$ROOT
EnvironmentFile=$ROOT/.env
ExecStart=$ROOT/.venv/bin/gitea-backup run
Nice=10
EOF
cat >"$dir/gitea-backup.timer" <<EOF
[Unit]
Description=Ежедневный бэкап репозиториев Gitea
[Timer]
OnCalendar=*-*-* 03:00:00
Persistent=true
RandomizedDelaySec=5m
[Install]
WantedBy=timers.target
EOF
systemctl --user daemon-reload
systemctl --user enable --now gitea-backup.timer
echo "Таймер включён. Проверка: systemctl --user status gitea-backup.timer"
}
case "${1:-}" in
--help|-h) usage ;;
--cron) install_cron ;;
--systemd) install_systemd ;;
"") setup_venv ;;
*) usage >&2; exit 1 ;;
esac
+23
View File
@@ -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"
+3
View File
@@ -0,0 +1,3 @@
"""Ежедневный бэкап репозиториев Gitea."""
__version__ = "1.0.0"
+92
View File
@@ -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())
+242
View File
@@ -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)
+141
View File
@@ -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)
+114
View File
@@ -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),
)
+73
View File
@@ -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)
+56
View File
@@ -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)
+14
View File
@@ -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
+10
View File
@@ -0,0 +1,10 @@
[Unit]
Description=Ежедневный бэкап репозиториев Gitea
[Timer]
OnCalendar=*-*-* 03:00:00
Persistent=true
RandomizedDelaySec=5m
[Install]
WantedBy=timers.target
+129
View File
@@ -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()
+59
View File
@@ -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()
+47
View File
@@ -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()