BlueGit

timfa bluegit

Files

bluegit / docs / BACKUP.md

BACKUP.md

BACKUP.md 9.0 KiB Download Raw

Backup servers (bluegit-backup)

Een losse backup server (bluegit-backup, in deze repository: cmd/bluegit-backup, zie BACKUP-SERVER.md) houdt een kopie bij van alle gegevens en configuratie van één BlueGit. Hij haalt ze langzaam op, krijgt na elke wijziging een melding, maakt periodiek een gecomprimeerd archief, en kan BlueGit naar zo'n archief terugzetten.

Eén BlueGit kan meerdere backup servers hebben (hoogstens 16), elk met een eigen Backupserver-Key. Een backup server hoort bij één BlueGit.

In BlueGit

Beheer > Backup (/admin/backup, alleen installatiebeheerders) toont de lijst met backup servers: naam, gekoppeld of wachtend op de key, adres en laatste contact. Backup server toevoegen maakt een nieuwe server met een eigen key, die één keer wordt getoond.

Per backup server (/admin/backup/s/<id>) staat dezelfde bediening als in de webinterface van de backup server zelf:

  • Status: laatste sync en het resultaat ervan, aantal syncs en meldingen, grootte van de kopie, archieven, de laatste rollback en de versie. Met de knoppen Nu synchroniseren, Nu archiveren en Nu opruimen.
  • Instellingen van de backup server: archiefinterval, bewaartermijn, minimale vrije ruimte, downloadsnelheid, syncintervallen, publiek adres en luisteradres. BlueGit krijgt de velden van de backup server en toont ze zoals ze daar staan.
  • Backup-archieven met Verwijderen en Rollback. Een rollback staat achter een grote rode waarschuwing, een vinkje ("ik begrijp dat dit niet terug te draaien is"), het intypen van de archiefnaam en een bevestigingsdialoog.
  • Backupserver-Key vervangen (de oude key werkt meteen niet meer; de server moet opnieuw koppelen), de server hernoemen, of key intrekken en de server verwijderen. Bij verwijderen vraagt BlueGit de backup server eerst om te ontkoppelen. De archieven blijven op de backup server staan.

BlueGit kent de acties niet vooraf. Het vraagt ze op bij de backup server (GET /api/v1/admin/actions) en stuurt ze ondertekend door. Alles wat de backup server voor BlueGit openzet, kan dus ook hier. Koppelen en een archief downloaden kan alleen op de backup server zelf.

Dezelfde acties via de API (token van een beheerder, scope api/admin):

GET /api/v1/admin/backupinstance_id en de lijst met backup servers
POST /api/v1/admin/backup/servers{"name"}: nieuwe backup server; het antwoord bevat eenmalig key
GET /api/v1/admin/backup/servers/{id}server met remote (status), archives en config, zoals de backup server ze meldt
PUT /api/v1/admin/backup/servers/{id}{"name"}: hernoemen
POST /api/v1/admin/backup/servers/{id}/keynieuwe key (eenmalig in het antwoord)
DELETE /api/v1/admin/backup/servers/{id}ontkoppelen en vergeten
POST /api/v1/admin/backup/servers/{id}/actions/{name}actie van de backup server, bijvoorbeeld config.update met {"retention_days": "14"}, sync, archive, prune, archive.delete met {"name"}, of rollback met {"archive": "naam", "confirm": "naam"}

Het antwoord van een actie is het antwoord van de backup server, met dezelfde statuscode.

Protocol

De backup server praat met BlueGit met de key als bearer-token (Authorization: Bearer bgbk_…):

GET /api/v1/backup/infoinstance_id, base_url, naam en adres van de server bij deze key
POST /api/v1/backup/connect{"server_url", "server_id"}: waar BlueGit meldingen heen stuurt
GET /api/v1/backup/manifestalle bestanden: pad, grootte, mtime, mode; de database ook met sha256
GET /api/v1/backup/file?path=…één bestand
POST /api/v1/backup/restoretar.gz met logische paden; BlueGit pakt uit en herstart (202)

Vijf mislukte key-pogingen per minuut per IP geven daarna 429.

