Wersja 1.0.0-alpha.1najnowsza
Rozdział 2.28
Wydawanie rozszerzenia
Jak wtyczka lub pakiet przechodzi od pomyślnej kompilacji do jednostek, które je uruchamiają, i jak zostaje z nich wycofana. Wersje, przegląd wydania, kanały i instalacje, podpisywanie, zatwierdzenia zmian, rekord tożsamości dostawy, migracje, wycofywanie zmian (rollback) oraz wygaszanie wersji.
Ta strona została przetłumaczona przez AI z angielskiego oryginału. W razie jakichkolwiek niejasności wersją wiążącą jest strona w języku angielskim. Przeczytaj tę stronę po angielsku

Cold chain 0.4.0 było pierwszym naszym wydaniem, które prosiło o więcej niż poprzednie. Dodało wysyłanie poczty i jeden adres zewnętrzny, na potrzeby alertów dotyczących kontenerów chłodniczych. Kompilacja była zielona, testy przeszły na wszystkich trzech syntetycznych oddziałach, a mimo to wydanie przez dwa dni pozostawało w przestrzeni deweloperskiej, podczas gdy dwie osoby czytały, czego wymaga, a trzecia zatwierdzała adres. Tak właśnie ma wyglądać wydawanie w Nexus: kod jest łatwą częścią, a to dowody i zatwierdzenia stanowią wydanie.
Ten rozdział obejmuje wszystko, co dzieje się między zieloną kompilacją a wersją działającą we wszystkich jednostkach, oraz sposoby wycofania się. Sama ścieżka promocji, od przestrzeni deweloperskiej przez staging i jednostkę pilotażową do wszystkich jednostek, została przedstawiona w rozdziale 2.24, Budowanie własnej branży od początku do końca, i nie będę tu powtarzać jej bramek. Całość wyznacza jedna zasada. Wdrażanie odbywa się wyłącznie przez kanały wydań danej instalacji. Nie ma bocznego wejścia dla pilnej poprawki i nikt nie edytuje ręcznie działającego obrazu.
Wersje
W wydaniu pakietu zmieniają się trzy numery wersji i warto wyraźnie je rozróżniać.
| Co | Gdzie się znajduje | Przykład | Reguła |
|---|---|---|---|
| Wtyczka | version w nexus.manifest.json |
0.4.0 |
Wersjonowanie semantyczne; dozwolony jest przyrostek wersji przedpremierowej, taki jak -rc.1 |
| Pakiet | version w pack.json |
0.4.0 |
Zmienia się wraz z soczewkami, słownictwem i klastrami pakietu |
| Model wiedzy | Własna wersja modelu | 1.3 do 1.4 |
Zmienia się wyłącznie poprzez wniosek o zmianę grafu |
Kompilacja deweloperska ma przyrostek 0.4.0-dev, dopóki nie trafi do stagingu. Należy utrzymywać równe wersje wtyczki i pakietu, gdy są wydawane razem; oszczędza to w każdym przeglądzie wydania sporu o to, do którego numeru należą dowody.
Dwie inne wersje są przypięte, a nie wybierane. Wersja szablonu pakietu (domain-pack@1.6.0 dla Cold chain) jest ustalana przy tworzeniu pakietu i zmienia się wyłącznie w drodze przeglądanej zmiany. SDK (zestaw narzędzi programistycznych) jest instalowany w dokładnej wersji, nigdy w zakresie, tak aby ta sama kompilacja dawała ten sam wynik w przyszłym miesiącu:
npm install --save-exact @adverant-nexus/plugin-sdk@2.50.0Umiejętności Skills Engine również mają wersje, ale zachowują się inaczej. Każda opublikowana wersja jest niezmienna, a live, canary i shadow to etykiety nadawane wersjom. Powrót do poprzedniej wersji przenosi etykietę, a przebiegi już trwające kończą się na wersji, od której się zaczęły.
Przed poproszeniem o przegląd: manifest
Strona Manifest i uprawnienia porównuje to, co deklaruje bieżące wydanie, z poprzednim wydaniem: zakresy, magazyny, adresy wychodzące i profil piaskownicy. Należy ją przeczytać, zanim poprosi się kogokolwiek o przegląd, ponieważ dokładnie pokazuje, co recenzenci będą musieli zaakceptować.
Wydanie, które prosi o więcej, niż wcześniej deklarował jego manifest, zostaje wstrzymane tam, gdzie jest, z MANIFEST_SCOPE_WIDENED, dopóki dwóch recenzentów nie zaakceptuje szerszego manifestu. Adres zewnętrzny wymaga ponadto zatwierdzenia przez osobę odpowiedzialną za adresy zewnętrzne u klienta; takie zatwierdzenie udzielane jest na określony czas, a nasze obowiązywało 12 miesięcy. Są dwie drogi naprzód: usunąć te pozycje albo poprosić o przegląd. Strona oferuje oba przyciski.
Każda pozycja na tej stronie jest egzekwowana w czasie działania, a nie tylko przeglądana. Każde wywołanie narzędzia jest sprawdzane względem zadeklarowanych zakresów, adres zewnętrzny jest blokowany, o ile nie znajduje się na liście, a profil piaskownicy nie dopuszcza żadnej innej sieci. Wtyczka, która próbuje połączyć się z czymś, czego nie zadeklarowała, otrzymuje odmowę, a jedynym rozwiązaniem jest nowe wydanie, które to deklaruje.
Przegląd wydania
Strona Przegląd wydania zbiera dowody dla jednego wydania w jednej tabeli, dla recenzenta, który nie jest autorem.
| Dowody | Co wykazały dla 0.4.0 |
|---|---|
| Testy | 66 z 66, na trzech syntetycznych oddziałach |
| Kontrole jakości | Dokumentacja i kod są zgodne |
| Zasada | Każda soczewka wyłącznie zawęża; pola osobowe domyślnie wyłączone |
| Podpisy | Obraz i pakiet podpisane przez potok |
| Porównanie zakresów | Dodaje wysyłanie poczty i jeden adres zewnętrzny wraz z jego zatwierdzeniem |
| Zgodność | Wersja platformy i wersja pakietu bazowego, względem których przeprowadzono testy |
| Zmiana modelu | Przebieg próbny wniosku o zmianę grafu: zmieniono nazwy 1284 powiązań, niczego nie usunięto |
Pod tabelą znajdują się komentarze do zmiany oraz informacje o pochodzeniu: który potok ją zbudował, z jakiej zmiany, skrót (digest) obrazu i szablon. Recenzenci zatwierdzają za pomocą swojego klucza dostępu (passkey). Zatwierdzają dwaj recenzenci niebędący autorem, a następnie potok przenosi wydanie do stagingu. Autor nigdy nie jest liczony jako recenzent, a próba zostaje odrzucona z NEEDS_SECOND_PERSON. Prośba o przegląd wygasa po 3 dniach.
Na pytania recenzentów należy odpowiadać w komentarzach, a nie w oknie czatu. Podczas naszego przeglądu nasz specjalista ds. zgodności zapytał, dlaczego kwota roszczenia została sklasyfikowana jako dane handlowe, a drugi recenzent poprosił o plan wycofania zmiany modelu. Obie odpowiedzi są teraz częścią zapisu wydania, czyli tam, gdzie zajrzy następny recenzent.
Zatwierdzenia zgodne z polityką zmian
Przegląd wydania obejmuje wydanie jako całość. Blok changePolicy w manifeście idzie dalej: określa, które klasy zmian w elementach wdrażanych wtyczki wymagają zatwierdzenia i przez ile osób.
"changePolicy": {
"enabled": true,
"classes": ["website", "bff", "migration"],
"approvals": { "website": 1, "bff": 1, "migration": 2 }
}Trzy klasy to website (aplikacja webowa), bff (backend dla frontendu) i migration (migracja bazy danych). Każda klasa wymieniona w classes musi mieć własną liczbę w approvals, od 1 do 10. Klasa pominięta nie podlega kontroli, a schemat wymusza zapisanie tego jako świadomego wyboru, a nie dojście do tego przez przeoczenie. Dla migracji wymagamy dwóch zatwierdzeń, ponieważ migracja to jedyna zmiana, którą trudno cofnąć.
Zatwierdzenia liczone są w odrębnych osobach, a wnioskodawca nigdy nie jest jedną z nich. Warto znać zasady, które to zapewniają, ponieważ każdej odpowiada odmowa:
- Zatwierdzenie od osoby, która zaproponowała zmianę, jest odrzucane z
TRUST_APPROVAL_SELF_APPROVAL. - Osoba, która w ogóle nie może wprowadzać zmian danej klasy, jest odrzucana z
CHANGE_CLASS_NOT_PERMITTED. - Gdy którykolwiek commit w zmianie jest podpisany tożsamością agenta organizacji, kworum wynosi zwykłe minimum plus jeden, a głos samego agenta nie jest liczony.
- Każde zatwierdzenie rejestruje różnice (diff) i wersję head, które widziało. Jeśli zmiana przesunie się po ostatnim zatwierdzeniu, jej scalenie jest odrzucane z
HASH_MISMATCH, a zatwierdzenia trzeba zebrać ponownie dla nowej treści.
Ta trzecia zasada ma znaczenie, jeśli korzystają Państwo z narzędzia do programowania opartego na AI (sztucznej inteligencji), jak opisano w rozdziale 2.26, Budowanie z użyciem narzędzi do programowania AI. Praca napisana przez agenta wymaga o jedno zatwierdzenie człowieka więcej niż praca napisana przez osobę. Należy to uwzględnić w planach.
Podpisywanie i weryfikacja
Każdy obraz i pakiet jest podpisany przez potok, który go zbudował, a podpisany obraz to jedna z bramek do stagingu. Przestrzeń deweloperska od początku uruchamia wyłącznie podpisane obrazy. W edycji Enterprise administrator ustawia każdą przestrzeń nazw tak, aby niepodpisane obrazy rejestrowała albo odrzucała, i przełącza przestrzenie nazw na odrzucanie jedną po drugiej, dzięki czemu w produkcji ostatecznie działają tylko obrazy zbudowane i podpisane przez potok. Podpisywanie jest częścią kompilacji, a nie czymś, co dodaje się przed wydaniem.
Zasada, która przewija się przez całość, brzmi: nieprawidłowy podpis oznacza odmowę, nigdy ostrzeżenie. Kontrola, która otrzyma SIG_INVALID, zatrzymuje się. Nie przechodzi na wersję niepodpisaną i nie kontynuuje z adnotacją w logu, ponieważ ostrzeżenie w logu kompilacji jest przepustką dla każdego, kto go nie przeczytał.
Ta sama zasada dotyczy wszystkiego, co przekazuje się na nośnikach. Zapieczętowany pakiet dla klienta w środowisku odizolowanym (air-gapped) jest weryfikowany względem Państwa klucza publicznego, zanim cokolwiek zostanie rozpakowane, a polecenie pokazano w rozdziale 2.25, Budowanie dla każdej edycji.
Tożsamość dostawy
Wtyczka jest dostarczana za pośrednictwem kilku elementów, z których każdy ma nazwę: repozytoriów, klucza podpisującego, przestrzeni nazw wdrożenia, prefiksu rejestru, schematu bazy danych, zestawu domen i polityki zmian. Każdy z nich to miejsce, w którym dwie wtyczki mogłyby kolidować albo jedna wtyczka mogłaby się rozjechać. Tożsamość dostarczania to jeden podpisany rekord na wtyczkę, który zawiera je wszystkie, dzięki czemu każda kontrola na ścieżce wydania odczytuje tę samą odpowiedź i odmawia w razie niezgodności.
Swoją część wnoszą Państwo wyłącznie przez manifest: schema, db, domains, changePolicy oraz URL repozytorium. Platforma uzupełnia rekord o resztę i go podpisuje. Nigdy nie nadają Państwo nazwy własnej przestrzeni nazw, prefiksu rejestru ani klucza podpisującego. Są one przydzielane, a manifest, który próbowałby je zadeklarować, zgłaszałby roszczenie, któremu kontrole musiałyby następnie nie dać wiary.
Podpisany rekord zawiera jedenaście pól: slug wtyczki, organizację będącą właścicielem, organizację, która ją buduje, jej repozytoria, nazwę jej klucza podpisującego, jej przestrzeń nazw wdrożenia, jej prefiks rejestru, jej schemat bazy danych, jej domeny, jej politykę zmian oraz krótką listę starszych nazw obrazów używanych przed powstaniem prefiksu rejestru. Ta ostatnia lista może się tylko skracać. Ponieważ jest podpisana, nowy podpis może usunąć wpis, a nic nie może po cichu go dodać. Podpis to Ed25519 nad standardową kanoniczną postacią JSON tych jedenastu pól, dzięki czemu rekord zawierający „Tomás” lub „Sinéad” weryfikuje się wszędzie tak samo.
Gdy wydanie nie zgadza się ze swoim rekordem, rozstrzyga pierwsza odmowa:
| Kod | Kiedy | HTTP |
|---|---|---|
DELIVERY_IDENTITY_MISSING |
Brak rekordu dla wtyczki | 403 |
DELIVERY_PATH_REFUSED |
Wypchnięcie obrazu poza prefiks rejestru, którego nie ma na podpisanej liście starszych nazw | 403 |
NAMESPACE_MISMATCH |
Wdrożenie kierowane do innej przestrzeni nazw | 403 |
IMAGE_NAME_COLLISION |
Nazwa obrazu, do której rości sobie prawo już inna wtyczka | 409 |
CHANGE_CLASS_NOT_PERMITTED |
Klasa zmian, której polityka nie obejmuje | 403 |
IMAGE_NAME_COLLISION to ta odmowa, która zaskakuje. Należy wybrać inną nazwę i nigdy nie używać jej ponownie: wspólna nazwa obrazu oznacza, że promocja jednej wtyczki może przenieść pody innej wtyczki.
Migracje: zatwierdzone i o określonym zakresie
Migracja jest dostarczana wewnątrz obrazu wtyczki i uruchamiana przed startem nowej wersji, za pośrednictwem jedynego mechanizmu uruchamiania migracji w SDK, nexus-migrate. Nie piszą Państwo własnego mechanizmu stosowania migracji. Zanim jakiekolwiek wydanie będzie mogło się przesunąć, ten sam mechanizm stosuje migracje plik po pliku na tymczasowej bazie danych, więc migracja, która ma się nie powieść, nie powiedzie się właśnie tam. Kompilacja shadow szablonu wywołuje mechanizm raz na plik, po kolei, i rejestruje każdy plik tak, jak zrobi to produkcja.
Zasady mechanizmu uruchamiania to te same zasady, które sprawdzają bramki, zapisane jako kod:
- Łączy się jako rola migratora schematu i uruchamia każdy plik jako właściciel schematu. Każde inne logowanie, a przede wszystkim superużytkownik, jest odrzucane. Plik, który sam próbuje przełączyć rolę, jest odrzucany, zanim cokolwiek zostanie uruchomione.
- Plik dzierżawy (tenancy), o numerze 0, nigdy nie jest edytowany po zastosowaniu. Zmiana dzierżawy otrzymuje własny plik rewizji,
000_tenancy_r<N>.sql, którynexus-tenancy render --revision <N>tworzy za Państwa. - Zwykle mechanizm zarządza transakcją każdego pliku i odrzuca
BEGINlubCOMMITw jego wnętrzu. Plik, który sam zarządza swoimi transakcjami, deklaruje, że jest uruchamiany instrukcja po instrukcji, a wtedy każda otwierana przez niegoBEGINmusi mieć swój odpowiednik. - Prowadzi rejestr, jeden wiersz na plik, z SHA-256 pliku i sposobem jego uruchomienia. Zastosowany plik nigdy nie jest zmieniany w miejscu; zmiana to nowy, numerowany plik.
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-tenancy render --manifest nexus.manifest.json --revision 2 --out migrations/000_tenancy_r2.sqlObjęcie zakresem oznacza, że każda nowa tabela zawiera organization_id, owner_user_id i business_unit_id, a także kolumnę znacznikową is_demo, chyba że gates/demo-exempt.json zwalnia tabelę z podaniem powodu, ma klucz główny rozpoczynający się od organizacji i klucze obce, które ją przenoszą, oraz wymuszone zabezpieczenia na poziomie wierszy. Bramka migrations-are-scoped sprawdza te zasady we wszystkich plikach, a migrations-commit-what-they-open sprawdza, czy każdy plik zatwierdza to, co otwiera. Druga bramka istnieje, ponieważ migracja, która po cichu wycofała zmiany, kiedyś zakończyła się kodem 0, a tabela, którą miała utworzyć, nigdy nie powstała.
Do każdego wydania należy jeszcze jeden plik. scripts/ci/required-env wypisuje zmienne środowiskowe potrzebne usłudze do uruchomienia, jako tablicę JSON pobraną z mechanizmu ładowania konfiguracji. Ścieżka wydania go uruchamia i odrzuca wydanie, którego wdrożenie nie ustawia każdej z nich, dzięki czemu brakująca zmienna zostaje wychwycona przed wydaniem, a nie przez pod, który nie chce się uruchomić.
node scripts/ci/required-envWydawanie umiejętności
Dwa rodzaje umiejętności docierają do użytkowników różnymi drogami, dlatego należy je wydawać w różny sposób.
Umiejętność z manifestu, czyli typowany wiersz w skills[] wtyczki, jest dostarczana razem z wtyczką i przechodzi tę samą promocję co reszta. Onboarding synchronizuje cały zestaw umiejętności z rejestrem przy każdym wydaniu. Umiejętność pominięta w zestawie zostaje wyłączona, a w edycji Enterprise synchronizacja z jedną błędną umiejętnością nie przyjmuje żadnej z nich, więc nadal działa poprzednia wersja, a nie połowa nowej.
Umiejętność Skills Engine jest publikowana z biblioteki. W planie Enterprise umiejętność, która dodaje narzędzie zapisu, czeka, aż zatwierdzą ją swoimi kluczami dostępu dwie wskazane osoby, a wnioskodawca nie może być jedną z nich. Zatwierdzona wersja działa następnie w trybie cienia, potem w trybie canary dla jednej jednostki za wskazanymi bramkami, a następnie dla wszystkich, i zatrzymuje się sama, jeśli warunek bramki nie zostanie spełniony. Jeśli Państwa wtyczka i umiejętność Skills Engine zależą od siebie nawzajem, proszę najpierw opublikować umiejętność i pozwolić jej dotrzeć do wszystkich, zanim wydanie wtyczki, które ją wywołuje, opuści fazę pilotażową.
Kanały i instalacje
Gdy wydanie przejdzie fazę pilotażową i dotrze do wszystkich jednostek, jest oferowane w kanale, a każda jednostka wybiera swój kanał. Jej administrator zatwierdza każdą zmianę. Strona Kanały i instalacje pokazuje, które jednostki uruchamiają którą wersję, a wskaźniki błędów podaje wyłącznie jako liczby: widzą Państwo, jak zachowuje się Państwa rozszerzenie, nigdy zaś, co ktokolwiek z nim zrobił.
Nasza wtyczka carrier-sync działa jednocześnie w trzech wersjach i jest to normalne. Większość jednostek korzysta z bieżącego wydania, jedna jednostka pozostaje przy starszej wersji w kanale utrzymywanym do określonej daty, a kandydat do wydania znajduje się w kanale, którego nikt jeszcze nie wybrał. Proszę z tym nie walczyć; jednostka, która potrzebuje stabilności na czas audytu, ma do niej prawo.
Logi i metryki Państwa rozszerzenia
Strona logów i metryk Państwa pakietu jest ograniczona do Państwa własnych obciążeń, w jednostkach, do których mają Państwo wgląd. Można filtrować według jednostki i środowiska, a widoczne są liczby, czasy i stany.
Pola osobowe są zastępowane przed zapisaniem wiersza, a treści klientów, takie jak tekst reklamacji, poczta czy zawartość dokumentów, nigdy nie są zapisywane w logach. Logi są przechowywane przez 14 dni. Organizację ustala brama, nigdy Państwa zapytanie, dlatego zapytanie wskazujące inną organizację jest odrzucane z kodem TENANT_BOUNDARY. Asystent w panelu może czytać te same logi razem z Państwem, i tylko te: gdy zapytałem go, dlaczego pewnego ranka rekordy przekroczeń napływały z opóźnieniem, prześledził 18 minut ponownych prób do zduplikowanych odczytów z zasilania jednego nabrzeża.
Wycofywanie zmian (rollback)
Istnieją dwa rodzaje wycofania i oba są weryfikowanymi zmianami, a nie przełącznikami.
Wycofanie środowiska wykorzystuje poprzednią wersję. Każde środowisko przechowuje ją przez 30 dni. Wycofanie jest przygotowywane jako zmiana wydania, pokazuje podgląd tego, co zrobi, i wymaga drugiej osoby; po zatwierdzeniu potok wycofuje zmiany w około minutę. Każde wycofanie jest mierzone w czasie, podobnie jak każde ćwiczenie, dlatego warto przećwiczyć je, zanim będzie potrzebne. Wycofanie jednej jednostki odbywa się na stronie Kanały i instalacje. Okno modalne wycofania informuje, co się zmienia (ta jednostka ponownie uruchamia starszą wersję, a jej wskaźnik błędów jest obserwowany przez godzinę), co pozostaje bez zmian (pozostałe jednostki oraz ustawienia i rekordy jednostki), jaki jest powód i kto jest drugą osobą: administrator tej jednostki.
Ustawienia i rekordy są zachowywane podczas wycofania, dlatego każde wydanie należy planować przy założeniu, że poprzednia wersja może ponownie działać na danych zapisanych przez nowszą. To praktyczny powód, aby w obrębie wydania, które może zostać wycofane, migracje miały wyłącznie charakter addytywny, i powód, dla którego prosimy, aby każdą z nich zatwierdzały dwie osoby. Ze zmianą modelu jest tak samo: recenzent może, a nawet powinien, poprosić o plan wycofania wniosku o zmianę grafu przed jego zatwierdzeniem.
Umiejętności wycofuje się łagodniej. Przeniesienie etykiety live z powrotem na wcześniejszą wersję to jeden krok, a uruchomienia już trwające kończą się na wersji, od której się rozpoczęły.
Wygaszanie wersji
Raz utworzone wydanie nigdy nie jest edytowane. Wersja, której nie należy już używać, zostaje wycofana z oferty, a poprawka jest dostarczana pod nowym numerem wersji. Kanały wydań samego SDK stosują tę samą zasadę: wadliwa wersja SDK jest wycofywana, nigdy nie jest zastępowana inną zawartością pod tym samym numerem. Proszę to naśladować, ponieważ numer wersji, który może oznaczać dwie różne kompilacje, sprawia, że wszelkie dowody jej dotyczące stają się bezwartościowe.
Wycofanie wtyczki lub pakietu z oferty zatrzymuje nowe instalacje. Jednostki zachowują uruchomioną wersję do czasu przejścia na inną, dlatego wycofanie z oferty jest sygnałem i terminem, a nie wyłącznikiem. Proszę poinformować administratorów jednostek, na którą wersję mają przejść i do kiedy.
Wycofanie umiejętności z użytku opiera się na tej samej idei, z jednym dodatkowym krokiem. Skills Engine przenosi wszystkich pozostałych wywołujących na zamiennik po uruchomieniu przypadków testowych zamiennika, zatrzymuje nowe uruchomienia i zachowuje wersje, przypadki testowe oraz zapieczętowane rekordy uruchomień, aby umiejętność można było przywrócić, jeśli zamiennik okaże się nieprawidłowy.
Lista kontrolna wydania
To lista, którą czytamy przed każdym wydaniem Cold chain. Jest krótka, ponieważ większość z niej platforma sprawdza za nas.
- Wersje są zgodne: manifest,
pack.jsonoraz model wiedzy, jeśli się zmienił. - Każda bramka jest zielona lokalnie, od czystego stanu, a każdy nowy test najpierw wykazał niepowodzenie.
- Strona Manifest i uprawnienia nie pokazuje rozszerzenia uprawnień albo rozszerzenie jest zamierzone, a recenzenci wiedzą dlaczego.
- Każda migracja to nowy numerowany plik, o określonym zakresie, zastosowany bez błędów na tymczasowej bazie danych.
scripts/ci/required-envzawiera każdą zmienną potrzebną usłudze, a wdrożenie ustawia każdą z nich.- Plan wycofania jest opisany w zmianie, również dla każdej zmiany modelu.
- W tym tygodniu dostępnych jest dwóch recenzentów, którzy nie są autorami.
Ostatni punkt brzmi banalnie. To jednak on opóźnił więcej naszych wydań niż wszystkie bramki razem wzięte.



