Արդիականացում առանց դադարի

Կանոնները docs/architecture/23-ops.md փաստաթղթի 7-րդ և docs/architecture/07-data.md փաստաթղթի 4.1 բաժիններում են։ Սա ընթացակարգն է։

Անվտանգությունն ապահովող երաշխիքը

R թողարկումը ճիշտ է աշխատում R և R-ից մեկով փոքր սխեմաների հետ։ Սխեմայի յուրաքանչյուր փոփոխություն բաժանվում է ընդլայնման, անցման և կրճատման փուլերի․

1. Ընդլայնում․ ավելացրեք նոր սյունակ, աղյուսակ կամ ինդեքս։ Հին կոդն անտեսում է այն։
2. Անցում, առնվազն մեկ թողարկման ընթացքում․ նոր կոդը գրում է երկու ձևաչափով և կարդում նորը, իսկ շարունակելի աշխատանքը լրացնում է հին տողերը։
3. Կրճատում․ հին ձևաչափը հեռացրեք ավելի ուշ թողարկման ժամանակ՝ որպես միակ փոփոխություն։

Այսպիսով փուլային արդիականացման ցանկացած պահին հին և նոր գործընթացները կարող են օգտագործել նույն տվյալների բազան։ Հետադարձ միգրացիաներ չկան․ մեկ ժամ առաջ սյունակ հեռացրած միգրացիան չի կարող վերադարձնել այդ ժամում գրված տողերը։

schema-compat CI աշխատանքը յուրաքանչյուր թողարկման ժամանակ ստուգում է այս երաշխիքը՝ նոր սխեմայի վրա գործարկելով նախորդ թողարկման թեստերը։

Սկսելուց առաջ

1. Կարդացեք թողարկման նշումները։ Սպասարկման դադար պահանջող թողարկումը դա հայտնում է՝ նշելով դրա տևողության գնահատականը․ յուրաքանչյուր թողարկմանը՝ առավելագույնը մեկ այդպիսի դեպք։
2. Անցկացրեք վերականգնման փորձը կամ հաստատեք, որ այն այս թողարկման համար հաջողությամբ ավարտվել է (backup-restore.md)։ Անհաջող փորձը արգելափակում է արդիականացումը։
3. Ստեղծեք սկզբնական պահուստային պատճեն․ docker compose -f docker/compose.yaml --profile backup run --rm backup։

Docker Compose՝ մեկ հոսթում

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. Հաջորդը՝ վեբ շերտը։ SIGTERM ազդանշան ստանալիս յուրաքանչյուր վեբ գործընթաց /readyz-ը փոխում է draining վիճակի, 30 վայրկյանի ընթացքում ավարտում ընթացիկ հարցումները, փակում հոսքերը՝ կրկին միանալու հուշումով, և դուրս է գալիս։ stop_grace_period-ը 40 վայրկյան է, ուստի Compose-ը երբեք չի ընդհատում առողջ ավարտման գործընթացը։
3. Աշխատողները՝ վերջինը, որպեսզի իրադարձության նորագույն ձևն արտադրվի, նախքան դրա սպասող նորագույն սպառողը գործարկվելը։ Աշխատողները միանգամից դադարում են հարցումներ ստանալ և ստանում են 120 վայրկյան։ Չավարտվող գործը կրկին ստացվում է այլ տեղում, ինչը անվտանգ է, քանի որ բոլոր գործերն իդեմպոտենտ են։ Ժամանակացույցը հաջորդ քայլի պահին փոխանցում է ղեկավարումը։

Մեկ հոսթում Compose-ը հերթով փոխարինում է յուրաքանչյուր կոնտեյները, ուստի ամեն ծառայություն կարճ դադար է ունենում։ Դադարն ամբողջությամբ վերացնելու համար գործարկեք վեբ շերտի երկու կոնտեյներ՝ ձեր սեփական պրոքսիի հետևում (գերադասման ֆայլ, որն ավելացնում է երկրորդ վեբ ծառայություն առանց հրապարակված պորտի), և վերստեղծեք դրանք մեկ առ մեկ՝ մինչև հաջորդը յուրաքանչյուրի առողջ դառնալուն սպասելով։

