Copi wrth gefn, adfer i adeg benodol a phrawf adfer

Mae’r dyluniad yn adran 8 o docs/architecture/23-ops.md. Dyma’r llawlyfr ar gyfer cynnyrch Docker Compose. Fe’i hysgrifennwyd i gael ei ddilyn gan rywun na wnaeth ei ysgrifennu; os nad yw cam yn glir, mae hynny’n ddiffyg yn y ddogfen hon.

Beth sy’n cael ei ddiogelu, a sut

Nodau: pwynt adfer o fewn 60 eiliad i’r methiant, ac adferiad o fewn 60 munud ar gyfer cronfa ddata 500 GB.

Mae dau gamgymeriad yn gyffredin. Mae cronfa ddata a adferir heb ei ffeiliau yn dangos tudalennau toredig. Ni all cronfa ddata a adferir heb QUIRE_MASTER_KEY ddadgryptio’r manylion mewngofnodi SSO, webhook ac integreiddio sydd ynddi; hyd nes bydd newid yr allwedd feistr wedi’i gwblhau heb ddim heb ei ddatrys (key-rotation.md), mae hynny’n cynnwys yr allweddi sydd wedi ymddeol. Mae’r ddau’n rhan o’r copi wrth gefn.

Gwneud copïau wrth gefn

Copi wrth gefn sylfaenol o’r clwstwr cyfan:

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

Mae’n cadw’r copïau wrth gefn sylfaenol diweddaraf hyd at QUIRE_BACKUP_KEEP (diofyn 5) ac yn tocio WAL nad oes ei angen ar yr un hynaf mwyach, felly ni all yr archif dyfu’n ddiderfyn. Trefnwch ef bob dydd gyda cron neu amserydd systemd ar y host:

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

Neu gadewch i’r stack ei drefnu: mae proffil backup yn rhedeg backup-scheduler, sy’n gwneud copi wrth gefn sylfaenol bob QUIRE_BACKUP_INTERVAL_HOURS (diofyn 24), a backup-offsite, a ddisgrifir nesaf.

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

Copïau wedi’u hamgryptio oddi ar y host

Mae’r ddwy gyfrol ar yr un host â’r gronfa ddata, ac nid copi wrth gefn yw un ar y peiriant a fethodd. Mae backup-offsite yn copïo pob copi wrth gefn sylfaenol a phob segment WAL sydd wedi’i archifo i storfa ar wahân drwy’r porth storio, yn eu hamgryptio, a’u cadw yno yn ôl cyfnod cadw:

• Amgryptio. AES-256-GCM gydag QUIRE_BACKUP_ENCRYPTION_KEY (neu’r ffeil a enwir gan QUIRE_BACKUP_ENCRYPTION_KEY_FILE): 32 beit, wedi’i chynhyrchu drwy openssl rand -hex 32. Mae gan bob ffeil ei nonce ei hun a thag dilysu, felly ni ellir darllen copi heb yr allwedd a chaiff unrhyw newid iddo ei ganfod. Cadwch yr allwedd gydag QUIRE_MASTER_KEY, oddi wrth y host hwn ac oddi wrth y storfa copi wrth gefn. Heb yr allwedd ni ellir adfer.
• Ble. Mae QUIRE_BACKUP_STORAGE_DRIVER yn s3, azure neu local (disg bell wedi’i mowntio yn QUIRE_BACKUP_STORAGE_ROOT). Gosodiadau storio ffeil yw’r rhain gyda rhagddodiad QUIRE_BACKUP_: QUIRE_BACKUP_S3_ENDPOINT, QUIRE_BACKUP_S3_BUCKET, QUIRE_BACKUP_S3_ACCESS_KEY_ID, ac ati. Defnyddiwch fwced gwahanol ac, yn ddelfrydol, gyfrif gwahanol i’r ffeiliau, gyda manylion mewngofnodi sy’n gallu ysgrifennu ond nid dileu os yw’r darparwr yn caniatáu hynny.
• Cadw. Copïau wrth gefn sylfaenol diweddaraf QUIRE_BACKUP_OFFSITE_KEEP (diofyn QUIRE_BACKUP_KEEP, fel arall 7) a’r WAL sydd ei angen ar yr hynaf ohonynt; caiff hen setiau a segmentau eu dileu o’r storfa.
• Pryd. Bob QUIRE_BACKUP_SHIP_INTERVAL_SECONDS (diofyn 300). Mae cludo yn idempotent: hepgorir yr hyn sydd eisoes wedi’i storio, a dim ond ar ôl ysgrifennu ei faniffest, yn olaf, y cyfrifir copi wrth gefn sylfaenol fel un wedi’i storio.

