Sovgad, rekiperasyon nan yon moman presi ak egzèsis restorasyon

Konsepsyon an nan docs/architecture/23-ops.md, seksyon 8. Sa a se gid operasyon pou pwodwi Docker Compose la. Yo ekri li pou yon moun ki pa t ekri l kapab suiv li; si yon etap pa klè, se yon defo nan dokiman sa a.

Sa ki pwoteje ak fason sa fèt

Objektif: yon pwen rekiperasyon ki nan 60 segonn apre aksidan an, epi yon restorasyon nan 60 minit pou yon bazdone 500 GB.

De erè rive souvan. Yon bazdone retabli san fichye pa li yo montre paj kase. Yon bazdone retabli san QUIRE_MASTER_KEY pa kapab dechifre kalifikatif SSO, webhook ak entegrasyon li genyen; jiskaske w fin chanje kle prensipal san anyen ki poko rezoud (key-rotation.md), sa gen ladan ansyen kle yo tou. Toude se pati sovgad la.

Pran sovgad

Men backup baz pou tout cluster la:

docker compose -f docker/compose.yaml --profile backup run --rm backup

Li konsève pi resan QUIRE_BACKUP_KEEP backup baz yo (default 5) epi li koupe WAL pi ansyen an pa bezwen ankò, konsa achiv la pa kapab grandi san limit. Mete l chak jou avèk cron oswa yon systemd timer sou host la:

15 2 * * * cd /srv/quire && docker compose -f docker/compose.yaml --profile backup run --rm backup >> /var/log/quire-backup.log 2>&1

Oswa kite stack la pwograme sa: pwofil backup la kouri backup-scheduler, ki pran yon backup baz chak QUIRE_BACKUP_INTERVAL_HOURS (default 24), epi kouri backup-offsite ki dekri pi ba a.

docker compose -f docker/compose.yaml --profile backup up -d

Kopi chiffres deyò host la

De volume yo sou menm host ak bazdone a; sovgad sou machin ki fè aksidan an pa yon sovgad. backup-offsite kopye chak backup baz ak chak segman WAL achive nan yon depo apa atravè pò depo a, li chiffre yo epi konsève yo dapre politik retansyon:

• Chifreman. AES-256-GCM avèk QUIRE_BACKUP_ENCRYPTION_KEY (oswa fichye QUIRE_BACKUP_ENCRYPTION_KEY_FILE nonmen an): 32 byte, ki soti nan openssl rand -hex 32. Chak fichye gen pwòp nonce ak authentication tag pa li; konsa, san kle a, yon kopi pa lizib epi tout chanjman parèt. Kenbe kle a ansanm ak QUIRE_MASTER_KEY, lwen host sa a ak depo sovgad la. San kle a, pa gen restorasyon.
• Kote. QUIRE_BACKUP_STORAGE_DRIVER se s3, azure oswa local (yon disk adistans ki monte nan QUIRE_BACKUP_STORAGE_ROOT). Paramèt yo se menm jan ak depo fichye, men avèk prefiks QUIRE_BACKUP_: QUIRE_BACKUP_S3_ENDPOINT, QUIRE_BACKUP_S3_BUCKET, QUIRE_BACKUP_S3_ACCESS_KEY_ID ak lòt ankò. Sèvi ak yon lòt bucket pase sa fichye yo itilize, e pi bon toujou, yon lòt kont; si founisè a pèmèt sa, sèvi ak kalifikatif ki ka ekri men ki pa ka efase.
• Retansyon. Pi resan QUIRE_BACKUP_OFFSITE_KEEP backup baz yo (default QUIRE_BACKUP_KEEP, sinon 7) ak WAL pi ansyen nan yo bezwen; yo efase ansyen seri ak segman nan depo a.
• Kilè. Chak QUIRE_BACKUP_SHIP_INTERVAL_SECONDS segonn (default 300). Voye a idempotent: li sote sa ki deja anrejistre, epi li konte yon backup baz kòm estoke sèlman apre li ekri manifest la, nan dènye etap la.

Menm kòmand lan mache alamen:

