Cúltaca, aisghabháil go tráthphointe agus cleachtadh athchóirithe

Tá an dearadh in alt 8 de docs/architecture/23-ops.md. Seo an leabhar treoracha don táirge Docker Compose. Scríobhadh é le go leanfadh duine nár scríobh é; más doiléir céim, is locht sa doiciméad seo é sin.

Na rudaí a chosnaítear agus an chaoi

Spriocanna: pointe athshlánaithe laistigh de 60 soicind den chliseadh agus athchóiriú laistigh de 60 nóiméad do bhunachar 500 GB.

Tarlaíonn dhá bhotún go minic. Briseann leathanaigh má dhéantar bunachar sonraí a athchóiriú gan a chuid comhad. Ní féidir le bunachar sonraí a athchóirítear gan QUIRE_MASTER_KEY na dintiúir SSO, webhook agus comhtháthaithe atá ann a dhíchriptiú; go dtí go gcríochnaítear rothlú máistireochrach gan luach ar bith gan réiteach (key-rotation.md), áirítear eochracha atá éirithe as leis sin. Is cuid den chúltaca iad an dá rud.

Cúltacaí a dhéanamh

Cúltaca bunúsach den chnuasach iomlán:

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

Coinníonn sé na QUIRE_BACKUP_KEEP cúltacaí bunúsacha is nua (5 de réir réamhshocraithe) agus bearrann sé WAL nach bhfuil ag teastáil ón gceann is sine a thuilleadh, ionas nach bhfásfaidh an chartlann gan teorainn. Sceideal é go laethúil le cron nó le lasc ama systemd ar an óstach:

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

Nó lig don chruach é a sceidealú: ritheann próifíl backup backup-scheduler, a dhéanann cúltaca bunúsach gach QUIRE_BACKUP_INTERVAL_HOURS (24 de réir réamhshocraithe), agus backup-offsite, a mhínítear ina dhiaidh seo.

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

Cóipeanna criptithe lasmuigh den óstach

Tá an dá imleabhar ar an óstach céanna leis an mbunachar sonraí, agus ní cúltaca é cúltaca ar an meaisín a theip. Cóipeálann backup-offsite gach cúltaca bunúsach agus gach mír WAL cartlainne chuig stór ar leith tríd an bport stórála, criptíonn sé iad agus coinníonn sé ansin iad de réir an bheartais choinneála:

• Criptiú. AES-256-GCM le QUIRE_BACKUP_ENCRYPTION_KEY (nó leis an gcomhad ainmnithe ag QUIRE_BACKUP_ENCRYPTION_KEY_FILE): 32 beart, ginte le openssl rand -hex 32. Bíonn nonce agus clib fíordheimhnithe dá chuid féin ag gach comhad, mar sin ní féidir cóip a léamh gan an eochair agus aimsítear aon athrú uirthi. Coinnigh an eochair le QUIRE_MASTER_KEY, amach ón óstach seo agus ón stór cúltaca. Ní féidir athchóiriú a dhéanamh gan an eochair.
• Áit. Is é QUIRE_BACKUP_STORAGE_DRIVER luach s3, azure nó local (diosca cianda feistithe ag QUIRE_BACKUP_STORAGE_ROOT). Is iad socruithe stórála comhad iad seo a bhfuil réimír QUIRE_BACKUP_ orthu: QUIRE_BACKUP_S3_ENDPOINT, QUIRE_BACKUP_S3_BUCKET, QUIRE_BACKUP_S3_ACCESS_KEY_ID agus a leithéid. Úsáid buicéad eile agus, más féidir, cuntas eile seachas iad siúd atá ag na comhaid, le dintiúir ar féidir leo scríobh ach nach féidir leo scriosadh, más féidir leis an soláthraí é sin a cheadú.
• Coinneáil. Coinnítear na QUIRE_BACKUP_OFFSITE_KEEP cúltacaí bunúsacha is nua (luach QUIRE_BACKUP_KEEP de réir réamhshocraithe, nó 7 mura bhfuil sé sin socraithe) agus WAL atá de dhíth ón gceann is sine; scriostar seantacair agus seanrannóga ón stór.
• Cathain. Gach QUIRE_BACKUP_SHIP_INTERVAL_SECONDS (300 de réir réamhshocraithe). Tá seoladh saor ó dhúbailt: scipeáiltear a bhfuil stóráilte cheana, agus ní áirítear cúltaca bunúsach mar stóráilte go dtí go scríobhtar a fhorógra ar deireadh.

Ritheann an t-ordú céanna de láimh:

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

Chun athchóiriú ar óstach nua, tabhair tacar ar ais ar dtús, ansin lean na céimeanna thíos agus cuir an chomhadlann a fuarthas in ionad imleabhar pgbackup agus an wal-archive a fuarthas in ionad pgwal:

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

Athchóirigh go tráthphointe

Úsáid é seo tar éis caillteanas sonraí: drochiompórtáil, cúrsa scriosta nó aistriú craptha nach mór a chealú. Tagann sé in ionad an bhunachair bheo, mar sin cleachtaigh é leis an druileáil thíos ar dtús.

