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

+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).