docker compose -f docker/compose.yaml run --rm backup-offsite bun apps/worker/src/backups/main.ts ship
docker compose -f docker/compose.yaml run --rm backup-offsite bun apps/worker/src/backups/main.ts verify

Pou retabli sou yon nouvo host, remete yon seri an premye, epi suiv etap ki pi ba yo avèk dosye ou telechaje a nan plas volume pgbackup la epi wal-archive telechaje a nan plas pgwal la:

bun apps/worker/src/backups/main.ts fetch base-20260924T021500Z /srv/restore

Retabli nan yon moman presi

Sèvi ak sa apre pèt done: yon move enpòtasyon, yon kou efase, oswa yon migration kontra ou bezwen defèt. Li ranplase bazdone an dirèk la; pratike ak egzèsis ki pi ba a anvan.

1. Chwazi lè sib la, an UTC, jis anvan domaj la: 2026-09-24 09:30:00+00. Jounal odit la (/admin/audit) anjeneral montre moman an.
2. Kanpe tout sa ki ekri: docker compose -f docker/compose.yaml stop web content worker scheduler collab
3. Kenbe cluster ki andomaje a jiskaske yo verifye restorasyon an:

   docker compose -f docker/compose.yaml stop postgres
   docker run --rm -v quire_postgres18-data:/from -v quire_postgres-damaged:/to alpine cp -a /from/. /to/

4. Dekonprese pi resan backup baz ki pi ansyen pase lè sib la nan volume done a, epi mande rekiperasyon pou moman presi a:

   docker run --rm -v quire_pgbackup:/backups:ro -v quire_postgres18-data:/var/lib/postgresql postgres:18-alpine sh -euc '
     base="$(ls -1d /backups/base-* | sort | tail -n 1)"   # or the one before the target
     rm -rf /var/lib/postgresql/18/docker && mkdir -p /var/lib/postgresql/18/docker
     tar -xzf "$base/base.tar.gz" -C /var/lib/postgresql/18/docker
     touch /var/lib/postgresql/18/docker/recovery.signal
     chown -R postgres:postgres /var/lib/postgresql/18/docker && chmod 700 /var/lib/postgresql/18/docker'

5. Rekipere: kòmanse Postgres yon sèl fwa avèk paramèt rekiperasyon yo, nan yon override Compose pou fichye nòmal la pa chanje:

   # docker/compose.recover.yaml
   services:
     postgres:
       command: [postgres, -c, "restore_command=cp /var/lib/postgresql/wal-archive/%f %p",
                 -c, "recovery_target_time=2026-09-24 09:30:00+00",
                 -c, recovery_target_action=promote, -c, archive_mode=off,
                 -c, max_connections=200, -c, hba_file=/etc/postgresql/pg_hba.conf]

   Override la ranplase tout command la, kidonk li repete de paramèt rekiperasyon an depann: max_connections pa dwe pi ba pase sou prensipal la (sinon rekiperasyon an sispann ak mesaj “insufficient parameter settings”) ansanm ak fichye pg_hba.conf ki monte a.

   docker compose -f docker/compose.yaml -f docker/compose.recover.yaml up -d postgres
   docker compose -f docker/compose.yaml logs -f postgres   # wait for "database system is ready"

6. Verifye li anvan ou kite nenpòt moun antre: chèn odit la (docker compose -f docker/compose.yaml run --rm worker bun tooling/audit-verify/run.ts), epi asire done ki te pèdi yo retounen.
7. Retounen nan nòmal: docker compose -f docker/compose.yaml up -d. Sa rekòmanse Postgres ak achivaj aktive epi li lanse yon nouvo timeline WAL. Pran yon nouvo backup baz tousuit.

Non pwojè quire la mete prefiks devan chak volume; docker volume ls montre non egzak yo.

Egzèsis verifikasyon pwograme

