پاڵپشتی، گەڕاندنەوەی خاڵی کاتی و کاری تاقیکردنەوەی گەڕاندنەوە

دیزاینەکە لە docs/architecture/23-ops.md بەشی 8ە. ئەمە ڕێبەری کاری بەرهەمی Docker Composeە. بە شێوەیەک نووسراوە بۆ ئەوەی کەسێک کە نەینووسیوە بەدوایدا بچێت؛ ئەگەر هەنگاوێک ناڕوونە، کەموکوڕیی ئەم بەڵگەنامەیە.

چی دەپارێزرێت و چۆن

ئامانجەکان: خاڵی گەڕاندنەوەی داتا لە ماوەی 60 چرکە لە شکستی سیستەم، و گەڕاندنەوە لە ماوەی 60 خولەک بۆ بنکەدراوەی 500 GB.

دوو هەڵە باون. بنکەدراوەیەک ئەگەر بەبێ فایلەکانی بگەڕێندرێتەوە پەڕەی تێکشکاو پیشان دەدات. بنکەدراوەیەک ئەگەر بەبێ 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

یان ڕێگە بدە stack خشتەبەندی بکات: profileی 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 و هتد. bucketێکی جیاواز و باشترە هەژمارێکی جیاواز لەگەڵ فایلەکان بەکاربهێنە، بە زانیارییەکی نهێنی کە بتوانێت بنووسێت بەڵام نەیسڕێتەوە ئەگەر دابینکەر ڕێگە بدات.
• ماوەی پاراستن. نوێترین QUIRE_BACKUP_OFFSITE_KEEP پاڵپشتیی بنەڕەت (بەپێی بنەڕەت QUIRE_BACKUP_KEEP، ئەگەر دانەنرابێت 7) و ئەو WALەی کە کۆنترینیان پێویستی پێیەتی؛ کۆمەڵە و پارچە کۆنەکان لە کۆگاکە دەسڕدرێنەوە.
• کات. هەر QUIRE_BACKUP_SHIP_INTERVAL_SECONDS جارێک (بەپێی بنەڕەت 300 چرکە). گواستنەوە idempotentە: ئەوەی پێشتر هەڵگیراوە پشتگوێ دەخرێت و پاڵپشتیی بنەڕەت تەنها دوای نووسینی manifestی کۆتایی وەک هەڵگیراو ژمێردرێت.

هەمان فەرمان بە دەستیش جێبەجێ دەبێت:

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 بۆ ئەوەی فایلی ئاسایی دەستکاری نەکرێت:

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

   جێگرەوەکە هەموو فەرمانەکە جێگۆڕکێ دەکات، بۆیە هەردوو ڕێکخستنی گەڕاندنەوە پێویستیانە دووبارە دەخاتە ناوەوە: 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 بە ئەرشیفکردنەوە دەست پێ دەکات و timelineی نوێی WAL دەست پێ دەکات. دەستبەجێ پاڵپشتیی بنەڕەتێکی نوێ وەربگرە.

ناوی پرۆژەی quire پێشگری هەر حەوزەیەکە؛ docker volume ls ناوی وردەکان پیشان دەدات.

کاری خشتەبەندی‌کراوی پشتڕاستکردنەوە

backup-offsite هەروەها هەر QUIRE_BACKUP_DRILL_INTERVAL_HOURS جارێک کاری تاقیکردنەوە جێبەجێ دەکات (بەپێی بنەڕەت 168، هەفتانە)، و دوای شکستی یەکەم لە بەشی داهاتوو دووبارەی دەکاتەوە. نوێترین پاڵپشتیی بنەڕەت لە دەرەوەی میواندار و هەموو پارچە WALەکانی دوای ئەوە دەهێنێتەوە، هەر یەکێک دەکاتەوە (بۆ سەلماندنی کارکردنی کلیل و نەگۆڕانیان)، هەر فایلێک لەگەڵ manifestی بەراورد دەکات، دڵنیا دەبێت ئەرشیفەکە بوخچەی داتای 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. توانای گەڕاندنەوە: کلاستەری کاتی WAL تا کاتی ئامانج جێبەجێ دەکات و دەکرێتەوە.
2. تەواوی داتا: ژمارەی ڕیزی هەر خشتە لەگەڵ بنکەدراوەی زیندوو (tooling/restore-drill). بنکەدراوەی زیندوو لەو کاتی ئامانجەوە گۆڕاوە، بۆیە ژمارەی خشتەیەک لەوانەیە بە گەورەترینی 500 ڕیز یان یەک لە سەدی قەبارەکە، لە هەر ئاراستەیەک جیاواز بێت (نووسین دەیخاتە دواوە و سڕینەوە وای دەکات گەڕاندنەوە زیاتر بگرێتەوە)؛ پارتیشنی دروستکراو دوای کاتی ئامانج خشتەی ونبوو نییە. بۆ دامەزراندنی چالاکتر ڕێگەپێدانی جیاوازی زیاد بکە بە QUIRE_DRILL_MAX_BEHIND و QUIRE_DRILL_MAX_DRIFT_RATIO. خشتەی ونبوو یان بەتاڵکراو شکستە.
3. تەواوی: زنجیرەی hashی پشکنین لەسەر کۆپیی گەڕێندراوە پشتڕاست دەبێتەوە.
4. بەکارهێنانی: ڕۆڵی بەرنامە لە ڕێگەی ئاسایشی ئاستی ڕیزەوە دەخوێنێتەوە.
5. کات: لە دەستپێکەوە تا دۆخی سەوز، بەرامبەر QUIRE_DRILL_RTO_SECONDS (بەپێی بنەڕەت 3600).

هەرگیز لە بنکەدراوەی زیندوو یان حەوزەکانی ناینووسێت: حەوزەکانی پاڵپشتی و WAL تەنها بۆ خوێندنەوە لۆد کراون و کلاستەری کاتی لە کۆتاییدا لادەبرێت، سەرکەوتوو یان نا.

QUIRE_DRILL_REPORT بۆ ڕێڕەوێک دابنێ تا ڕاپۆرتی JSON بنووسێت، بە سەرکەوتن یان شکست؛ لە میوانداری 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ەکەوەیە.