BlueGit praat met de backup server met een HMAC-handtekening. Het geheim is sha256("bluegit-backup-sign:" + key) als hex; beide kanten leiden het af uit de key. Koppen:

X-BlueGit-Instance:  <instance_id>
X-BlueGit-Timestamp: <unix-seconden>      (hoogstens 5 minuten verschil)
X-BlueGit-Signature: hex(HMAC-SHA256(geheim, METHOD "\n" PAD "\n" TS "\n" sha256hex(body)))
POST /api/v1/notifyer is iets veranderd
GET /api/v1/archives{"archives": [{name, created_at, size}]}
GET /api/v1/statusinterval, bewaartermijn, stand van de laatste rollback
POST /api/v1/rollback{"archive": "naam"}
* /api/v1/admin/…de beheeracties van de backup server (lijst: GET /api/v1/admin/actions, veld bluegit: true)

Meldingen. Elke gekoppelde backup server krijgt ze, ondertekend met zijn eigen key. Na elk schrijvend HTTP-verzoek (behalve de backup-API zelf en git-upload-pack), na elke push (ook SSH) en bij elke CI-gebeurtenis meldt BlueGit een wijziging. Meldingen worden 2 seconden gebundeld en bij een fout tot vier keer opnieuw geprobeerd. De backup server haalt daarnaast periodiek alles op, dus een gemiste melding kost alleen vertraging. Het adres van de backup server mag een privéadres zijn (de beheerder koppelt hem met een eigen key); de SSRF-regels van webhooks gelden hier niet.

Compatibiliteit (protocolversie)

Elke kant heeft een protocolversie (wat hij spreekt) en een minimumversie (de oudste versie van de andere kant die hij nog ondersteunt). Nu is dat aan beide kanten protocol 1, minimum 1.

  • BlueGit stuurt X-BlueGit-Protocol, X-BlueGit-Min-Protocol en X-BlueGit-Version mee op elk verzoek aan de backup server (meldingen, status, beheeracties, rollback) en op elk antwoord van de backup-API; GET /api/v1/backup/info geeft ook protocol, min_protocol, version en compat.
  • De backup server stuurt X-Backup-Protocol, X-Backup-Min-Protocol en X-Backup-Version mee op elk verzoek aan BlueGit en op elk antwoord.
  • Ontbreken de koppen, dan is het protocol 1 (BlueGit vóór deze versie en bluegit-backup v0.1.0).
  • Ze passen als de backup server minstens het minimum van BlueGit spreekt en BlueGit minstens het minimum van de backup server. Anders is het backup_too_old (update de backup server) of bluegit_too_old (update BlueGit).

Wat er gebeurt als ze niet passen:

  • BlueGit onthoudt per backup server het laatst gemelde protocol in backup.json en toont beheerders bovenaan elke pagina een banner met de naam van de backup server, wie er geüpdatet moet worden en een link naar Beheer → Backup. Andere gebruikers zien niets. De lijst en de pagina van de server tonen het ook, en de API (GET /api/v1/admin/backup) geeft per server compat en protocol.
  • BlueGit weigert manifest, file en restore met 426 Upgrade Required ({"error", "compat", "protocol", "min_protocol"}); info en connect blijven werken, zodat beide kanten het kunnen melden.
  • De backup server vraagt vóór elke sync, rollback of restore info op en weigert zelf als het niet past; zijn webinterface toont een banner en GET /api/v1/admin/status geeft compat en compat_message.
  • Na een update van de verouderde kant herstelt alles vanzelf bij het volgende contact.

Een test-build met een ander protocol: go build -ldflags "-X gitlab.com/Timfa/bluegit/internal/backup.protocolVersion=99 -X gitlab.com/Timfa/bluegit/internal/backup.minBackupProtocol=99" ./cmd/bluegit (de integratietests in internal/backupserver/integration doen dat zelf in hun TestMain).

Wat er in een backup zit

state/bluegit.db      consistente kopie (VACUUM INTO), niet het live bestand
state/secret.key      nodig voor de versleutelde geheimen in de database
state/ssh/…           SSH-hostkey
state/logos/…, state/avatars/…
data/repos/…          bare repositories
data/releases/…       release-assets (zonder .incoming)
data/artifacts/…      CI-artifacts

