Verzió 1.0.0-alpha.1legújabb
2.28. fejezet
A kiegészítő kiadása
Hogyan jut el egy beépülő modul vagy csomag a sikeres buildtől a futtató egységekig, és hogyan vonható vissza. Verziók, kiadási ellenőrzés, csatornák és telepítések, aláírás, változtatási jóváhagyások, a szállítási identitásrekord, migrációk, visszaállítás és egy verzió kivezetése.
Ezt az oldalt AI fordította az eredeti angol szövegből. Ha bármi nem egyértelmű, az angol nyelvű oldal az irányadó. Oldal olvasása angolul

A Cold chain 0.4.0 volt az első olyan kiadásunk, amely többet kért, mint az előző. Hozzáadta a levelek küldését és egy külső címet a hűtőkonténer-riasztásokhoz. A build sikeres volt, a tesztek mindhárom szintetikus ágon lefutottak, mégis két napig a fejlesztői térben maradt, amíg ketten átolvasták, mit kér, egy harmadik személy pedig jóváhagyta a címet. A Nexuson a kiadásnak pontosan ilyennek kell lennie: a kód a könnyű rész, a kiadást a bizonyítékok és a jóváhagyások jelentik.
Ez a fejezet mindent lefed a sikeres buildtől addig, hogy egy verzió minden egységen fut, valamint a visszalépés módjait is. Magát az előléptetési útvonalat, a fejlesztői tértől a staging környezeten és egy pilot egységen át az összes egységig, a 2.24. fejezet (Egyedi vertikális megoldás teljes felépítése) mutatja be, ezért annak kapuit itt nem ismétlem meg. Egyetlen szabály keretezi az egészet. A telepítés kizárólag a telepítés kiadási csatornáin keresztül történik. Sürgős javításhoz sincs kiskapu, és senki sem szerkeszt kézzel futó image-et.
Verziók
Egy csomagkiadásban három verziószám változik, és érdemes ezeket fejben elkülöníteni.
| Mi | Hol található | Példa | Szabály |
|---|---|---|---|
| A bővítmény | version, itt: nexus.manifest.json |
0.4.0 |
Szemantikus verzió; megengedett egy előzetes kiadási utótag, például -rc.1 |
| A csomag | version, itt: pack.json |
0.4.0 |
A csomag nézeteivel, szavaival és klasztereivel együtt változik |
| A tudásmodell | A modell saját verziója | 1.3 → 1.4 |
Csak gráfmódosítási kérelemmel változik |
A fejlesztői build utótagot visel, 0.4.0-dev, amíg el nem éri a staging környezetet. Ha a bővítményt és a csomagot együtt szállítja, tartsa a verzióikat azonosan; így minden kiadási felülvizsgálaton megspórolhat egy vitát arról, melyik számhoz tartoznak a bizonyítékok.
Két másik verziót nem választanak, hanem rögzítenek. A csomag sablonverziója (a Cold chain esetében domain-pack@1.6.0) a csomag létrehozásakor rögzül, és csak felülvizsgált módosításként változik. Az SDK (szoftverfejlesztői készlet) pontos verzióval van telepítve, soha nem tartománnyal, így ugyanaz a build a következő hónapban is ugyanazt az eredményt adja:
npm install --save-exact @adverant-nexus/plugin-sdk@2.50.0A Skills Engine képességeinek is van verziója, ezek azonban másként viselkednek. Minden közzétett verzió rögzített, a live, a canary és a shadow pedig a verziókon lévő címkék. A visszaváltás egy címkét helyez át, a már folyamatban lévő futások pedig azon a verzión fejeződnek be, amelyen elindultak.
Mielőtt ellenőrzést kérne: a leírófájl (manifest)
A Manifest és engedélyek oldal összeveti, amit ez a kiadás deklarál, az előző kiadással: a hatóköreit, a tárolóit, a kimenő címeit és a sandboxprofilját. Olvassa el, mielőtt bárkit felülvizsgálatra kérne, mert pontosan megmutatja, mit kell majd a felülvizsgálóknak elfogadniuk.
Az a kiadás, amely többet kér, mint amit a manifestje korábban deklarált, a helyén marad a következővel: MANIFEST_SCOPE_WIDENED, amíg két felülvizsgáló el nem fogadja a bővebb manifestet. Egy külső címhez az ügyfélnél a külső címekért felelős személy jóváhagyása is szükséges; ez a jóváhagyás meghatározott időre szól, a miénk 12 hónapra. Két út áll Ön előtt: eltávolítja a sorokat, vagy felülvizsgálatot kér. Az oldal mindkét gombot felkínálja.
Az oldal minden sorát futásidőben is kikényszeríti a rendszer, nem csupán felülvizsgálja. Minden eszközhívást ellenőriz a deklarált hatókörökkel szemben, a külső címet blokkolja, ha nincs felsorolva, és a sandboxprofil más hálózatot nem engedélyez. Az a bővítmény, amely olyasmit próbál elérni, amit nem deklarált, elutasításban részesül, és az egyetlen megoldás egy új kiadás, amely deklarálja azt.
Kiadási ellenőrzés
A Kiadási felülvizsgálat oldal egy kiadás bizonyítékait egyetlen táblázatban jeleníti meg egy olyan felülvizsgáló számára, aki nem a szerző.
| Bizonyíték | Amit a 0.4.0 esetében mutatott |
|---|---|
| Tesztek | 66/66, három szintetikus ágon |
| Minőségellenőrzések | A dokumentáció és a kód összhangban van |
| Szabályzat | Minden nézet csak szűkít; a személyes mezők alapértelmezés szerint ki vannak kapcsolva |
| Aláírások | Az image-et és a csomagot a pipeline írta alá |
| Hatókör-eltérés | Hozzáadja a levelek küldését és egy külső címet, annak jóváhagyásával |
| Kompatibilitás | A platformverzió és az alapcsomag verziója, amelyekkel tesztelték |
| Modellmódosítás | A gráfmódosítási kérelem próbafuttatása: 1284 kapcsolat átnevezve, semmi sem lett eltávolítva |
A táblázat alatt találhatók a módosításhoz fűzött megjegyzések és az eredetadatok: melyik pipeline készítette, melyik módosításból, az image digestje és a sablon. A felülvizsgálók a passkey-jükkel hagyják jóvá. Két, a szerzőtől különböző felülvizsgáló jóváhagyása után a pipeline áthelyezi a kiadást a staging környezetbe. A szerző soha nem számít felülvizsgálónak, és erre irányuló kísérlet esetén a rendszer a következővel utasítja el: NEEDS_SECOND_PERSON. A felülvizsgálati kérelem 3 nap után lejár.
A felülvizsgálók kérdéseire a megjegyzésekben válaszoljon, ne csevegőablakban. A felülvizsgálatunk során a megfelelőségi felelősünk megkérdezte, miért minősül a kárigény összege kereskedelmi adatnak, a második felülvizsgáló pedig a modellmódosítás visszaállítási tervét kérte. Mindkét válasz a kiadás nyilvántartásának része lett, és a következő felülvizsgáló ott fogja keresni őket.
Változtatási szabályzat jóváhagyásai
A kiadási felülvizsgálat a kiadás egészére vonatkozik. A manifest changePolicy blokkja ennél tovább megy: meghatározza, hogy a bővítmény telepíthető elemeinek mely módosítási osztályai igényelnek jóváhagyást, és hány személytől.
"changePolicy": {
"enabled": true,
"classes": ["website", "bff", "migration"],
"approvals": { "website": 1, "bff": 1, "migration": 2 }
}A három osztály a website (a webalkalmazás), a bff (a frontendhez tartozó backend) és a migration (adatbázis-migráció). A classes által megnevezett minden osztálynak saját számmal kell rendelkeznie a approvals részben, 1 és 10 között. A kihagyott osztály szabályozatlan, és a séma arra kényszeríti, hogy ezt tudatos döntésként írja le, ne pedig kihagyással jusson el hozzá. Migrációkhoz két jóváhagyást kérünk, mert a migráció az egyetlen olyan módosítás, amelyet nehéz visszavonni.
A jóváhagyásokat különböző személyekben számolják, és a javaslattevő soha nem tartozik közéjük. Az ezt alátámasztó szabályokat érdemes ismerni, mert mindegyikhez tartozik egy elutasítás:
- A módosítást javasló személy jóváhagyását a rendszer a következővel utasítja el:
TRUST_APPROVAL_SELF_APPROVAL. - Annak a személynek a jóváhagyását, aki egyáltalán nem végezhet ilyen osztályú módosítást, a rendszer a következővel utasítja el:
CHANGE_CLASS_NOT_PERMITTED. - Ha a módosítás bármely commitját a szervezet ügynökidentitása írta alá, a kvórum a szokásos minimum plusz egy, és az ügynök saját szavazata nem számít.
- Minden jóváhagyás rögzíti az általa látott diffet és headet. Ha a módosítás az utolsó jóváhagyás után megváltozik, az egyesítését a rendszer a következővel utasítja el:
HASH_MISMATCH, és a jóváhagyásokat az új tartalomra újra be kell gyűjteni.
Ez a harmadik szabály akkor fontos, ha AI (mesterséges intelligencia) alapú kódolóeszközzel fejleszt, ahogyan azt a 2.26. fejezet (Fejlesztés AI kódolóeszközökkel) ismerteti. Az ügynök által írt munkához eggyel több emberi jóváhagyás szükséges, mint az ember által írthoz. Számoljon ezzel.
Aláírás és hitelesítés
Minden image-et és csomagot az azt elkészítő pipeline ír alá, és az aláírt image a staging környezetbe vezető kapuk egyike. A fejlesztői tér kezdettől fogva csak aláírt image-eket futtat. Enterprise kiadásban egy rendszergazda minden névteret úgy állít be, hogy az aláíratlan image-eket vagy naplózza, vagy elutasítsa, és a névtereket egyenként állítja át elutasításra, így végül az éles környezet csak a pipeline által készített és aláírt image-eket futtatja. Az aláírás a build része, nem olyasmi, amit egy kiadás előtt ad hozzá.
Az egészen végighúzódó szabály az, hogy a sikertelen aláírás elutasítás, soha nem figyelmeztetés. Az az ellenőrzés, amely SIG_INVALID eredményt kap, leáll. Nem tér vissza az aláíratlan verzióra, és nem folytatja egy naplóbejegyzéssel, mert a build naplójában lévő figyelmeztetés mindenki számára átengedést jelent, aki nem olvasta el.
Ugyanez a szabály vonatkozik mindenre, amit adathordozón ad át. Egy air-gapped ügyfélnek szánt lezárt csomagot a rendszer az Ön nyilvános kulcsával ellenőriz, mielőtt bármit kicsomagolna, a parancsot pedig a 2.25. fejezet (Fejlesztés az egyes kiadásokhoz) mutatja be.
Szállítási identitás
Egy bővítmény több olyan elemen keresztül kerül szállításra, amelyek mindegyikének van neve: a tárolói, egy aláírókulcs, egy telepítési névtér, egy registry-előtag, egy adatbázisséma, tartományok halmaza és egy módosítási szabályzat. Bármelyikük olyan pont, ahol két bővítmény ütközhet, vagy egy bővítmény eltérhet. A szállítási identitás bővítményenként egyetlen aláírt rekord, amely mindezeket tartalmazza, így a kiadási útvonal minden ellenőrzése ugyanazt a választ olvassa, és eltérés esetén elutasít.
Az Ön része a manifesten keresztül kerül be, és semmi máson keresztül: schema, db, domains, changePolicy és a tároló URL-je. A platform a többivel egészíti ki a rekordot, és aláírja. Soha nem Ön nevezi meg a saját névterét, registry-előtagját vagy aláírókulcsát. Ezeket Önhöz rendelik, és az a manifest, amely megpróbálná deklarálni őket, olyan állítást tenne, amelyet az ellenőrzéseknek aztán el kellene vetniük.
Az aláírt rekord tizenegy mezőt tartalmaz: a bővítmény slugját, a tulajdonos szervezetet, az azt fejlesztő szervezetet, a tárolóit, az aláírókulcsa nevét, a telepítési névterét, a registry-előtagját, az adatbázissémáját, a tartományait, a módosítási szabályzatát, valamint azon régebbi image-nevek rövid listáját, amelyeket a registry-előtagja létezése előtt használt. Ez utóbbi lista csak csökkenhet. Mivel alá van írva, egy új aláírás eltávolíthat belőle egy bejegyzést, de semmi sem adhat hozzá egyet észrevétlenül. Az aláírás Ed25519 a tizenegy mező szabványos kanonikus JSON-formáján, így egy "Tomás" vagy "Sinéad" nevet tartalmazó rekord mindenhol ugyanúgy ellenőrizhető.
Ha egy kiadás nem egyezik a rekordjával, az első elutasítás érvényesül:
| Kód | Mikor | HTTP |
|---|---|---|
DELIVERY_IDENTITY_MISSING |
Nincs rekord a bővítményhez | 403 |
DELIVERY_PATH_REFUSED |
Image feltöltése a registry-előtagon kívülre, amely nem szerepel a régebbi nevek aláírt listáján | 403 |
NAMESPACE_MISMATCH |
Másik névteret célzó telepítés | 403 |
IMAGE_NAME_COLLISION |
Olyan image-név, amelyet már egy másik bővítmény igényel | 409 |
CHANGE_CLASS_NOT_PERMITTED |
Olyan módosítási osztály, amelyet a szabályzat nem szabályoz | 403 |
A IMAGE_NAME_COLLISION az, amely meglepi az embereket. Válasszon másik nevet, és soha ne használjon fel újra egyet: a közös image-név azt jelenti, hogy az egyik bővítmény előléptetése egy másik bővítmény podjait is áthelyezheti.
Véglegesített és hatókörhöz kötött migrációk
A migráció a bővítmény image-ében kerül szállításra, és az új verzió indulása előtt fut le, az SDK egyetlen migrációfuttatóján, a nexus-migrate eszközön keresztül. Saját alkalmazót nem kell írnia. Mielőtt bármely kiadás továbbléphetne, ugyanez a futtató egyenként alkalmazza a migrációkat egy eldobható adatbázison, így a sikertelen migráció ott hiúsul meg. A sablon shadow buildje fájlonként egyszer, sorrendben hívja meg a futtatót, és minden fájlt úgy rögzít, ahogyan az éles környezet fogja.
A futtató szabályai ugyanazok, amelyeket a kapuk ellenőriznek, kódként megírva:
- A séma migrátor szerepkörével kapcsolódik, és minden fájlt a séma tulajdonosaként futtat. Minden más bejelentkezést elutasít, elsősorban a superuserét. Azt a fájlt, amely maga próbál szerepkört váltani, elutasítja, mielőtt bármi lefutna.
- A 0-s számú tenancy-fájlt alkalmazása után soha nem szerkesztik. A tenancy módosítása saját revíziós fájlt kap,
000_tenancy_r<N>.sql, amelyet anexus-tenancy render --revision <N>ír meg Ön helyett. - Általában a futtató kezeli az egyes fájlok tranzakcióját, és elutasítja a benne lévő
BEGINvagyCOMMITutasítást. Az a fájl, amely saját tranzakcióit kezeli, deklarálja, hogy utasításonként fut, és ekkor minden általa megnyitottBEGINutasításnak párral kell rendelkeznie. - Naplót vezet, fájlonként egy sorral, a fájl SHA-256 értékével és a futtatás módjával. Az alkalmazott fájlt soha nem módosítják helyben; a módosítás egy új, sorszámozott fájl.
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-tenancy render --manifest nexus.manifest.json --revision 2 --out migrations/000_tenancy_r2.sqlA hatókörhöz kötöttség azt jelenti, hogy minden új tábla tartalmazza a organization_id, owner_user_id és business_unit_id oszlopot, valamint a is_demo jelölőoszlopot, kivéve, ha a gates/demo-exempt.json indoklással mentesíti a táblát; elsődleges kulcsa a szervezettel kezdődik, idegen kulcsai hordozzák azt, és a sorszintű biztonság kötelezően be van kapcsolva rajta. A migrations-are-scoped kapu minden fájlon ellenőrzi ezeket a szabályokat, a migrations-commit-what-they-open pedig megszámolja, hogy minden fájl véglegesíti-e, amit megnyit. A második kapu azért létezik, mert egyszer egy csendben visszagörgetett migráció 0 kóddal lépett ki, és a tábla, amelyet létre kellett volna hoznia, soha nem jött létre.
Még egy fájl tartozik minden kiadáshoz. A scripts/ci/required-env kiírja a szolgáltatás indításához szükséges környezeti változókat, a konfigurációbetöltőből vett JSON-tömbként. A kiadási útvonal futtatja, és elutasítja azt a kiadást, amelynek telepítése nem állítja be mindegyiket, így a hiányzó változó még a kiadás előtt kiderül, nem pedig egy el nem induló pod miatt.
node scripts/ci/required-envKépességek (skills) kiadása
A kétféle képesség eltérő úton jut el az emberekhez, ezért különbözőképpen adja ki őket.
A manifestképesség, a bővítmény skills[] tömbmezőjének egy típusos sora, a bővítménnyel együtt kerül szállításra, és annak többi részével azonos előléptetésen megy át. Az onboarding minden kiadáskor a teljes képességkészletet szinkronizálja a registryvel. Ha egy képességet kihagy a készletből, az letiltásra kerül, és Enterprise kiadásban egy hibás képességet tartalmazó szinkronizálás egyiket sem veszi át, így az előző verzió fut tovább, nem pedig az új verzió fele.
A Skills Engine skillt a könyvtárból teszik közzé. Enterprise csomagban az a skill, amely írási eszközt ad hozzá, addig várakozik, amíg két megnevezett személy jóvá nem hagyja a passkey-ével, és a javaslattevő nem lehet közöttük. A jóváhagyott verzió ezután shadow módban fut, majd canary módban egy egységnél, megnevezett kapuk mögött, majd mindenkinél, és leállítja önmagát, ha egy kapu feltétele nem teljesül. Ha az Ön pluginja és egy Skills Engine skill egymástól függ, először a skillt tegye közzé, és várja meg, amíg mindenkihez eljut, mielőtt az azt meghívó plugin-kiadás kikerül a pilotból.
Csatornák és telepítések
Miután egy kiadás túljutott a piloton és elérte az összes egységet, egy csatornán válik elérhetővé, és minden egység maga választja ki a csatornáját. Minden váltáshoz az egység adminisztrátorának hozzájárulása szükséges. A Csatornák és telepítések oldal megmutatja, mely egységek melyik verziót futtatják, a hibaarányokat pedig csak darabszámként jeleníti meg: Ön azt látja, hogyan viselkedik a bővítménye, azt soha, hogy bárki mit csinált vele.
A carrier-sync pluginunk egyszerre három verzióban fut, és ez természetes. A legtöbb egység az aktuális kiadást használja, egy egység egy régebbi verzión marad egy megadott dátumig fenntartott csatornán, egy kiadásra jelölt verzió pedig olyan csatornán van, amelyet még senki sem választott. Ne küzdjön ellene; egy egységnek, amelynek egy audit miatt stabilitásra van szüksége, joga van ehhez.
A kiegészítő naplói és metrikái
A csomag naplói és metrikái oldal a saját munkaterheléseire korlátozódik, azokban az egységekben, ahol betekinthet. Szűrhet egység és környezet szerint, és darabszámokat, időzítéseket és állapotokat lát.
A személyes mezők cseréje még a sor kiírása előtt megtörténik, az ügyféltartalmak, például a kárigények szövege, a levelek vagy a dokumentumok tartalma pedig soha nem kerülnek a naplókba. A naplók megőrzési ideje 14 nap. A szervezetet az átjáró állítja be, soha nem az Ön lekérdezése, így egy másik szervezetet megnevező lekérdezést a rendszer TENANT_BOUNDARY hibával elutasít. A dokkban lévő asszisztens ugyanezeket a naplókat olvashatja Önnel együtt, és csak ezeket: amikor megkérdeztem tőle, miért érkeztek késve az eltérési rekordok egyik reggel, 18 percnyi újrapróbálkozást vezetett vissza az egyik rakpart áramellátásából származó ismétlődő mérésekre.
Visszaállítás (rollback)
Kétféle visszaállítás létezik, és mindkettő felülvizsgált módosítás, nem pedig kapcsoló.
Egy környezet visszaállítása az előző verziót használja. Minden környezet 30 napig megőrzi azt. A visszaállítás a kiadás módosításaként készül el, előre megmutatja, mit fog tenni, és egy második személyre van szükség hozzá; jóváhagyás után a pipeline körülbelül egy perc alatt végrehajtja a visszaállítást. Minden visszaállítás időmérés alatt áll, ahogy minden gyakorlat is, ezért gyakorolja be, mielőtt szüksége lenne rá. Egyetlen egység visszaállítása a Csatornák és telepítések oldalon történik. A visszaállítási modális ablak megadja, mi változik (az adott egység ismét a régebbi verziót futtatja, és hibaarányát egy órán át figyelik), mi marad (a többi egység, valamint az egység beállításai és rekordjai), az indoklást, és hogy ki a második személy: az adott egység adminisztrátora.
A beállítások és a rekordok megmaradnak a visszaállítás során, ezért minden kiadást abból a feltételezésből kiindulva tervezzen meg, hogy az előző verzió ismét futhat az újabb által írt adatokon. Ez a gyakorlati oka annak, hogy a migrációk additívak maradjanak egy olyan kiadáson belül, amelyet esetleg visszaállít, és ezért kérjük, hogy mindegyiket két személy hagyja jóvá. A modellmódosítás ugyanígy működik: a felülvizsgáló kérheti, és kérnie is kell, egy gráfmódosítási kérelem visszaállítási tervét, mielőtt jóváhagyja.
A skillek visszaállítása kíméletesebb. Az élő címke visszahelyezése egy korábbi verzióra egyetlen lépés, és a már folyamatban lévő futtatások azon a verzión fejeződnek be, amelyen elindultak.
Verzió kivezetése
Egy elkészült kiadást soha nem szerkesztünk. A már nem használandó verziót visszavonjuk, a javítás pedig új verziószámmal jelenik meg. Az SDK saját kiadási csatornái ugyanezt a szokást követik: a hibás SDK-verziót visszahúzzuk, és soha nem cseréljük le más tartalomra ugyanazon szám alatt. Kövesse ezt Ön is, mert egy olyan verziószám, amely két különböző buildet is jelenthet, értéktelenné tesz minden róla szóló bizonyítékot.
Egy plugin vagy csomag visszavonása leállítja az új telepítéseket. Az egységek megtartják az általuk futtatott verziót, amíg nem váltanak, így a visszavonás jelzés és határidő, nem pedig kikapcsoló. Közölje az egységek adminisztrátoraival, melyik verzióra és milyen határidőig kell váltaniuk.
Egy skill kivezetése ugyanezt az elvet követi, egy további lépéssel. A Skills Engine az összes megmaradt hívót áthelyezi egy helyettesítőre, miután lefuttatta a helyettesítő teszteseteit, leállítja az új futtatásokat, és megőrzi a verziókat, a teszteseteket és a lezárt futtatási rekordokat, így a skill visszaállítható, ha a helyettesítő hibásnak bizonyul.
Kiadási ellenőrzőlista
Ezt a listát olvassuk át minden Cold chain kiadás előtt. Azért rövid, mert a nagy részét a platform ellenőrzi helyettünk.
- A verziók egyeznek: a manifest, a
pack.json, és a tudásmodell, ha változott. - Minden kapu zöld helyben, tiszta állapotból indítva, és minden új tesztről igazoltuk, hogy először elbukott.
- A Manifest és jogosultságok oldal nem mutat bővülést, vagy a bővülés szándékos, és a felülvizsgálók tudják, miért.
- Minden migráció új, sorszámozott fájl, hatóköre meghatározott, és hibátlanul lefut egy eldobható adatbázison.
- A
scripts/ci/required-envfelsorol minden változót, amelyre a szolgáltatásnak szüksége van, és a telepítés mindegyiket beállítja. - A visszaállítási terv szerepel a módosításban, beleértve minden modellmódosítást is.
- Ezen a héten rendelkezésre áll két felülvizsgáló, akik nem a szerzők.
Az utolsó pont jelentéktelennek tűnik. Mégis ez késleltette több kiadásunkat, mint az összes kapu együttvéve.