Մի քանի հոսթ կամ նվագախմբիչ

Կիրառեք նույն հերթականությունը․ մեկ անգամ միգրացիա՝ առանձին աշխատանքով, հետո թարմացրեք վեբ շերտը՝ մեկ ավելացվող և զրո անհասանելի օրինակով, ապա՝ աշխատողներին։ Պատրաստության ստուգումները ուղղեք դեպի /readyz, իսկ կենսունակության ստուգումները՝ դեպի /healthz։

Նվիրված հաճախորդային բազաների դեպքում migrate քայլն անում է երկուսն էլ․ նախ միգրացնում է կառավարման բազան, ապա՝ մեկ առ մեկ ops.tenant_database-ում նշված յուրաքանչյուր տվյալների բազան՝ ամեն մեկն իր փականքի ներքո։ Հաճախորդի մեկ բազայի խափանումը չի կանգնեցնում մյուսներին։ Բոլորի ավարտից հետո այն համեմատում է միգրացիաների մատյանները և ոչ զրոյական կարգավիճակով ավարտվում, եթե բոլոր բազաներում ճշգրիտ այն միգրացիաները չեն կիրառվել, որոնք կան կառավարման բազայում․ նշվում է յուրաքանչյուր ետ մնացած կամ առաջ անցած բազան։ Նույն հրամանը յուրաքանչյուր բազայում տեղադրում է հերթի աղյուսակները, քանի որ աշխատողը կարդում է ամրագրված հաճախորդի այն աշխատանքները, որտեղ դրանք գրվել են։

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

Յուրաքանչյուր նվիրված տվյալների բազայի հետ կապը հաստատվում է այն անունով, որով գրանցված է։ env:QUIRE_DB_NORTHWIND_URL անունով գրանցված բազային պետք են․

_MIGRATOR կապ չունեցող գրանցված տվյալների բազան նշվում է որպես ձախողում, երբեք չի բաց թողնվում։ Վեբ շերտը կարելի է հերթով թարմացնել կառավարման բազայի ավարտից հետո։ Մեկ ժամով հետ մնացած հաճախորդի բազան նախազգուշացում է առաջացնում, մեկ օրովը՝ հրատապ ծանուցում։

pgvector

0264 միգրացիայից սկսած՝ հիմքավորման կորպուսն օգտագործում է pgvector HNSW ինդեքս, եթե սերվերն ունի այդ ընդլայնումը․ Compose-ի postgres ծառայությունը կառուցվում է դրանով (docker/postgres.Dockerfile)։ Պատկերների փոխելուց հետո առաջին migrate-ը ընդլայնումը ստեղծում է սուպերօգտատիրոջ նախնական կազմաձևման միջոցով, ապա 0264-ը ավելացնում է գեներացվող վեկտորային սյունակ և կառուցում ինդեքսը։ Սյունակն ավելացնելիս app.ai_chunk-ը մեկ անգամ վերագրվում է բացառիկ փականքի ներքո, ուստի հիմքավորման հարցումները սպասում են․ այդ աղյուսակին ուրիշ ոչինչ չի դիպչում։

Առանց pgvector-ի սերվերում 0264-ը գրանցում է ծանուցում և ոչինչ չի փոխում, իսկ որոնումը մնում է ճշգրիտ։ 0.8-ից հին pgvector-ի դեպքում սյունակն ու ինդեքսը կառուցվում են, բայց որոնումը մնում է ճշգրիտ մինչև ընդլայնումը արդիականացնելը (alter extension vector update), որովհետև ֆիլտրով HNSW որոնումներին պետք են 0.8-ի կրկնվող որոնումները։ Հետագայում այն առանց ընդլայնման սերվերում միացնելու համար տեղադրեք ընդլայնումը, կրկին գործարկեք նախնական կազմաձևումը (կամ որպես սուպերօգտատեր՝ create extension vector), ապա 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-ը սահմանեք նախորդ tag-ին և կրկին գործարկեք 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