Versija 1.0.0-alpha.1naujausia
2.21 skyrius
Įskiepių SDK
Įskiepių SDK (programinės įrangos kūrimo rinkinio) diegimas, jo komandinės eilutės įrankiai, pilnos tarnybos šablono apžvalga, v2 manifesto laukai po vieną ir dvidešimt du barjerai, užtikrinantys, kad įskiepis laikytųsi taisyklių.
Šį puslapį iš originalo anglų kalba išvertė DI. Jei kas nors neaišku, remkitės puslapiu anglų kalba. Skaityti šį puslapį anglų kalba

Mano antrajam papildiniui sukurti prireikė trečdalio laiko, kurį skyriau pirmajam, ir beveik visą sutaupymą lėmė SDK (programinės įrangos kūrimo rinkinys). Pirmą kartą parašiau aprėpties patikrą, konfigūracijos įkėliklį ir migracijų vykdyklę, o recenzentas grąžino kiekvieną iš jų. Antrą kartą paleidau vieną karkaso komandą, ištryniau pavyzdinį nuotaikų analizės įgūdį ir savo dienas skyriau anomalijų peržiūros įrašams, kurių iš tikrųjų reikėjo mūsų skrydžio dinamikos komandai.
@adverant-nexus/plugin-sdk yra vienas npm paketas. Jame yra v2 manifesto schema ir ją skaitantys tikrintuvai (definePlugin, defineSkill), vykdymo aplinkos moduliai, kuriuos jūsų papildinys importuoja aprėpčiai, duomenų bazei, siuntimui ir kitoms reikmėms, testavimo pagalbinės priemonės, atitikties vartai ir komandinės eilutės įrankiai. Šiame skyriuje aprašoma, kaip jį įdiegti, taip pat įrankiai, šablonas, manifestas ir vartai. 2.22 skyriuje „Papildinio vykdymo aplinka“ aprašomi vykdymo aplinkos moduliai jūsų veikiančiame kode.
Jo diegimas
Paketas gaunamas iš Adverant registro adresu https://registry.adverant.ai/npm/, niekada ne iš viešojo npm registro, ir jums reikia atsisiuntimo prieigos rakto iš jūsų paskyros puslapio „Pull tokens and install commands“. Nukreipkite @adverant-nexus aprėptį į registrą savo saugyklos faile .npmrc:
@adverant-nexus:registry=https://registry.adverant.ai/npm/
//registry.adverant.ai/npm/:_authToken=<pull-token>
<pull-token> yra prieigos raktas iš jūsų paskyros puslapio. Konvejeryje perduokite jį iš slapto kintamojo ir niekada jo neįtraukite į saugyklą; šablono Dockerfile atsisako kurti atvaizdą be jo ir, įvykdžius npm ci, ištrina .npmrc iš kūrimo etapo, todėl prieigos raktas niekada nepatenka į atvaizdą.
Tada tiksliai užfiksuokite versiją:
npm install --save-exact @adverant-nexus/plugin-sdk@2.50.0Pirmą kartą diegdami įtraukite package-lock.json į saugyklą. Šablono atvaizdo kūrimas vykdo npm ci ir atsisako grįžti prie npm install: užrakto failas yra sutartis. Pačiam SDK reikia bent Node 18; šablonas skirtas Node 20.
Komandinės eilutės įrankiai pateikiami pakete, todėl kiekvienoje šios dokumentacijos komandoje paketas ir jo versija nurodomi su npx -p. Atskirai npx create-nexus-plugin ieškomas viešajame registre, o tas pavadinimas nėra šis paketas.
Komandinės eilutės įrankiai
| Įrankis | Ką daro |
|---|---|
create-nexus-plugin |
Sukuria papildinio karkasą, patikrina manifestą, perkelia v1 manifestą į v2 ir sugeneruoja vartotojo vadovą jūsų sąsajos kūrėjui |
nexus-tenancy |
Iš manifesto sugeneruoja jūsų schemos nuomininkų atskyrimo SQL: vaidmenis, suteikimus, eilučių lygio saugos šabloną ir grafo lenteles |
nexus-migrate |
Taiko jūsų migracijas: vieną kartą sukuria vaidmenis, tada kiekvieną numeruotą failą vykdo migratoriaus vaidmeniu |
nexus-gates |
Vykdo visus atitikties vartus ir kiekvienų vartų savitikrą |
create-nexus-plugin neatlieka jokių tinklo užklausų ir neįkelia jokio nuotolinio kodo. Jis vykdo tuos pačius procese veikiančius tikrintuvus, kuriuos vykdo platformos prijungimo procesas, todėl nėra neatitikimo tarp „mano kompiuteryje patikrinimas praėjo“ ir „platforma jį priėmė“.
| Komanda | Vėliavėlės | Ką daro | Užbaigimo kodai |
|---|---|---|---|
scaffold <name> |
--tier full-service\|ui-only\|skills-only, --dir <path>, --print |
Sukuria naują papildinio katalogą; --print išveda tik manifestą |
0 įrašyta · 1 atsisakyta perrašyti · 2 netinkamas naudojimas |
validate <file> |
Patikrina nexus.manifest.json arba .ts ar .js modulį, kuris jį eksportuoja |
0 tinkamas · 1 netinkamas arba neperskaitomas · 2 netinkamas naudojimas | |
migrate <file> |
--write |
Perkelia v1 manifestą į v2 ir jį išveda arba įrašo vietoje | 0 · 1 · 2, kaip nurodyta aukščiau |
guide |
--manifest <file>, --narrative <dir>, --out <guide.md>, --check, --lint |
Iš manifesto ir jūsų aprašomojo teksto sugeneruoja vartotojo vadovą; --check palygina su įtraukta kopija ir nieko neįrašo |
0 · 1 neatitikimas arba stiliaus tikrinimo pažeidimas · 2 netinkamas naudojimas |
help |
Išveda naudojimo informaciją | 0 |
Ruošinių kūrimas ir trys pakopos
npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin scaffold anomaly-review --tier full-service--tier numatytoji reikšmė yra full-service. Karkaso generatorius atsisako rašyti į jau esamą katalogą, o jo įrašytas manifestas jau praeina patikrinimą; jis niekada nesukuria netinkamo manifesto.
Pakopą pasirinkite pagal tai, ką turi jūsų papildinys.
| Pakopa | Turi | Privalo deklaruoti |
|---|---|---|
skills-only |
Tik manifesto įgūdžius | skills[], su bent vienu įrašu |
ui-only |
Sąsajos paviršių apvalkale | frontend |
full-service |
Užpakalinę ir priekinę dalis, paprastai su savo schema | backend ir frontend; o kadangi turi užpakalinę dalį, ir runtime.healthCheck |
Jei nesate tikri, sukurkite full-service karkasą ir ištrinkite tai, ko jums nereikia. Einant priešinga kryptimi tektų rašyti dalis, kurias jums būtų pateikęs šablonas.
Pilnos tarnybos šablono apžvalga
Šablonas yra pavyzdinis papildinys, sukurtas pagal griežtą modelį, kurį numato visi tolesni skyriai. Kopijuokite jo struktūrą, ne jo pavyzdinę logiką.
| Kelias | Kas tai yra |
|---|---|
nexus.manifest.json |
v2 manifestas: trys dėsniai, pakartoti iš naujo, maršrutų lentelė ir jos teisių registras |
src/config.ts |
Konfigūracijos įkėliklis. Viena specifikacija, perskaitoma vieną kartą; visos problemos surenkamos prieš procesui atsisakant paleisti |
src/scope.ts |
Vienintelis failas, kuris užklausą paverčia aprėptimi, su griežtu SDK prieigos rakto tikrintuvu ir dviem režimais: asmens nešėjo prieigos raktu ir platformos tarnybos iškvietimu |
src/db.ts |
Kiekvienas sakinys sudaromas su tenantFence() ir vykdomas withScopedTx viduje |
src/uno.ts |
Vienintelis siuntimo failas: vienas URL, vienas klientas, uždaras leidžiamųjų sąrašas |
src/routes/*.ts |
health (anoniminis, tikslus kelias), /api maršrutai (su aprėptimi) ir /internal atgalinis iškvietimas (saugomas tarnybos apsaugos) |
src/skills/sentiment.ts |
Deterministinis host_callback įgūdis; pakeiskite žodyną savo logika |
src/server.ts |
Kompozicijos šaknis: vieną kartą įdiegia atsisakymų žurnalą, laukia duomenų bazės (ribotą laiką), tada prieš pradėdamas klausytis atlieka izoliacijos ir žurnalo patikras |
migrations/000_tenancy.sql |
Sugeneruojama nexus-tenancy render kuriant karkasą: vaidmenys, schema, eilučių lygio saugos šablonas |
migrations/001_init.sql |
Dvi lentelės su sudėtiniu raktu, prasidedančiu nuomininku, ir sudėtiniu, nuomininką apimančiu išoriniu raktu |
migrations/002_refusal_ledger.sql |
Lentelė, į kurią rašo atsisakymų žurnalas |
scripts/ci/required-env |
Išveda paleidimui būtinų aplinkos kintamųjų pavadinimus JSON formatu |
scripts/ci/shadow-migrate-*.sh |
Konvejerio bandomasis migracijų paleidimas per nexus-migrate |
gates/ |
Vartų išimčių katalogas: tuščias, ir tai yra teisinga naujo papildinio būsena |
test/ |
Aprėpties, maršrutų, duomenų bazės, siuntimo ir paleidimo testai su aprėpties pakaitalais, kuriuos įterpia kiekvienas testas |
Dockerfile |
Ne root atvaizdas (naudotojo ID 10001) su jame esančiomis migracijomis |
Kai kuriuos iš šių failų verta panagrinėti atidžiau.
src/config.ts laikosi dviejų taisyklių. Prieš išmesdamas klaidą jis surenka visas problemas, todėl vienas paleidimas iš naujo įvardija visus penkis trūkstamus kintamuosius, užuot penkiems paleidimams iš naujo įvardijus po vieną. Be to, numatytąją reikšmę jis nustato tik tada, kai klaidinga reikšmė negali lemti tylaus klaidingo atsakymo: PORT numatytoji reikšmė gali būti 8080, nes dėl klaidingo prievado susiejimas matomai nepavyksta, o DATABASE_URL ir UNO_DISPATCH_URL yra privalomi ir turi būti klasterio vidaus adresai. Viešas adresas atmetamas paleidžiant.
node scripts/ci/required-env["DATABASE_URL","PLATFORM_JWT_SECRET","PLATFORM_SERVICE_KEY","UNO_DISPATCH_URL"]
Paties šablono testas paleidžia tą failą ir palygina jo išvestį su pavadinimais, kuriuos konfigūracijos specifikacija žymi kaip privalomus, todėl pridėjus privalomą kintamąjį neatnaujinus sąrašo npm test nepavyksta.
src/server.ts nepradeda klausytis, kol neatsako duomenų bazė, o laukimą apriboja 120 sekundžių ir registruoja kiekvieną nepavykusį bandymą su jo priežastimi. Tada jis paeiliui patikrina, kad programos vaidmuo negali iš naujo susieti nuomininko ir kad kiekvienai lentelei priverstinai taikoma eilučių lygio sauga, kad kiekvieno podo telkinys neviršija vaidmens jungčių limito ir kad į atsisakymų žurnalo lentelę galima įrašyti eilutę. Jei bet kuri iš trijų patikrų atsisako, pranešimas išvedamas visas, o procesas baigiamas kodu 2.
v2 manifestas, laukas po lauko
Manifestas yra mašininiu būdu skaitoma papildinio sutartis su platforma. Jis tikrinamas, kai jį rengiate, kai platforma jį prijungia, ir nuolat po to. Schema visuose lygiuose yra additionalProperties: false: jei jūsų papildinys turi skyrių, jam yra savybė, o nedeklaruotas raktas atmetamas. Sprendimas visada yra naudoti tinkamą neprivalomą savybę.
Privalomasis branduolys
| Laukas | Taisyklė |
|---|---|
manifestVersion |
Tiksliai "2". v1 dokumentas perkeliamas, niekada iš naujo netikrinamas vietoje |
name |
^[a-z0-9]+([-.][a-z0-9]+)*$, ne daugiau kaip 64 simboliai. Papildinio ID, naudojamas registruojant, siuntimo vardų erdvėse ir nuomininko aprėpties eilutėse. Įgūdžius deklaruojančiam papildiniui taip pat reikia pavadinimo be taško ir neprasidedančio skaitmeniu |
displayName |
Nuo 1 iki 120 simbolių |
version |
Semantinė versija; jūsų pačių leidimų ciklas |
description, author, license |
Kiekvienas bent vieno simbolio |
tier |
skills-only, ui-only arba full-service |
trust |
core, verified, community arba untrusted |
runtime |
Privaloma: executionMode, isolationLevel (nuo 1 iki 4), entrypoint. Neprivaloma: nodeVersion, healthCheck, readinessCheck, livenessCheck, kiekvienas – kelias, prasidedantis /. Režimas nustatomas pagal lygį: 1 external_https, 2 mcp_container, 3 hardened_docker, 4 firecracker |
architecture |
compute, ai ir deploy – trys platformos dėsniai, pakartoti iš naujo. Tikrintuvas užfiksuoja formuluotę |
Papildiniui, kurį kuriate savo įdiegčiai, šie trys sakiniai skamba taip. ai sakinys apima dirbtinį intelektą (DI) ir yra vieta nurodyti, kad papildinys neturi jokių modelių prisijungimo duomenų.
"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."
}Maršrutų lentelė: api ir rights
api reikia version ir basePath, o neprivalomai – websocket (path, auth) ir endpoints[]. Maršrutų lentelė yra stipriausia schemos idėja: vartai ją palygina su maršrutais, kuriuos jūsų kodas iš tikrųjų registruoja, abiem kryptimis, todėl manifestas yra patikrinama sutartis, o ne dokumentacija.
Kiekvienam galiniam taškui reikia method (GET, POST, PUT, PATCH arba DELETE) ir path. Visa kita:
| Laukas | Ką tai reiškia |
|---|---|
auth |
Viena iš penkių klasių: scope (asmens maršrutas už aprėpties apsaugos), service-key ir internal (iš serverio į serverį, niekada nepasiekiami iš naršyklės), public (visada tik tikslus kelias su allowAnonymous) ir device (įrenginys su savais prisijungimo duomenimis, už įrenginio apsaugos) |
right |
Privaloma kiekviename maršrute, kurį aptarnauja aprėpties apsauga, ir atmetama bet kuriame kitame: teisės pavadinimas iš rights registro |
needsUnit |
Maršrutas atsisako, kai nepavyksta nustatyti iškviečiančiojo padalinio |
allowAnonymous |
Tik tikslaus atitikimo leidžiamųjų sąrašas. Dėl prefikso taisyklės /health-of-tenant-42 ir tampa viešas |
group, serves, screens |
release bloke: galimybių grupė, kurią aptarnauja maršrutas, ką jis atsako, kai tos grupės licencijuota funkcija užrakinta (data, teaser, sighting arba ask), ir ekranai, kuriuos jis aptarnauja |
query |
required (kiekvienas pavadinimas su pavyzdine reikšme) ir allowed: užklausos parametrai, kuriuos skaito maršrutas |
body |
example: rašymo maršruto pavyzdinis turinys, kurį priima jo paties tikrintuvas. Niekada GET užklausoje |
rights yra registras, kurį įvardija šie maršrutai. Kiekviena teisė turi roles (viršutinę ribą) ir neprivalomai summary, never (vaidmenis, kurie niekada negali jos naudoti, kad ir ką dar turėtų), barred (paties produkto žodžius atsisakant never vaidmeniui), seat (taip pat reikia aktyvios vietos), self (ją turi kiekvienas patvirtintas asmuo – teisėms į savo seansą), grants (turėtojai suteikia vietas; tai gali nurodyti daugiausia viena teisė), licence (licencijuota funkcija, kurią turi apimti organizacijos licencija), installation (ją turi tik pačios įdiegties administratoriai) ir platform (ją turi tik Adverant platformos administratoriai; joje nenurodomi jokie vaidmenys). Teisių pavadinimuose yra bent vienas taškas: 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"] }
}definePlugin atmeta aprėpties maršrutą be teisės (ENDPOINT_RIGHT_MISSING), teisę, kurios registre nėra (ENDPOINT_RIGHT_NOT_REGISTERED), ir teisę maršrute, kurio neaptarnauja jokia apsauga (ENDPOINT_RIGHT_UNGUARDED). Jis taip pat atmeta pats sau prieštaraujantį registrą, o du vieno maršruto užrašymo variantus (:id ir :recordId) – kaip DUPLICATE_ENDPOINT.
Jūsų duomenys: databases, schema ir db
schema yra vienintelė Postgres schema, kuri priklauso papildiniui. public, plugins, auth ir nexus draudžiamos, o jei databases[] taip pat nurodo Postgres schemą, jos turi sutapti.
databases[] kiekvieną saugyklą deklaruoja pagal variklį: postgresql (schema, tables, migrations ir granted – lentelės, kurias kita organizacija gali skaityti pagal užregistruotą suteikimą), neo4j (schemas), qdrant (collections) arba redis (purpose).
db saugo seanso ribas kiekvienai papildinio atidaromai jungčiai; jos deklaruojamos čia, o ne užkoduojamos, kad jas galėtų perskaityti ir recenzentas, ir diegimas:
| Laukas | Ką riboja |
|---|---|
maxConnections |
Telkinį vienai replikai |
pods |
Didžiausią podų, vienu metu turinčių telkinį, skaičių: replikos plius slenkančio atnaujinimo perteklius. Kiekvieno vaidmens jungčių limitas sugeneruojamas kaip maxConnections × pods; jei jo nenurodysite, definePlugin įspės DB_PODS_UNDECLARED |
statementTimeoutMs |
Vieną sakinį |
idleInTransactionTimeoutMs |
Atvirą transakciją, kuri nieko nevykdo |
workMemKB |
Vieną rūšiavimo arba maišos mazgą, kiekvienam mazgui, ne kiekvienai užklausai |
piiMask[] |
table.column įrašai, kuriuose yra asmens duomenų, maskuojami valdomoje SQL konsolėje ir žurnaluose |
Įgūdžiai ir įrankiai: skills, mcpTools, entitlements
skills[] saugo manifesto įgūdžius; jų laukai ir pakopos aprašyti 2.20 skyriuje „Įgūdžiai“. mcpTools[] saugo papildinio skelbiamus MCP (Model Context Protocol) įrankius, kurių kiekvienas turi name, description ir inputSchema be aukščiausio lygio oneOf, allOf ar anyOf.
entitlements reikalauja featureIdPattern ir priima alwaysOn[], source ir store. Šablonas nurodo vardų erdvę, kurioje yra jūsų funkcijų ID, paprastai papildinio name plius vienas segmentas, kurį jūsų kodas užpildo kiekvienam paviršiui. alwaysOn[] yra trumpas, tikslus sąrašas to, kas turi atsakyti net tada, kai teisių sprendimo gauti neįmanoma: būklė, parengtis, prisijungimas ir nustatymai, kurių administratoriui reikia teisėms atkurti.
Pakeitimų valdymas: changePolicy
"changePolicy": {
"enabled": true,
"classes": ["website", "bff", "migration"],
"approvals": { "website": 1, "bff": 1, "migration": 2 }
}Patvirtinimai skaičiuojami pagal skirtingus asmenis, o pakeitimą pasiūlęs asmuo niekada nėra vienas iš jų; be abiejų šių dalių „du patvirtinimai“ virsta vienu asmeniu, spustelėjusiu du kartus. enabled: true reikalauja classes, o kiekvienai nurodytai klasei reikia savo skaičiaus. Klasė, kurios nenurodote, lieka nevaldoma – tai teisėtas pasirinkimas, kurį schema verčia jus užrašyti.
Kas jūs esate: domains, branding, routing
domains[] (kiekvienas primary ir aliases[]; domain yra vieno domeno forma) nurodo, kur papildinys atsako. branding reikalauja appName ir priima tagline, logo, favicon, primaryColor, accentColor, oauthClientRef, passkeyRpId ir gaId. Viskas, kas yra branding, yra vieša: prisijungimo puslapis tai perskaito dar prieš kam nors turint prisijungimo duomenis, todėl ten niekada nėra slaptų duomenų ar vidinių adresų. routing (type, gateway, virtualService) skirtas papildiniams, kurie patys aprašo savo maršrutizavimą.
Dydžio nustatymas ir kita
resources reikalauja cpuMillicores (nuo 10 iki 64,000) ir memoryMB (nuo 16 iki 262,144) bei priima diskGB, timeoutMs, port ir wsPort. backend apima port, healthPath, apiPrefix, framework ir platformClients[] – SDK klientus, kuriuos jūsų backend importuoja pagal pavadinimą. Sąrašas yra uždaras, o patikra jį sutikrina su jūsų importais. Schema leidžia keturiolika pavadinimų: access, bindings, documents, files, governance, graph, jobs, keys, memory, platform, runs, signin ir uno, taip pat vieną klientui, kuris atsako į plano teisių atsisakymus ir išlaiko vidinį pavadinimą. Funkcijų teisių klientas runtime/entitlements nėra vienas iš jų ir niekada neįtraukiamas į sąrašą, nes jūsų entitlements blokas jį jau deklaruoja, o backend, kuris jį importuoja neturėdamas entitlements bloko, neišlaiko tos pačios patikros. frontend apima basePath, mountPath ir framework. nexus apima minVersion, maxVersion, capabilities[] ir permissions[].
Kiekvienas likęs blokas skirtas vienai užduočiai:
| Blokas | Paskirtis |
|---|---|
settings |
Jūsų nustatymai bendrojoje sistemoje: groups ir keys, nustatomi kiekvieno nurodytuose lygiuose |
people |
sweep (service, port): organizacijos nariai, sinchronizuojami iš tapatybės paslaugos, kai kas nors išeina, vietos išjungiamos |
ontology |
entityTypes ir relationshipTypes: tipizuotas grafas, saugomas jūsų pačių schemoje |
release |
groups ir frame: funkcijų grupės, kuriose etapais diegiami jūsų maršrutai, pirmiausia išleidžiami kaip canary |
cells[] |
Įskiepis, sudarytas iš kelių diegiamų vienetų: kiekvienam name, kind, entrypoint, port, wsPort |
pricing |
model, currency, tiers[] jūsų katalogo įrašui |
marketplace |
category, icon, screenshots, documentation, featured |
compliance |
instruments[], dataResidency, sovereignty |
developer, repository, keywords |
Kas jį publikuoja ir kur yra jo kodas |
metrics, atlas |
Du sąmoningai atviri objektai jūsų pačių metrikų pavadinimams ir architektūros dokumentacijos generavimui |
Ko schema negali išreikšti
JSON Schema nustato formą; definePlugin prideda taisykles, kurių schema negali išreikšti. Įgūdžio classification negali viršyti pasitikėjimo ribos. Tik core ir verified įskiepiai gali deklaruoti tool_using ir llm_only įgūdžius. Kiekvienas deklaruotas kelias turi būti santykinis ir tos pačios kilmės, be schemos, be // ir be atvirkštinio pasvirojo brūkšnio, nes URL analizatorius \ paverčia į /, o /\evil.example/x išsprendžiamas į kitą kilmę. Kiekviena taisyklė, kurią registro sinchronizavimas taiko įgūdžiui, pirmiausia pritaikoma čia, naudojant paties sinchronizavimo kodą, todėl validate ir sinchronizavimas pažeistą taisyklę įvardija vienodai.
Tikrinimas ir perkėlimas iš v1
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
Klaidos atveju išspausdinamas tikslus kelias, o sinchronizavimo taisyklės atveju – pirmiausia kodas. Paverskite tai commit kabliu.
v1 manifestas perkeliamas mechaniškai. migrate prideda tris įstatymo sakinius, perkelia domain į domains[] ir atsisako sugalvoti įėjimo tašką, kurio neturėjote. Prieš ką nors išspausdindamas ar įrašydamas, jis patikrina rezultatą, todėl migracija niekada neperkelia klaidos iš įrankio į jūsų repozitoriją.
npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin migrate nexus.manifest.json --writePrieš pateikdami pakeitimus (commit) peržiūrėkite skirtumus. Jų pridedami įstatymo sakiniai yra formuluotė, kurią fiksuoja validatorius; savo diegimui nustatykite deploy į anksčiau parodytą sakinį.
Nuomininko aplinkos generavimas ir vaidmenų parūpinimas
Niekada nerašote savo vaidmenų teisių ar eilučių lygio saugumo šablono rankiniu būdu. nexus-tenancy render juos parašo pagal manifesto schema ir db:
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-tenancy render --manifest nexus.manifest.json --out migrations/000_tenancy.sqlSugeneruotas failas sukuria penkis schemos vaidmenis, kiekvienam nurodydamas, ko jis negali turėti: migratorių, kuris gali tik tapti savininku, savininką, kuris negali prisijungti, programos vaidmenį užklausų keliui, ataskaitų vaidmenį, kuris mato tik agregatus, ir žurnalo vaidmenį, kuris gali tik pridėti. Nė vienas vaidmuo neturi BYPASSRLS. Vienintelis būdas susieti nuomininką yra viena duomenų bazės funkcija, o set_config atšaukta visiems vaidmenims, išskyrus savininką.
Pritaikytas nuomos failas niekada neredaguojamas. Pakeitimas yra revizija su savo 0 numerio failu, ir skaitymo vieta tarporganizacinėms teisėms atsiranda būtent taip, kaip 2 revizija. --graph sugeneruoja dvi tipizuoto grafo, kurį deklaruoja jūsų ontology, lenteles kaip kitą sunumeruotą migraciją.
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.sqlNuomos failas sukuria būtent tuos vaidmenis, kuriais jungiasi vykdyklė, todėl jį taiko duomenų bazės savininkas naudodamas nexus-migrate provision:
DATABASE_URL=<database-owner-url> npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-migrate provision --state <dir><database-owner-url> yra duomenų bazės savininko prisijungimo eilutė, o <dir> – privatus katalogas. Parengimas pritaiko bazinį nuomos failą ir visas revizijas iš eilės, įrašo migrator.url ir app.url (ir seat.url, kai yra 2 revizija) į <dir> su režimu 0600 ir neišspausdina nieko slapto. Kiekvieno paleidimo metu jis nustato kiekvieno vaidmens prisijungimų ribą pagal db.maxConnections × db.pods. Pakartotinis paleidimas išlaiko esamus slaptažodžius, nebent paprašysite: --passwords <dir> nustato juos iš failų, o --rotate <roles> suteikia nurodytiems vaidmenims naujus. Paverskite failus savo diegimo paslaptimis.
Po to taikymas jungiasi naudodamas migratoriaus prisijungimo eilutę, kurią įrašė parengimas:
DATABASE_URL="$(cat <dir>/migrator.url)" npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-migrate apply --manifest nexus.manifest.jsonJis vykdo failus nuo 001 kaip migratorius – kiekvieną failą po SET ROLE <schema>_owner, po vieną transakciją kiekvienam failui. Jis tvarko žurnalą <schema>.schema_migrations su kiekvieno failo kontroline suma; pritaikytas failas, kurio baitai pasikeitė, atmetamas nurodant pavadinimą (CHECKSUM_DRIFT), niekada nevykdomas iš naujo ir niekada nepraleidžiamas. Kiekvienas laukiantis failas išanalizuojamas tikrąja Postgres gramatika prieš paleidžiant pirmąjį, todėl atmetimas palieka duomenų bazę nepaliestą. Vienintelė antraštė, kurią gali turėti failas, yra -- nexus-migration: transaction=file|per-statement su neprivalomais užrakto ir sakinio laiko limitais; per-statement skirta CREATE INDEX CONCURRENTLY.
Barjerai
nexus-gates vykdo dvidešimt dvi patikras. Kiekviena užkoduoja vieną defektų klasę, kad ji negalėtų būti išleista du kartus, ir kiekviena turi savitestį, įrodantį, kad ji neišlaiko su tam sukurtu fiktyviu rinkiniu. Paleiskite jas prieš siųsdami pakeitimus:
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --self-test| Patikra | Ką ji aptinka |
|---|---|
scope-adherence |
/api maršrutą be prieigos srities apsaugos; anoniminį kelią, kuris nėra tiksliai deklaruotas; įrenginio maršrutą be įrenginio apsaugos arba su asmens apsauga šalia jos |
one-fence |
Nuomininko predikatą, apibrėžtą kur nors kitur nei vienoje vietoje, įskaitant rankomis sukurtą vietos ar teisės užtvarą |
sql-fence |
Sakinį, kuris skaito ar atnaujina apribotą lentelę be užtvaros bet kuriame FROM, JOIN, USING ar UPDATE taikinyje |
migrations-are-scoped |
Lentelę, kurioje trūksta ašies, nuomininku prasidedančio sudėtinio rakto, nuomininką turinčio išorinio rakto ar demonstracinio stulpelio |
migrations-commit-what-they-open |
Migraciją, kurios BEGIN skaičius nesutampa su jos COMMIT ir ROLLBACK skaičiumi |
no-direct-compute |
Tiesioginį modelio teikėjo, variklio, eilės ar darbo eigos serverio iškvietimą; antrą siuntimo URL skaitytoją |
no-credentials |
Modelio teikėjo kredencialą, kurį galima perskaityti repozitorijoje ar aplinkoje |
crud-adherence |
Keičiantį maršrutą, kurio teisės patikra nenurodo nieko registre |
blocked-backends |
Maršrutą, kuris nėra nei aptarnaujamas, nei blokuojamas pagal pavadinimą, nei atmetamas pagal įstatymą, nei priklauso kitur |
every-test-runs |
Testus, kurių testų scenarijaus glob šablonas niekada nepasiekia |
tiles-are-invariant |
Nuo nuomininko nepriklausomą talpykloje saugomą sąsają, kuri skaito nuomininko reikšmę arba praleidžia autentifikavimą |
api-contract |
Užregistruotą maršrutą, kurio manifestas nedeklaruoja, arba deklaruotą, kurio kodas niekada neužregistruoja |
rls-present |
Lentelę be priverstinio eilučių lygio saugumo; SECURITY DEFINER funkciją be fiksuoto search_path |
no-set-config |
Įskiepio kodą, kuris pats susieja nuomininko nustatymą |
db-role-honest |
Užklausos kelią, kuris jungiasi kaip savininkas ar migratorius arba prašo SUPERUSER ar BYPASSRLS |
platform-clients |
SDK klientą, kuris importuotas, bet neįtrauktas į backend.platformClients, arba įtrauktas, bet niekada neimportuotas |
rights-register |
Prieigos srities maršrutą be deklaruotos teisės; teisės patikrą šalia registro |
refusal-ledger |
Deklaruotą atmetimų lentelę be įdiegto žurnalo arba atmetimo turinį, siunčiamą jį apeinant |
grants-declared |
Lentelę su suteiktomis teisėmis, kurios manifestas nedeklaruoja; skaitymo vietos privilegijas, suteiktas rankiniu būdu |
people-declared |
people bloką be jo valymo maršruto, apsaugos ir lentelių |
functions-closure |
Azure Functions įskiepį, kurio aptarnaujami ir deklaruoti maršrutai nesutampa |
declared-input |
Apdorojimo funkcijos užklausos parametrų sąrašą, kuris nesutampa su maršruto deklaruotu query |
Kataloge gates/ yra penki išimčių failai, kuriuos patikra gali skaityti (demo-exempt.json, non-crud.json, blocked-backends.json, tenant-resolving.json ir invariant-seams.json), po vieną priežastį kiekvienam įrašui. Tuščia priežastis laikoma įrašo nebuvimu, o įrašas, nurodantis tai, ko nebėra, neišlaiko patikros. Ten taip pat galite įdėti savo patikrų modulius, ir nexus-gates juos aptiks šalia integruotųjų.
Šablono konvejeris
Šablone nėra rankomis parašytos darbo eigos. Jo konvejerio konfigūracija nurodo Dockerfile, vienintelį kūrimo argumentą (registro prieigos raktą), bandomąjį migracijos vykdymą ir paleidimo zondą bei patikrą, kurią vykdo suliejimo eilė. Tvarka yra ta, kuria norėtumėte, kad būtų aptinkamos klaidos.
npm cinpm run typechecknpm run buildnpm testnpm run validate:manifest, kuris yracreate-nexus-plugin validate nexus.manifest.jsonnpm run gates, kuris yranexus-gates --self-testnode scripts/ci/required-env
Aplink atvaizdą vykdomos dar dvi patikros. Bandomasis migracijos vykdymas pritaiko kiekvieną failą vienkartinei Postgres duomenų bazei, prieš išleidžiant atvaizdą, naudodamas tą pačią vykdyklę kaip ir gamybinė aplinka: nexus-migrate provision vieną kartą kaip supernaudotojas, tada kiekvieną sunumeruotą failą kaip migratorius. Paleidimo zondas paleidžia sukurtą atvaizdą su jo paties įėjimo tašku ir visais kintamaisiais, kuriuos išspausdina required-env, nukreiptais į pakaitalus, kurie priima prisijungimus ir niekada neatsako. Serveris laukia duomenų bazės savo ribotame laiko lange, ir šis laukimas yra sėkmės signalas; konfigūracijos įkėlėjas, kuris atsisako pasileisti, sužlugdo kūrimą čia, o ne gamybinėje aplinkoje.
Kiek tai kainuoja
SDK priima sprendimus už jus, ir kai kuriuos iš jų būtumėte priėmę kitaip. Manifestas atmeta jam nežinomus raktus, maršrutų lentelė turi tiksliai atitikti jūsų kodą, duomenų bazės vaidmenų kurti ne jums, o patikros sužlugdo kūrimą dėl trūkstamos teisės skaitymo operacijai. Kurdamas pirmąjį įskiepį, visą dieną ginčijausi su api-contract dėl maršruto, kurį buvau užregistravęs, bet pamiršęs deklaruoti. Jis buvo teisus – maršrutas buvo neapsaugotas. Tikėkitės, kad pirmasis įskiepis atrodys lėtas, o antrasis užtruks trečdalį to laiko.

