Mete ajou san tan san sèvis

Règ yo nan docs/architecture/23-ops.md, seksyon 7, ak docs/architecture/07-data.md, seksyon 4.1. Men pwosedi a.

Garanti ki fè sa san danje

Vèsyon R mache kòrèkteman sou estrikti bazdone R ak estrikti R mwens youn. Yo separe chak chanjman estrikti an agrandisman, tranzisyon ak kontraksyon:

1. Agrandisman: ajoute nouvo chan, tab oswa endèks. Ansyen kòd la inyore li.
2. Tranzisyon, pandan omwen yon vèsyon: nouvo kòd ekri toude fòm yo epi li nouvo a; yon travay ki kapab reprann ranpli ansyen liy yo.
3. Kontraksyon: efase ansyen fòm nan nan yon vèsyon pita, poukont li.

Kidonk, nan chak moman pandan mizajou pwogresif la, ansyen ak nouvo pwosesis yo kapab pataje menm bazdone a. Pa gen migration pou desann vèsyon: yon migration ki te efase yon chan sa gen yon èdtan pa kapab remèt liy yo ki te ekri pandan lè sa a.

Travay CI schema-compat verifye garanti sa a nan chak vèsyon lè li kouri tès vèsyon anvan an kont nouvo estrikti a.

Anvan ou kòmanse

1. Li nòt vèsyon yo. Yon vèsyon ki bezwen antretyen di sa ak estimasyon tan an; gen omwen youn pou chak vèsyon.
2. Kouri egzèsis restorasyon an oswa verifye li te fini avèk siksè pou vèsyon sa a (backup-restore.md). Yon egzèsis ki echwe bloke mizajou a.
3. Pran yon backup baz: docker compose -f docker/compose.yaml --profile backup run --rm backup.

Docker Compose sou yon sèl 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

Lòd la fèt espre:

1. Fè migration an premye, pandan ansyen vèsyon an toujou ap sèvi demann yo. Migration agrandisman yo pa vizib pou li.
2. Web tier la apre sa. Lè chak pwosesis web resevwa SIGTERM, li mete /readyz sou draining, fini demann ki deja ankou yo nan 30 segonn, fèmen stream yo ak yon avi rekoneksyon epi soti. stop_grace_period bay 40 segonn pou Compose pa koupe yon drenaj ki an sante.
3. Worker yo an dènye, konsa yo pwodui nouvo fòm evènman an anvan nouvo consumer lan tann li. Worker yo sispann chèche travay tousuit epi yo jwenn 120 segonn; nenpòt travay yo pa ka fini repran yon lòt kote, sa san danje paske tout travay idempotent. Scheduler la transfere lidèchip nan pwochen tick li.

Sou yon sèl host, Compose ranplase chak container youn apre lòt, kidonk chak sèvis gen yon ti entèripsyon. Pou pa gen entèripsyon ditou, kouri web tier la nan de container dèyè pwòp proxy pa w (yon fichye override ki ajoute yon dezyèm sèvis web san pò piblik), epi rekreye yo youn apre lòt; tann chak bay rapò sante anvan ou pase nan pwochen an.

Plizyè host oswa yon orchestrator

Kenbe menm lòd la: fè migration yon sèl fwa nan yon sèl travay, answit woule web tier la ak surge yon sèl epi unavailable zewo, epi pase nan worker yo. Mete readiness probe yo sou /readyz, liveness sou /healthz.

Avèk bazdone tenant dedye, etap migrate la fè toude: li migre bazdone kontwòl la an premye, apre sa chak bazdone ki nan ops.tenant_database, youn apre lòt, anba pwòp lock pa yo. Yon echèk nan yon bazdone tenant pa kanpe lòt yo. Lè tout bazdone fini, pwosesis la konpare rejis migration yo epi li sòti ak kòd ki pa zewo sof si chak bazdone aplike egzakteman menm migration ak bazdone kontwòl la; li bay non chak bazdone ki an reta oswa devan. Menm kòmand lan enstale tab ke travay yo nan chak bazdone paske worker la konsome travay tenant ki fikse nan bazdone kote yo ekri yo.

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

Yo jwenn chak bazdone dedye sou non yo anrejistre li a. Yon bazdone ki anrejistre kòm env:QUIRE_DB_NORTHWIND_URL bezwen:

Yo rapòte yon bazdone anrejistre ki pa gen koneksyon _MIGRATOR kòm echèk; yo pa janm sote li. Web tier la kapab kòmanse woule yon fwa bazdone kontwòl la fini. Si yon bazdone tenant gen inèdtan reta, li bay avètisman; apre yon jou, li voye alèt ijan.

pgvector

Apati migration 0264, done tèks yo itilize pou jwenn kontèks sèvi ak yon endèks HNSW pgvector kote sèvè a gen ekstansyon an; sèvis Compose postgres la konstwi avèk li (docker/postgres.Dockerfile). Premye kòmand migrate apre chanjman image la kreye ekstansyon an atravè demaraj superuser, epi 0264 ajoute yon kolòn vector ki pwodui otomatikman ak endèks la. Ajoute kolòn nan re-ekri app.ai_chunk yon sèl fwa anba yon lock eksklizif, kidonk demann rechèch kontèks tann; anyen lòt pa manyen tab sa a.

Sou yon sèvè ki pa gen pgvector, 0264 ekri yon avi nan log epi li pa chanje anyen; rechèch la rete egzak. Si pgvector pi ansyen pase 0.8, kolòn ak endèks la fèt men rechèch la rete egzak jiskaske yo mete ekstansyon an ajou (alter extension vector update), paske scan HNSW filtre bezwen scan iteratif vèsyon 0.8 la. Pou aktive pita sou yon sèvè ki pa gen li, enstale ekstansyon an, relanse demaraj baz la (oswa create extension vector kòm superuser), epi kòm quire_migrator:

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

Kòmand lan idempotent epi li retounen enabled oswa unavailable. Kouri li nan chak bazdone tenant dedye tou.

Retounen nan vèsyon anvan

Ou kapab toujou retounen kòd la: mete QUIRE_RELEASE sou tag anvan an epi kouri up -d ankò. Sa mache paske estrikti a konpatib nan toude direksyon nan yon menm vèsyon.

Yo pa ofri retou sou estrikti bazdone a. Men sa ki pa ka defèt ak fason pou rekipere:

Se poutèt sa yon migration kontraksyon soti poukont li: restorasyon an gen yon limit klè.

Verifye mizajou a

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