Αναβάθμιση χωρίς διακοπή λειτουργίας

Οι κανόνες περιγράφονται στην ενότητα 7 του docs/architecture/23-ops.md και στην ενότητα 4.1 του docs/architecture/07-data.md. Ακολουθεί η διαδικασία.

Η εγγύηση που την καθιστά ασφαλή

Η έκδοση R λειτουργεί σωστά τόσο με το σχήμα R όσο και με το σχήμα R μείον ένα. Κάθε αλλαγή σχήματος χωρίζεται σε επέκταση, μετάβαση και κατάργηση:

1. Επέκταση: προσθήκη νέας στήλης, πίνακα ή ευρετηρίου. Ο παλιός κώδικας το αγνοεί.
2. Μετάβαση, για τουλάχιστον μία έκδοση: ο νέος κώδικας γράφει και στις δύο μορφές και διαβάζει τη νέα· μια εργασία που μπορεί να συνεχιστεί συμπληρώνει τις παλιές γραμμές.
3. Κατάργηση: αφαίρεση της παλιάς μορφής, μόνη της σε μεταγενέστερη έκδοση.

Έτσι, σε κάθε στιγμή μιας σταδιακής αναβάθμισης, παλιές και νέες διεργασίες μπορούν να χρησιμοποιούν την ίδια βάση δεδομένων. Δεν υπάρχουν μεταναστεύσεις υποβάθμισης: μια μετανάστευση που διέγραψε στήλη πριν από μία ώρα δεν μπορεί να επαναφέρει τις γραμμές που γράφτηκαν εκείνη την ώρα.

Η εργασία CI schema-compat ελέγχει την εγγύηση σε κάθε έκδοση, εκτελώντας τις δοκιμές της προηγούμενης έκδοσης στο νέο σχήμα.

Πριν ξεκινήσετε

1. Διαβάστε τις σημειώσεις έκδοσης. Μια έκδοση που απαιτεί παράθυρο συντήρησης το αναφέρει μαζί με την εκτίμηση διάρκειας· υπάρχει το πολύ μία ανά έκδοση.
2. Εκτελέστε την άσκηση επαναφοράς ή επιβεβαιώστε ότι ολοκληρώθηκε επιτυχώς για αυτή την έκδοση (backup-restore.md). Μια αποτυχημένη άσκηση εμποδίζει την αναβάθμιση.
3. Δημιουργήστε βασικό αντίγραφο ασφαλείας: docker compose -f docker/compose.yaml --profile backup run --rm backup.

Docker Compose σε έναν host

export QUIRE_RELEASE=2026.10.0            # or set it in docker/.env
docker compose -f docker/compose.yaml pull   # or build
docker compose -f docker/compose.yaml run --rm migrate
docker compose -f docker/compose.yaml up -d --no-deps web content collab
docker compose -f docker/compose.yaml up -d --no-deps worker scheduler

Η σειρά είναι σκόπιμη:

1. Πρώτα η μετανάστευση, ενώ η παλιά έκδοση εξυπηρετεί την κίνηση. Οι μεταναστεύσεις επέκτασης είναι αόρατες για αυτήν.
2. Έπειτα ο web tier. Κατά το SIGTERM, κάθε διεργασία web αλλάζει το /readyz σε draining, ολοκληρώνει τα αιτήματα που βρίσκονται σε εξέλιξη μέσα σε 30 δευτερόλεπτα, κλείνει τις ροές με υπόδειξη επανασύνδεσης και τερματίζεται. Το stop_grace_period είναι 40 δευτερόλεπτα, ώστε το Compose να μη διακόψει ομαλό τερματισμό.
3. Τελευταίοι οι workers, ώστε να παραχθεί πρώτα η νεότερη μορφή συμβάντος και έπειτα να την αναμένει ο νεότερος καταναλωτής. Οι workers σταματούν αμέσως να αντλούν εργασίες και έχουν 120 δευτερόλεπτα· μια εργασία που δεν μπορεί να ολοκληρωθεί αναλαμβάνεται ξανά αλλού. Αυτό είναι ασφαλές επειδή κάθε εργασία είναι ιδιοδύναμη. Ο scheduler παραδίδει την ηγεσία στο επόμενο χρονικό βήμα.

Σε έναν host, το Compose αντικαθιστά τα κοντέινερ με τη σειρά, οπότε υπάρχει σύντομο κενό για κάθε υπηρεσία. Για να μην υπάρχει καθόλου κενό, εκτελέστε τον web tier σε δύο κοντέινερ πίσω από δικό σας proxy (ένα αρχείο override προσθέτει δεύτερη υπηρεσία web χωρίς δημοσιευμένη θύρα) και δημιουργήστε τα ξανά ένα κάθε φορά, περιμένοντας να δηλωθεί καθένα ως υγιές πριν συνεχίσετε.

Πολλοί hosts ή ενορχηστρωτής

Ακολουθήστε την ίδια σειρά: εκτελέστε μία φορά τη μετανάστευση από μεμονωμένη εργασία, έπειτα κάντε σταδιακή ανάπτυξη του web tier με μία επιπλέον παρουσία και καμία μη διαθέσιμη, και τέλος των workers. Ορίστε τους ελέγχους ετοιμότητας στο /readyz και τους ελέγχους λειτουργίας στο /healthz.

