Nadogradnja bez prekida rada

Pravila su navedena u docs/architecture/23-ops.md odjeljku 7 i docs/architecture/07-data.md odjeljku 4.1. Ovo je postupak.

Jamstvo koje čini postupak sigurnim

Izdanje R ispravno radi sa shemom R i shemom R minus jedan. Svaka promjena sheme dijeli se na proširenje, prijelaz i uklanjanje:

1. Proširenje: dodajte novi stupac, tablicu ili indeks. Stari ga kod zanemaruje.
2. Prijelaz, tijekom najmanje jednog izdanja: novi kod zapisuje oba oblika i čita novi; posao koji se može nastaviti popunjava stare retke.
3. Uklanjanje: odbacite stari oblik u kasnijem izdanju, kao jedinu promjenu.

Tako u svakom trenutku postupne nadogradnje stari i novi procesi mogu dijeliti istu bazu podataka. Povratne migracije ne postoje: migracija koja je prije sat vremena uklonila stupac ne može vratiti retke zapisane tijekom tog sata.

CI zadatak schema-compat provjerava ovo jamstvo u svakom izdanju tako što pokreće testove prethodnog izdanja nad novom shemom.

Prije početka

1. Pročitajte napomene uz izdanje. Izdanje za koje je potreban prozor održavanja to navodi zajedno s procjenom; najviše jedno izdanje po prozoru.
2. Provedite probu vraćanja iz sigurnosne kopije ili potvrdite da je za ovo izdanje uspješno završena (backup-restore.md). Neuspjela proba zaustavlja nadogradnju.
3. Izradite osnovnu sigurnosnu kopiju: docker compose -f docker/compose.yaml --profile backup run --rm backup.

Docker Compose, jedan poslužitelj

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

Redoslijed je namjeran:

1. Najprije migrirajte, dok promet poslužuje staro izdanje. Migracije proširenja njemu su nevidljive.
2. Zatim web sloj. Pri SIGTERM-u svaki web proces postavlja /readyz na draining, dovršava zahtjeve u tijeku unutar 30 sekundi, zatvara tokove uz napomenu o ponovnom povezivanju i izlazi. stop_grace_period iznosi 40 sekundi, pa Compose nikad ne prekida uredno gašenje dok je proces zdrav.
3. Radnike pokrenite posljednje, kako bi se najnoviji oblik događaja proizveo prije nego što ga najnoviji potrošač očekuje. Radnici odmah prestaju dohvaćati poslove i dobivaju 120 sekundi; posao koji se ne može dovršiti dohvaća se drugdje, što je sigurno jer je svaki posao idempotentan. Planer predaje vodstvo pri sljedećem otkucaju.

Na jednom poslužitelju Compose redom zamjenjuje spremnike, pa za svaku uslugu postoji kratki prekid. Za potpuno neprekinut rad pokrenite web sloj u dva spremnika iza vlastitog posredničkog poslužitelja (datoteka za nadjačavanje koja dodaje drugu web uslugu bez objavljenog porta) i ponovno ih stvarajte jedan po jedan; prije sljedećeg pričekajte da svaki postane zdrav.

Više poslužitelja ili orkestrator

Primijenite isti redoslijed: jednom migrirajte iz jednokratnog zadatka, zatim postupno uvodite web sloj s jednim dodatnim i nijednim nedostupnim primjerkom, a potom radnike. Provjere spremnosti usmjerite na /readyz, a provjere živosti na /healthz.

Uz namjenske baze podataka za klijente, korak migrate radi oboje: najprije migrira upravljačku bazu, a zatim jednu po jednu svaku bazu navedenu u ops.tenant_database, svaku pod zasebnim zaključavanjem. Neuspjeh u jednoj bazi klijenta ne zaustavlja ostale. Kad završi sa svim bazama, uspoređuje registre migracija i vraća status različit od nule ako svaka baza nije primijenila točno one migracije koje ima upravljačka baza, uz navođenje svake zaostale ili ispredne baze. Ista naredba postavlja tablice reda u svakoj bazi, jer radnik troši poslove prikvačenog klijenta ondje gdje su zapisani.

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

Uobičajena migracija i početno postavljanje također instaliraju kanonske engleske pravne dokumente Quire operatera u ops.platform_policy_version. Instalacijski program je idempotentan: zamjenjuju se samo nedostajući engleski tekstovi i točno oni privremeni tekstovi koje je stvorila migracija. Sjemenke se arhiviraju i umeće se nova objavljena verzija; povijesne reference prihvaćanja i tekstovi zadržavaju se. Svaka autentična verzija koju je napisao operater, uključujući nacrt, čuva se i mora se upravljati putem konzole Pravila platforme. Dokumenti, verzije i privola pravila najmoprimca nikada se ne mijenjaju ovim prijelazom. Ovo je objava teksta operatera, a ne pravna certifikacija niti automatsko ispunjenje njegovih obećanja.

Do svake namjenske baze dolazi se preko naziva pod kojim je registrirana. Baza registrirana kao env:QUIRE_DB_NORTHWIND_URL treba sljedeće:

Registrirana baza bez veze _MIGRATOR prijavljuje se kao neuspjeh i nikad se ne preskače. Web sloj može se postupno uvesti kad se dovrši upravljačka baza. Zaostatak baze klijenta od jednog sata izaziva upozorenje; zaostatak od jednog dana šalje hitnu obavijest.

pgvector

Od migracije 0264 korpus za utemeljenje koristi indeks pgvector HNSW na poslužitelju s tim proširenjem; usluga Compose postgres izgrađena je s njim (docker/postgres.Dockerfile). Prvi migrate nakon promjene slike stvara proširenje kroz početnu konfiguraciju superkorisnika, a 0264 zatim dodaje generirani vektorski stupac i izrađuje indeks. Dodavanje stupca jednom prepisuje app.ai_chunk pod ekskluzivnim zaključavanjem, pa zahtjevi za utemeljenje čekaju; ništa drugo ne pristupa toj tablici.

Na poslužitelju bez pgvectora 0264 zapisuje obavijest i ne mijenja ništa, a dohvaćanje ostaje egzaktno. Uz pgvector stariji od 0.8 stupac i indeks izrađuju se, ali dohvaćanje ostaje egzaktno sve dok se proširenje ne nadogradi (alter extension vector update), jer filtrirana HNSW pretraživanja trebaju iterativna pretraživanja iz verzije 0.8. Da biste ga naknadno uključili na poslužitelju koji ga nema, instalirajte proširenje, ponovno pokrenite početnu konfiguraciju (ili kao superkorisnik izvršite create extension vector), a zatim kao quire_migrator pokrenite:

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

Operacija je idempotentna i vraća enabled ili unavailable. Pokrenite je i na svakoj namjenskoj bazi klijenta.

Povratak na prethodno izdanje

Povratak koda uvijek je moguć: postavite QUIRE_RELEASE na prethodnu oznaku i ponovno pokrenite up -d. To funkcionira jer je shema kompatibilna u oba smjera unutar jednog izdanja.

Povratak sheme nije podržan. Ovo se ne može poništiti, a ovako se oporavlja:

Zato se migracija uklanjanja isporučuje sama: vraćanje tada ima jasnu granicu.

Provjera nadogradnje

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