Mae’r un gorchymyn yn rhedeg â llaw:

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

I adfer ar host newydd, dewch â set yn ôl yn gyntaf, yna dilynwch y camau isod gyda’r cyfeiriadur a gafwyd yn lle cyfrol pgbackup a’r wal-archive a gafwyd yn lle pgwal:

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

Adfer i adeg benodol

Defnyddiwch hwn ar ôl colli data: mewnforio gwael, cwrs wedi’i ddileu, mudo contractio y mae angen ei ddadwneud. Mae’n disodli’r gronfa ddata fyw, felly ymarferwch ag ef drwy’r prawf isod yn gyntaf.

1. Dewiswch yr amser targed, yn UTC, ychydig cyn y difrod: 2026-09-24 09:30:00+00. Mae’r cofnod archwilio (/admin/audit) fel arfer yn dangos y foment.
2. Stopiwch bopeth sy’n ysgrifennu: docker compose -f docker/compose.yaml stop web content worker scheduler collab
3. Cadwch y clwstwr sydd wedi’i ddifrodi nes bod yr adferiad wedi’i ddilysu:

   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. Dadbecynnu’r copi wrth gefn sylfaenol diweddaraf sy’n hŷn na’r targed i’r gyfrol ddata, a gofyn am adfer wedi’i dargedu:

   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. Adfer: cychwynnwch Postgres unwaith gyda gosodiadau adfer, drwy wrthwneud Compose fel na newidir y ffeil arferol:

   # 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]

   Mae’r gwrthwneud yn disodli’r gorchymyn cyfan, felly mae’n ailadrodd y ddau osodiad y mae adfer yn dibynnu arnynt: max_connections heb fod yn is na’r prif un (fel arall daw adfer i ben â “insufficient parameter settings”) a’r pg_hba.conf a fowntiwyd.

   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. Gwiriwch ef cyn gadael neb i mewn: y gadwyn archwilio (docker compose -f docker/compose.yaml run --rm worker bun tooling/audit-verify/run.ts), a bod y data coll wedi dychwelyd.
7. Dychwelwch i’r arfer: docker compose -f docker/compose.yaml up -d. Mae hyn yn ailgychwyn Postgres gydag archifo ymlaen, a bydd llinell amser WAL newydd yn dechrau. Gwnewch gopi wrth gefn sylfaenol newydd yn syth.

Mae enw’r prosiect quire yn rhagddodi pob cyfrol; mae docker volume ls yn dangos yr union enwau.

Y prawf dilysu wedi’i drefnu

Mae backup-offsite hefyd yn rhedeg prawf bob QUIRE_BACKUP_DRILL_INTERVAL_HOURS (diofyn 168, wythnosol), ac eto ar y rhediad nesaf ar ôl methiant. Mae’n nôl y copi wrth gefn sylfaenol diweddaraf oddi ar y host a phob segment WAL wedyn, yn dadgryptio pob un (sy’n profi bod yr allwedd yn dal i’w hagor ac na newidiwyd dim), yn cymharu pob ffeil â’i maniffest, yn gwirio bod yr archif yn gyfeiriadur data Postgres, ac yn sicrhau nad oes bwlch yn y WAL o’r copi wrth gefn ymlaen. Ysgrifennir yr adroddiad yn y storfa fel reports/drill-<time>.json ac yng nghofnod y gwasanaeth; mae prawf a fethodd yn enwi’r ffeil neu’r segment coll cyntaf.

