Версия 1.0.0-alpha.1последно
Глава 2.28
Пускане на Вашето разширение
Как един плъгин или пакет преминава от успешна компилация до звената, които го изпълняват, и как се извежда от употреба. Версии, преглед на изданието, канали и инсталации, подписване, одобрения на промени, запис за идентичност на доставката, миграции, връщане към стара версия (rollback) и оттегляне на версия.
Тази страница е преведена от ИИ от английския оригинал. Ако нещо е неясно, английската страница е референтна. Прочетете тази страница на английски

Cold chain 0.4.0 беше първото ни издание, което поиска повече от предишното. То добави изпращане на поща и един външен адрес за предупреждения за хладилни контейнери. Компилацията беше успешна, тестовете минаха и на трите синтетични клона, и въпреки това изданието остана два дни в пространството за разработка, докато двама души прочетоха какво иска, а трети одобри адреса. Точно така трябва да се усеща издаването в Nexus: кодът е лесната част, а доказателствата и одобренията са самото издание.
Тази глава обхваща всичко между успешната компилация и версия, работеща за всички звена, както и начините за връщане назад. Самият път на повишаване, от пространството за разработка към staging, към пилотно звено и към всички звена, е представен в глава 2.24, Изграждане на персонализирана вертикала от край до край, и тук няма да повтарям неговите контролни точки. Едно правило рамкира всичко. Внедряването става само чрез каналите за издания на инсталацията. Няма странична врата за спешна поправка и никой не редактира работещ образ ръчно.
Версии
При издание на пакет се променят три номера на версии и си струва да ги държите ясно разграничени.
| Какво | Къде се намира | Пример | Правило |
|---|---|---|---|
| Плъгинът | version в nexus.manifest.json |
0.4.0 |
Семантична версия; разрешен е суфикс за предварително издание, например -rc.1 |
| Пакетът | version в pack.json |
0.4.0 |
Променя се заедно с лещите, думите и клъстерите на пакета |
| Моделът на знанието | Собствената версия на модела | 1.3 до 1.4 |
Променя се само чрез заявка за промяна на графа |
Компилацията за разработка носи суфикс, 0.4.0-dev, докато не достигне staging. Поддържайте версиите на плъгина и на пакета еднакви, когато се доставят заедно; това спестява спора при всеки преглед на издание за това към кой номер принадлежат доказателствата.
Две други версии са фиксирани, а не избирани. Версията на шаблона на пакета (domain-pack@1.6.0 за Cold chain) се фиксира при създаването на пакета и се променя само чрез прегледана промяна. SDK (комплектът за разработка на софтуер) се инсталира в точна версия, никога в диапазон, така че същата компилация дава същия резултат и следващия месец:
npm install --save-exact @adverant-nexus/plugin-sdk@2.50.0Уменията на Skills Engine също имат версии, но се държат различно. Всяка публикувана версия е фиксирана, а live, canary и shadow са етикети върху версиите. Връщането назад премества етикет, а вече започналите изпълнения завършват с версията, с която са започнали.
Преди да поискате преглед: манифестът
Страницата Манифест и разрешения сравнява декларираното в това издание с последното издание: обхватите, хранилищата, изходящите адреси и профила на изолираната среда. Прочетете я, преди да помолите някого за преглед, защото тя ви показва точно какво ще бъдат помолени да приемат рецензентите.
Издание, което иска повече, отколкото манифестът му е декларирал преди, се задържа там, където е, с MANIFEST_SCOPE_WIDENED, докато двама рецензенти не приемат разширения манифест. Външният адрес изисква и одобрение от отговорника за външните адреси при клиента; това одобрение се дава за определен срок, а нашето беше за 12 месеца. Имате два пътя напред: да премахнете редовете или да поискате преглед. Страницата предлага и двата бутона.
Всеки ред на тази страница се прилага по време на изпълнение, а не само се преглежда. Всяко извикване на инструмент се проверява спрямо декларираните обхвати, външен адрес се блокира, освен ако не е изброен, а профилът на изолираната среда не позволява друга мрежа. Плъгин, който се опита да достигне нещо, което не е декларирал, получава отказ и единственото решение е ново издание, което го декларира.
Преглед на изданието
Страницата Преглед на изданието събира доказателствата за едно издание в една таблица, за рецензент, който не е авторът.
| Доказателство | Какво показа за 0.4.0 |
|---|---|
| Тестове | 66 от 66, на три синтетични клона |
| Проверки за качество | Документацията и кодът са в съответствие |
| Политика | Всяка леща само стеснява; личните полета са изключени по подразбиране |
| Подписи | Образът и пакетът са подписани от конвейера |
| Разлика в обхватите | Добавя изпращане на поща и един външен адрес с неговото одобрение |
| Съвместимост | Версията на платформата и версията на базовия пакет, спрямо които е тествано |
| Промяна на модела | Пробното изпълнение на заявката за промяна на графа: 1284 преименувани връзки, нищо премахнато |
Под таблицата са коментарите по промяната и произходът: кой конвейер я е компилирал, от коя промяна, дайджестът на образа и шаблонът. Рецензентите одобряват с ключа си за достъп (passkey). Одобряват двама рецензенти, които не са авторът, след което конвейерът премества изданието в staging. Авторът никога не се брои за рецензент и опитът се отказва с NEEDS_SECOND_PERSON. Заявката за преглед изтича след 3 дни.
Отговаряйте на въпросите на рецензентите в коментарите, а не в прозорец за чат. По време на нашия преглед служителят ни по съответствието попита защо сумата на иска е класифицирана като търговска, а вторият рецензент поиска плана за връщане назад при промяната на модела. И двата отговора вече са част от записа на изданието, където ще погледне следващият рецензент.
Одобрения според правилата за промени
Прегледът на изданието обхваща изданието като цяло. Блокът changePolicy в манифеста отива по-далеч: той указва кои класове промени в разгръщаемите компоненти на вашия плъгин изискват одобрение и от колко души.
"changePolicy": {
"enabled": true,
"classes": ["website", "bff", "migration"],
"approvals": { "website": 1, "bff": 1, "migration": 2 }
}Трите класа са website (уеб приложението), bff (бекендът за фронтенда) и migration (миграция на база данни). Всеки клас, посочен в classes, трябва да има собствен брой в approvals, от 1 до 10. Клас, който пропуснете, е неуправляван и схемата ви кара да запишете това като избор, а не да стигнете до него по пропуск. Изискваме две одобрения за миграциите, защото миграцията е единствената промяна, която трудно се отменя.
Одобренията се броят в отделни хора и предложителят никога не е сред тях. Правилата, които поддържат това, си струва да се знаят, защото всяко има отказ:
- Одобрение от лицето, предложило промяната, се отказва с
TRUST_APPROVAL_SELF_APPROVAL. - Лице, което изобщо няма право да прави промяна от този клас, получава отказ с
CHANGE_CLASS_NOT_PERMITTED. - Когато някой къмит в промяната е подписан с агентската идентичност на организацията, кворумът е обичайният минимум плюс едно и собственият глас на агента не се брои.
- Всяко одобрение записва разликата и главата (head), които е видяло. Ако промяната се измени след последното одобрение, сливането ѝ се отказва с
HASH_MISMATCHи одобренията трябва да се съберат отново за новото съдържание.
Третото правило е важно, ако разработвате с инструмент за кодиране с ИИ (изкуствен интелект), както е описано в глава 2.26, Разработване с инструменти за кодиране с ИИ. Работа, написана от агент, изисква едно човешко одобрение повече от работа, написана от човек. Планирайте това.
Подписване и проверка
Всеки образ и пакет се подписва от конвейера, който го е компилирал, а подписаният образ е една от контролните точки към staging. Пространството за разработка изпълнява само подписани образи от самото начало. В Enterprise администраторът настройва всяко пространство от имена или да записва неподписаните образи, или да ги отказва, и преминава пространствата към отказване едно по едно, така че в production накрая работят само образи, компилирани и подписани от конвейера. Подписването е част от компилацията, а не нещо, което добавяте преди издание.
Правилото, което минава през всичко това, е, че неуспешен подпис е отказ, никога предупреждение. Проверка, която получи SIG_INVALID, спира. Тя не преминава към неподписаната версия и не продължава с бележка в лог, защото предупреждение в лога на компилацията е одобрение за всеки, който не го е прочел.
Същото правило важи за всичко, което предавате на носител. Запечатан пакет за клиент с изолирана от мрежата среда се проверява спрямо вашия публичен ключ, преди нещо да бъде разопаковано, а глава 2.25, Разработване за всяко издание на продукта, показва командата.
Идентичност на доставката
Плъгинът се доставя чрез няколко неща, всяко от които има име: неговите хранилища, ключ за подписване, пространство от имена за внедряване, префикс в регистъра, схема на база данни, набор от домейни и политика за промени. Всяко от тях е място, където два плъгина могат да се сблъскат или един плъгин може да се отклони. Идентичността за доставка е един подписан запис за всеки плъгин, който съдържа всички тях, така че всяка проверка по пътя на изданието чете един и същ отговор и отказва при несъответствие.
Вие допринасяте своята част чрез манифеста и нищо друго: schema, db, domains, changePolicy и URL адреса на хранилището. Платформата допълва записа с останалото и го подписва. Никога не посочвате собственото си пространство от имена, префикс в регистъра или ключ за подписване. Те ви се присвояват, а манифест, който се опита да ги декларира, би предявил твърдение, на което проверките след това ще трябва да не повярват.
Подписаният запис съдържа единадесет полета: slug идентификатора на плъгина, организацията собственик, организацията, която го компилира, неговите хранилища, името на ключа му за подписване, пространството от имена за внедряване, префикса в регистъра, схемата на базата данни, домейните, политиката за промени и кратък списък с по-стари имена на образи, които е използвал преди появата на префикса му в регистъра. Последният списък може само да намалява. Тъй като е подписан, нов подпис може да премахне запис, но нищо не може да добави такъв незабелязано. Подписът е Ed25519 върху стандартната канонична JSON форма на тези единадесет полета, така че запис със "Tomás" или "Sinéad" в него се проверява еднакво навсякъде.
Когато изданието не съответства на записа си, важи първият отказ:
| Код | Кога | HTTP |
|---|---|---|
DELIVERY_IDENTITY_MISSING |
Няма запис за плъгина | 403 |
DELIVERY_PATH_REFUSED |
Публикуване на образ извън префикса в регистъра, което не е в подписания списък с по-стари имена | 403 |
NAMESPACE_MISMATCH |
Внедряване, насочено към друго пространство от имена | 403 |
IMAGE_NAME_COLLISION |
Име на образ, което вече е заявено от друг плъгин | 409 |
CHANGE_CLASS_NOT_PERMITTED |
Клас промяна, който политиката не управлява | 403 |
IMAGE_NAME_COLLISION е този, който изненадва хората. Изберете друго име и никога не използвайте повторно вече използвано: споделено име на образ означава, че повишаването на един плъгин може да премести подовете на друг плъгин.
Миграции – потвърдени и с ограничен обхват
Миграцията се доставя в образа на вашия плъгин и се изпълнява преди стартирането на новата версия, чрез единствения инструмент за изпълнение на миграции в SDK, nexus-migrate. Не пишете собствен инструмент за прилагане. Преди което и да е издание да може да продължи, същият инструмент прилага миграциите ви файл по файл върху временна база данни, така че миграция, която се проваля, се проваля там. Shadow компилацията на шаблона извиква инструмента веднъж за всеки файл, по ред, и записва всеки файл така, както ще го направи production.
Правилата на инструмента са тези, които проверяват контролните точки, написани като код:
- Той се свързва с ролята за миграции на вашата схема и изпълнява всеки файл като собственик на схемата. Всяко друго влизане, и преди всичко суперпотребител, се отказва. Файл, който сам се опитва да смени ролята, се отказва, преди да се изпълни каквото и да било.
- Файлът за наемателството (tenancy), с номер 0, никога не се редактира, след като е приложен. Промяна в наемателството получава собствен файл с ревизия,
000_tenancy_r<N>.sql, койтоnexus-tenancy render --revision <N>създава вместо вас. - Обикновено инструментът управлява транзакцията на всеки файл и отказва
BEGINилиCOMMITв него. Файл, който сам управлява транзакциите си, декларира, че се изпълнява по команди, и тогава всекиBEGIN, който отваря, трябва да има съответствие. - Той води регистър, по един ред за файл, със SHA-256 на файла и начина, по който е изпълнен. Приложен файл никога не се променя на място; промяната е нов номериран файл.
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-tenancy render --manifest nexus.manifest.json --revision 2 --out migrations/000_tenancy_r2.sqlОбхванат означава, че всяка нова таблица съдържа organization_id, owner_user_id и business_unit_id, както и колоната маркер is_demo, освен ако gates/demo-exempt.json не освобождава таблицата с причина, с първичен ключ, който започва с организацията, и външни ключове, които я съдържат, и с принудително включена защита на ниво ред. Контролната точка migrations-are-scoped проверява тези правила във всеки файл, а migrations-commit-what-they-open отчита дали всеки файл потвърждава (commit) това, което отваря. Втората контролна точка съществува, защото веднъж миграция, която беше тихо отменена, завърши с код 0, а таблицата, която трябваше да създаде, така и не съществуваше.
Още един файл принадлежи на всяко издание. scripts/ci/required-env извежда променливите на средата, необходими за стартиране на вашата услуга, като JSON масив, взет от вашия зареждач на конфигурация. Пътят на изданието го изпълнява и отказва издание, чието внедряване не задава всяка от тях, така че липсваща променлива се улавя преди изданието, а не от под, който не стартира.
node scripts/ci/required-envПускане на умения
Двата вида умения достигат до хората по различни пътища, затова ги издавайте по различен начин.
Умение от манифеста, типизиран ред в skills[] на вашия плъгин, се доставя с плъгина и преминава през същото повишаване като останалата част от него. Въвеждането синхронизира целия набор от умения с регистъра при всяко издание. Ако пропуснете умение от набора, то се деактивира, а в Enterprise синхронизация с едно лошо умение не приема нито едно от тях, така че предишната версия продължава да работи, вместо половината от новата.
Умение на Skills Engine се публикува от библиотеката. В Enterprise умение, което добавя инструмент за запис, изчаква двама посочени поименно души да го одобрят със своите ключове за достъп (passkeys), като предложилият не може да бъде един от тях. След това одобрената версия се изпълнява в режим shadow, след това в режим canary за едно звено зад посочени контролни прагове, след това за всички, и се спира сама, ако даден праг не е изпълнен. Ако Вашият плъгин и умение на Skills Engine зависят едно от друго, първо публикувайте умението и изчакайте то да достигне до всички, преди изданието на плъгина, което го извиква, да излезе от пилотната фаза.
Канали и инсталации
След като дадено издание е преминало пилотната фаза и е достигнало до всички звена, то се предлага в канал, а всяко звено избира своя канал. Неговият администратор одобрява всяко преминаване. Страницата „Канали и инсталации“ показва кои звена коя версия изпълняват, като процентът грешки е представен само като броя: виждате как се държи Вашето разширение, но никога какво е правил някой с него.
Нашият плъгин carrier-sync работи едновременно в три версии и това е нормално. Повечето звена са на текущото издание, едно звено остава на по-стара версия в канал, поддържан до определена дата, а кандидат-издание е в канал, който все още никой не е избрал. Не се борете с това; звено, което се нуждае от стабилност заради одит, има право на нея.
Дневници и метрики на Вашето разширение
Страницата с логове и метрики за Вашия пакет е ограничена до собствените Ви работни натоварвания в звената, до които имате достъп. Можете да филтрирате по звено и среда и виждате броя, времена и състояния.
Личните полета се заменят, преди даден ред да бъде записан, а клиентско съдържание, като текст на рекламации, поща или съдържание на документи, никога не се записва в логовете. Логовете се съхраняват 14 дни. Организацията се задава от шлюза, никога от Вашата заявка, така че заявка, която посочва друга организация, се отхвърля с TENANT_BOUNDARY. Асистентът в панела може да чете същите логове заедно с Вас и само тях: когато го попитах защо записите за отклонения постъпиха със закъснение една сутрин, той проследи 18 минути повторни опити до дублирани показания от захранването на един кей.
Връщане към предишна версия
Има два вида връщане към предишна версия и и двата са прегледани промени, а не превключватели.
Връщането на среда към предишна версия използва предходната версия. Всяка среда я пази 30 дни. Връщането се подготвя като промяна в изданието, показва предварително какво ще направи и изисква втори човек; след одобрение конвейерът извършва връщането за около минута. Всяко връщане се засича, както и всяко учение, затова го упражнете, преди да Ви потрябва. Връщането на едно звено използва страницата „Канали и инсталации“. Прозорецът за връщане посочва какво се променя (звеното отново изпълнява по-старата версия, а процентът грешки се наблюдава в продължение на един час), какво остава (другите звена, както и настройките и записите на звеното), причината и кой е вторият човек: администраторът на това звено.
Настройките и записите се запазват при връщане към предишна версия, затова планирайте всяко издание с допускането, че предходната версия може отново да работи с данните, записани от по-новата. Това е практическата причина миграциите да бъдат само добавящи в рамките на издание, което може да се наложи да върнете, и причината да изискваме двама души да одобряват всяка от тях. Същото важи и за промяна на модела: рецензентът може и трябва да поиска плана за връщане на заявка за промяна на графа, преди да я одобри.
Уменията се връщат по-щадящо. Преместването на етикета за активна версия обратно към по-ранна версия е една стъпка, а вече започналите изпълнения завършват с версията, с която са стартирали.
Оттегляне на версия
Веднъж направено, едно издание никога не се редактира. Версия, която вече не бива да се използва, се оттегля, а корекцията се публикува с нов номер на версия. Собствените канали за издания на SDK следват същия навик: лоша версия на SDK се изтегля и никога не се заменя с различно съдържание под същия номер. Възприемете този подход, защото номер на версия, който може да означава две различни компилации, обезсмисля всяко доказателство за нея.
Оттеглянето на плъгин или пакет спира новите инсталации. Звената запазват версията, която изпълняват, докато не преминат към друга, затова оттеглянето е сигнал и краен срок, а не изключвател. Уведомете администраторите на звената към коя версия да преминат и до кога.
Извеждането на умение от употреба следва същата идея с една допълнителна стъпка. Skills Engine премества всички оставащи извикващи към заместител, след като изпълни тестовите случаи на заместителя, спира новите изпълнения и запазва версиите, тестовите случаи и запечатаните записи за изпълнения, така че умението да може да бъде върнато, ако заместителят се окаже погрешен.
Контролен списък за пускане на издание
Това е списъкът, който преглеждаме преди всяко издание на Cold chain. Кратък е, защото платформата проверява повечето от него вместо нас.
- Версиите съвпадат: манифестът,
pack.jsonи моделът на знанието, ако е променен. - Всеки контролен праг е зелен локално, от чисто състояние, и за всеки нов тест е показано, че първо се проваля.
- Страницата „Манифест и разрешения“ не показва разширяване или разширяването е това, което сме имали предвид, и рецензентите знаят защо.
- Всяка миграция е нов номериран файл с ограничен обхват, приложен безпроблемно към временна база данни.
scripts/ci/required-envизброява всяка променлива, от която услугата се нуждае, и разгръщането задава всяка от тях.- Планът за връщане е описан в промяната, включително за всяка промяна на модела.
- Двама рецензенти, които не са авторът, са на разположение тази седмица.
Последната точка звучи тривиално. Тя е забавила повече от нашите издания, отколкото всички контролни прагове взети заедно.



