Verzia 1.0.0-alpha.1najnovšia
Kapitola 2.28
Vydanie vášho rozšírenia
Ako sa zásuvný modul alebo balík dostane od úspešnej zostavy k jednotkám, ktoré ho spúšťajú, a ako sa z nich opäť stiahne. Verzie, kontrola pred vydaním, kanály a inštalácie, podpisovanie, schvaľovanie zmien, záznam o identite doručenia, migrácie, návrat k predchádzajúcej verzii (rollback) a vyradenie verzie.
Táto stránka bola preložená pomocou AI z anglického originálu. V prípade akýchkoľvek nejasností je rozhodujúca anglická verzia stránky. Prečítať túto stránku v angličtine

Cold chain 0.4.0 bolo prvé naše vydanie, ktoré žiadalo viac než to predchádzajúce. Pridalo odosielanie pošty a jednu externú adresu pre upozornenia z chladiarenských kontajnerov. Zostavenie bolo zelené, testy prešli na všetkých troch syntetických pobočkách, a napriek tomu zostalo dva dni v dev space, kým dvaja ľudia čítali, čo požaduje, a tretí schválil adresu. Presne takto má vydávanie v Nexus pôsobiť: kód je tá jednoduchšia časť a vydaním sú dôkazy a schválenia.
Táto kapitola pokrýva všetko medzi zeleným zostavením a verziou spustenou pre všetky jednotky, ako aj spôsoby návratu späť. Samotná cesta povýšenia, z dev space do staging, na pilotnú jednotku a na všetky jednotky, je predstavená v kapitole 2.24, Budovanie vlastnej vertikály od začiatku do konca, a jej brány tu nebudem opakovať. Celý proces rámcuje jedno pravidlo. Nasadenie prebieha výlučne cez kanály vydaní inštalácie. Pre urgentnú opravu neexistujú žiadne zadné dvierka a nikto neupravuje bežiaci obraz ručne.
Verzie
Pri vydaní balíka sa menia tri čísla verzií a oplatí sa ich v hlave držať oddelene.
| Čo | Kde sa nachádza | Príklad | Pravidlo |
|---|---|---|---|
| Plugin | version v nexus.manifest.json |
0.4.0 |
Sémantická verzia; prípona predbežného vydania, napríklad -rc.1, je povolená |
| Balík | version v pack.json |
0.4.0 |
Mení sa spolu s pohľadmi, slovami a klastrami balíka |
| Znalostný model | Vlastná verzia modelu | 1.3 na 1.4 |
Mení sa iba prostredníctvom žiadosti o zmenu grafu |
Vývojové zostavenie nesie príponu 0.4.0-dev, kým sa nedostane do staging. Keď sa plugin a balík dodávajú spolu, udržiavajte ich verzie rovnaké; ušetríte si tým pri každej revízii vydania spor o to, ku ktorému číslu dôkazy patria.
Dve ďalšie verzie sú pevne určené, nie zvolené. Verzia šablóny balíka (domain-pack@1.6.0 pre Cold chain) sa stanoví pri vytvorení balíka a mení sa iba ako revidovaná zmena. SDK (súprava na vývoj softvéru) sa inštaluje v presnej verzii, nikdy nie v rozsahu, aby rovnaké zostavenie dalo budúci mesiac rovnaký výsledok:
npm install --save-exact @adverant-nexus/plugin-sdk@2.50.0Aj zručnosti Skills Engine majú verzie, správajú sa však inak. Každá zverejnená verzia je nemenná a live, canary a shadow sú štítky na verziách. Návrat späť presunie štítok a behy, ktoré už prebiehajú, sa dokončia na verzii, na ktorej začali.
Pred požiadaním o kontrolu: manifest
Stránka Manifest a oprávnenia porovnáva, čo deklaruje toto vydanie, s posledným vydaním: jeho rozsahy, úložiská, odchádzajúce adresy a profil sandboxu. Prečítajte si ju skôr, než niekoho požiadate o revíziu, pretože vám presne povie, čo budú revízori žiadaní prijať.
Vydanie, ktoré žiada viac, než predtým deklaroval jeho manifest, sa zadrží na mieste s MANIFEST_SCOPE_WIDENED, kým širší manifest neprijmú dvaja revízori. Externá adresa navyše potrebuje schválenie toho, kto u zákazníka zodpovedá za externé adresy; toto schválenie sa udeľuje na pevne stanovené obdobie a naše platilo 12 mesiacov. Máte dve možnosti: odstrániť tieto riadky alebo požiadať o revíziu. Stránka ponúka obe tlačidlá.
Každý riadok na tejto stránke sa za behu vynucuje, nielen reviduje. Každé volanie nástroja sa kontroluje voči deklarovaným rozsahom, externá adresa je zablokovaná, ak nie je uvedená, a profil sandboxu nepovoľuje žiadnu inú sieť. Plugin, ktorý sa pokúsi dostať k niečomu, čo nedeklaroval, je odmietnutý a jedinou nápravou je nové vydanie, ktoré to deklaruje.
Kontrola pred vydaním
Stránka Revízia vydania zhromažďuje dôkazy k jednému vydaniu v jednej tabuľke pre revízora, ktorý nie je autorom.
| Dôkaz | Čo ukázal pre 0.4.0 |
|---|---|
| Testy | 66 zo 66 na troch syntetických pobočkách |
| Kontroly kvality | Dokumentácia a kód sú v súlade |
| Politika | Každý pohľad iba zužuje; osobné polia sú predvolene vypnuté |
| Podpisy | Obraz a balík podpísané pipeline |
| Rozdiel rozsahov | Pridáva odosielanie pošty a jednu externú adresu s jej schválením |
| Kompatibilita | Verzia platformy a verzia základného balíka, voči ktorým bolo testované |
| Zmena modelu | Skúšobný beh žiadosti o zmenu grafu: 1 284 premenovaných prepojení, nič nebolo odstránené |
Pod tabuľkou sú komentáre k zmene a pôvod: ktorá pipeline ju zostavila, z ktorej zmeny, digest obrazu a šablóna. Revízori schvaľujú pomocou svojho prístupového kľúča (passkey). Schvaľujú dvaja revízori, ktorí nie sú autormi, a pipeline potom presunie vydanie do staging. Autor sa nikdy nepočíta ako revízor a pokus o to je odmietnutý s NEEDS_SECOND_PERSON. Žiadosť o revíziu vyprší po 3 dňoch.
Na otázky revízorov odpovedajte v komentároch, nie v okne chatu. Počas našej revízie sa náš compliance officer pýtal, prečo bola suma nároku klasifikovaná ako obchodná, a druhý revízor žiadal plán návratu pre zmenu modelu. Obe odpovede sú teraz súčasťou záznamu vydania, kde sa bude pozerať ďalší revízor.
Schválenia politiky zmien
Revízia vydania pokrýva vydanie ako celok. Blok changePolicy v manifeste ide ďalej: určuje, ktoré triedy zmien nasaditeľných súčastí vášho pluginu vyžadujú schválenie a od koľkých ľudí.
"changePolicy": {
"enabled": true,
"classes": ["website", "bff", "migration"],
"approvals": { "website": 1, "bff": 1, "migration": 2 }
}Tri triedy sú website (webová aplikácia), bff (backend pre frontend) a migration (migrácia databázy). Každá trieda uvedená v classes musí mať vlastný počet v approvals, od 1 do 10. Trieda, ktorú vynecháte, nie je riadená a schéma vás núti zapísať to ako voľbu, nie dospieť k tomu opomenutím. Pri migráciách žiadame dve schválenia, pretože migrácia je jediná zmena, ktorú je ťažké vrátiť.
Schválenia sa počítajú podľa rôznych osôb a navrhovateľ medzi nich nikdy nepatrí. Pravidlá, ktoré to zabezpečujú, sa oplatí poznať, pretože každé má svoje odmietnutie:
- Schválenie od osoby, ktorá zmenu navrhla, je odmietnuté s
TRUST_APPROVAL_SELF_APPROVAL. - Osoba, ktorá zmenu danej triedy nesmie vykonať vôbec, je odmietnutá s
CHANGE_CLASS_NOT_PERMITTED. - Ak je ktorýkoľvek commit v zmene podpísaný identitou agenta organizácie, kvórum je obvyklé minimum plus jedna a vlastný hlas agenta sa nepočíta.
- Každé schválenie zaznamená diff a head, ktoré videlo. Ak sa zmena po poslednom schválení posunie, jej zlúčenie je odmietnuté s
HASH_MISMATCHa schválenia sa musia pre nový obsah zozbierať znova.
Toto tretie pravidlo je dôležité, ak vyvíjate pomocou nástroja na programovanie s AI (umelá inteligencia), ako popisuje kapitola 2.26, Vývoj s nástrojmi na programovanie s AI. Práca, ktorú napísal agent, potrebuje o jedno ľudské schválenie viac než práca, ktorú napísal človek. Počítajte s tým.
Podpisovanie a overovanie
Každý obraz a balík je podpísaný pipeline, ktorá ho zostavila, a podpísaný obraz je jednou z brán do staging. Dev space od začiatku spúšťa iba podpísané obrazy. V edícii Enterprise administrátor nastaví každý namespace tak, aby nepodpísané obrazy buď zaznamenával, alebo odmietal, a namespaces prepína na odmietanie postupne jeden po druhom, takže v produkcii nakoniec bežia iba obrazy, ktoré pipeline zostavila a podpísala. Podpisovanie je súčasťou zostavenia, nie niečo, čo pridáte pred vydaním.
Pravidlo, ktoré sa tým všetkým tiahne, znie: podpis, ktorý zlyhá, je odmietnutím, nikdy nie varovaním. Kontrola, ktorá dostane SIG_INVALID, sa zastaví. Neprejde na nepodpísanú verziu a nepokračuje s poznámkou v logu, pretože varovanie v logu zostavenia je priepustkou pre každého, kto ho nečítal.
Rovnaké pravidlo platí pre všetko, čo odovzdávate na médiách. Zapečatený balík pre zákazníka s air-gapped prostredím sa pred rozbalením čohokoľvek overí voči vášmu verejnému kľúču a kapitola 2.25, Vývoj pre jednotlivé edície, ukazuje príslušný príkaz.
Identita doručenia
Plugin sa dodáva prostredníctvom viacerých vecí, z ktorých každá má názov: jeho repozitáre, podpisový kľúč, namespace nasadenia, prefix registra, databázová schéma, súbor domén a politika zmien. Ktorákoľvek z nich je miestom, kde by sa dva pluginy mohli dostať do kolízie alebo kde by sa jeden plugin mohol odchýliť. Identita dodávky je jeden podpísaný záznam na plugin, ktorý ich všetky obsahuje, takže každá kontrola na ceste vydania číta rovnakú odpoveď a pri nezhode odmietne.
Svoju časť prispievate výlučne cez manifest: schema, db, domains, changePolicy a URL repozitára. Platforma doplní zvyšok záznamu a podpíše ho. Nikdy sami neurčujete svoj namespace, prefix registra ani podpisový kľúč. Tie vám sú pridelené a manifest, ktorý by sa ich pokúsil deklarovať, by vznášal tvrdenie, ktorému by kontroly potom museli neveriť.
Podpísaný záznam obsahuje jedenásť polí: slug pluginu, vlastniacu organizáciu, organizáciu, ktorá ho zostavuje, jeho repozitáre, názov jeho podpisového kľúča, jeho namespace nasadenia, jeho prefix registra, jeho databázovú schému, jeho domény, jeho politiku zmien a krátky zoznam starších názvov obrazov, ktoré používal predtým, ako existoval jeho prefix registra. Tento posledný zoznam sa môže iba zmenšovať. Keďže je podpísaný, nový podpis môže položku odstrániť, ale nič ju nemôže potichu pridať. Podpis je Ed25519 nad štandardnou kanonickou formou JSON týchto jedenástich polí, takže záznam s "Tomás" alebo "Sinéad" sa všade overí rovnako.
Ak vydanie nezodpovedá svojmu záznamu, platí prvé odmietnutie:
| Kód | Kedy | HTTP |
|---|---|---|
DELIVERY_IDENTITY_MISSING |
Pre plugin neexistuje žiadny záznam | 403 |
DELIVERY_PATH_REFUSED |
Push obrazu mimo prefixu registra, ktorý nie je na podpísanom zozname starších názvov | 403 |
NAMESPACE_MISMATCH |
Nasadenie zacielené na iný namespace | 403 |
IMAGE_NAME_COLLISION |
Názov obrazu, ktorý si už nárokuje iný plugin | 409 |
CHANGE_CLASS_NOT_PERMITTED |
Trieda zmeny, ktorú politika neriadi | 403 |
IMAGE_NAME_COLLISION je to, ktoré ľudí prekvapí. Zvoľte iný názov a nikdy žiadny nepoužívajte opakovane: zdieľaný názov obrazu znamená, že povýšenie jedného pluginu môže presunúť pody iného pluginu.
Migrácie, potvrdené a s vymedzeným rozsahom
Migrácia sa dodáva vo vnútri obrazu vášho pluginu a spúšťa sa pred štartom novej verzie, prostredníctvom jediného nástroja na spúšťanie migrácií v SDK, nexus-migrate. Vlastný nástroj na aplikovanie nepíšete. Skôr než sa akékoľvek vydanie môže posunúť, ten istý nástroj aplikuje vaše migrácie po jednom súbore na dočasnú databázu, takže migrácia, ktorá zlyhá, zlyhá tam. Tieňové zostavenie šablóny volá tento nástroj raz pre každý súbor, v poradí, a každý súbor zaznamená tak, ako to urobí produkcia.
Pravidlá nástroja sú tie, ktoré kontrolujú brány, zapísané ako kód:
- Pripája sa ako rola migrátora vašej schémy a každý súbor spúšťa ako vlastník schémy. Akékoľvek iné prihlásenie, predovšetkým superuser, je odmietnuté. Súbor, ktorý sa sám pokúsi prepnúť roly, je odmietnutý ešte predtým, ako sa čokoľvek spustí.
- Súbor tenancy s číslom 0 sa po aplikovaní už nikdy neupravuje. Zmena tenancy dostane vlastný revízny súbor,
000_tenancy_r<N>.sql, ktorý za vás napíšenexus-tenancy render --revision <N>. - Za normálnych okolností nástroj vlastní transakciu každého súboru a odmietne v nej
BEGINaleboCOMMIT. Súbor, ktorý spravuje vlastné transakcie, deklaruje, že sa spúšťa po jednotlivých príkazoch, a potom každýBEGIN, ktorý otvorí, musí mať svoj pár. - Vedie register, jeden riadok na súbor, so SHA-256 súboru a spôsobom, akým bol spustený. Aplikovaný súbor sa nikdy nemení na mieste; zmena je nový očíslovaný súbor.
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-tenancy render --manifest nexus.manifest.json --revision 2 --out migrations/000_tenancy_r2.sqlOhraničený znamená, že každá nová tabuľka obsahuje organization_id, owner_user_id a business_unit_id, plus stĺpec so značkou is_demo, pokiaľ gates/demo-exempt.json tabuľku s uvedením dôvodu neoslobodí, s primárnym kľúčom, ktorý začína organizáciou, a cudzími kľúčmi, ktoré ju nesú, a s vynútenou bezpečnosťou na úrovni riadkov. Brána migrations-are-scoped kontroluje tieto pravidlá vo všetkých súboroch a migrations-commit-what-they-open overuje, že každý súbor potvrdí to, čo otvorí. Druhá brána existuje preto, lebo migrácia, ktorá sa potichu vrátila späť, raz skončila s kódom 0 a tabuľka, ktorú mala vytvoriť, nikdy neexistovala.
Ku každému vydaniu patrí ešte jeden súbor. scripts/ci/required-env vypíše premenné prostredia, ktoré vaša služba potrebuje na spustenie, ako pole JSON prevzaté z vášho načítavača konfigurácie. Cesta vydania ho spustí a odmietne vydanie, ktorého nasadenie nenastavuje každú z nich, takže chýbajúca premenná sa zachytí pred vydaním, nie až podom, ktorý sa nespustí.
node scripts/ci/required-envVydávanie zručností
Dva druhy zručností sa k ľuďom dostávajú rôznymi cestami, preto ich vydávajte rozdielne.
Zručnosť z manifestu, typovaný riadok vo vašom skills[] pluginu, sa dodáva s pluginom a prechádza rovnakým povýšením ako jeho zvyšok. Onboarding pri každom vydaní synchronizuje celú sadu zručností do registra. Ak zručnosť zo sady vynecháte, bude vypnutá, a v edícii Enterprise synchronizácia s jednou chybnou zručnosťou neprevezme žiadnu z nich, takže ďalej beží predchádzajúca verzia namiesto polovice novej.
Zručnosť Skills Engine sa publikuje z knižnice. V edícii Enterprise zručnosť, ktorá pridáva nástroj na zápis, čaká, kým ju svojimi prístupovými kľúčmi (passkeys) schvália dve menovite určené osoby, pričom navrhovateľ nemôže byť jednou z nich. Schválená verzia potom beží v tieňovom režime, potom v režime canary pre jednu jednotku za menovite určenými bránami, potom pre všetkých a ak niektorá brána nie je splnená, sama sa zastaví. Ak sú váš plugin a zručnosť Skills Engine navzájom závislé, najprv publikujte zručnosť a nechajte ju dostať sa ku všetkým, až potom môže vydanie pluginu, ktoré ju volá, opustiť pilotnú fázu.
Kanály a inštalácie
Keď vydanie prejde pilotnou fázou a dostane sa do všetkých jednotiek, ponúka sa v kanáli a každá jednotka si svoj kanál vyberie. Jej administrátor súhlasí s každým presunom. Stránka Kanály a inštalácie zobrazuje, ktoré jednotky používajú ktorú verziu, pričom chybovosť uvádza iba ako počty: vidíte, ako sa vaše rozšírenie správa, nikdy však nie to, čo s ním ktokoľvek robil.
Náš plugin carrier-sync beží súčasne v troch verziách a je to normálne. Väčšina jednotiek používa aktuálne vydanie, jedna jednotka zostáva na staršej verzii v kanáli udržiavanom do stanoveného dátumu a kandidát na vydanie je v kanáli, ktorý si zatiaľ nikto nevybral. Nebojujte proti tomu; jednotka, ktorá potrebuje stabilitu kvôli auditu, má na ňu nárok.
Záznamy (logy) a metriky vášho rozšírenia
Stránka protokolov a metrík vášho balíka je obmedzená na vaše vlastné úlohy v jednotkách, do ktorých smiete nahliadať. Môžete filtrovať podľa jednotky a prostredia a vidíte počty, časy a stavy.
Osobné polia sa nahradia pred zapísaním riadku a obsah zákazníkov, ako je text reklamácie, pošta alebo obsah dokumentov, sa do protokolov nikdy nezapisuje. Protokoly sa uchovávajú 14 dní. Organizáciu nastavuje brána, nikdy nie váš dotaz, takže dotaz, ktorý uvádza inú organizáciu, sa odmietne s TENANT_BOUNDARY. Asistent v paneli môže čítať tie isté protokoly spolu s vami, a iba tieto: keď som sa ho opýtal, prečo jedného rána prišli záznamy o odchýlkach neskoro, vystopoval 18 minút opakovaných pokusov k duplicitným meraniam z napájania jedného nábrežia.
Návrat k predchádzajúcej verzii (rollback)
Existujú dva druhy vrátenia a obe sú posudzované zmeny, nie prepínače.
Vrátenie prostredia používa predchádzajúcu verziu. Každé prostredie ju uchováva 30 dní. Vrátenie sa pripraví ako zmena vydania, zobrazí ukážku toho, čo vykoná, a vyžaduje druhú osobu; po schválení pipeline vykoná vrátenie približne za minútu. Každé vrátenie sa meria, rovnako ako každé cvičenie, preto si ho precvičte skôr, než ho budete potrebovať. Vrátenie jednej jednotky sa vykonáva na stránke Kanály a inštalácie. Modálne okno vrátenia uvádza, čo sa zmení (daná jednotka opäť používa staršiu verziu a jej chybovosť sa hodinu sleduje), čo zostane (ostatné jednotky a nastavenia a záznamy jednotky), dôvod a kto je druhou osobou: administrátor danej jednotky.
Nastavenia a záznamy sa pri vrátení zachovávajú, preto každé vydanie plánujte s predpokladom, že predchádzajúca verzia môže opäť bežať nad údajmi, ktoré zapísala novšia. To je praktický dôvod, prečo udržiavať migrácie v rámci vydania, ktoré možno budete vracať, iba doplnkové, a dôvod, prečo žiadame, aby každú schválili dve osoby. Zmena modelu je rovnaká: posudzovateľ môže, a mal by, pred schválením požiadať o plán vrátenia požiadavky na zmenu grafu.
Zručnosti sa vracajú šetrnejšie. Presunutie označenia live späť na staršiu verziu je jeden krok a už prebiehajúce behy sa dokončia na verzii, s ktorou začali.
Vyradenie verzie
Vydanie sa po vytvorení nikdy neupravuje. Verzia, ktorá by sa už nemala používať, sa stiahne a oprava sa dodá ako nové číslo verzie. Vlastné kanály vydaní SDK dodržiavajú rovnaký zvyk: chybná verzia SDK sa stiahne (yank), nikdy sa nenahradí iným obsahom pod rovnakým číslom. Osvojte si to, pretože číslo verzie, ktoré môže znamenať dve rôzne zostavenia, robí každý dôkaz o nej bezcenným.
Stiahnutie pluginu alebo balíka zastaví nové inštalácie. Jednotky si ponechajú verziu, ktorú používajú, kým neprejdú inam, takže stiahnutie je signál a termín, nie vypínač. Oznámte administrátorom jednotiek, na ktorú verziu majú prejsť a dokedy.
Vyradenie zručnosti sa riadi rovnakou myšlienkou s jedným krokom navyše. Skills Engine po spustení testovacích prípadov náhrady presunie všetkých zostávajúcich volajúcich na náhradu, zastaví nové behy a uchová verzie, prípady a zapečatené záznamy o behoch, takže zručnosť možno obnoviť, ak sa náhrada ukáže ako chybná.
Kontrolný zoznam pre vydanie
Toto je zoznam, ktorý čítame pred každým vydaním Cold chain. Je krátky, pretože väčšinu z neho za nás kontroluje platforma.
- Verzie sa zhodujú: manifest,
pack.jsona znalostný model, ak sa zmenil. - Každá brána je lokálne zelená, od čistého stavu, a každý nový test najprv preukázateľne zlyhal.
- Stránka Manifest a oprávnenia nezobrazuje žiadne rozšírenie, alebo je rozšírenie presne to, čo sme zamýšľali, a posudzovatelia vedia prečo.
- Každá migrácia je nový očíslovaný súbor s vymedzeným rozsahom, bez problémov aplikovaný na dočasnú databázu.
scripts/ci/required-envuvádza každú premennú, ktorú služba potrebuje, a nasadenie nastavuje každú z nich.- Plán vrátenia je zapísaný v zmene, vrátane akejkoľvek zmeny modelu.
- Tento týždeň sú k dispozícii dvaja posudzovatelia, ktorí nie sú autormi.
Posledná položka znie triviálne. Práve ona však zdržala viac našich vydaní než všetky brány dohromady.