Y prawf adfer

Nid copi wrth gefn yw un nas adferwyd erioed. Mae’r prawf yn adfer y copi wrth gefn sylfaenol cyflawn diweddaraf a wnaed cyn y targed, ynghyd â’r archif WAL, i Postgres dros dro nad yw’n rhannu dim â’r un byw, ac yn profi’r canlyniad:

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

Mae’r targed yn UTC yn union yn y ffurf honno. Mae angen copi wrth gefn sylfaenol sy’n hŷn nag ef ac WAL wedi’i archifo ar ei ôl: mewn gosodiad newydd, gwnewch gopi wrth gefn sylfaenol ac arhoswch am y segment archif nesaf (uchafswm munud gyda rhywfaint o ysgrifennu) cyn dewis targed ar ôl y copi wrth gefn. Mae angen Docker a bash ar y host ar y prawf, dim byd arall.

Mae pob cam yn methu’r prawf:

1. Posibilrwydd adfer: mae’r clwstwr dros dro’n ailchwarae hyd at y targed ac yn agor.
2. Cyflawnrwydd: cyfrif rhesi pob tabl yn erbyn y gronfa fyw (tooling/restore-drill). Mae’r gronfa fyw wedi symud ymlaen ers y targed, felly gall tabl amrywio gan y mwyaf o 500 rhes neu ddegfed o’i faint, i’r ddau gyfeiriad (mae ysgrifennu’n peri ei fod ar ei hôl hi, mae dileu’n peri bod mwy yn yr adferiad); nid yw rhaniad a grëwyd ar ôl y targed yn dabl coll. Ehangwch y lwfans ar osodiad prysurach gyda QUIRE_DRILL_MAX_BEHIND a QUIRE_DRILL_MAX_DRIFT_RATIO. Mae tabl coll neu wag yn achosi methiant.
3. Uniondeb: dilysir cadwyn hash yr archwiliad ar y copi a adferwyd.
4. Defnyddioldeb: mae rôl y rhaglen yn darllen drwy ddiogelwch ar lefel rhes.
5. Amser: o’r dechrau i’r golau gwyrdd, yn erbyn QUIRE_DRILL_RTO_SECONDS (diofyn 3600).

Nid yw byth yn ysgrifennu i’r gronfa ddata fyw na’i chyfeintiau: mae cyfrolau copi wrth gefn a WAL wedi’u mowntio’n ddarllen-yn-unig, ac mae’r clwstwr dros dro’n cael ei dynnu ar y diwedd, boed yn llwyddo neu’n methu.

Gosodwch QUIRE_DRILL_REPORT i lwybr i ysgrifennu adroddiad JSON, p’un a yw’n pasio neu’n methu, a’i redeg ar amserlen o’r host Docker:

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

Rhedwch ef bob mis a chyn pob uwchraddiad. Mae prawf a fethodd yn rhwystro’r uwchraddiad. Unwaith bob chwarter, gofynnwch i rywun na ysgrifennodd y llawlyfr hwn wneud adferiad pwynt-amser go iawn ar host sbâr, gan ddefnyddio’r ddogfen hon yn unig.

Ffeiliau

Mae ffeiliau lleol yn byw yn y gyfrol files. Gwnewch gopi wrth gefn ohoni gyda’r gronfa ddata, ar yr un pryd, ac adferwch y ddau gyda’i gilydd:

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 .

Gyda storfa wrthrychau, trowch fersiynu bwced ymlaen a chadwch 35 diwrnod o fersiynau nad ydynt yn gyfredol; adferiad pwynt-amser ar gyfer ffeiliau yw’r bwced ei hun wedyn.