1. Roghnaigh an t-am sprice, in UTC, díreach roimh an damáiste: 2026-09-24 09:30:00+00. Is minic a léiríonn log an iniúchta (/admin/audit) an t-am.
2. Stop gach rud a scríobhann: docker compose -f docker/compose.yaml stop web content worker scheduler collab
3. Coinnigh an cnuasach millte go dtí go bhfíoraítear an t-athchóiriú:

   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. Díphacáil an cúltaca bunúsach is nua atá níos sine ná an sprioc isteach san imleabhar sonraí, agus iarr ar athshlánú spriocdhírithe:

   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. Athshlánaigh: tosaigh Postgres uair amháin leis na socruithe athshlánaithe, ó shárú Compose ionas nach n-athraítear an gnáthchomhad:

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

   Tagann an t-ordú iomlán in ionad an ghnáthordaithe, mar sin déanann sé an dá shocrú a bhfuil an t-athshlánú ag brath orthu arís: ní féidir le max_connections bheith níos lú ná luach an phríomha (nó teipeann ar an athshlánú le “insufficient parameter settings”), agus ní mór an pg_hba.conf feistithe a áireamh.

   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. Seiceáil é sula ligtear aon duine isteach: slabhra iniúchta (docker compose -f docker/compose.yaml run --rm worker bun tooling/audit-verify/run.ts) agus dearbhaigh go bhfuil na sonraí caillte ar ais.
7. Fill ar an ngnáthoibriú: docker compose -f docker/compose.yaml up -d. Atosaíonn sé seo Postgres agus cartlannú ar siúl, agus tosaíonn líne ama WAL nua. Déan cúltaca bunúsach úr láithreach.

Cuireann ainm tionscadail quire mar réimír le gach imleabhar; taispeánann docker volume ls na hainmneacha cruinne.

An cleachtadh fíoraithe sceidealaithe

Ritheann backup-offsite cleachtadh gach QUIRE_BACKUP_DRILL_INTERVAL_HOURS (168 de réir réamhshocraithe, go seachtainiúil), agus arís ar an gcéad bhabhta tar éis teipe. Faigheann sé an cúltaca bunúsach lasmuigh den óstach is nua agus gach deighleog WAL ina dhiaidh; díchriptíonn sé gach ceann (rud a chruthaíonn go n-osclaíonn an eochair iad fós agus nár athraíodh iad), cuireann sé gach comhad i gcomparáid lena fhógra, seiceálann sé gur comhadlann sonraí Postgres atá sa chartlann agus cinntíonn sé nach bhfuil bearna in WAL ón gcúltaca ar aghaidh. Scríobhtar tuarascáil chuig an stór mar reports/drill-<time>.json agus chuig log na seirbhíse; ainmníonn druileáil theipthe an comhad nó an chéad deighleog atá ar iarraidh.

An cleachtadh athchóirithe

Ní cúltaca é cúltaca nár athchóiríodh riamh. Athchóiríonn an cleachtadh an cúltaca bunúsach iomlán is nua a tógadh roimh an sprioc, chomh maith le cartlann WAL, chuig Postgres trialach nach roinneann tada leis an gceann beo, agus cruthaíonn sé go bhfuil an toradh bailí:

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

Caithfidh an sprioc a bheith in UTC san fhormáid sin go díreach. Teastaíonn cúltaca bunúsach atá níos sine ná í agus WAL cartlainne ina diaidh: ar shuiteáil nua, déan cúltaca bunúsach agus fan leis an gcéad deighleog chartlainne eile (nóiméad amháin ar a mhéad nuair a bhíonn scríbhinní ann) sula roghnaíonn tú sprioc i ndiaidh an chúltaca. Níl ag teastáil ón gcleachtadh ach Docker agus bash ar an óstach.

Teipeann ar an gcleachtadh má theipeann ar aon chéim:

1. Athshlánaitheacht: athsheinneann an cnuasach trialach go dtí an sprioc agus osclaítear é.
2. Iomláine: líon ró gach tábla i gcomparáid leis an mbunachar beo (tooling/restore-drill). Tá an bunachar beo tar éis bogadh ón sprioc, mar sin féadfaidh tábla a bheith éagsúil faoin luach is mó idir 500 ró agus an deichiú cuid dá mhéid, sa dá threo (bíonn sé chun deiridh mar gheall ar scríbhinní agus bíonn níos mó ann san athchóiriú mar gheall ar scriosadh); ní tábla caillte é deighilt a cruthaíodh tar éis na sprice. Méadaigh an lamháltas ar shuiteáil níos gnóthaí le QUIRE_DRILL_MAX_BEHIND agus QUIRE_DRILL_MAX_DRIFT_RATIO. Teipeann ar thábla atá ar iarraidh nó folamh.
3. Sláine: fíoraítear slabhra hais an iniúchta ar an gcóip athchóirithe.
4. Inúsáidteacht: léann ról an fheidhmchláir trí shlándáil ar leibhéal ró.
5. Am: am ón tús go toradh maith, de réir QUIRE_DRILL_RTO_SECONDS (3600 de réir réamhshocraithe).

Ní scríobhann sé riamh chuig an mbunachar beo ná chuig a imleabhair: feistítear imleabhair chúltaca agus WAL inléite amháin, agus baintear an cnuasach trialach ag an deireadh, bíodh toradh dearfach nó diúltach ann.

Socraigh QUIRE_DRILL_REPORT ar chonair chun tuarascáil JSON a fháil, bíodh toradh dearfach nó diúltach ann, agus sceideal ar óstach 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

Rith go míosúil é agus roimh gach uasghrádú. Cuireann cleachtadh teipthe bac ar uasghrádú. Uair amháin sa ráithe, iarr ar dhuine nár scríobh an leabhar treoracha seo athchóiriú fíor go tráthphointe a dhéanamh ar óstach spártha agus an doiciméad seo amháin á úsáid aige.

Comhaid

Tá comhaid áitiúla san imleabhar files. Déan cúltaca de in éineacht leis an mbunachar sonraí, ag an am céanna, agus athchóirigh an dá cheann le chéile:

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 .

Le stóráil oibiachtaí, cuir leaganú buicéid ar siúl agus coinnigh 35 lá de leaganacha nach bhfuil reatha; is é córas an bhuicéid féin a láimhseálann athshlánú comhad go tráthphointe ansin.