backup-offsite lanse egzèsis tou chak QUIRE_BACKUP_DRILL_INTERVAL_HOURS (default 168, chak semèn), epi nan pwochen tès la apre yon echèk. Li pran pi resan backup baz ki deyò host la ak tout segman WAL apre li, dechifre chak (sa pwouve kle a toujou louvri fichye yo e anyen pa chanje), konpare chak fichye ak manifest li, verifye achiv la se yon repètwa done Postgres epi verifye WAL la pa gen twou apati backup la. Yo ekri rapò a nan depo a kòm reports/drill-<time>.json ak nan log sèvis la; lè yon egzèsis echwe, li bay non fichye a oswa premye segman ki manke a.

Egzèsis restorasyon

Yon sovgad yo pa janm retabli se pa yon sovgad. Egzèsis la retabli pi resan backup baz konplè ki te fèt anvan lè sib la, ansanm ak achiv WAL la, nan yon Postgres tanporè ki pa pataje anyen ak bazdone an dirèk la; apre sa, li pwouve rezilta a:

docker/scripts/restore-drill.sh                                  # to ninety minutes ago
docker/scripts/restore-drill.sh --target "2026-09-24 09:30:00+00"

Lè sib la dwe UTC nan fòm egzak sa a. Li bezwen yon backup baz ki pi ansyen ak WAL achive apre li: nan yon nouvo enstalasyon, pran backup baz epi tann pwochen segman achive a (nan plis yon minit si gen ekriti) anvan w chwazi yon sib apre backup la. Egzèsis la bezwen Docker ak bash sou host la, anyen ankò.

Chak etap kapab fè egzèsis la echwe:

1. Kapasite rekiperasyon: cluster tanporè a rejwe jiska lè sib la epi li ouvri.
2. Konplè: konpare kantite liy chak tab ak bazdone an dirèk la (tooling/restore-drill). Bazdone an dirèk la avanse depi lè sib la, kidonk kantite a ka diferan nan nenpòt sans: yo pèmèt pi gwo nan 500 liy oswa yon dizyèm gwosè tab la (ekriti fè restorasyon an an reta; efasman fè li kenbe plis liy). Yon patisyon ki kreye apre sib la pa yon tab ki pèdi. Ogmante tolerans lan sou enstalasyon ki gen plis aktivite avèk QUIRE_DRILL_MAX_BEHIND ak QUIRE_DRILL_MAX_DRIFT_RATIO. Yon tab ki manke oswa vid fè tès la echwe.
3. Entegrite: chèn hash odit la verifye nan kopi retabli a.
4. Itilite: wòl aplikasyon an li atravè sekirite nivo liy.
5. Tan: depi kòmansman jouk rezilta pozitif, dapre QUIRE_DRILL_RTO_SECONDS (default 3600).

Li pa janm ekri nan bazdone an dirèk la oswa volume li yo: yo monte volume sovgad ak WAL yo an lekti sèlman, epi yo retire cluster tanporè a nan fen, kit egzèsis la reyisi kit li echwe.

Pou ekri yon rapò JSON, mete QUIRE_DRILL_REPORT sou yon chemen; yo ekri li kit tès la reyisi kit li echwe. Pwograme li sou host Docker la:

30 3 1 * * cd /srv/quire && QUIRE_DRILL_REPORT=/var/log/quire-drill.json docker/scripts/restore-drill.sh >> /var/log/quire-drill.log 2>&1

Kouri li chak mwa ak anvan chak mizajou. Yon egzèsis ki echwe bloke mizajou a. Yon fwa chak trimès, mande yon moun ki pa t ekri gid operasyon sa a fè vrè restorasyon nan yon moman presi sou yon host rezèv, avèk dokiman sa a sèlman.

Fichye

Fichye lokal yo nan volume files la. Fè sovgad yo ansanm ak bazdone a, nan menm moman, epi retabli yo ansanm:

docker run --rm -v quire_files:/files:ro -v "$PWD":/out alpine tar -czf /out/files-$(date -u +%Y%m%d).tar.gz -C /files .

Avèk depo objè, aktive vèsyon bucket epi kenbe 35 jou vèsyon ki pa aktyèl ankò; se bucket la ki jere rekiperasyon nan yon moman presi pou fichye yo.