Versión 1.0.0-alpha.1 más reciente
Capítulo 2.25
Compilación para cada edición
Qué cambia cuando una misma extensión debe funcionar en todas las ediciones, en un emplazamiento aislado de la red (air-gapped), en una carga útil de Nexus Edge o bajo la propia marca de un cliente. Cubre el límite de licencia para los módulos Enterprise y la entrega firmada sin conexión, con una matriz de qué hacer de forma diferente para cada destino.
Esta página fue traducida por IA a partir del original en inglés. Si algo no está claro, la página en inglés es la referencia. Leer esta página en inglés

En Corrán Orbital distribuimos software a más destinos que la mayoría de los equipos. Nuestros propios ingenieros ejecutan Enterprise en tierra. Un satélite, CORR-3, ejecuta un paquete de misión en Nexus Edge. Dos clientes ejecutan Community en un único servidor, uno ejecuta una instalación Enterprise aislada de la red que nunca se conecta a internet, y hemos creado un paquete para una aseguradora en su propia instalación. El código subyacente es en su mayor parte el mismo, y las diferencias radican principalmente en adónde se le permite ir y cómo llega hasta allí.
Este capítulo recorre cada destino por turno: sobre qué se compila, qué no está permitido tocar y cómo llega el resultado al cliente. Al final, una matriz lo resume todo en una sola página. El capítulo 2.18, El modelo de extensión, explica en qué se diferencian las habilidades, los plugins, los paquetes y los módulos. El capítulo 2.2, Las ediciones por dentro, describe las ediciones en sí.
Community y el núcleo abierto
Community es el núcleo abierto, bajo la licencia Apache, versión 2.0. Puede bifurcarlo y publicar cambios en él. El archivo NOTICE que lo acompaña indica algo que conviene saber antes de aplicar cualquier marca: la licencia no concede el uso de los nombres ni de las marcas comerciales de Adverant más allá de indicar el origen del trabajo.
Community se amplía de la misma manera que Enterprise. El Plugin SDK (kit de desarrollo de software) es el mismo paquete en ambas ediciones, y ni la plantilla de servicio completo ni los 22 controles de conformidad cambian; el capítulo 2.21, El Plugin SDK, lo aborda en detalle. Las habilidades también funcionan. Community incluye el creador y la biblioteca completos del Skills Engine, con versiones y pruebas, mientras que los despliegues canarios y la aprobación de dos personas se reservan para Enterprise.
Las páginas para desarrolladores en Community ofrecen las mismas rutas recomendadas (golden paths) con tres diferencias que notará de inmediato:
- Su código reside en GitHub en lugar de en los repositorios propios de la instalación. La ruta recomendada de plugins crea un repositorio de GitHub y un espacio de desarrollo a partir de la misma plantilla fijada que utiliza Enterprise; la pantalla DV18 muestra cómo crea
room-bookings. - Las rutas recomendadas de paquetes de dominio y de plataforma son exclusivas de Enterprise. En Community usted crea plugins y habilidades, además de lentes y flujos de trabajo sobre lo que ejecuta.
- Los pases de Community se detienen por debajo del nivel Elevate. En un único servidor no hay un entorno de producción al que llegar desde un IDE (entorno de desarrollo integrado), y usted administra el servidor directamente. Cualquier intento desde el IDE se rechaza con
PASS_TIER_REQUIRED.
Un espacio de desarrollo de Community en un servidor pequeño es modesto. El nuestro tenía 2 núcleos y 8 GiB de memoria, estaba cerrado salvo por lo declarado en el manifiesto y finalizaba tras 7 días de inactividad.
Contribuir al proyecto
El Skills Engine también tiene licencia Apache-2.0 y acepta contribuciones de la forma habitual. Bifurque el repositorio, cree una rama a partir de main, realice el cambio con sus pruebas y ejecute las comprobaciones antes de abrir una solicitud de extracción (pull request):
git checkout -b feature/skill-synthesis-validation
npm test
npm run lint
npm run typecheckUna contribución que cambie el comportamiento necesita una prueba que falle sin ella. No es una simple convención interna: las propias reglas de pruebas del SDK establecen que debe demostrarse que toda prueba nueva falla en el árbol antes del cambio, y los revisores solicitan la evidencia.
Módulos Enterprise y el límite de licencia
Enterprise es Community más módulos con licencia. Un módulo con licencia es un artefacto independiente que un servicio de Community carga al iniciarse, y es la forma en que las funcionalidades de Enterprise, así como cualquier módulo cerrado que usted cree para clientes de Enterprise, se acoplan al núcleo abierto.
La regla que hace que esto funcione es la línea de licencia. Un módulo cerrado puede acceder a la edición Community a través de un único paquete, @adverant/nexus-spi, la interfaz de proveedor de servicios. Tiene licencia Apache-2.0 y contiene interfaces además de las guardas de tipos que un host y un módulo utilizan para validarse mutuamente, sin ninguna otra lógica en tiempo de ejecución. El acoplamiento a través de la línea es una interfaz o un protocolo de red, nunca código fuente.
| Exportación | Qué es |
|---|---|
RouteModule |
Un módulo de rutas con licencia: id, featureGroup, bodies y register(app, ctx), que monta sus enrutadores en la aplicación del host |
SpiApp |
La parte de la aplicación HTTP del host que toca un módulo: use |
SpiContext |
Lo que el host entrega a un módulo: el control de producto y la guarda de alcance, el lector de licencias, el grupo de consultas con alcance, el esquema del servicio, las direcciones de origen (upstream) y los clientes de la plataforma |
SpiRuntime |
Los valores del SDK de plugins que un host entrega a un módulo, de modo que el módulo nunca importa por sí mismo el entorno de ejecución del SDK |
SpiPlane |
Lo que añade un plano con licencia además de rutas, como las lecturas de pantalla que sirve |
ScreenModule |
Un grupo de pantallas con licencia de una consola: group, featureGroup, routes, screens y menu |
GrantCheck |
(featureGroup) => Promise<{ entitled, code?: 'LICENCE_LOCKED' }> |
El marco de trabajo HTTP y el tipo de pantalla de la consola son parámetros de tipo, por lo que la interfaz no vincula a ninguno de los dos. A continuación se muestra el esqueleto de un módulo de rutas, con un tipo de manejador de Express:
import type { GrantCheck, RouteModule, SpiApp, SpiContext } from "@adverant/nexus-spi";
import { Router, type RequestHandler } from "express";
export function auditTrail(checkGrant: GrantCheck): RouteModule<RequestHandler> {
return {
id: "audit-trail",
featureGroup: "<feature-group>",
bodies: [],
register(app: SpiApp<RequestHandler>, ctx: SpiContext<RequestHandler>) {
const router = Router();
router.get("/api/audit-trail", ...ctx.requireScope, async (_req, res) => {
const verdict = await checkGrant("<feature-group>");
if (!verdict.entitled) {
res.status(403).json({
error: true,
code: verdict.code,
message: "This organisation's licence does not carry the audit trail.",
troubleshooting: ["An owner or administrator can turn it on with a licence from Adverant."],
});
return;
}
res.json({ entries: [] });
});
app.use(router);
},
};
}<feature-group> es el grupo de funcionalidades de la matriz de ediciones al que sirve el módulo. Toda ruta con licencia se ejecuta detrás de ctx.requireScope, el control de producto y guarda de alcance del host, y el módulo también comprueba su propia concesión antes de responder. Un módulo que no tiene autorización rechaza la petición con LICENCE_LOCKED y muestra el avance de la funcionalidad, nunca sus datos. Su módulo tampoco importa nunca el entorno de ejecución del SDK de plugins, porque el SDK es un paquete de Community que la línea no admite. El host le entrega los valores del SDK a los que llama. Antes de cargar cualquier módulo, el host instala un SpiHost en globalThis bajo Symbol.for(SPI_HOST_KEY), que contiene el entorno de ejecución del SDK y el propio kit de rutas de la aplicación. Esto debe ocurrir primero: un módulo compilado en un único paquete se evalúa como un todo, y una llamada a register llegaría demasiado tarde para el código que lee los valores del SDK mientras se carga. Para los tipos, @adverant/nexus-spi/sdk/<module> reexporta las declaraciones del SDK, incorporadas sin cambios desde una versión del SDK y fijadas mediante suma de comprobación, de modo que su módulo comprueba los tipos frente a los mismos cuerpos de rechazo y clientes que utiliza un plugin.
Un módulo de pantallas sigue una regla más: un módulo por grupo de funcionalidades, de modo que un grupo cuyas pantallas pertenecen a dos grupos de funcionalidades se distribuye como dos módulos, y solo uno de ellos lleva la fila del menú.
Qué rechaza el control de la línea de licencia
El control de la línea de licencia de Adverant exige que cada módulo de Enterprise respete la línea, y conviene aplicar la misma regla a sus propios módulos cerrados. Su configuración consta de un solo archivo:
{
"communityScopes": ["@adverant/", "@adverant-nexus/"],
"allowedCommunityPackages": ["@adverant/nexus-spi"],
"enterprisePrefixes": ["@adverant/enterprise-", "@adverant-enterprise/"],
"communityRepos": ["nexus-community", "nexus-core", "Adverant-Nexus-Open-Core"],
"allowedCommunityGoModules": []
}Cada uno de los siguientes casos constituye un hallazgo con su archivo y línea:
- cualquier importación de un paquete bajo un ámbito de Community que no sea la interfaz permitida o un paquete de Enterprise, incluidas las importaciones dinámicas;
- cualquier especificador, ruta de importación de Go o URL de dependencia que nombre un repositorio de Community, a menos que sea un módulo de Go enumerado en
allowedCommunityGoModules; - una importación relativa que salga fuera del repositorio;
- una dependencia en
package.jsonque sea una rutafile:,link:,portal:oworkspace:fuera del repositorio, o una URL de Git hacia un repositorio de Community; - un
go.modreplaceque apunte fuera del repositorio.
Termina con código 0 cuando está limpio y 1 si hay hallazgos. El código de salida 2 significa que rechazó la ejecución, ya sea porque su configuración era incorrecta o porque no analizó nada. El paquete de interfaz no se publica en un registro. Usted incluye una copia fijada byte a byte del paquete compilado dentro de su repositorio como un paquete local file:, con una fijación SHA256SUMS y una comprobación en su canalización que rechaza cualquier copia que difiera. Como la copia está dentro del repositorio, el control la acepta.
Compilaciones por edición
Si su extensión se distribuye a clientes en ambas ediciones, debe compilarla una vez por edición, y cada compilación tiene lugar en su propio árbol compuesto. Componer un árbol significa tomar únicamente los archivos que pertenecen a esa edición. La propia exportación de Adverant hace esto a partir de una lista de límites en la que cada archivo rastreado se asigna mediante reglas en las que gana la primera coincidencia: una regla nombra una capacidad y la edición del archivo se deduce del nivel de esa capacidad en la matriz de ediciones, o bien nombra una clase de archivo que no se incluye en ninguna de las ediciones, indicando el motivo. Los archivos exclusivos de compilación se incluyen en el árbol de Enterprise y, cuando están marcados, también en el árbol de Community. La cadena de migración de un módulo constituye datos del instalador y se incluye en el árbol de todas las ediciones.
A continuación, ejecute la compilación completa desde cero en cada árbol compuesto. Eso significa ejecutar los tres comandos, siempre:
npm ci
npm test
npm run buildAprendimos esto por las malas: un árbol de Enterprise superó sus pruebas mientras que el árbol de Community falló en su compilación de producción, porque un tipo que necesitaba existía únicamente en un archivo de Enterprise. Que las pruebas pasen en un árbol no dice nada sobre el otro. Las pruebas de una edición solo pueden importar lo que contiene el árbol de esa edición, y la exportación rechaza cualquier prueba que acceda al exterior.
La exportación también escribe la licencia de cada edición. Los archivos de Community llevan el identificador SPDX (Software Package Data Exchange) Apache-2.0; los archivos de Enterprise llevan LicenseRef-Adverant-Enterprise y su package.json indica UNLICENSED. No edite esos campos manualmente: la exportación los reescribe, y cualquier copia que deje de coincidir con su texto de licencia fijado es rechazada.
Team: solo en la nube
Team es Community más el conjunto Team, y se ejecuta únicamente en la nube de Adverant. No existe una versión autoalojada de Team. El conjunto Team añade seis capacidades sobre Community, entre ellas el panel de trabajo consolidado, los cuadernos compartidos, la administración de la biblioteca de habilidades y las operaciones de flujo de trabajo con promoción entre entornos.
Para un creador, que sea solo en la nube significa una cosa: un cliente de Team obtiene su plugin como una versión firmada a través del catálogo, nunca desde los servidores de usted. Usted lo compila de la misma manera que lo hace un editor externo, en un clúster de editor.
Un clúster de editor es un clúster virtual en la nube de Adverant con una cuota establecida por Adverant. Contiene únicamente datos de muestra y no tiene ruta hacia ningún cliente. Solicitar allí una copia enmascarada de los datos de un cliente se rechaza con TENANT_BOUNDARY; un cliente puede compartir con usted los resultados de las pruebas, pero nunca sus datos. Su pase en dicho clúster nunca llega hasta un cliente. Cuando la versión está lista, Adverant la firma y la revisa antes de incluirla en el catálogo. A continuación, cada cliente decide si desea instalarla y le concede únicamente lo que declara su manifiesto, unidad por unidad. Cualquier llamada a algo que el manifiesto no haya declarado se rechaza en el extremo del cliente con CONNECTION_SCOPE_EXCEEDED, y la única forma de añadirlo es mediante una nueva versión que el cliente revise.
Clientes en entornos aislados (air-gapped)
Uno de nuestros clientes ejecuta Nexus en un entorno donde nada entra ni sale a través de una red. Su instalación se describe en el capítulo 2.10, Instalación aislada de la red. Para nosotros, eso significó enviar nuestro plugin en un soporte firmado, y la herramienta para ello es nexus-airgap, del kit de entrega soberana @adverant/nexus-sovereign.
Un paquete sellado es un único archivo tar autocontenido y firmado. Puede contener imágenes y migraciones, habilidades prefirmadas y pesos de modelos, así como un SBOM (lista de materiales de software) con las licencias de todo su contenido. Su manifiesto enumera cada archivo con su SHA-256 y está firmado con Ed25519. Compilar uno a partir del código es así:
import { SealedBundleExporter } from "@adverant/nexus-sovereign";
const { bundleDigest } = await new SealedBundleExporter().export(source, {
outPath: "./cold-chain-0.4.0.tar.gz",
profile: "airgap",
signerPrivateKeyPem,
});signerPrivateKeyPem es su clave de firma de versiones. El comando nexus-airgap bundle hace lo mismo desde la línea de comandos. A continuación, el operador del cliente lo comprueba antes que nada:
nexus-airgap verify --bundle cold-chain-0.4.0.tar.gz --trusted-key corran-release.pub.pem --profile airgapLa verificación vuelve a calcular el hash de cada archivo frente al manifiesto, rechaza cualquier archivo que no figure en el manifiesto, exige un firmante Ed25519 de confianza y rechaza cualquier paquete cuya lista de redes permitidas no esté vacía. Un archivo modificado después de la firma falla con BUNDLE_INTEGRITY_VIOLATION. Indique al operador que se detenga ahí y le llame; existe un modificador no estricto, pero nunca debe utilizarlo.
Tres reglas rigieron nuestra entrega:
- La clave de confianza viaja por separado del paquete. Enviamos la clave pública y el SHA-256 del paquete por una vía distinta a la del soporte físico, de modo que un paquete no pueda avalarse a sí mismo.
- Nada en el paquete puede necesitar la red durante la instalación. Ni obtención de paquetes, ni descarga de modelos, ni llamadas de licencia. Si el plugin necesita un modelo, el propio servidor de modelos del cliente lo proporciona a través del AI (inteligencia artificial) Provider Router.
- Tras la verificación, el operador incorpora la versión a través de los canales de versiones propios de la instalación, exactamente igual que lo haría un cliente conectado. El paquete es el medio por el que llegan los bytes, no una forma de eludir los controles de promoción.
El trabajo aislado de la red es más lento, y no hay forma de solucionarlo por nuestra parte. Un byte erróneo cuesta un nuevo juego de soportes físicos y otro viaje, por lo que nosotros mismos verificamos el paquete en una máquina limpia con el mismo comando antes de que salga del edificio.
Paquetes de misión de Nexus Edge
Nexus Edge es un Nexus más pequeño que se ejecuta en satélites y drones, en ordenadores de misión mantenidos por separado del ordenador de vuelo. Es un complemento con una licencia por plataforma o flota. Lo que cambia de una misión a la siguiente es el paquete de misión, y crearlos constituye una buena parte de mi trabajo.
Un paquete de misión contiene lo que la carga útil necesita para una misión. Junto con sus modelos y adaptadores, contiene la ontología con un grafo inicial, pasos de agentes, reglas de alerta, las prioridades sobre qué se descarga primero, una tabla de ubicación que indica qué ordenador ejecuta cada cosa, los niveles de degradación a los que puede pasar la plataforma cuando falla un ordenador y los casos de prueba que debe superar a bordo.
Los paquetes se compilan y se firman en tierra. Algunas reglas prácticas de nuestras compilaciones:
- Mantenga estables las partes grandes. Maritime watch 1.5 añadió un adaptador de localización de buques y dos reglas de alerta; el modelo de lenguaje y la ontología no cambiaron, por lo que el paquete ocupaba 412 MB en lugar de 9.8 GB. El enlace ascendente es estrecho y los modelos base se cargan antes del lanzamiento.
- Utilice un único modelo de incrustación (embedding) para toda la familia de misiones, tanto en tierra como en la carga útil, de modo que los cambios del grafo que se descarguen puedan fusionarse con el grafo en tierra.
- La carga útil nunca envía un comando a los sistemas de vuelo. Envía solicitudes tipadas a través del supervisor al ordenador de vuelo, el cual responde a cada una indicando un motivo.
- Cada tipo de hardware necesita su propia comprobación del paquete. La instalación de un paquete no comprobado para el hardware de un dispositivo se rechaza con
PACK_NOT_CHECKED_FOR_HARDWARE.
El lanzamiento necesita dos de tres firmas. La nuestra y la de Adverant son el par habitual, y la tercera es una clave sin conexión que guardamos en una caja fuerte por si se pierde una de las otras dos. El paquete sube a la ranura inactiva, se verifica, ejecuta sus casos de prueba en las placas reales y se activa solo si todos se superan, con un contador que impide reinstalar un paquete más antiguo. Si una prueba falla, la plataforma permanece con el paquete anterior y el fallo se descarga en la siguiente pasada. Desplegamos una plataforma a la vez, cada una tras una semana sin incidencias. Los paquetes siguen siendo válidos mientras una plataforma está fuera de contacto, por lo que un satélite sin enlace sigue funcionando con el paquete que tiene.
En vehículos y embarcaciones, Edge puede ejecutarse sobre k3s. Una nave espacial ejecuta un supervisor con imágenes firmadas o binarios estáticos y una tabla de ubicación fija en lugar de Kubernetes, y es por eso por lo que la tabla de ubicación viaja dentro del paquete.
Escaparates de marca blanca
El complemento Storefront / marca blanca permite a un cliente poner su propia marca y dominio en lo que ven sus usuarios, con sus propias pantallas de inicio de sesión, y aceptar pagos a través de sus propias pasarelas. Los datos de las tarjetas nunca tocan Nexus.
Un plugin creado para un cliente de marca blanca nunca debe mostrar a Adverant. El manifiesto contiene todo lo específico de la marca, y la plataforma resuelve el resto a partir de la propia marca de la organización en lugar de cualquier valor codificado de forma fija en su código:
{
"domains": [
{ "primary": "<app-domain>", "aliases": ["www.<app-domain>"] }
],
"branding": {
"appName": "<app name>",
"tagline": "<one line>",
"primaryColor": "<hex>",
"accentColor": "<hex>",
"passkeyRpId": "<app-domain>",
"oauthClientRef": "brand:<plugin name>:google"
}
}<app-domain> es el dominio propio del cliente, y passkeyRpId debe coincidir con él, porque las llaves de acceso (passkeys) están vinculadas al dominio en el que una persona inicia sesión. Una aplicación web en su propio origen inicia la sesión de las personas a través de los asistentes de inicio de sesión del SDK, cuyas dos rutas públicas son las únicas rutas /api sin protección que acepta el control de alcance, y solo cuando el manifiesto las declara como auth: public con allowAnonymous: true. Las llamadas del frontend pasan por el proxy de lista permitida del backend para frontend, nunca directamente a una dirección de servicio. El administrador del cliente configura la parte de los pagos, desde las pasarelas hasta el proceso de pago con su marca. Su plugin no lo hace.
La matriz
| Destino de compilación | Compilar sobre | Qué se hace de forma diferente | Cómo llega al cliente |
|---|---|---|---|
| Community | Plugin SDK, Skills Engine | Código en GitHub; sin rutas de paquete de dominio ni de plataforma; sin Elevate | El cliente lo instala; no requiere revisión de catálogo |
| Enterprise (su propia instalación) | Plugin SDK, Skills Engine, plantillas de paquetes | Espacios de desarrollo, ramas de datos, copias enmascaradas con el propietario de los datos; paquetes y lentes | Promoción desde preproducción (staging) a una unidad piloto, luego a todas partes |
| Módulo de Enterprise (cerrado) | Solo @adverant/nexus-spi |
Regla de la línea de licencia; comprobación de concesión en su propio grupo de funcionalidades; LICENCE_LOCKED cuando no tiene autorización |
Cargado por un servicio de Community al iniciar, en instalaciones con licencia |
| Ambas ediciones | Plugin SDK | Componer el árbol de cada edición; npm ci, pruebas y compilación de producción en cada uno |
Una versión por edición |
| Team | Plugin SDK en un clúster de editor | Solo datos de muestra; solo en la nube | Versión firmada, revisión de Adverant, catálogo |
| Aislado de la red | Plugin SDK, @adverant/nexus-sovereign |
Paquete sellado; clave y suma de comprobación enviadas por separado; no se descarga nada al instalar | Soporte firmado, verificado y, a continuación, los canales de versiones de la instalación |
| Nexus Edge | Contenido del paquete de misión | Tabla de ubicación, niveles de degradación, pruebas a bordo, comprobaciones de hardware | Dos de tres firmas, ranura inactiva, activado tras superar las pruebas |
| Marca blanca | Plugin SDK | domains y branding en el manifiesto; sin el nombre de Adverant en ninguna parte |
Igual que para Enterprise, en el dominio propio del cliente |
Sea cual sea el destino, el despliegue se realiza únicamente a través de los canales de versiones de la instalación. El capítulo 2.28, Lanzamiento de su extensión, aborda esos canales. El capítulo 2.27, Escenarios de compilación, incluye una receta para cada una de las filas anteriores.