Niet mee: config.yml, storage_path, cache.json, backup.json en instance_id (horen bij deze installatie), data/work, *.lock en symlinks. Elke backup server krijgt bij GET /api/v1/backup/manifest een eigen databasekopie (<state>/.backup/snapshot-<id>.db); kopieën worden één voor één gemaakt, zodat twee servers die tegelijk synchroniseren elkaars kopie niet vervangen. Verwijderen van een server ruimt zijn kopie op. De koppelingen staan in <state>/backup.json (0600, per server alleen de hash van de key) en niet in de database, zodat een rollback naar een oud archief de koppeling niet terugdraait.

Terugzetten

POST /api/v1/backup/restore pakt het archief uit in <state>/.restore en <datadisk>/.restore; de live gegevens blijven tot dan onaangeroerd. Een ongeldig archief (pad buiten de lijst hierboven, .., symlink, geen database of secret.key) wordt geweigerd en opgeruimd. Daarna weigert BlueGit schrijvende verzoeken (503), sluit af zoals bij een gewone stop en start zichzelf opnieuw met exec (zelfde PID, dus systemd ziet geen crash). Bij de start, vóór de database opengaat, worden de mappen omgewisseld: alles uit de lijst hierboven wordt vervangen, ook wat niet in het archief zat. Een BlueGit zonder datadisk kan geen archief met repositories aannemen; kies eerst de datadisk in /setup.

