Камдык көчүрмө, учурга чейинки калыбына келтирүү жана калыбына келтирүү машыгуусу

Дизайн docs/architecture/23-ops.md 8-бөлүмүндө. Бул Docker Compose продукты үчүн иш китепчеси. Аны жазбаган адам аткарышы үчүн жазылган; кадам түшүнүксүз болсо, бул документтин кемчилиги.

Эмне корголот жана кантип

Максаттар: ийгиликсиздиктен кийинки 60 секунддун ичиндеги калыбына келтирүү чекити, жана 500 ГБ маалымат базасы үчүн 60 мүнөттүн ичинде калыбына келтирүү.

Эки ката кеңири таралган. Файлдарысыз калыбына келтирилген маалымат базасы бузук беттерди көрсөтөт. QUIRE_MASTER_KEY’сиз калыбына келтирилген маалымат базасы камтый турган SSO, вебхук жана интеграция купуялык маалыматтарын шифрлөөдөн чыгара албайт; негизги килит алмаштыруусу чечилбеген эч нерсе калбай бүткөнгө чейин (key-rotation.md), ага кетирилген килттер да кирет. Экөө тең камдык көчүрмөнүн бир бөлүгү.

Камдык көчүрмө алуу

Бүткүл кластердин негизги камдык көчүрмөсү:

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

Ал эң жаңы QUIRE_BACKUP_KEEP негизги камдык көчүрмөсүн (демилгелик 5) сактап, эң эскисине кереги жок WAL’ды тазалайт, ошондуктан архив чексиз өсө албайт. Аны хосттогу cron же systemd таймери менен күнүнө жайыңыз:

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

Же топтомго өзү жайы берсин: backup профили backup-scheduler’ди иштетет, ал ар QUIRE_BACKUP_INTERVAL_HOURS сайын (демилгелик 24) негизги камдык көчүрмө алат, жана төмөндө сүрөттөлгөн backup-offsite.

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

Шифрленген хосттон тышкары көчүрмөлөр

Эки том тең маалымат базасы менен бир хостто турат, жана ийгиликсиз болгон машинадагы камдык көчүрмө — камдык көчүрмө эмес. backup-offsite ар бир негизги камдык көчүрмөнү жана ар бир архивленген WAL бөлүгүн сактоо порту аркылуу айырма кампага, шифрлөө менен көчүрөт жана аларды ал жерде сактоо мөөнөтү менен кармайт:

• Шифрлөө. QUIRE_BACKUP_ENCRYPTION_KEY (же QUIRE_BACKUP_ENCRYPTION_KEY_FILE атаган файл) менен AES-256-GCM: 32 байт, openssl rand -hex 32 аркылуу. Ар бир файлдын өз nonce’у жана текшерүү белгиси бар, ошондуктан килитсиз көчүрмө окулбайт жана андагы каалаган өзгөрүү аныкталат. Килитти QUIRE_MASTER_KEY менен бирге, бул хосттон жана камдык көчүрмө кампасынан алыс кармаңыз. Килитсиз калыбына келтирүү жок.
• Кайда. QUIRE_BACKUP_STORAGE_DRIVER — s3, azure же local (QUIRE_BACKUP_STORAGE_ROOT жеринде туташтырылган алыскы диск). Жөндөөлөр файл сактоонукулары менен бирдей, QUIRE_BACKUP_ префикси менен: QUIRE_BACKUP_S3_ENDPOINT, QUIRE_BACKUP_S3_BUCKET, QUIRE_BACKUP_S3_ACCESS_KEY_ID ж.б. Файлдардан айрыма bucket жана, мүмкүн болсо, айрыма эсеп колдонуңуз, провайдер уруксат кылса өчүрө албай, жаза алган купуялыктар менен.
• Сактоо мөөнөтү. Эң жаңы QUIRE_BACKUP_OFFSITE_KEEP негизги камдык көчүрмөсү (демилгелик QUIRE_BACKUP_KEEP, болбосо 7) жана алардын эң эскисине керектүү WAL; эски топтомдор жана бөлүктөр кампадан өчүрүлөт.
• Качан. Ар QUIRE_BACKUP_SHIP_INTERVAL_SECONDS (демилгелик 300). Жеткирүү бирдейликке ээ: мурунтан сакталганы өткөрүлөт, жана негизги камдык көчүрмө манифести акыркысы болуп жазылганча гана сакталган деп эсептенет.

Ошол эле буйрук кол менен иштетилет:

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

Жаңы хостто калыбына келтирүү үчүн, алгач топтомду алып келиңиз, андан кийин төмөндөгү кадамдарды аткарыңыз, pgbackup томнүн ордуна жүктөлгөн папканы жана wal-archive’ты pgwal ордуна колдонуп:

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

Белгилүү учурга калыбына келтирүү

Буну маалымат жоготкодон кийин колдонуңуз: бузулган импорт, өчүрүлгөн курс, кайтарыш керек болгон кыскартуу миграциясы. Ал азыркы маалымат базасын алмаштырат, ошондуктан аны алгач төмөндөгү машыгуу менен машыктырыңыз.

