Initial curated RAGcore source from c16667f0c9397e2bfc8dd0255b114fba23c8d05e
This commit is contained in:
Public Source Publisher committed
commit
7ca726caf2
659 files changed
+98171
No files matched your search
@@ -0,0 +1,130 @@
|
||||
# Upgrade Strategy
|
||||
|
||||
## Applicatie
|
||||
|
||||
Build immutable image, run migrations/preflight, deploy, verify health and smoke tests. Database migrations are backward compatible for at least one application rollout whenever practical.
|
||||
|
||||
## Embedding/index
|
||||
|
||||
Never in place. Register new profile, build shadow collection, evaluate, activate alias, retain old build for rollback.
|
||||
|
||||
## PostgreSQL/Qdrant
|
||||
|
||||
Pin exact supported versions, read release notes, test backup restore and application suite in staging/temporary environment, then maintenance deployment. No automatic major upgrades.
|
||||
|
||||
## Rollback
|
||||
|
||||
Application image rollback plus compatible migration strategy; index alias rollback for retrieval; config/profile activation history. Restore is last resort, not ordinary rollback.
|
||||
|
||||
## Upgrade naar 1.2.1
|
||||
|
||||
Deze release bundelt drie rondes: SOURCE-CONVERGENCE (migratie `0017`),
|
||||
OPERATIONS-ISOLATION (`0018`) en RELEASE-CLEANUP (`0019`). Eén
|
||||
`alembic upgrade head` voert ze in volgorde uit; de stappen hieronder
|
||||
beschrijven wat er per ronde verandert en wat je vóór de uitrol moet zetten.
|
||||
|
||||
### SOURCE-CONVERGENCE (`0017`)
|
||||
|
||||
1. **Eerst configureren, dan uitrollen.** `RAGCORE_SOURCE_ROOTS` is een expliciete
|
||||
allowlist van server-side paden die een Folder- of Git-bron mag lezen, en is
|
||||
*leeg by default* -- fail closed. Zolang die leeg is kan geen enkele
|
||||
filesystem-bron worden aangemaakt of gesynchroniseerd, en falen bestaande
|
||||
folder/Git-syncs **terminaal** (`source path is outside every allowed source
|
||||
root`). Zet de waarde dus vóór de uitrol, met de paden zoals de *worker* ze
|
||||
ziet, en zorg dat elk pad ook read-only in de worker gemount is
|
||||
(`RAGCORE_SOURCE_MOUNT` in `compose.yaml`). Mount zonder allowlist leest
|
||||
niets; allowlist zonder mount resolvet niet. Er is bewust geen impliciete
|
||||
default, `/` al helemaal niet.
|
||||
2. Migratie `0017_source_convergence` (`alembic upgrade head`) voegt de
|
||||
convergentie-administratie toe aan `content.source_items`
|
||||
(`applied_fingerprint`, `applied_at`, `pending_job_id`, `attempts`,
|
||||
`last_failure_code`, `last_failure_retryable`), `pending` aan
|
||||
`source_sync_runs`, verbreedt `sync_state`/`outcome` naar 32 tekens, en
|
||||
vervangt de foreign key van `content.documents` door een samengestelde
|
||||
`(source_id, workspace_id, space_id)` met een bijbehorende unique key op
|
||||
`content.sources`.
|
||||
3. **Twee datawijzigingen in die migratie, geen schemawijzigingen:**
|
||||
(a) bestaande onthouden items worden als *applied* gebackfilld -- ze zijn
|
||||
geïngest onder het oude model, waarin een afgeronde discovery het enige
|
||||
completion-signaal was; (b) een bron die door `0016` over meerdere knowledge
|
||||
spaces heen mocht liggen wordt gesplitst naar per-space zusterbronnen
|
||||
(deterministisch afgeleid id) en de documenten daarvan worden omgehangen.
|
||||
4. Qdrant-punten van zulke *gesplitste* documenten dragen nog het oude
|
||||
`source_id`. Draai daarna een authoritative reconcile/rebuild van de actieve
|
||||
collectie, net als bij de 1.2.0-upgrade. Controleer vooraf of er iets te
|
||||
splitsen valt:
|
||||
|
||||
```sql
|
||||
SELECT DISTINCT d.source_id, d.workspace_id, d.space_id
|
||||
FROM content.documents AS d
|
||||
JOIN content.sources AS s ON s.id = d.source_id
|
||||
WHERE d.workspace_id <> s.workspace_id OR d.space_id <> s.space_id;
|
||||
```
|
||||
|
||||
Geen rijen = geen split en geen rebuild nodig voor deze stap.
|
||||
5. **Downgrade is niet symmetrisch.** De split wordt niet teruggedraaid (de
|
||||
zusterbronnen zijn echte bronnen geworden), en `awaiting_ingest` /
|
||||
`completed_with_failures` bestaan niet in het oude schema: die vallen bij een
|
||||
downgrade terug op `applying` respectievelijk `failed`, zodat een
|
||||
gedowngrade deployment "onaf of mislukt" leest in plaats van "geslaagd".
|
||||
6. Verwachte gedragsverandering na de uitrol: een sync meldt `awaiting_ingest`
|
||||
tot zijn child-`ingest_upload`-jobs teruggerapporteerd hebben, en
|
||||
`last_successful_sync_at` schuift alleen op bij een volledig geconvergeerde
|
||||
run. Een bron die eerder direct "Last sync ok" toonde, toont nu eerst
|
||||
"Indexing" -- dat is de correctie, geen regressie.
|
||||
|
||||
### OPERATIONS-ISOLATION (`0018`)
|
||||
|
||||
7. Migratie `0018_job_workspace_ownership` maakt eigenaarschap van een job een
|
||||
echte kolom (`jobs.jobs.workspace_id`, geïndexeerd) en voegt
|
||||
`content.source_items.last_failure_job_id` toe. De backfill is bewust
|
||||
fail-closed: alleen een `payload->>'workspace_id'` die zowel een geldige
|
||||
UUID is *als* een bestaande workspace aanwijst wordt overgenomen. Al het
|
||||
andere blijft `NULL` = *legacy*, en dat betekent onzichtbaar en
|
||||
onwijzigbaar voor elke workspace-gebonden principal; alleen een Platform
|
||||
Admin ziet zulke jobs nog. Verwachte gedragsverandering: een operator die
|
||||
vóór deze upgrade jobs van andere tenants zag, ziet nu alleen de eigen
|
||||
workspace. Controleer hoeveel rijen legacy blijven:
|
||||
|
||||
```sql
|
||||
SELECT count(*) FROM jobs.jobs WHERE workspace_id IS NULL;
|
||||
```
|
||||
|
||||
Die jobs zijn niet stuk; ze zijn alleen niet toewijsbaar. Laat ze aflopen of
|
||||
ruim ze op als Platform Admin.
|
||||
8. **`FILESYSTEM_SOURCE_MANAGE` is nieuw en ligt uitsluitend bij
|
||||
`PLATFORM_ADMIN`.** Een Folder- of Git-bron aanmaken *of wijzigen* vereist
|
||||
die permissie bovenop `SOURCE_MANAGE`. Workspace Admins en Space Managers
|
||||
die vóór deze upgrade filesystem-bronnen beheerden, kunnen dat niet meer;
|
||||
plan wie dat overneemt. De permissie en de `RAGCORE_SOURCE_ROOTS`-sandbox
|
||||
zijn onafhankelijke poorten: een pad buiten de allowlist wordt ook voor een
|
||||
Platform Admin geweigerd.
|
||||
|
||||
### RELEASE-CLEANUP (`0019`)
|
||||
|
||||
9. Migratie `0019_job_listing_index` voegt alleen een index toe
|
||||
(`ix_jobs_workspace_status_recent` op `(workspace_id, status, updated_at)`).
|
||||
Geen datawijziging, geen gedragsverandering buiten performance: het
|
||||
jobsoverzicht filtert vanaf deze release in SQL over de hele workspace in
|
||||
plaats van over een opgehaalde pagina, en dit is de index waarop die query
|
||||
draait. Op een grote `jobs.jobs` kost het aanmaken kort een write-lock;
|
||||
gebruik zo nodig `CREATE INDEX CONCURRENTLY` buiten Alembic om en markeer de
|
||||
migratie daarna als uitgevoerd.
|
||||
|
||||
## Upgrade naar 1.2.0
|
||||
|
||||
1. Migratie `0016_sources_lifecycle` (`alembic upgrade head`) maakt `content.sources`,
|
||||
`source_sync_runs`, `source_items`, voegt `documents.source_id` (NOT NULL, FK) toe en
|
||||
backfillt die uit `source_key` met dezelfde regel die de runtime gebruikt
|
||||
(UUID-vormige key = caller-bron; anders de ingebouwde *Uploads*-bron van de space).
|
||||
Voor iedere backfilled bron ontstaat een registry-record (kind `upload`).
|
||||
2. Qdrant-punten die vóór 1.2.0 zijn geïndexeerd dragen nog het oude synthetische
|
||||
`source_id` (uuid5 per document). Draai na de migratie een authoritative
|
||||
reconcile/rebuild van de actieve collectie (`IndexBuildService.reconcile`/`build`,
|
||||
beide gebruiken nu de canonical IndexPoint-mapping) zodat `source_ids`-filters en
|
||||
provenance ook voor bestaande content kloppen; tot die tijd matchen filters op die
|
||||
oude punten niet.
|
||||
3. Worker en app opnieuw uitrollen (nieuwe job-operation `sync_source`; nieuwe
|
||||
Control Plane-routes `/admin/sources`, `/admin/documents`, `/admin/system`).
|
||||
4. SDK-consumers: de citation-schema's kregen additieve optionele velden
|
||||
(`source_id`, `source_name`, `source_kind`, `locator`, `revision`, `display`).
|
||||
Reference in new issue
Block a user