Σε αποκλειστικές βάσεις δεδομένων μισθωτών, το βήμα migrate κάνει και τα δύο: μεταφέρει πρώτα την ελεγκτική βάση και έπειτα κάθε βάση που αναφέρεται στο ops.tenant_database, μία τη φορά και καθεμία με δικό της κλείδωμα. Αποτυχία σε μία βάση μισθωτή δεν σταματά τις υπόλοιπες. Όταν ολοκληρωθούν όλες, συγκρίνει τα αρχεία καταγραφής μεταναστεύσεων και τερματίζεται με μη μηδενικό κωδικό, εκτός αν κάθε βάση έχει εφαρμόσει ακριβώς τις ίδιες μεταναστεύσεις με την ελεγκτική. Κατονομάζει κάθε βάση που υστερεί ή προηγείται. Η ίδια εντολή εγκαθιστά τους πίνακες ουράς σε κάθε βάση, καθώς ο worker καταναλώνει τις εργασίες ενός δεσμευμένου μισθωτή από τη βάση όπου γράφτηκαν.

bun apps/worker/src/migrate.ts   # what the Compose step runs
bun run db:migrate:all                            # the same, from a checkout

Η συνήθης μετεγκατάσταση και η αρχική εγκατάσταση εγκαθιστούν επίσης τα κανονικά αγγλικά νομικά έγγραφα του διαχειριστή Quire στο ops.platform_policy_version. Το πρόγραμμα εγκατάστασης είναι αμετάβλητο ως προς το αποτέλεσμα: αντικαθίστανται μόνο τα αγγλικά κείμενα που λείπουν και ακριβώς τα προσωρινά κείμενα που δημιούργησε η μετεγκατάσταση. Τα αρχικά δεδομένα αρχειοθετούνται και εισάγεται νέα δημοσιευμένη έκδοση· οι ιστορικές αναφορές αποδοχής και τα κείμενα διατηρούνται. Κάθε γνήσια έκδοση που συνέταξε ο διαχειριστής, συμπεριλαμβανομένου προσχεδίου, διατηρείται και πρέπει να διαχειρίζεται μέσω της κονσόλας Πολιτικών της πλατφόρμας. Τα έγγραφα, οι εκδόσεις και η συναίνεση των πολιτικών μισθωτή δεν αλλάζουν ποτέ με αυτή τη μετάβαση. Πρόκειται για δημοσίευση κειμένου του διαχειριστή, όχι για νομική πιστοποίηση ούτε για αυτοματοποιημένη εκπλήρωση των υποσχέσεών του.

Κάθε αποκλειστική βάση προσπελαύνεται με το όνομα καταχώρισής της. Μια βάση που έχει καταχωριστεί ως env:QUIRE_DB_NORTHWIND_URL χρειάζεται:

Μια καταχωρισμένη βάση χωρίς σύνδεση _MIGRATOR αναφέρεται ως αποτυχία και δεν παραλείπεται ποτέ. Ο web tier μπορεί να ανανεωθεί μόλις ολοκληρωθεί η ελεγκτική βάση. Μια βάση μισθωτή που καθυστερεί μία ώρα προκαλεί προειδοποίηση· μετά από μία ημέρα ενεργοποιείται ειδοποίηση.

pgvector

Από τη μετανάστευση 0264, το σώμα δεδομένων grounding χρησιμοποιεί ευρετήριο HNSW του pgvector όπου ο διακομιστής διαθέτει την επέκταση· η υπηρεσία Compose postgres δημιουργείται με αυτή (docker/postgres.Dockerfile). Η πρώτη εκτέλεση του migrate μετά την αλλαγή image δημιουργεί την επέκταση μέσω της ρύθμισης superuser και στη συνέχεια η 0264 προσθέτει παραγόμενη διανυσματική στήλη και δημιουργεί το ευρετήριο. Η προσθήκη της στήλης ξαναγράφει μία φορά το app.ai_chunk υπό αποκλειστικό κλείδωμα, επομένως τα αιτήματα grounding περιμένουν· τίποτα άλλο δεν χρησιμοποιεί αυτόν τον πίνακα.

Σε διακομιστή χωρίς pgvector, η 0264 καταγράφει ειδοποίηση χωρίς αλλαγές και η ανάκτηση παραμένει ακριβής. Με pgvector παλαιότερο από 0.8 δημιουργούνται η στήλη και το ευρετήριο, αλλά η ανάκτηση παραμένει ακριβής έως ότου αναβαθμιστεί η επέκταση (alter extension vector update), επειδή οι σαρώσεις φιλτραρισμένου HNSW χρειάζονται τις επαναληπτικές σαρώσεις της έκδοσης 0.8. Για να την ενεργοποιήσετε αργότερα σε διακομιστή χωρίς pgvector, εγκαταστήστε την επέκταση, εκτελέστε ξανά τη ρύθμιση εκκίνησης (ή create extension vector ως superuser) και έπειτα, ως quire_migrator, εκτελέστε:

set maintenance_work_mem = '1GB';  -- the HNSW build is much faster in memory
select ops.ai_chunk_enable_vector_index();

Η λειτουργία είναι ιδιοδύναμη και επιστρέφει enabled ή unavailable. Εκτελέστε την και σε κάθε αποκλειστική βάση μισθωτή.

Επαναφορά προηγούμενης έκδοσης

Η επαναφορά του κώδικα είναι πάντα διαθέσιμη: ορίστε το QUIRE_RELEASE στην προηγούμενη ετικέτα και εκτελέστε ξανά up -d. Αυτό λειτουργεί επειδή το σχήμα είναι συμβατό και προς τις δύο κατευθύνσεις μέσα σε μια έκδοση.

Δεν προσφέρεται επαναφορά σχήματος. Όσα δεν αναστρέφονται και πώς γίνεται η ανάκτηση:

Γι’ αυτό μια μετανάστευση κατάργησης κυκλοφορεί μόνη της: έτσι η επαναφορά έχει καθαρό όριο.

Έλεγχος της αναβάθμισης

docker compose -f docker/compose.yaml ps           # every service healthy
curl -fsS http://localhost:8080/readyz             # ready, and what is configured
docker compose -f docker/compose.yaml logs migrate # the migrations applied