Verzió 1.0.0-alpha.1legújabb
2.21. fejezet
A Plugin SDK
A Plugin SDK (szoftverfejlesztő készlet) telepítése, parancssori eszközei, a teljes körű szolgáltatási sablon bemutatása, a v2 manifesztum mezőről mezőre, valamint a huszonkét kapu, amely betartatja a szabályokat a beépülő modullal.
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 második pluginom harmadannyi idő alatt készült el, mint az első, és a megtakarítás szinte teljes egészében az SDK-nak (szoftverfejlesztői készletnek) volt köszönhető. Első alkalommal írtam egy hatókör-ellenőrzést, egy konfigurációbetöltőt és egy migrációfuttatót, és a bíráló mindegyiket visszaküldte. Második alkalommal egyetlen vázgeneráló parancsot futtattam, töröltem a minta hangulatelemző skillt, és a napjaimat azokra az anomália-felülvizsgálati rekordokra fordítottam, amelyekre a repülésdinamikai csapatunknak ténylegesen szüksége volt.
A @adverant-nexus/plugin-sdk egyetlen npm-csomag. Tartalmazza a v2 manifest sémáját és az azt olvasó validátorokat (definePlugin, defineSkill), azokat a futásidejű modulokat, amelyeket a pluginja a hatókörhöz, az adatbázishoz, a diszpécseléshez és a többihez importál, a teszt-segédeszközöket, a megfelelőségi kapukat és a parancssori eszközöket. Ez a fejezet a telepítést, az eszközöket, a sablont, a manifestet és a kapukat tárgyalja. A futó kódban használt futásidejű modulokat a 2.22. fejezet, A plugin futtatókörnyezete tárgyalja.
Telepítés
A csomag az Adverant https://registry.adverant.ai/npm/ címen elérhető registryjéből származik, soha nem a nyilvános npm registryből, és szüksége van a fiókja „Pull tokens and install commands” oldalán található pull tokenre. Állítsa a @adverant-nexus hatókört a registryre a repository .npmrc fájljában:
@adverant-nexus:registry=https://registry.adverant.ai/npm/
//registry.adverant.ai/npm/:_authToken=<pull-token>
A <pull-token> a fiókoldaláról származó token. Pipeline-ban titokból adja át, és soha ne commitolja; a sablon Dockerfile-ja nélküle megtagadja a buildet, és a npm ci lefutása után törli a .npmrc fájlt a build szakaszból, így a token soha nem kerül bele image-be.
Ezután rögzítse pontosan a verziót:
npm install --save-exact @adverant-nexus/plugin-sdk@2.50.0Az első telepítéskor commitolja a package-lock.json fájlt. A sablon image-buildje a npm ci parancsot futtatja, és megtagadja a npm install parancsra való visszalépést: a lockfile a szerződés. Az SDK minimális követelménye a Node 18; a sablon a Node 20-at célozza.
A parancssori eszközök a csomagon belül érkeznek, ezért a dokumentáció minden parancsa a npx -p használatával megnevezi a csomagot és annak verzióját. Önmagában a npx create-nexus-plugin a nyilvános registryben kerül keresésre, és az a név nem ez a csomag.
A parancssori eszközök
| Eszköz | Mit csinál |
|---|---|
create-nexus-plugin |
Pluginvázat generál, manifestet validál, v1 manifestet migrál v2-re, és elkészíti a fogyasztói útmutatót a frontendfejlesztője számára |
nexus-tenancy |
A manifestből előállítja a séma bérlőkezelési SQL-jét: szerepköröket, jogosultságokat, a sorszintű biztonsági sablont és a gráftáblákat |
nexus-migrate |
Alkalmazza a migrációkat: egyszer létrehozza a szerepköröket, majd migrátor szerepkörként lefuttatja az egyes számozott fájlokat |
nexus-gates |
Lefuttatja az összes megfelelőségi kaput és az egyes kapuk saját önellenőrzését |
A create-nexus-plugin nem indít hálózati hívást, és nem tölt be távoli kódot. Ugyanazokat a folyamaton belüli validátorokat futtatja, mint a platform bevezetési folyamata, így nincs eltérés a „nálam validált” és a „a platform elfogadta” között.
| Művelet | Kapcsolók | Mit csinál | Kilépési kódok |
|---|---|---|---|
scaffold <name> |
--tier full-service\|ui-only\|skills-only, --dir <path>, --print |
Új pluginkönyvtárat ír; a --print csak a manifestet írja ki |
0 megírva · 1 felülírás megtagadva · 2 hibás használat |
validate <file> |
Validál egy nexus.manifest.json fájlt, vagy egy ilyet exportáló .ts vagy .js modult |
0 érvényes · 1 érvénytelen vagy olvashatatlan · 2 hibás használat | |
migrate <file> |
--write |
Egy v1 manifestet v2-re emel, és kiírja vagy helyben felülírja | 0 · 1 · 2, mint fent |
guide |
--manifest <file>, --narrative <dir>, --out <guide.md>, --check, --lint |
Elkészíti a fogyasztói útmutatót a manifestből és az Ön leírásából; a --check összeveti a commitolt példánnyal, és semmit nem ír |
0 · 1 eltérés vagy lint-szabálysértés · 2 hibás használat |
help |
Kiírja a használati útmutatót | 0 |
Alapstruktúra-generálás (scaffolding) és a három szint
npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin scaffold anomaly-review --tier full-serviceA --tier alapértéke full-service. A vázgenerátor megtagadja az írást létező könyvtárba, és az általa írt manifest már átmegy a validáláson; soha nem hoz létre érvénytelent.
A szintet aszerint válassza, hogy mi van a pluginjában.
| Szint | Tartalmaz | Kötelezően deklarálandó |
|---|---|---|
skills-only |
Csak manifest skilleket | skills[], legalább egy bejegyzéssel |
ui-only |
Frontendfelületet a shellen belül | frontend |
full-service |
Backendet és frontendet, általában saját sémával | backend és frontend; és mivel backendje van, runtime.healthCheck |
Ha bizonytalan, generálja a full-service vázat, és törölje, amire nincs szüksége. A másik irány azt jelenti, hogy meg kell írnia azokat a részeket, amelyeket a sablon megadott volna.
A teljes körű szolgáltatási sablon bemutatása
A sablon a referenciaplugin, amely a későbbi fejezetek által feltételezett szigorú mintára épül. Az alakját másolja le, ne a mintalogikáját.
| Elérési út | Mi ez |
|---|---|
nexus.manifest.json |
A v2 manifest: a három törvény újrafogalmazva, az útvonaltábla és a jogosultság-nyilvántartása |
src/config.ts |
A konfigurációbetöltő. Egy specifikáció, egyszer beolvasva, minden hiba összegyűjtve, mielőtt a folyamat megtagadja az indulást |
src/scope.ts |
Az egyetlen fájl, amely a kérésből hatókört képez, az SDK szigorú tokenellenőrzőjével és két renddel: egy személy bearer tokenjével és a platform szolgáltatáshívásával |
src/db.ts |
Minden utasítás a tenantFence() használatával épül fel, és a withScopedTx belül fut |
src/uno.ts |
Az egyetlen diszpécserfájl: egy URL, egy kliens, zárt engedélyezési lista |
src/routes/*.ts |
health (névtelen, pontos útvonal), a /api útvonalak (hatókörhöz kötött) és a /internal visszahívás (szolgáltatásvédett) |
src/skills/sentiment.ts |
Determinisztikus host_callback skill; cserélje le a szótárat a saját logikájára |
src/server.ts |
A kompozíciós gyökér: egyszer telepíti az elutasítási naplót, (korlátozott ideig) vár az adatbázisra, majd a figyelés megkezdése előtt lefuttatja az izolációs és naplóellenőrzéseket |
migrations/000_tenancy.sql |
A nexus-tenancy render állítja elő a vázgeneráláskor: szerepkörök, séma, a sorszintű biztonsági sablon |
migrations/001_init.sql |
Két tábla bérlővel kezdődő összetett kulccsal és összetett, bérlőt hordozó idegen kulccsal |
migrations/002_refusal_ledger.sql |
Az a tábla, amelybe az elutasítási napló ír |
scripts/ci/required-env |
JSON formátumban kiírja az indításhoz szükséges környezeti változók neveit |
scripts/ci/shadow-migrate-*.sh |
A pipeline migrációs próbafuttatása a nexus-migrate használatával |
gates/ |
A kapuk mentességi könyvtára: üres, ami egy új plugin helyes állapota |
test/ |
Tesztek a hatókörhöz, az útvonalakhoz, az adatbázishoz, a diszpécseléshez és az indításhoz, azokkal a hatókör-helyettesítőkkel, amelyeket minden teszt injektál |
Dockerfile |
Nem root image (felhasználói azonosító: 10001), benne a migrációkkal |
Néhány fájlt érdemes közelebbről is megvizsgálni.
A src/config.ts két szabályt követ. Minden hibát összegyűjt, mielőtt kivételt dob, így egyetlen újraindítás megnevezi mind az öt hiányzó változót ahelyett, hogy öt újraindítás nevezne meg egyet-egyet. Továbbá csak akkor ad alapértéket, ha egy hibás érték nem vezethet csendes, hibás eredményhez: a PORT alapértéke lehet 8080, mert a hibás port láthatóan meghiúsítja a kötést, míg a DATABASE_URL és a UNO_DISPATCH_URL kötelező, és fürtön belüli címnek kell lennie. A nyilvános címet az indításkor elutasítja.
node scripts/ci/required-env["DATABASE_URL","PLATFORM_JWT_SECRET","PLATFORM_SERVICE_KEY","UNO_DISPATCH_URL"]
A sablon saját tesztje lefuttatja ezt a fájlt, és összeveti a kimenetét azokkal a nevekkel, amelyeket a konfigurációs specifikáció kötelezőként jelöl, így ha egy kötelező változót a lista frissítése nélkül vesz fel, a npm test sikertelen lesz.
A src/server.ts addig nem kezd figyelni, amíg az adatbázis nem válaszol, és a várakozást 120 másodpercre korlátozza, minden sikertelen kísérletet az okával együtt naplózva. Ezután sorrendben igazolja, hogy az alkalmazás szerepköre nem tudja újrakötni a bérlőt, és minden tábla kényszerítetten sorszintű biztonság alatt áll, hogy minden pod készlete belefér a szerepkör kapcsolatkorlátjába, és hogy az elutasítási napló táblája képes sort fogadni. A három bármelyikének elutasítása teljes egészében kiírásra kerül, és a folyamat 2-es kóddal kilép.
A v2 manifesztum, mezőről mezőre
A manifest a plugin géppel olvasható szerződése a platformmal. Validálásra kerül, amikor Ön megírja, amikor a platform bevezeti, és azt követően folyamatosan. A séma minden szinten additionalProperties: false: ha a pluginjának van egy szakasza, létezik hozzá tulajdonság, a nem deklarált kulcsot pedig elutasítja. A megoldás mindig a megfelelő opcionális tulajdonság használata.
A kötelező mag
| Mező | Szabály |
|---|---|
manifestVersion |
Pontosan "2". A v1 dokumentum migrálásra kerül, soha nem validálódik újra helyben |
name |
^[a-z0-9]+([-.][a-z0-9]+)*$, legfeljebb 64 karakter. A regisztrációban, a diszpécselési névtérképzésben és a bérlőhöz kötött sorokban használt pluginazonosító. A skilleket deklaráló pluginnak olyan névre is szüksége van, amely nem tartalmaz pontot, és nem kezdődik számjeggyel |
displayName |
1–120 karakter |
version |
Szemantikus verzió; az Ön saját kiadási ütemezése |
description, author, license |
Mindegyik legalább egy karakter |
tier |
skills-only, ui-only vagy full-service |
trust |
core, verified, community vagy untrusted |
runtime |
Kötelező: executionMode, isolationLevel (1–4), entrypoint. Opcionális: nodeVersion, healthCheck, readinessCheck, livenessCheck, mindegyik / kezdetű útvonal. A mód a szintből adódik: 1 external_https, 2 mcp_container, 3 hardened_docker, 4 firecracker |
architecture |
compute, ai és deploy, a három platformtörvény újrafogalmazva. A validátor rögzíti a megfogalmazást |
A saját telepítéséhez készített plugin esetében a három mondat a következőképpen hangzik. A ai mondat a mesterséges intelligenciára (AI) vonatkozik, és itt kell kijelenteni, hogy a plugin nem tárol modell-hitelesítő adatokat.
"architecture": {
"compute": "All compute runs via UNO dispatch (nexus-orchestrator /api/v1/dispatch + nexus-workflows). No direct engine, queue or model-provider calls from plugin code.",
"ai": "All AI goes through the AI Provider Router, which alone owns the credential and the final provider/model decision. This plugin holds no model credentials.",
"deploy": "Deploy is through the installation's release channels only."
}Az útvonaltábla: api és rights
A api megköveteli a version és a basePath mezőt, opcionálisan a websocket (path, auth) és a endpoints[] mezőt is. Az útvonaltábla a séma legerősebb gondolata: egy kapu mindkét irányban összeveti azokkal az útvonalakkal, amelyeket a kódja ténylegesen regisztrál, így a manifest ellenőrizhető szerződés, nem pedig dokumentáció.
Minden végpontnak szüksége van a method (GET, POST, PUT, PATCH vagy DELETE) és a path mezőre. A többi:
| Mező | Mit tartalmaz |
|---|---|
auth |
Öt osztály egyike: scope (egy személy útvonala, a hatókörvédő mögött), service-key és internal (szerver–szerver, böngészőből soha nem érhető el), public (mindig csak pontos útvonal a allowAnonymous mellett) és device (saját hitelesítő adattal rendelkező gép, az eszközvédő mögött) |
right |
Kötelező minden olyan útvonalon, amelyet a hatókörvédő szolgál ki, és minden másikon elutasított: a rights nyilvántartásban szereplő jogosultság neve |
needsUnit |
Az útvonal elutasít, ha a hívó egysége nem oldható fel |
allowAnonymous |
Csak pontos egyezésű engedélyezési lista. Egy előtagszabály miatt válik a /health-of-tenant-42 nyilvánossá |
group, serves, screens |
Egy release blokkon belül: az útvonal által kiszolgált képességcsoport, az, amit akkor válaszol, ha a csoport licencelt funkciója zárolva van (data, teaser, sighting vagy ask), valamint az általa kiszolgált képernyők |
query |
required (mindegyik név egy példaértékkel) és allowed: az útvonal által olvasott lekérdezési paraméterek |
body |
example: egy író útvonal példatörzse, amelyet a saját validátora elfogad. GET esetén soha |
A rights az a nyilvántartás, amelyre ezek az útvonalak hivatkoznak. Minden jogosultságnak van roles mezője (a felső határ), és opcionálisan summary, never (azok a szerepkörök, amelyek soha nem gyakorolhatják, bármi mással rendelkeznek is), barred (a termék saját megfogalmazása egy never szerepkör elutasítására), seat (élő licenchely is szükséges), self (minden ellenőrzött személy rendelkezik vele, a saját munkamenetük feletti jogosultságokhoz), grants (a birtokosai licenchelyeket osztanak ki; legfeljebb egy jogosultság mondhatja ezt), licence (olyan licencelt funkció, amelyet a szervezet licencének tartalmaznia kell), installation (csak a telepítés saját adminisztrátorai rendelkeznek vele) és platform (csak az Adverant platformadminisztrátorai rendelkeznek vele; szerepköröket nem nevez meg). A jogosultságnevek legalább egy pontot tartalmaznak: project.read, money.pay.
"api": {
"version": "1",
"basePath": "/",
"endpoints": [
{ "method": "GET", "path": "/health", "summary": "Liveness", "auth": "public", "allowAnonymous": true },
{ "method": "GET", "path": "/api/projects", "summary": "List the caller's projects", "auth": "scope", "right": "project.read" },
{ "method": "POST", "path": "/api/projects", "summary": "Create a project", "auth": "scope", "right": "project.create" },
{ "method": "POST", "path": "/internal/skills/sentiment_score", "summary": "host_callback receiver", "auth": "service-key" }
]
},
"rights": {
"project.read": { "summary": "Read the organisation's projects.", "roles": ["owner", "admin", "member", "viewer"] },
"project.create": { "summary": "Open a project.", "roles": ["owner", "admin", "member"] }
}A definePlugin elutasítja a jogosultság nélküli hatókör-útvonalat (ENDPOINT_RIGHT_MISSING), a nyilvántartásban nem szereplő jogosultságot (ENDPOINT_RIGHT_NOT_REGISTERED), valamint az olyan útvonalon lévő jogosultságot, amelyet egyetlen védő sem szolgál ki (ENDPOINT_RIGHT_UNGUARDED). Elutasítja az önellentmondó nyilvántartást is, valamint egy útvonal két írásmódját (:id és :recordId) DUPLICATE_ENDPOINT hibaként.
Az Ön adatai: databases, schema és db
A schema az egyetlen Postgres-séma, amely a pluginé. A public, plugins, auth és nexus tiltott, és ha a databases[] is megnevez egy Postgres-sémát, a kettőnek egyeznie kell.
A databases[] motoronként deklarálja az egyes tárolókat: postgresql (schema, tables, migrations és granted, azok a táblák, amelyeket egy másik szervezet rögzített engedély alapján olvashat), neo4j (schemas), qdrant (collections) vagy redis (purpose).
A db tartalmazza a plugin által megnyitott összes kapcsolat munkamenet-korlátait, amelyeket itt deklarálnak, nem pedig kódban, hogy a bíráló és a telepítés egyaránt olvashassa őket:
| Mező | Mit korlátoz |
|---|---|
maxConnections |
A replikánkénti készletet |
pods |
Az egyszerre készletet tartó podok maximális számát, a replikák és a gördülő frissítés túllépésének összegét. Az egyes szerepkörök kapcsolatkorlátja maxConnections × pods formában jelenik meg; ha elhagyja, a definePlugin figyelmeztet: DB_PODS_UNDECLARED |
statementTimeoutMs |
Egy utasítást |
idleInTransactionTimeoutMs |
Egy nyitott, semmit nem futtató tranzakciót |
workMemKB |
Egy rendező vagy hash csomópontot, csomópontonként, nem lekérdezésenként |
piiMask[] |
Személyes adatokat tartalmazó table.column bejegyzések, amelyek maszkolva jelennek meg a szabályozott SQL-konzolban és a naplókban |
Skillek és eszközök: skills, mcpTools, entitlements
A skills[] a manifest skilleket tartalmazza; mezőiket és szintjeiket a 2.20. fejezet, Skillek tárgyalja. A mcpTools[] a plugin által közzétett MCP- (Model Context Protocol) eszközöket tartalmazza, mindegyik egy name, egy description és egy inputSchema, legfelső szintű oneOf, allOf vagy anyOf nélkül.
A entitlements megköveteli a featureIdPattern mezőt, és elfogadja a alwaysOn[], source és store mezőt. A minta azt a névteret nevezi meg, amelyben a funkcióazonosítók élnek, megállapodás szerint a plugin name értékét és egy további szegmenst, amelyet a kódja felületenként tölt ki. A alwaysOn[] az a rövid, pontos lista, amelynek akkor is válaszolnia kell, ha nem kapható jogosultsági döntés: állapot, készenlét, bejelentkezés, valamint azok a beállítások, amelyekre egy adminisztrátornak a jogosultság helyreállításához szüksége van.
Változáskezelés: changePolicy
"changePolicy": {
"enabled": true,
"classes": ["website", "bff", "migration"],
"approvals": { "website": 1, "bff": 1, "migration": 2 }
}A jóváhagyásokat különböző személyek szerint számolják, és a változtatást javasló személy soha nem tartozik közéjük; e két feltétel nélkül a „két jóváhagyás” egyetlen személy kétszeri kattintásává válik. A enabled: true megköveteli a classes mezőt, és minden megnevezett osztálynak saját darabszám kell. Az elhagyott osztály szabályozatlan, ami jogos választás, de a séma megköveteli, hogy ezt írásban rögzítse.
Kicsoda Ön: domains, branding, routing
A domains[] (mindegyik primary és aliases[]; a domain az egytartományos forma) felsorolja, hol válaszol a plugin. A branding megköveteli a appName mezőt, és elfogadja a tagline, logo, favicon, primaryColor, accentColor, oauthClientRef, passkeyRpId és gaId mezőt. A branding tartalma teljes egészében nyilvános: a bejelentkezési oldal azelőtt olvassa, hogy bárkinek hitelesítő adata lenne, ezért soha nem tartalmazhat titkot vagy belső címet. A routing (type, gateway, virtualService) azoknak a pluginoknak szól, amelyek saját útválasztásukat írják le.
Méretezés és egyebek
A(z) resources megköveteli a(z) cpuMillicores (10 és 64 000 között) és a(z) memoryMB (16 és 262 144 között) mezőt, és elfogadja a(z) diskGB, timeoutMs, port és wsPort mezőt. A(z) backend tartalmazza a(z) port, healthPath, apiPrefix, framework és platformClients[] elemet, azokat az SDK-klienseket, amelyeket a háttérrendszere név szerint importál. A lista zárt, és egy ellenőrzőkapu összeveti az Ön importjaival. A séma tizennégy nevet enged meg: access, bindings, documents, files, governance, graph, jobs, keys, memory, platform, runs, signin és uno, továbbá egyet annak a kliensnek, amely a csomagjogosultsági elutasításokra válaszol, és amely belső nevet visel. A funkciójogosultsági kliens, a(z) runtime/entitlements, nem tartozik közéjük, és soha nem kerül fel a listára, mert az Ön entitlements blokkja már deklarálja, és az a háttérrendszer, amely entitlements blokk nélkül importálja, ugyanazon az ellenőrzőkapun bukik el. A(z) frontend tartalmazza a(z) basePath, mountPath és framework elemet. A(z) nexus tartalmazza a(z) minVersion, maxVersion, capabilities[] és permissions[] elemet.
A többi blokk mindegyike egyetlen feladatot szolgál:
| Blokk | Célja |
|---|---|
settings |
Az Ön beállításai a közös keretrendszeren: groups és keys, az egyes beállítások által megnevezett szinteken megadva |
people |
sweep (service, port): a szervezet tagjai, az identitásszolgáltatásból szinkronizálva, a helyek kikapcsolásával, amikor valaki távozik |
ontology |
entityTypes és relationshipTypes: a típusos gráf, amelyet a saját sémájában tárol |
release |
groups és frame: azok a képességcsoportok, amelyekben az útvonalai fokozatosan kerülnek bevezetésre, elsőként canary kiadásként |
cells[] |
Több telepíthető egységből álló bővítmény: mindegyikhez name, kind, entrypoint, port, wsPort |
pricing |
model, currency, tiers[] a katalógusbeli listázásához |
marketplace |
category, icon, screenshots, documentation, featured |
compliance |
instruments[], dataResidency, sovereignty |
developer, repository, keywords |
Ki teszi közzé, és hol található a kódja |
metrics, atlas |
A két szándékosan nyitott objektum, a saját metrikaneveihez és az architektúra-dokumentáció generálásához |
Amit a séma nem tud kifejezni
A JSON Schema a szerkezetet rögzíti; a(z) definePlugin hozzáadja azokat a szabályokat, amelyeket egy séma nem tud kifejezni. Egy képesség classification értéke nem haladhatja meg a bizalmi felső határt. Csak core és verified bővítmények deklarálhatnak tool_using és llm_only képességeket. Minden deklarált útvonalnak relatívnak és azonos eredetűnek kell lennie, séma, // és fordított perjel nélkül, mert az URL-elemző a(z) \ karaktert / karakterré alakítja, és a(z) /\evil.example/x más eredetre oldódik fel. Minden szabályt, amelyet a regisztrációs szinkronizálás egy képességre alkalmaz, előbb itt alkalmazunk, a szinkronizálás saját kódjával, így a(z) validate és a szinkronizálás ugyanúgy nevezi meg a megsértett szabályt.
Validálás és átállás v1-ről
npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin validate nexus.manifest.json✔ anomaly-review@0.3.0 · tier=full-service · trust=community · skills=1 · mcpTools=0
Hiba esetén pontos útvonalat ír ki, szinkronizálási szabály esetén pedig elsőként a kódot. Állítsa be commit hookként.
Egy v1 manifest gépiesen átemelhető. A(z) migrate hozzáadja a három jogi mondatot, a(z) domain elemet a(z) domains[] helyre mozgatja, és nem hajlandó olyan belépési pontot kitalálni, amely korábban nem létezett. Az eredményt kiírás vagy mentés előtt validálja, így a migráció soha nem helyez át egy hibát az eszközből az Ön tárolójába.
npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin migrate nexus.manifest.json --writeOlvassa el a diffet, mielőtt véglegesíti. Az általa hozzáadott jogi mondatok a validátor által rögzített megfogalmazást követik; saját telepítéséhez állítsa a(z) deploy értékét a korábban bemutatott mondatra.
A bérlői környezet (tenancy) kirenderelése és a szerepkörök kiosztása
A szerepkör-jogosultságokat és a sorszintű biztonsági sablont soha nem kell kézzel megírnia. A(z) nexus-tenancy render a manifest schema és db eleméből állítja elő őket:
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-tenancy render --manifest nexus.manifest.json --out migrations/000_tenancy.sqlAz előállított fájl öt szerepkört hoz létre a sémához, mindegyiket azzal együtt, amivel nem rendelkezhet: egy migrátort, amely csak tulajdonossá válhat, egy tulajdonost, amely nem tud bejelentkezni, egy alkalmazásszerepkört a kérések útvonalához, egy jelentésszerepkört, amely csak összesítéseket lát, és egy főkönyvi szerepkört, amely csak hozzáfűzni tud. Egyik szerepkör sem rendelkezik BYPASSRLS jogosultsággal. Bérlőt kizárólag egyetlen adatbázisfüggvénnyel lehet kötni, és a(z) set_config jogosultság a tulajdonos kivételével minden szerepkörtől vissza van vonva.
Egy már alkalmazott bérlői fájlt soha nem szerkesztünk. A módosítás egy revízió, saját 0-s számú fájllal, és a szervezetek közötti jogosultságokhoz tartozó olvasási hely is így érkezik, 2. revízióként. A(z) --graph a(z) ontology által deklarált típusos gráf két tábláját a következő sorszámozott migrációként állítja elő.
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-tenancy render --manifest nexus.manifest.json --revision 2 --out migrations/000_tenancy_r2.sql
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-tenancy render --manifest nexus.manifest.json --graph --out migrations/001_graph.sqlA bérlői fájl éppen azokat a szerepköröket hozza létre, amelyekként a futtató csatlakozik, ezért az adatbázis tulajdonosa alkalmazza a(z) nexus-migrate provision paranccsal:
DATABASE_URL=<database-owner-url> npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-migrate provision --state <dir>A(z) <database-owner-url> az adatbázis tulajdonosának kapcsolati karakterlánca, a(z) <dir> pedig egy privát könyvtár. A provisioning sorrendben alkalmazza az alap bérlői fájlt és minden revíziót, a(z) migrator.url és app.url fájlt (valamint a(z) seat.url fájlt, ha a 2. revízió létezik) 0600 jogosultsággal a(z) <dir> könyvtárba írja, és semmilyen titkos adatot nem ír ki. Minden futtatáskor beállítja az egyes szerepkörök kapcsolati korlátját a(z) db.maxConnections × db.pods alapján. Ismételt futtatáskor a meglévő jelszavak megmaradnak, hacsak másként nem kéri: a(z) --passwords <dir> fájlokból állítja be őket, a(z) --rotate <roles> pedig új jelszót ad a megnevezett szerepköröknek. Alakítsa a fájlokat a telepítése titkaivá.
Ezt követően az alkalmazás a migrátor azon kapcsolati karakterláncával csatlakozik, amelyet a provisioning kiírt:
DATABASE_URL="$(cat <dir>/migrator.url)" npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-migrate apply --manifest nexus.manifest.jsonA 001-es fájltól kezdve migrátorként futtatja a(z) SET ROLE <schema>_owner alatti összes fájlt, fájlonként egy tranzakcióban. Főkönyvet vezet, a(z) <schema>.schema_migrations táblát, minden fájl ellenőrzőösszegével; egy már alkalmazott fájlt, amelynek bájtjai megváltoztak, név szerint elutasít (CHECKSUM_DRIFT), soha nem futtat újra és soha nem hagy ki. Minden függőben lévő fájlt a valódi Postgres-nyelvtannal elemez, mielőtt az első lefutna, így elutasítás esetén az adatbázis érintetlen marad. Egy fájl egyetlen fejlécet tartalmazhat, a(z) -- nexus-migration: transaction=file|per-statement fejlécet, opcionális zárolási és utasítás-időkorlátokkal; a(z) per-statement a(z) CREATE INDEX CONCURRENTLY számára szolgál.
A kapuk
A(z) nexus-gates huszonkét ellenőrzőkaput futtat. Mindegyik a hibák egy osztályát rögzíti, hogy az ne kerülhessen ki kétszer, és mindegyikhez tartozik egy önteszt, amely igazolja, hogy elbukik egy kifejezetten erre készített teszt-adatkészleten. Futtassa őket, mielőtt push műveletet végez:
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --self-test| Ellenőrzőkapu | Mit szűr ki |
|---|---|
scope-adherence |
/api útvonal hatókörvédelem nélkül; névtelen útvonal, amely nem pontosan egy deklarált útvonal; eszközútvonal eszközvédelem nélkül, vagy mellette egy személyre vonatkozó védelemmel |
one-fence |
Bérlői predikátum, amely nem az egyetlen kijelölt helyen van definiálva, beleértve a kézzel írt hely- vagy jogosultsági korlátot is |
sql-fence |
Olyan utasítás, amely hatókörhöz kötött táblát olvas vagy frissít a korlát nélkül, bármely FROM, JOIN, USING vagy UPDATE célban |
migrations-are-scoped |
Olyan tábla, amelyből hiányzik egy tengely, egy bérlővel kezdődő összetett kulcs, egy bérlőt hordozó idegen kulcs vagy a demóoszlop |
migrations-commit-what-they-open |
Olyan migráció, amelynek BEGIN száma nem egyezik a(z) COMMIT és ROLLBACK számával |
no-direct-compute |
Modellszolgáltató, motor, sor vagy munkafolyamat-gazda közvetlen hívása; a diszpécser-URL második olvasója |
no-credentials |
A tárolóban vagy a környezetben olvasható modellszolgáltatói hitelesítő adat |
crud-adherence |
Módosító útvonal, amelynek jogosultság-ellenőrzése semmit sem nevez meg a nyilvántartásból |
blocked-backends |
Olyan útvonal, amelyet sem nem szolgálnak ki, sem nem tiltanak le név szerint, sem nem utasít el jogszabály, sem nem birtokol más |
every-test-runs |
Tesztek, amelyeket a tesztszkript globmintája soha nem ér el |
tiles-are-invariant |
Bérlőfüggetlen, gyorsítótárazott csatlakozási pont, amely bérlői értéket olvas vagy kihagyja a hitelesítést |
api-contract |
Regisztrált útvonal, amelyet a manifest nem deklarál, vagy deklarált útvonal, amelyet a kód soha nem regisztrál |
rls-present |
Kényszerített sorszintű biztonság nélküli tábla; SECURITY DEFINER függvény rögzített search_path nélkül |
no-set-config |
Bővítménykód, amely maga köti a bérlői beállítást |
db-role-honest |
Kérési útvonal, amely tulajdonosként vagy migrátorként csatlakozik, vagy SUPERUSER vagy BYPASSRLS jogosultságot kér |
platform-clients |
SDK-kliens, amely importálva van, de nem szerepel a(z) backend.platformClients listában, vagy szerepel, de soha nincs importálva |
rights-register |
Hatóköri útvonal deklarált jogosultság nélkül; jogosultság-ellenőrzés a nyilvántartás mellett |
refusal-ledger |
Deklarált elutasítási tábla telepített főkönyv nélkül, vagy azt megkerülve küldött elutasítási törzs |
grants-declared |
Jogosultsággal ellátott tábla, amelyet a manifest nem deklarál; kézzel kiosztott olvasásihely-jogosultságok |
people-declared |
people blokk a hozzá tartozó takarítási útvonal, védelem és táblák nélkül |
functions-closure |
Azure Functions-bővítmény, amelynek kiszolgált és deklarált útvonalai eltérnek |
declared-input |
Kezelő, amelynek lekérdezésiparaméter-listája nem egyezik az útvonal deklarált query értékével |
A(z) gates/ könyvtár tartalmazza azt az öt kivételfájlt, amelyet egy ellenőrzőkapu olvashat (demo-exempt.json, non-crud.json, blocked-backends.json, tenant-resolving.json és invariant-seams.json), bejegyzésenként egy indoklással. Az üres indoklás bejegyzés hiányának számít, és az a bejegyzés, amely már nem létező elemet nevez meg, az ellenőrzőkapu bukását okozza. Saját ellenőrzőkapu-moduljait is elhelyezheti itt, és a(z) nexus-gates a beépítettek mellett ezeket is felismeri.
A sablon CI/CD folyamata (pipeline)
A sablon nem tartalmaz kézzel írt munkafolyamatot. A folyamatkonfigurációja megnevezi a Dockerfile-t, az egyetlen buildargumentumot (a registry tokent), a migrációs próbafuttatást és az indítási próbát, valamint az ellenőrzőkaput, amelyet az egyesítési sor futtat. A sorrend az, amelyben a hibákat észlelni szeretné.
npm cinpm run typechecknpm run buildnpm testnpm run validate:manifest, azazcreate-nexus-plugin validate nexus.manifest.jsonnpm run gates, azaznexus-gates --self-testnode scripts/ci/required-env
Az image körül további két ellenőrzés fut. A migrációs próbafuttatás minden fájlt alkalmaz egy eldobható Postgres-példányon, mielőtt az image kiadható lenne, ugyanazzal a futtatóval, amelyet az éles környezet is használ: a(z) nexus-migrate provision parancsot egyszer superuserként futtatja, majd minden sorszámozott fájlt migrátorként alkalmaz. Az indítási próba a saját belépési pontjával indítja el az elkészült image-et, minden olyan változóval, amelyet a(z) required-env kiír, olyan helyettesítőkre irányítva, amelyek elfogadják a kapcsolatokat, de soha nem válaszolnak. A szerver a korlátozott időablakán belül vár az adatbázisra, és ez a várakozás a sikeresség jele; az a konfigurációbetöltő, amely nem hajlandó elindulni, ott bukja el a buildet, nem pedig éles környezetben.
Mennyibe kerül
Az SDK döntéseket vesz el Öntől, és ezek közül néhányat Ön másként hozott volna meg. A manifest elutasítja az ismeretlen kulcsokat, az útvonaltáblának pontosan egyeznie kell a kóddal, az adatbázis-szerepkörök megtervezése nem az Ön feladata, és az ellenőrzőkapuk egy olvasási művelethez hiányzó jogosultság miatt is elbuktatják a buildet. Az első bővítményemnél egy napot vitatkoztam a(z) api-contract eszközzel egy útvonal miatt, amelyet regisztráltam, de elfelejtettem deklarálni. Neki volt igaza: az útvonal védelem nélkül maradt. Számítson arra, hogy az első bővítmény lassúnak tűnik majd, és arra, hogy a második harmannyi időt vesz igénybe.

