Frissítés leállás nélkül

A szabályokat a docs/architecture/23-ops.md 7. szakasza és a docs/architecture/07-data.md 4.1 szakasza írja le. Ez az eljárás.

A biztonságot garantáló feltétel

Az R kiadás helyesen működik az R és az R mínusz egy sémával. Minden sémaváltozás három részre oszlik: bővítés, átmenet és szerződés:

1. Bővítés: új oszlop, tábla vagy index hozzáadása. A régi kód figyelmen kívül hagyja.
2. Átmenet, legalább egy kiadáson át: az új kód mindkét formát írja, az újat olvassa; egy folytatható háttérfeladat feltölti a régi sorokat.
3. Szerződés: a régi forma eltávolítása egy későbbi, önálló kiadásban.

Így a fokozatos frissítés minden pillanatában a régi és új folyamatok ugyanazt az adatbázist használhatják. Nincsenek visszafelé futtatható migrációk: az egy órája oszlopot törlő migráció nem tudja visszaadni az azóta beleírt sorokat.

A schema-compat CI-feladat minden kiadásnál ellenőrzi a feltételt, az előző kiadás tesztjeit az új sémán futtatva.

Kezdés előtt

1. Olvassa el a kiadási megjegyzéseket. Ha egy kiadáshoz karbantartási időablak kell, ezt jelezni kell a becsült idővel; kiadásonként legfeljebb egy ilyen lehet.
2. Futtassa le a visszaállítási próbát, vagy ellenőrizze, hogy ez a kiadás sikeresen teljesítette (backup-restore.md). Sikertelen próba megakadályozza a frissítést.
3. Készítsen alapmentést: docker compose -f docker/compose.yaml --profile backup run --rm backup.

Docker Compose egy hoston

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

A sorrend szándékos:

1. Először a migráció, miközben a régi kiadás kiszolgálja a forgalmat. A bővítő migrációk nem láthatók számára.
2. Ezután a webes réteg. SIGTERM esetén minden webfolyamat a /readyz végpontot draining állapotba kapcsolja, 30 másodpercen belül befejezi a folyamatban lévő kéréseket, újracsatlakozásra utaló jelzéssel lezárja az adatfolyamokat, majd kilép. A stop_grace_period 40 másodperc, így a Compose nem szakít meg egészséges leállítást.
3. A workerek utoljára következnek, hogy a legújabb eseményforma már létrejöjjön, mielőtt a legújabb fogyasztó elvárná. A workerek azonnal leállítják az új feladatok lekérését, és 120 másodpercet kapnak; az időben be nem fejezett feladatot máshol újra lekérik, ami biztonságos, mert minden feladat idempotens. A scheduler a következő ütemezett időpontban átadja a vezetést.

Egy hoston a Compose egymás után cseréli le a konténereket, ezért szolgáltatásonként rövid kimaradás van. Ha egyáltalán nem szeretne szünetet, futtassa a webes réteget két konténerben, saját proxy mögött (az override fájl adjon hozzá egy második webszolgáltatást közzétett port nélkül), majd egyenként hozza létre újra őket, és várja meg, hogy a következő előtt mindegyik egészséges legyen.

Több host vagy orchestrator

Tartsa ugyanazt a sorrendet: migráljon egyszer, egyetlen feladatból, majd fokozatosan frissítse a webes réteget egyes maximális többlettel és nulla kieső példánnyal, aztán a workereket. A readiness ellenőrzés a /readyz, a liveness ellenőrzés pedig a /healthz útvonalat használja.

Dedikált tenant-adatbázisoknál a migrate lépés mindkettőt elvégzi: először a vezérlő adatbázist migrálja, majd az ops.tenant_database listáján szereplő összes adatbázist egyesével, saját zárral. Egy tenant-adatbázis hibája nem állítja le a többit. Ha mind elkészült, összehasonlítja a migrációs naplókat, és nem nulla kóddal lép ki, ha bármelyik adatbázis nem pontosan ugyanazokat a migrációkat alkalmazta, mint a vezérlő; név szerint megjelöli a lemaradókat és előrébb járókat. Ugyanez a parancs minden adatbázisban telepíti a queue-táblákat is, mert a worker ott dolgozza fel a rögzített tenant feladatait, ahová bekerültek.

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

Minden dedikált adatbázist a regisztrációs nevén ér el. A env:QUIRE_DB_NORTHWIND_URL néven regisztrált adatbázishoz ezek kellenek:

Ha egy regisztrált adatbázisnak nincs _MIGRATOR kapcsolata, azt hibaként jelenti, soha nem hagyja ki. A webes réteg akkor frissíthető, amikor a vezérlő adatbázis elkészült. Az egy órát késő tenant-adatbázis figyelmeztet, egy nap után riasztást küld.

pgvector

A 0264-es migrációtól kezdve a grounding korpusz pgvector HNSW-indexet használ, ha a kiszolgálón elérhető a bővítmény; a Compose postgres szolgáltatása ezzel készül (docker/postgres.Dockerfile). A lemezképek cseréje utáni első migrate a superuser-indító lépésen keresztül létrehozza a bővítményt, majd a 0264 létrehoz egy generált vektoroszlopot és felépíti az indexet. Az oszlop hozzáadása egyszer, kizárólagos zárral újraírja az app.ai_chunk táblát, ezért a grounding kérések várakoznak; semmi más nem módosítja ezt a táblát.

Pgvector nélküli kiszolgálón a 0264 értesítést ír, és nem változtat semmin; a lekérdezés pontos marad. 0.8-nál régebbi pgvector esetén létrehozza az oszlopot és indexet, de a lekérdezés pontos marad a bővítmény frissítéséig (alter extension vector update), mert a szűrt HNSW-kereséshez a 0.8 iteratív keresése szükséges. Későbbi engedélyezéshez telepítse a bővítményt, futtassa újra az indító lépést (vagy superuserként a create extension vector parancsot), majd quire_migrator szerepkörrel:

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

A művelet idempotens, és enabled vagy unavailable értéket ad vissza. Minden dedikált tenant-adatbázison is futtassa le.

Visszaállítás

A kód visszaállítása mindig lehetséges: állítsa a QUIRE_RELEASE értékét az előző címkére, majd futtassa újra az up -d parancsot. Ez azért működik, mert egy kiadáson belül a séma mindkét irányban kompatibilis.

A séma visszaállítása nem elérhető. Amit nem lehet visszavonni, és a helyreállítás módja:

Ezért jelenik meg a szerződésmigráció önálló kiadásként: a visszaállításnak így tiszta határa van.

Frissítés ellenőrzése

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