Files
2026-11-08 17:06:04 +03:00

230 lines
9.6 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Бэкап репозиториев 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
```