init repo
This commit is contained in:
commit
6c63a20d8d
24 files changed
+2010
No files matched your search
@@ -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
|
||||
```
|
||||
@@ -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/`.
|
||||
@@ -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 ещё не создана
|
||||
```
|
||||
@@ -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
|
||||
```
|
||||
@@ -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).
|
||||
Reference in new issue
Block a user