Útgáfa 1.0.0-alpha.1nýjast
Kafli 2.21
Viðbóta-SDK
Uppsetning á viðbóta-SDK (þróunarsetti), skipanalínuverkfærum þess, kynningarferð um fullbúna sniðmátið, v2-yfirlýsingaskrána reit fyrir reit, og hliðin tuttugu og tvö sem halda viðbót innan reglnanna.
Þessi síða var þýdd með gervigreind úr enska frumtextanum. Ef eitthvað er óljóst gildir enska síðan til viðmiðunar. Lesa þessa síðu á ensku

Önnur viðbótin mín tók þriðjung þess tíma sem sú fyrsta tók, og nánast allur sparnaðurinn var SDK-inu (hugbúnaðarþróunarsetti) að þakka. Í fyrra skiptið skrifaði ég umfangsathugun, stillingahleðslu og flutningskeyrslu, og yfirlesari sendi hverja einustu þeirra til baka. Í seinna skiptið keyrði ég eina grunnsmíðaskipun, eyddi sýnifærninni fyrir tilfinningagreiningu og varði dögunum í frávikayfirferðarfærslurnar sem flugaflfræðiteymið okkar þurfti í raun.
@adverant-nexus/plugin-sdk er einn npm-pakki. Hann geymir v2-skilgreiningarskema upplýsingaskrárinnar og sannprófarana sem lesa það (definePlugin, defineSkill), keyrslueiningarnar sem viðbótin þín flytur inn fyrir umfang, gagnagrunn, sendingu og fleira, prófunarhjálpartól, fylgnihliðin og skipanalínutólin. Í þessum kafla er fjallað um uppsetningu hans, tólin, sniðmátið, upplýsingaskrána og hliðin. Kafli 2.22, Keyrsluumhverfi viðbóta, fjallar um keyrslueiningarnar í keyrandi kóða þínum.
Uppsetning þess
Pakkinn kemur úr skráasafni Adverant á https://registry.adverant.ai/npm/, aldrei úr opinbera npm-skráasafninu, og þú þarft sóttartáknið af síðunni „Pull tokens and install commands“ á reikningnum þínum. Beindu @adverant-nexus-umfanginu að skráasafninu í .npmrc geymslunnar þinnar:
@adverant-nexus:registry=https://registry.adverant.ai/npm/
//registry.adverant.ai/npm/:_authToken=<pull-token>
<pull-token> er táknið af reikningssíðunni þinni. Í ferli skaltu senda það inn úr leyndarmáli og aldrei vista það í útgáfustýringu; Dockerfile sniðmátsins neitar að smíða án þess og eyðir .npmrc úr smíðastiginu þegar npm ci hefur keyrt, svo táknið fylgir aldrei með í mynd.
Festu síðan útgáfuna nákvæmlega:
npm install --save-exact @adverant-nexus/plugin-sdk@2.50.0Vistaðu package-lock.json í útgáfustýringu við fyrstu uppsetningu. Myndsmíði sniðmátsins keyrir npm ci og neitar að falla aftur á npm install: læsingarskráin er samningurinn. Lágmark SDK-sins sjálfs er Node 18; sniðmátið miðar á Node 20.
Skipanalínutólin fylgja pakkanum, svo hver skipun í þessum gögnum tilgreinir pakkann og útgáfu hans með npx -p. Eitt og sér er npx create-nexus-plugin flett upp í opinbera skráasafninu, og það heiti er ekki þessi pakki.
Skipanalínuverkfærin
| Tól | Hvað hann gerir |
|---|---|
create-nexus-plugin |
Býr til grunn viðbótar, sannprófar upplýsingaskrá, flytur v1-upplýsingaskrá yfir í v2 og útbýr notendaleiðbeiningarnar fyrir framendaforritarann þinn |
nexus-tenancy |
Útbýr leigjenda-SQL skemans þíns út frá upplýsingaskránni: hlutverk, heimildir, sniðmát raðöryggis og graftöflurnar |
nexus-migrate |
Keyrir flutningana þína: útvegar hlutverkin einu sinni og keyrir síðan hverja númeraða skrá sem flutningshlutverkið |
nexus-gates |
Keyrir öll fylgnihlið og sjálfsprófun hvers hliðs |
create-nexus-plugin framkvæmir ekkert netkall og hleður engum fjarkóða. Það keyrir sömu innanferlissannprófara og innleiðing verkvangsins keyrir, svo ekkert misræmi verður á milli „það stóðst sannprófun hjá mér“ og „verkvangurinn samþykkti það“.
| Aðgerð | Flögg | Hvað hann gerir | Útgöngukóðar |
|---|---|---|---|
scaffold <name> |
--tier full-service\|ui-only\|skills-only, --dir <path>, --print |
Skrifar nýja viðbótarmöppu; --print prentar aðeins upplýsingaskrána |
0 skrifað · 1 neitaði að yfirskrifa · 2 röng notkun |
validate <file> |
Sannprófar nexus.manifest.json, eða .ts- eða .js-einingu sem flytur hana út |
0 gilt · 1 ógilt eða ólæsilegt · 2 röng notkun | |
migrate <file> |
--write |
Lyftir v1-upplýsingaskrá upp í v2 og prentar hana, eða skrifar hana á sama stað | 0 · 1 · 2, eins og að ofan |
guide |
--manifest <file>, --narrative <dir>, --out <guide.md>, --check, --lint |
Útbýr notendaleiðbeiningarnar úr upplýsingaskránni og frásögn þinni; --check ber saman við vistaða eintakið og skrifar ekkert |
0 · 1 misræmi eða brot í lintun · 2 röng notkun |
help |
Prentar notkunarleiðbeiningar | 0 |
Grunngerð og þrepin þrjú
npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin scaffold anomaly-review --tier full-service--tier er sjálfgefið full-service. Grunnsmiðurinn neitar að skrifa í möppu sem er þegar til, og upplýsingaskráin sem hann skrifar stenst þegar sannprófun; hann skilar aldrei ógildri.
Veldu stigið eftir því hvað viðbótin þín inniheldur.
| Þrep | Inniheldur | Verður að skilgreina |
|---|---|---|
skills-only |
Færni í upplýsingaskrá og ekkert annað | skills[], með að minnsta kosti einni færslu |
ui-only |
Framendaviðmót innan skeljarinnar | frontend |
full-service |
Bakenda og framenda, yfirleitt með eigið skema | backend og frontend; og þar sem hún hefur bakenda, runtime.healthCheck |
Ef þú ert ekki viss skaltu búa til grunn með full-service og eyða því sem þú þarft ekki. Að fara hina leiðina þýðir að skrifa þá hluta sem sniðmátið hefði gefið þér.
Kynningarferð um fullbúna sniðmátið
Sniðmátið er viðmiðunarviðbótin, smíðuð eftir hinu stranga mynstri sem allir síðari kaflar gera ráð fyrir. Afritaðu lögun hennar, ekki sýnirökfræði hennar.
| Slóð | Hvað það er |
|---|---|
nexus.manifest.json |
v2-upplýsingaskráin: lögin þrjú endurorðuð, leiðatöflan og réttindaskrá hennar |
src/config.ts |
Stillingahleðslan. Ein forskrift, lesin einu sinni, öllum vandamálum safnað saman áður en ferlið neitar að ræsa |
src/scope.ts |
Eina skráin sem breytir beiðni í umfang, með ströngum táknsannprófara SDK-sins og tveimur fyrirkomulögum: handhafatákni einstaklings og þjónustukalli verkvangsins |
src/db.ts |
Hver skipun setur saman tenantFence() og keyrir innan withScopedTx |
src/uno.ts |
Eina sendingarskráin: ein vefslóð, einn biðlari, lokaður leyfislisti |
src/routes/*.ts |
health (nafnlaust, nákvæm slóð), /api-leiðirnar (með umfangi) og /internal-bakkallið (varið sem þjónusta) |
src/skills/sentiment.ts |
Ákvarðanleg host_callback-færni; skiptu orðasafninu út fyrir eigin rökfræði |
src/server.ts |
Samsetningarrótin: setur upp synjunarskrána einu sinni, bíður eftir gagnagrunninum (með tímamörkum) og keyrir síðan einangrunar- og skráarathuganirnar áður en hún hlustar |
migrations/000_tenancy.sql |
Útbúið af nexus-tenancy render við grunnsmíði: hlutverk, skema, sniðmát raðöryggis |
migrations/001_init.sql |
Tvær töflur með samsettum lykli sem hefst á leigjanda og samsettum ytri lykli sem ber leigjandann |
migrations/002_refusal_ledger.sql |
Taflan sem synjunarskráin skrifar í |
scripts/ci/required-env |
Prentar heiti umhverfisbreytanna sem ræsing krefst sem JSON |
scripts/ci/shadow-migrate-*.sh |
Prufukeyrsla ferlisins á flutningum, í gegnum nexus-migrate |
gates/ |
Undanþágumappa hliðanna: tóm, sem er rétt staða fyrir nýja viðbót |
test/ |
Prófanir fyrir umfang, leiðir, gagnagrunn, sendingu og ræsingu, með umfangsstaðgenglunum sem hver prófun fær innsetta |
Dockerfile |
Mynd sem keyrir ekki sem rót (notandakenni 10001) með flutningana innanborðs |
Nokkrar þessara skráa eru þess virði að skoða nánar.
src/config.ts fylgir tveimur reglum. Hún safnar öllum vandamálum saman áður en hún kastar villu, svo ein endurræsing nefnir allar fimm breyturnar sem vantar í stað fimm endurræsinga sem nefna eina hver. Og hún gefur gildi sjálfgefið aðeins þegar rangt gildi getur ekki leitt til hljóðlauss rangs svars: PORT má vera sjálfgefið 8080, því röng gátt veldur sýnilegri villu við bindingu, en DATABASE_URL og UNO_DISPATCH_URL eru áskilin og verða að vera vistföng innan klasans. Opinberu vistfangi er hafnað við ræsingu.
node scripts/ci/required-env["DATABASE_URL","PLATFORM_JWT_SECRET","PLATFORM_SERVICE_KEY","UNO_DISPATCH_URL"]
Eigin prófun sniðmátsins keyrir þá skrá og ber úttak hennar saman við heitin sem stillingaforskriftin merkir sem áskilin, svo ef áskilinni breytu er bætt við án þess að uppfæra listann bregst npm test.
src/server.ts hlustar ekki fyrr en gagnagrunnurinn svarar og takmarkar biðina við 120 sekúndur, þar sem hver misheppnuð tilraun er skráð ásamt orsök sinni. Síðan sannar hún, í þessari röð, að forritshlutverkið geti ekki endurbundið leigjandann og að allar töflur séu þvingaðar undir raðöryggi, að tengingasafn hvers pods rúmist innan tengingamarka hlutverksins og að tafla synjunarskrárinnar geti tekið við röð. Synjun frá einhverri þessara þriggja er prentuð í heild sinni og ferlið hættir með 2.
v2-yfirlýsingaskráin, reit fyrir reit
Upplýsingaskráin er véllesanlegur samningur viðbótarinnar við verkvanginn. Hún er sannprófuð þegar þú semur hana, þegar verkvangurinn innleiðir hana og stöðugt eftir það. Skemað er additionalProperties: false á öllum stigum: ef viðbótin þín hefur hluta er til eiginleiki fyrir hann, og óskilgreindum lykli er hafnað. Lausnin er alltaf að nota rétta valfrjálsa eiginleikann.
Áskilinn kjarni
| Reitur | Regla |
|---|---|
manifestVersion |
Nákvæmlega "2". v1-skjal er flutt, aldrei endursannprófað á sama stað |
name |
^[a-z0-9]+([-.][a-z0-9]+)*$, að hámarki 64 stafir. Auðkenni viðbótarinnar sem notað er við skráningu, nafnasvæði sendinga og raðir bundnar leigjanda. Viðbót sem skilgreinir færni þarf einnig heiti án punkts og án tölustafs í upphafi |
displayName |
1 til 120 stafir |
version |
Merkingarbær útgáfa; þín eigin útgáfuröð |
description, author, license |
Að minnsta kosti einn stafur hvert |
tier |
skills-only, ui-only eða full-service |
trust |
core, verified, community eða untrusted |
runtime |
Áskilið: executionMode, isolationLevel (1 til 4), entrypoint. Valfrjálst: nodeVersion, healthCheck, readinessCheck, livenessCheck, hvert slóð sem hefst á /. Hátturinn ræðst af stiginu: 1 external_https, 2 mcp_container, 3 hardened_docker, 4 firecracker |
architecture |
compute, ai og deploy, lög verkvangsins þrjú endurorðuð. Sannprófarinn festir orðalagið |
Fyrir viðbót sem þú smíðar fyrir eigin uppsetningu hljóða setningarnar þrjár svona. ai-setningin fjallar um gervigreind og er staðurinn til að taka fram að viðbótin geymi engin auðkenni líkana.
"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."
}Leiðataflan: api og rights
api þarf version og basePath, og valfrjálst websocket (path, auth) og endpoints[]. Leiðataflan er sterkasta hugmyndin í skemanu: hlið ber hana saman við leiðirnar sem kóðinn þinn skráir í raun, í báðar áttir, svo upplýsingaskráin er sannreynanlegur samningur en ekki skjölun.
Hver endapunktur þarf method (GET, POST, PUT, PATCH eða DELETE) og path. Afgangurinn:
| Reitur | Hvað stendur í því |
|---|---|
auth |
Einn af fimm flokkum: scope (leið einstaklings, á bak við umfangsvörðinn), service-key og internal (netþjónn til netþjóns, aldrei aðgengilegt úr vafra), public (alltaf aðeins nákvæm slóð með allowAnonymous) og device (vél með eigin auðkenni, á bak við tækjavörðinn) |
right |
Áskilið á hverri leið sem umfangsvörðurinn þjónar og hafnað á öllum öðrum: heiti réttinda í rights-skránni |
needsUnit |
Leiðin synjar þegar ekki er hægt að ákvarða einingu kallandans |
allowAnonymous |
Eingöngu leyfislisti með nákvæmri samsvörun. Forskeytisregla er leiðin til þess að /health-of-tenant-42 endar opinbert |
group, serves, screens |
Undir release-blokk: getuflokkurinn sem leiðin þjónar, hverju hún svarar þegar leyfisskyldur eiginleiki þess flokks er læstur (data, teaser, sighting eða ask), og skjámyndirnar sem hún þjónar |
query |
required (hvert heiti með dæmigildi) og allowed: fyrirspurnarfæribreyturnar sem leiðin les |
body |
example: dæmi um meginmál ritunarleiðar, sem hennar eigin sannprófari samþykkir. Aldrei á GET |
rights er skráin sem þessar leiðir vísa í. Hver réttindi hafa roles (þakið) og valfrjálst summary, never (hlutverk sem mega aldrei beita þeim, hvað sem þau hafa annað), barred (eigin orð vörunnar til að synja never-hlutverki), seat (virkt sæti þarf líka), self (allir staðfestir einstaklingar hafa þau, fyrir réttindi yfir eigin lotu), grants (handhafar úthluta sætum; í mesta lagi ein réttindi segja það), licence (leyfisskyldur eiginleiki sem leyfi fyrirtækisins verður að innihalda) installation (aðeins í höndum eigin stjórnenda uppsetningarinnar) og platform (aðeins í höndum verkvangsstjórnenda Adverant; nefnir engin hlutverk). Heiti réttinda innihalda að minnsta kosti einn punkt: 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 hafnar umfangsleið án réttinda (ENDPOINT_RIGHT_MISSING), réttindum sem skrána vantar (ENDPOINT_RIGHT_NOT_REGISTERED) og réttindum á leið sem enginn vörður þjónar (ENDPOINT_RIGHT_UNGUARDED). Það hafnar einnig skrá sem stangast á við sjálfa sig, og tveimur ritháttum einnar leiðar (:id og :recordId) sem DUPLICATE_ENDPOINT.
Gögnin þín: databases, schema og db
schema er eina Postgres-skemað sem viðbótin á. public, plugins, auth og nexus eru bönnuð, og ef databases[] nefnir einnig Postgres-skema verða þau tvö að passa saman.
databases[] skilgreinir hverja geymslu eftir vél: postgresql (schema, tables, migrations og granted, töflurnar sem annað fyrirtæki má lesa samkvæmt skráðri heimild), neo4j (schemas), qdrant (collections) eða redis (purpose).
db geymir lotumörkin fyrir allar tengingar sem viðbótin opnar, skilgreind hér frekar en kóðuð svo bæði yfirlesari og uppsetningin geti lesið þau:
| Reitur | Hvað það takmarkar |
|---|---|
maxConnections |
Tengingasafnið á hvert afrit |
pods |
Mesti fjöldi podda sem hafa tengingasafn samtímis, afrit auk aukningar við rúllandi uppfærslu. Tengingamörk hvers hlutverks eru útbúin sem maxConnections × pods; ef þú sleppir þessu varar definePlugin við DB_PODS_UNDECLARED |
statementTimeoutMs |
Ein skipun |
idleInTransactionTimeoutMs |
Opin færsla sem keyrir ekkert |
workMemKB |
Einn röðunar- eða tætihnútur, á hvern hnút, ekki á hverja fyrirspurn |
piiMask[] |
table.column-færslur sem geyma persónuupplýsingar, huldar í stýrðu SQL-stjórnborðinu og í annálum |
Færni og tól: skills, mcpTools, entitlements
skills[] geymir færni upplýsingaskrárinnar; kafli 2.20, Færni, fjallar um svið hennar og stig. mcpTools[] geymir MCP-tólin (Model Context Protocol) sem viðbótin birtir, hvert með name, description og inputSchema án oneOf, allOf eða anyOf á efsta stigi.
entitlements krefst featureIdPattern og tekur við alwaysOn[], source og store. Mynstrið tilgreinir nafnasvæðið sem auðkenni eiginleika þinna eru í, venjulega name viðbótarinnar auk eins hluta sem kóðinn þinn fyllir út fyrir hvert viðmót. alwaysOn[] er stutti, nákvæmi listinn sem verður að svara jafnvel þegar enginn úrskurður um réttindi fæst: heilbrigði, reiðubúni, innskráning og stillingarnar sem stjórnandi þarf til að lagfæra réttindin.
Breytingastjórnun: changePolicy
"changePolicy": {
"enabled": true,
"classes": ["website", "bff", "migration"],
"approvals": { "website": 1, "bff": 1, "migration": 2 }
}Samþykki eru talin í aðskildum einstaklingum, og sá sem lagði breytinguna til er aldrei einn þeirra; án beggja helminganna verða „tvö samþykki“ að einum einstaklingi sem smellir tvisvar. enabled: true krefst classes, og hver flokkur sem er nefndur þarf eigin fjölda. Flokkur sem þú sleppir er óstýrður, sem er lögmætt val sem skemað lætur þig skrá niður.
Hver þú ert: domains, branding, routing
domains[] (hvert primary og aliases[]; domain er form fyrir eitt lén) tilgreinir hvar viðbótin svarar. branding krefst appName og tekur við tagline, logo, favicon, primaryColor, accentColor, oauthClientRef, passkeyRpId og gaId. Allt í branding er opinbert: innskráningarsíðan les það áður en nokkur hefur auðkenni, svo það geymir aldrei leyndarmál eða innra vistfang. routing (type, gateway, virtualService) er fyrir viðbætur sem lýsa eigin leiðavali.
Stærðarval og annað
resources krefst cpuMillicores (10 til 64,000) og memoryMB (16 til 262,144) og tekur við diskGB, timeoutMs, port og wsPort. backend geymir port, healthPath, apiPrefix, framework og platformClients[], SDK-biðlarana sem bakendinn yðar flytur inn eftir nafni. Listinn er lokaður og hlið ber hann saman við innflutninga yðar. Skemað leyfir fjórtán nöfn: access, bindings, documents, files, governance, graph, jobs, keys, memory, platform, runs, signin og uno, auk eins fyrir biðlarann sem svarar synjunum um áskriftarréttindi, sem heldur innra nafni. Biðlarinn fyrir eiginleikaréttindi, runtime/entitlements, er ekki einn þeirra og fer aldrei á listann, því að entitlements-blokkin yðar lýsir honum þegar yfir, og bakendi sem flytur hann inn án entitlements-blokkar fellur á sama hliði. frontend geymir basePath, mountPath og framework. nexus geymir minVersion, maxVersion, capabilities[] og permissions[].
Hver hinna blokkanna er til staðar fyrir eitt verk:
| Blokk | Til hvers |
|---|---|
settings |
Stillingar yðar á sameiginlega rammanum: groups og keys, stilltar á þeim stigum sem hvor tilgreinir |
people |
sweep (service, port): meðlimir fyrirtækisins, samstilltir frá auðkennisþjónustunni, þar sem slökkt er á sætum þegar einhver hættir |
ontology |
entityTypes og relationshipTypes: tegundabundna grafið sem geymt er í yðar eigin skema |
release |
groups og frame: getuhóparnir sem leiðir yðar eru settar upp í, gefnir fyrst út sem kanarí-útgáfa |
cells[] |
Viðbót sem samanstendur af nokkrum uppsetningareiningum: name, kind, entrypoint, port, wsPort fyrir hverja |
pricing |
model, currency, tiers[] fyrir skráningu yðar í vörulistanum |
marketplace |
category, icon, screenshots, documentation, featured |
compliance |
instruments[], dataResidency, sovereignty |
developer, repository, keywords |
Hver gefur hana út og hvar kóði hennar er geymdur |
metrics, atlas |
Hlutirnir tveir sem eru vísvitandi opnir, fyrir yðar eigin mælikvarðanöfn og gerð arkitektúrsskjala |
Það sem skemað getur ekki tjáð
JSON Schema ákvarðar lögun; definePlugin bætir við reglunum sem skema getur ekki tjáð. classification færni má ekki fara yfir traustþakið. Aðeins core- og verified-viðbætur mega lýsa yfir tool_using- og llm_only-færni. Sérhver yfirlýst slóð verður að vera afstæð og af sama uppruna, án skema, án // og án öfugs skástriks, því að URL-þáttarinn breytir \ í / og /\evil.example/x vísar á annan uppruna. Sérhver regla sem samstilling skrárinnar beitir á færni er beitt hér fyrst, með kóða samstillingarinnar sjálfrar, svo að validate og samstillingin nefna brotna reglu á sama hátt.
Sannprófun og færsla úr 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
Villa prentar nákvæma slóð og, fyrir samstillingarreglu, kóðann fyrst. Gerið þetta að commit-krók.
Hægt er að lyfta v1-skilgreiningarskrá vélrænt. migrate bætir við lagasetningunum þremur, færir domain í domains[] og neitar að búa til inngangspunkt sem þér höfðuð ekki. Hún staðfestir niðurstöðuna áður en hún prentar eða skrifar nokkuð, svo að flutningur færir aldrei villu úr tólinu inn í gagnageymslu yðar.
npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin migrate nexus.manifest.json --writeLesið mismuninn áður en þér framið hann. Lagasetningarnar sem bætt er við eru orðalagið sem staðfestingartólið festir; fyrir yðar eigin uppsetningu skuluð þér stilla deploy á setninguna sem sýnd var fyrr.
Framsetning leigueiningar og úthlutun hlutverka
Þér skrifið aldrei hlutverkaheimildir yðar eða sniðmátið fyrir öryggi á línustigi í höndunum. nexus-tenancy render skrifar þau út frá schema og db í skilgreiningarskránni:
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-tenancy render --manifest nexus.manifest.json --out migrations/000_tenancy.sqlMyndaða skráin býr til fimm hlutverk fyrir skemað, hvert með því sem það má ekki hafa: flutningshlutverk sem getur aðeins orðið eigandinn, eiganda sem getur ekki skráð sig inn, forritshlutverk fyrir beiðnaslóðina, skýrsluhlutverk sem sér aðeins samantektir og bókhaldshlutverk sem getur aðeins bætt við. Ekkert hlutverk hefur BYPASSRLS. Eina leiðin til að binda leigjanda er eitt gagnagrunnsfall og set_config er afturkallað frá öllum hlutverkum nema eigandanum.
Leigjendaskrá sem hefur verið beitt er aldrei breytt. Breyting er endurskoðun með eigin skrá númer 0, og lessætið fyrir heimildir milli fyrirtækja kemur á þann hátt, sem endurskoðun 2. --graph myndar töflurnar tvær í tegundabundna grafinu sem ontology yðar lýsir yfir sem næsta númeraða flutning yðar.
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.sqlLeigjendaskráin býr til einmitt þau hlutverk sem keyrslutólið tengist sem, svo að eigandi gagnagrunnsins beitir henni með 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> er tengistrengur fyrir eiganda gagnagrunnsins og <dir> er einkamappa. Úthlutun beitir grunnleigjendaskránni og öllum endurskoðunum í röð, skrifar migrator.url og app.url (og seat.url þegar endurskoðun 2 er til) í <dir> með ham 0600 og prentar ekkert leyndarmál. Hún stillir tengingamörk hvers hlutverks út frá db.maxConnections × db.pods við hverja keyrslu. Endurkeyrsla heldur núverandi lykilorðum nema þér biðjið um annað: --passwords <dir> stillir þau úr skrám og --rotate <roles> gefur tilgreindum hlutverkum ný. Gerið skrárnar að leyndarmálum uppsetningar yðar.
Eftir það tengist beiting með tengistreng flutningshlutverksins sem úthlutunin skrifaði:
DATABASE_URL="$(cat <dir>/migrator.url)" npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-migrate apply --manifest nexus.manifest.jsonHún keyrir skrár frá 001 og áfram sem flutningshlutverkið, allar skrár undir SET ROLE <schema>_owner, eina færslu á hverja skrá. Hún heldur bókhald, <schema>.schema_migrations, með gátsummu hverrar skrár; beittri skrá þar sem bætin hafa breyst er hafnað eftir nafni (CHECKSUM_DRIFT), hún aldrei endurkeyrð og aldrei sleppt. Sérhver skrá í bið er þáttuð með raunverulegri Postgres-málfræði áður en sú fyrsta keyrir, svo að höfnun skilur gagnagrunninn eftir ósnertan. Eini hausinn sem skrá má bera er -- nexus-migration: transaction=file|per-statement, með valfrjálsum tímamörkum fyrir læsingu og skipun; per-statement er fyrir CREATE INDEX CONCURRENTLY.
Hliðin
nexus-gates keyrir tuttugu og tvö hlið. Hvert þeirra kóðar einn flokk galla svo að hann komist ekki tvisvar í útgáfu, og hvert hefur sjálfprófun sem sannar að það falli á prófunargögnum sem eru smíðuð til að fella það. Keyrið þau áður en þér ýtið:
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --self-test| Hlið | Hvað það grípur |
|---|---|
scope-adherence |
/api-leið án umfangsvarðarins; nafnlaus slóð sem er ekki nákvæmlega yfirlýst; tækjaleið án tækjavarðarins, eða með varðar einstaklings við hlið hans |
one-fence |
Leigjendaskilyrði sem er skilgreint annars staðar en á einum stað, þar á meðal handgerð sæta- eða heimildagirðing |
sql-fence |
Skipun sem les eða uppfærir umfangsbundna töflu án girðingarinnar, í hvaða FROM-, JOIN-, USING- eða UPDATE-markmiði sem er |
migrations-are-scoped |
Tafla sem vantar ás, samsettan lykil með leigjanda fremst, ytri lykil sem ber leigjanda eða sýnidálkinn |
migrations-commit-what-they-open |
Flutningur þar sem fjöldi BEGIN passar ekki við fjölda COMMIT og ROLLBACK |
no-direct-compute |
Beint kall í líkanaveitu, vél, biðröð eða verkflæðishýsil; annar lesandi sendingarslóðarinnar |
no-credentials |
Auðkenni líkanaveitu sem er læsilegt í gagnageymslunni eða umhverfinu |
crud-adherence |
Breytandi leið þar sem réttindaprófunin nefnir ekkert í skránni |
blocked-backends |
Leið sem hvorki er þjónustuð, lokað eftir nafni, hafnað samkvæmt lögum né í eigu annars staðar |
every-test-runs |
Prófanir sem glob prófunarskriftunnar nær aldrei til |
tiles-are-invariant |
Leigjendaóháð skyndiminnissamskeyti sem les gildi leigjanda eða sleppir auðkenningu |
api-contract |
Skráð leið sem skilgreiningarskráin lýsir ekki yfir, eða yfirlýst leið sem kóðinn skráir aldrei |
rls-present |
Tafla án þvingaðs öryggis á línustigi; SECURITY DEFINER-fall án festrar search_path |
no-set-config |
Viðbótarkóði sem bindur leigjandastillinguna sjálfur |
db-role-honest |
Beiðnaslóð sem tengist sem eigandi eða flutningshlutverk, eða biður um SUPERUSER eða BYPASSRLS |
platform-clients |
SDK-biðlari sem er fluttur inn en ekki skráður í backend.platformClients, eða skráður en aldrei fluttur inn |
rights-register |
Umfangsleið án yfirlýsts réttar; réttindaprófun við hlið skrárinnar |
refusal-ledger |
Yfirlýst höfnunartafla án uppsetts bókhalds, eða höfnunarmeginmál sent fram hjá því |
grants-declared |
Heimiluð tafla sem skilgreiningarskráin lýsir ekki yfir; lessætisréttindi veitt í höndunum |
people-declared |
people-blokk án hreinsunarleiðar sinnar, varðar og taflna |
functions-closure |
Azure Functions-viðbót þar sem þjónustaðar leiðir og yfirlýstar leiðir stangast á |
declared-input |
Listi fyrirspurnarbreyta meðhöndlara sem passar ekki við yfirlýst query leiðarinnar |
gates/-mappan geymir undanþáguskrárnar fimm sem hlið má lesa (demo-exempt.json, non-crud.json, blocked-backends.json, tenant-resolving.json og invariant-seams.json), eina ástæðu á hverja færslu. Auð ástæða telst engin færsla, og færsla sem nefnir eitthvað sem er ekki lengur til fellir hliðið. Þér getið einnig sett yðar eigin hliðaeiningar þar og nexus-gates tekur þær upp við hlið innbyggðu eininganna.
Keyrsluferli sniðmátsins
Sniðmátið fylgir ekkert handskrifað verkflæði. Leiðslustillingar þess nefna Dockerfile-skrána, einu byggingarbreytuna (aðgangslykil skrárinnar), prufukeyrslu flutninga og ræsingarprófunina, og hliðið sem samrunabiðröðin keyrir. Röðin er sú röð sem þér vilduð að villur kæmu fram í.
npm cinpm run typechecknpm run buildnpm testnpm run validate:manifest, sem ercreate-nexus-plugin validate nexus.manifest.jsonnpm run gates, sem ernexus-gates --self-testnode scripts/ci/required-env
Tvær athuganir til viðbótar keyra í kringum myndina. Prufuflutningurinn keyrir hverja skrá á einnota Postgres áður en hægt er að gefa myndina út, með sama keyrsluforriti og raunumhverfið notar: nexus-migrate provision einu sinni sem ofurnotandi, og síðan hverja númeraða skrá sem flutningsnotandi. Ræsiskanninn ræsir smíðuðu myndina með sínum eigin inngangspunkti og öllum breytum sem required-env prentar út, og beinir henni að staðgenglum sem taka við tengingum en svara aldrei. Þjónninn bíður eftir gagnagrunninum, innan sinna skilgreindu tímamarka, og sú bið er merki um að prófið hafi tekist; stillingahleðslutæki sem neitar að ræsa sig fellir smíðina þar en ekki í raunumhverfi.
Hvað það kostar
SDK-pakkinn tekur ákvarðanirnar af þér, og sumar þeirra hefðir þú tekið öðruvísi. Yfirlýsingaskráin hafnar lyklum sem hún þekkir ekki, leiðataflan verður að passa nákvæmlega við kóðann þinn, hlutverk gagnagrunnsins eru ekki þín til að hanna og hliðin fella smíði ef réttindi vantar á lestur. Við gerð fyrstu viðbótarinnar minnar eyddi ég heilum degi í að þræta við api-contract um leið sem ég hafði skráð en gleymt að lýsa yfir. Það hafði rétt fyrir sér; leiðin var óvarin. Búist við að fyrsta viðbótin virki hægfara, og búist við að sú næsta taki þriðjung af tímanum.

