Сақтық көшірме, уақыт бойынша қалпына келтіру және қалпына келтіру жаттығуы

Жоба docs/architecture/23-ops.md құжатының 8-тармағында. Бұл Docker Compose өнімінің жұмыс нұсқаулығы. Ол оны жазбаған адам орындайтын дейін жазылған; қадам түсініксіз болса, бұл құжаттың өз ақауы.

Нені қорғайды және қалай

Мақсаттар: сәтсіздіктен кейін 60 секунд ішіндегі қалпына келтіру нүктесі және 500 GB дерекқор үшін 60 минут ішіндегі қалпына келтіру.

Екі қате жиі кездеседі. Файлдарынсыз қалпына келтірілген дерекқор бұзылған беттерді көрсетеді. QUIRE_MASTER_KEYсыз қалпына келтірілген дерекқор ұстап тұрған SSO, webhook және интеграция кілттерін аша алмайды; мастер-кілт ауыстыру шешілмеген нәрсесіз аяқталғанға дейін (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 бөлігін қойма порты арқылы шифрленген түрде бөлек қоймаға көшіреді және оларды сонда сақтайды:

• Шифрлеу. AES-256-GCM QUIRE_BACKUP_ENCRYPTION_KEY кілтімен (QUIRE_BACKUP_ENCRYPTION_KEY_FILE атайтын файлдың орнына): 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 және т.б. Файлдардан бөлек шелек және мүмкін болса бөлек аккаунт пайдаланыңыз, провайдер рұқсат етсе, жаза алатын, бірақ жоя алмайтын кілттермен.
• Сақтау мерзімі. Ең жаңа 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

Уақыт бойынша қалпына келтіру

Мұны деректер жоғалғаннан кейін пайдаланыңыз: нашар импорт, жойылған курс, болдырмау керек contract миграциясы. Ол тірі дерекқорды ауыстырады, сондықтан алдымен төмендегі жаттығумен тексеріп көріңіз.

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 .

Объектілік қоймамен шелектің нұсқаларын қосып, 35 күндік емес ағымдағы нұсқаларды сақтаңыз; файлдар үшін уақыт бойынша қалпына келтіру содан кейін шелектің өзінде болады.