1. Максат убакытты тандаңыз, UTC’де, зыяндан бир аз мурда: 2026-09-24 09:30:00+00. Аудит журналы (/admin/audit) адатта ошол учурду көрсөтөт.
2. Бардык жазууну токтотуңуз: docker compose -f docker/compose.yaml stop web content worker scheduler collab
3. Бузулган кластерди калыбына келтирүү текшерилгиче кармаңыз:

   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. Максаттан мурунку эң жаңы негизги камдык көчүрмөнү маалымат томунун ичине чыгарып, багыттуу калыбына келтирүүнү сураңыз:

   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. Калыбына келтирүү: Postgres’ти калыбына келтирүү жөндөөлөрү менен бир жолу иштетиңиз, адаттагы файлга тийбегидей кылып Compose override аркылуу:

   # 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 бардык буйрукту алмаштырат, ошондуктан ал калыбына келтирүүгө керек болгон эки жөндөөнү кайталайт: max_connections негизги базадан төмөн болбосу (болбосо калыбына келтирүү “insufficient parameter settings” себебинен токтойт) жана туташтырылган pg_hba.conf.

   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. Аны текшериңиз, эч кимди киргизүүдөн мурун: аудит чынжырын (docker compose -f docker/compose.yaml run --rm worker bun tooling/audit-verify/run.ts), жана жоголгон маалымат кайта келгенин.
7. Адаттагы абалга кайтыңыз: docker compose -f docker/compose.yaml up -d. Бул Postgres’ти архивлөө менен кайра иштетет жана жаңы WAL убакыт чынжыры башталат. Дароо жаңы негизги камдык көчүрмө алыңыз.

Проект аты quire ар бир томдун алдына кошулат; так аттарды docker volume ls көрсөтөт.

Пландаштырылган текшерүү машыгуусу

backup-offsite ошондой эле ар QUIRE_BACKUP_DRILL_INTERVAL_HOURS сайын (демилгелик 168, жумасына) машыгуу иштетет, жана бири ийгиликсиз болсо кийинки өтүшүндө кайра. Ал эң жаңы хосттон тышкары негизги камдык көчүрмөнү жана андан кийинки ар бир WAL бөлүгүн жүктөп алат, ар бирин шифрлөөдөн чыгарат (бул килит дагы эле ачарын жана эч нерсе өзгөртүлбөгөнүн далилдейт), ар бир файлды анын манифести менен салыштырат, архив Postgres маалымат папкасы экенин текшерет жана камдык көчүрмөдөн бери WAL’да үзүлүш жок экенин текшерет. Отчёт кампага reports/drill-<time>.json катары жана кызматтын журналына жазылат; ийгиликсиз машыгуу файлды же биринчи жетпей турган бөлүктү атайт.

Калыбына келтирүү машыгуусу

Эч качан калыбына келтирилбеген камдык көчүрмө — камдык көчүрмө эмес. Машыгуу максатка чейин алынган эң жаңы толук негизги камдык көчүрмөнү, WAL архивин кошо, тирүү менен эч нерсе бөлүшпөй турган убактылуу Postgres’ке калыбына келтирет жана натыйжаны далилдейт:

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

Максат так ушул түрдө UTC болот. Ага андан мурунку негизги камдык көчүрмө жана андан ары архивленген WAL керек: жаңы орнотууда негизги камдык көчүрмө алып, максатты камдык көчүрмөдөн кийин тандаганга чейин кийинки архивленген бөлүктү күтүңүз (жазуу болгондо көп болгондо бир мүнөт). Машыгууга хостто Docker жана bash керек, башка эч нерсе керек эмес.

Ар бир кадам машыгууну ийгиликсиз кылат:

1. Калыбына келтирилүүчүлүк: убактылуу кластер максатка чейин кайра ойнотуп, ачылат.
2. Толуктуу: ар бир таблицанын сабынын саны тирүү маалымат базасына каршы (tooling/restore-drill). Тирүү маалымат базасы максаттан бери өнүп кеткен, ошондуктан таблица 500 саптын жана өлчөмүнүн ондон биринин чоңураагы боюнча айырмашышы мүмкүн, эки багытта да (жазуулар аны кечиктирет, өчүрүүлөр калыбына келтирүү көбүрөөк камтыйт); максаттан кийин түзүлгөн бөлүм жоголгон таблица эмес. Ортодо көбүрөк орнотууда QUIRE_DRILL_MAX_BEHIND жана QUIRE_DRILL_MAX_DRIFT_RATIO менен чени кеңиңүрөк кылыңыз. Жетпей турган же бош таблица ийгиликсиз кылат.
3. Бүтүндүк: аудит хэш чынжыры калыбына келтирилген көчүрмөдө текшерилет.
4. Жеткиликтүүлүк: колдонмо ролу сап деңгээлинде коргоо аркылуу окуйт.
5. Убакыт: баштаптан жашылга чейин, QUIRE_DRILL_RTO_SECONDS’ка каршы (демилгелик 3600).

Ал тирүү маалымат базасына же анын томдоруна эч качан жазбайт: камдык көчүрмө жана WAL томдору окуу гана режиминде туташтырылган жана убактылуу кластер аяктоодо, өтсө да өтпөсө да өчүрүлөт.

JSON отчёт жазылышы үчүн, өтсө да өтпөсө да, QUIRE_DRILL_REPORT’ти жолго коюңуз жана аны 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

Аны ай сайын жана ар бир жаңылоодон мурун иштетиңиз. Ийгиликсиз машыгуу жаңылоону тосуп калат. Ар чейректе, бул иш китепчесин жазбаган адамга, ушул документти гана колдонуп, атайын хостто чыныгы учурга чейинки калыбына келтирүүнү жасатыңыз.

Файлдар

Жергиликтүү файлдар files томндө. Аны маалымат базасы менен бирге, ал эми учурда, камдыкка көчүрүңүз жана экөөнүн да чогуу калыбына келтириңиз:

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 .

Объекттик сактоо менен bucket версиялаштыруусун күйгүзүп, 35 күндүк актуалдуу эмес версияларды кармаңыз; андан кийин файлдар үчүн учурга чейинки калыбына келтирүү — bucket’тын өзү.