Source
1# Backup servers (bluegit-backup)
2
3Een losse backup server (`bluegit-backup`, in deze repository: `cmd/bluegit-backup`, zie [BACKUP-SERVER.md](BACKUP-SERVER.md)) houdt een kopie bij van alle gegevens en configuratie van één BlueGit. Hij haalt ze langzaam op, krijgt na elke wijziging een melding, maakt periodiek een gecomprimeerd archief, en kan BlueGit naar zo'n archief terugzetten.
4
5Eén BlueGit kan meerdere backup servers hebben (hoogstens 16), elk met een eigen Backupserver-Key. Een backup server hoort bij één BlueGit.
6
7## In BlueGit
8
9**Beheer > Backup** (`/admin/backup`, alleen installatiebeheerders) toont de lijst met backup servers: naam, gekoppeld of wachtend op de key, adres en laatste contact. **Backup server toevoegen** maakt een nieuwe server met een eigen key, die één keer wordt getoond.
10
11Per backup server (`/admin/backup/s/<id>`) staat dezelfde bediening als in de webinterface van de backup server zelf:
12
13- **Status**: laatste sync en het resultaat ervan, aantal syncs en meldingen, grootte van de kopie, archieven, de laatste rollback en de versie. Met de knoppen *Nu synchroniseren*, *Nu archiveren* en *Nu opruimen*.
14- **Instellingen** van de backup server: archiefinterval, bewaartermijn, minimale vrije ruimte, downloadsnelheid, syncintervallen, publiek adres en luisteradres. BlueGit krijgt de velden van de backup server en toont ze zoals ze daar staan.
15- **Backup-archieven** met *Verwijderen* en *Rollback*. Een rollback staat achter een grote rode waarschuwing, een vinkje ("ik begrijp dat dit niet terug te draaien is"), het intypen van de archiefnaam en een bevestigingsdialoog.
16- **Backupserver-Key** vervangen (de oude key werkt meteen niet meer; de server moet opnieuw koppelen), de server hernoemen, of key intrekken en de server verwijderen. Bij verwijderen vraagt BlueGit de backup server eerst om te ontkoppelen. De archieven blijven op de backup server staan.
17
18BlueGit kent de acties niet vooraf. Het vraagt ze op bij de backup server (`GET /api/v1/admin/actions`) en stuurt ze ondertekend door. Alles wat de backup server voor BlueGit openzet, kan dus ook hier. Koppelen en een archief downloaden kan alleen op de backup server zelf.
19
20Dezelfde acties via de API (token van een beheerder, scope `api`/`admin`):
21
22| | |
23|---|---|
24| `GET /api/v1/admin/backup` | `instance_id` en de lijst met backup servers |
25| `POST /api/v1/admin/backup/servers` | `{"name"}`: nieuwe backup server; het antwoord bevat eenmalig `key` |
26| `GET /api/v1/admin/backup/servers/{id}` | server met `remote` (status), `archives` en `config`, zoals de backup server ze meldt |
27| `PUT /api/v1/admin/backup/servers/{id}` | `{"name"}`: hernoemen |
28| `POST /api/v1/admin/backup/servers/{id}/key` | nieuwe key (eenmalig in het antwoord) |
29| `DELETE /api/v1/admin/backup/servers/{id}` | ontkoppelen en vergeten |
30| `POST /api/v1/admin/backup/servers/{id}/actions/{name}` | actie van de backup server, bijvoorbeeld `config.update` met `{"retention_days": "14"}`, `sync`, `archive`, `prune`, `archive.delete` met `{"name"}`, of `rollback` met `{"archive": "naam", "confirm": "naam"}` |
31
32Het antwoord van een actie is het antwoord van de backup server, met dezelfde statuscode.
33
34## Protocol
35
36**De backup server praat met BlueGit** met de key als bearer-token (`Authorization: Bearer bgbk_…`):
37
38| | |
39|---|---|
40| `GET /api/v1/backup/info` | `instance_id`, `base_url`, naam en adres van de server bij deze key |
41| `POST /api/v1/backup/connect` | `{"server_url", "server_id"}`: waar BlueGit meldingen heen stuurt |
42| `GET /api/v1/backup/manifest` | alle bestanden: pad, grootte, mtime, mode; de database ook met sha256 |
43| `GET /api/v1/backup/file?path=…` | één bestand |
44| `POST /api/v1/backup/restore` | tar.gz met logische paden; BlueGit pakt uit en herstart (202) |
45
46Vijf mislukte key-pogingen per minuut per IP geven daarna `429`.
47
48**BlueGit praat met de backup server** met een HMAC-handtekening. Het geheim is `sha256("bluegit-backup-sign:" + key)` als hex; beide kanten leiden het af uit de key. Koppen:
49
50```text
51X-BlueGit-Instance: <instance_id>
52X-BlueGit-Timestamp: <unix-seconden> (hoogstens 5 minuten verschil)
53X-BlueGit-Signature: hex(HMAC-SHA256(geheim, METHOD "\n" PAD "\n" TS "\n" sha256hex(body)))
54```
55
56| | |
57|---|---|
58| `POST /api/v1/notify` | er is iets veranderd |
59| `GET /api/v1/archives` | `{"archives": [{name, created_at, size}]}` |
60| `GET /api/v1/status` | interval, bewaartermijn, stand van de laatste rollback |
61| `POST /api/v1/rollback` | `{"archive": "naam"}` |
62| `* /api/v1/admin/…` | de beheeracties van de backup server (lijst: `GET /api/v1/admin/actions`, veld `bluegit: true`) |
63
64**Meldingen.** Elke gekoppelde backup server krijgt ze, ondertekend met zijn eigen key. Na elk schrijvend HTTP-verzoek (behalve de backup-API zelf en `git-upload-pack`), na elke push (ook SSH) en bij elke CI-gebeurtenis meldt BlueGit een wijziging. Meldingen worden 2 seconden gebundeld en bij een fout tot vier keer opnieuw geprobeerd. De backup server haalt daarnaast periodiek alles op, dus een gemiste melding kost alleen vertraging. Het adres van de backup server mag een privéadres zijn (de beheerder koppelt hem met een eigen key); de SSRF-regels van webhooks gelden hier niet.
65
66### Compatibiliteit (protocolversie)
67
68Elke kant heeft een **protocolversie** (wat hij spreekt) en een **minimumversie** (de oudste versie van de andere kant die hij nog ondersteunt). Nu is dat aan beide kanten protocol 1, minimum 1.
69
70- BlueGit stuurt `X-BlueGit-Protocol`, `X-BlueGit-Min-Protocol` en `X-BlueGit-Version` mee op elk verzoek aan de backup server (meldingen, status, beheeracties, rollback) en op elk antwoord van de backup-API; `GET /api/v1/backup/info` geeft ook `protocol`, `min_protocol`, `version` en `compat`.
71- De backup server stuurt `X-Backup-Protocol`, `X-Backup-Min-Protocol` en `X-Backup-Version` mee op elk verzoek aan BlueGit en op elk antwoord.
72- Ontbreken de koppen, dan is het protocol 1 (BlueGit vóór deze versie en bluegit-backup v0.1.0).
73- Ze passen als de backup server minstens het minimum van BlueGit spreekt en BlueGit minstens het minimum van de backup server. Anders is het `backup_too_old` (update de backup server) of `bluegit_too_old` (update BlueGit).
74
75Wat er gebeurt als ze niet passen:
76
77- BlueGit onthoudt per backup server het laatst gemelde protocol in `backup.json` en toont **beheerders bovenaan elke pagina een banner** met de naam van de backup server, wie er geüpdatet moet worden en een link naar Beheer → Backup. Andere gebruikers zien niets. De lijst en de pagina van de server tonen het ook, en de API (`GET /api/v1/admin/backup`) geeft per server `compat` en `protocol`.
78- BlueGit weigert `manifest`, `file` en `restore` met `426 Upgrade Required` (`{"error", "compat", "protocol", "min_protocol"}`); `info` en `connect` blijven werken, zodat beide kanten het kunnen melden.
79- De backup server vraagt vóór elke sync, rollback of restore `info` op en weigert zelf als het niet past; zijn webinterface toont een banner en `GET /api/v1/admin/status` geeft `compat` en `compat_message`.
80- Na een update van de verouderde kant herstelt alles vanzelf bij het volgende contact.
81
82Een test-build met een ander protocol: `go build -ldflags "-X gitlab.com/Timfa/bluegit/internal/backup.protocolVersion=99 -X gitlab.com/Timfa/bluegit/internal/backup.minBackupProtocol=99" ./cmd/bluegit` (de integratietests in `internal/backupserver/integration` doen dat zelf in hun `TestMain`).
83
84## Wat er in een backup zit
85
86```text
87state/bluegit.db consistente kopie (VACUUM INTO), niet het live bestand
88state/secret.key nodig voor de versleutelde geheimen in de database
89state/ssh/… SSH-hostkey
90state/logos/…, state/avatars/…
91data/repos/… bare repositories
92data/releases/… release-assets (zonder .incoming)
93data/artifacts/… CI-artifacts
94```
95
96Niet mee: `config.yml`, `storage_path`, `cache.json`, `backup.json` en `instance_id` (horen bij deze installatie), `data/work`, `*.lock` en symlinks. Elke backup server krijgt bij `GET /api/v1/backup/manifest` een eigen databasekopie (`<state>/.backup/snapshot-<id>.db`); kopieën worden één voor één gemaakt, zodat twee servers die tegelijk synchroniseren elkaars kopie niet vervangen. Verwijderen van een server ruimt zijn kopie op. De koppelingen staan in `<state>/backup.json` (0600, per server alleen de hash van de key) en niet in de database, zodat een rollback naar een oud archief de koppeling niet terugdraait.
97
98## Terugzetten
99
100`POST /api/v1/backup/restore` pakt het archief uit in `<state>/.restore` en `<datadisk>/.restore`; de live gegevens blijven tot dan onaangeroerd. Een ongeldig archief (pad buiten de lijst hierboven, `..`, symlink, geen database of `secret.key`) wordt geweigerd en opgeruimd. Daarna weigert BlueGit schrijvende verzoeken (503), sluit af zoals bij een gewone stop en start zichzelf opnieuw met `exec` (zelfde PID, dus systemd ziet geen crash). Bij de start, vóór de database opengaat, worden de mappen omgewisseld: alles uit de lijst hierboven wordt vervangen, ook wat niet in het archief zat. Een BlueGit zonder datadisk kan geen archief met repositories aannemen; kies eerst de datadisk in `/setup`.