Hloov version yam tsis muaj downtime

Cov cai nyob hauv ntu 7 ntawm docs/architecture/23-ops.md thiab ntu 4.1 ntawm docs/architecture/07-data.md. Nov yog txheej txheem.

Qhov lav uas ua kom nyab xeeb

Release R khiav raug nrog schema R thiab schema R rho ib version. Faib txhua schema hloov ua peb ntu: nthuav, hloov thiab txo:

1. Nthuav: ntxiv column, table lossis index tshiab. Code qub tsis quav ntsej nws.
2. Hloov, tsawg kawg ib release: code tshiab sau tau ob daim qauv thiab nyeem daim tshiab; job rov pib tau sau cov kab qub kom tiav.
3. Txo: tso tseg daim qauv qub hauv release tom ntej, ua ib leeg xwb.

Yog li txhua lub sijhawm hloov version ib ntus, process qub thiab tshiab siv tau database tib yam. Tsis muaj down migration: migration rho column ib teev dhau los yeej muab tsis tau kab uas sau hauv teev ntawd rov qab.

CI job schema-compat xyuas qhov lav rau txhua release los ntawm khiav test ntawm release dhau los tawm tsam schema tshiab.

Ua ntej pib

1. Nyeem release notes. Release uas xav maintenance window yuav qhia nrog kwv yees sijhawm; ntau kawg ib zaug ib release.
2. Khiav restore drill, lossis xyuas tias release no twb khiav dhau lawm (backup-restore.md). Drill poob ces thaiv upgrade.
3. Thaub qab base: docker compose -f docker/compose.yaml --profile backup run --rm backup.

Docker Compose, ib 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

Kev txiav txim muaj laj thawj:

1. Migrate ua ntej, thaum release qub tseem pab neeg siv. Nws tsis pom expansion migration.
2. Tom qab ntawd web tier. Thaum SIGTERM, txhua web process hloov /readyz ua draining, ua kom request khiav lawm tiav hauv 30 vib nas this, kaw stream nrog lus qhia reconnect thiab tawm. stop_grace_period yog 40 vib nas this kom Compose tsis txiav kev drain uas zoo.
3. Workers kawg, kom event qauv tshiab raug tsim ua ntej consumer tshiab xav tau. Workers nres txais haujlwm tam sim thiab tau 120 vib nas this; job uas ua tsis tiav yuav raug txais dua lwm qhov, nyab xeeb vim txhua job idempotent. Scheduler hloov tus coj ntawm tick tom ntej.

Ntawm ib host, Compose hloov container ib zaug zuj zus, ces muaj qhov khoob luv rau txhua service. Xav tsis muaj qhov khoob li, khiav web tier ua ob container qab proxy koj tswj (override file ntxiv web service thib ob uas tsis publish port), ces tsim lawv ib zaug zuj zus; tos kom ib qho qhia noj qab nyob zoo ua ntej hloov lwm qhov.

Ntau host lossis orchestrator

Siv tib txoj kev txiav txim: migrate ib zaug ntawm ib job, ces hloov web tier nrog surge ib thiab unavailable xoom, ces hloov workers. Teem readiness probe rau /readyz thiab liveness rau /healthz.

Yog muaj tenant database tshwj xeeb, kauj ruam migrate ua ob yam: xub hloov control database, ces txhua database hauv ops.tenant_database, ib zaug zuj zus, txhua qhov siv nws tus lock. Database tenant ib qho poob tsis nres lwm qhov. Thaum txhua database tiav, piv migration ledger thiab tawm code tsis yog xoom tshwj tsis yog txhua database siv migration tib yam li control database; qhia npe txhua qhov uas qab lossis ua ntej. Command tib yam nruab queue table rau txhua database, vim worker txais job ntawm tenant pinned hauv database uas sau.

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

Txuas txhua database tshwj xeeb raws npe uas nws tso npe. Database tso npe ua env:QUIRE_DB_NORTHWIND_URL xav tau:

Database tso npe uas tsis muaj _MIGRATOR connection yuav qhia ua yuam kev, tsis txhob hla. Web tier hloov tau thaum control database tiav. Tenant database qab ib teev mam ceeb toom; dhau ib hnub mam hu.

pgvector

Txij migration 0264, grounding corpus siv pgvector HNSW index yog server muaj extension; Compose postgres service tsim nrog nws (docker/postgres.Dockerfile). Thawj migrate tom qab hloov image tsim extension ntawm superuser bootstrap, ces 0264 ntxiv generated vector column thiab tsim index. Ntxiv column rov sau app.ai_chunk ib zaug nrog exclusive lock, ces grounding request tos; tsis muaj ib yam ntxiv kov table ntawd.

Yog server tsis muaj pgvector, 0264 teev lus ceeb toom thiab tsis hloov dab tsi; retrieval tseem tshawb tseeb. Yog pgvector laus dua 0.8, tsim column thiab index tiamsis retrieval tseem tshawb tseeb txog thaum upgrade extension (alter extension vector update), vim filtered HNSW scan xav tau iterative scan ntawm 0.8. Yuav qhib tom qab server uas tsis muaj extension, nruab extension, khiav bootstrap dua (lossis create extension vector ua superuser), ces ua quire_migrator:

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

Nws idempotent thiab rov enabled lossis unavailable. Khiav rau txhua database tenant tshwj xeeb thiab.

Rov qab version

Rov qab code yeej ua tau: teem QUIRE_RELEASE ua tag dhau los thiab khiav up -d dua. Qhov no ua haujlwm vim schema phim ob sab hauv ib release.

Rov qab schema tsis muaj. Yam thim tsis tau thiab txoj kev rov qab:

Vim li no contract migration tshaj tawm ib leeg: restore muaj ciam meej.

Kuaj upgrade

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