Versión 1.0.0-alpha.1 más reciente
Capítulo 2.15
Día dos: operación de Nexus
El trabajo rutinario de operar una instalación después de la primera semana. Comienza con el desbloqueo del almacén de claves tras un reinicio y termina con la desinstalación.
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

La primera vez que falló el suministro eléctrico en la sala de servidores de Harrow Port Authority, todo volvió a funcionar excepto las partes que necesitaban claves. Los pods estaban en estado Running y la consola cargaba. Nadie podía abrir un archivo. Tomás Reilly había leído sobre esto y, aun así, tardó veinte minutos en recordar por qué. El desbloqueador del almacén de claves se inicia sellado tras cada reinicio de su nodo, y solo un custodio puede abrirlo.
Este capítulo sigue la rutina del operador después de la primera semana, desde el almacén de claves y sus custodios hasta la desinstalación. Cada verbo de nexusctl aquí acepta --explain, que imprime las operaciones de kubectl y helm que ejecutaría sin llegar a ejecutarlas. Úselo la primera vez que ejecute cualquier comando en un clúster de producción.
Custodia del almacén de claves
Una instalación tiene dos servidores OpenBao en su espacio de nombres. El almacén de claves, openbao, guarda todas las claves que utiliza Nexus. El desbloqueador, openbao-unsealer, es un segundo OpenBao más pequeño cuya única función es desellar el almacén de claves. El almacén de claves se desella a sí mismo mediante la clave de tránsito del desbloqueador; el desbloqueador está sellado con el esquema de Shamir, dividido en 5 fragmentos de los cuales 3 cualesquiera lo desellan.
En la primera instalación, un Job de custodia inicializa ambos servidores dentro del clúster. Cifra los fragmentos del desbloqueador y las claves de recuperación del almacén de claves en su propia memoria para cada custodio nombrado en keys.custody.recipients, y almacena únicamente el texto cifrado (los Secrets openbao-unseal-shares-encrypted y openbao-recovery-keys-encrypted). Revoca ambos tokens raíz en el mismo Job. El paquete de cada custodio contiene suficientes fragmentos para desellar por sí solo, por lo que basta con un custodio tras un reinicio.
Tras el reinicio de un nodo
Tras cualquier reinicio del nodo en el que se ejecuta el desbloqueador (un corte eléctrico, un reinicio de la máquina, un reinicio del entorno de ejecución de contenedores), el desbloqueador se inicia sellado. Hasta que un custodio lo deselle, el almacén de claves también permanece sellado y nada que necesite una clave funciona. La consola sigue respondiendo y los usuarios pueden iniciar sesión, pero cualquier acción que requiera una clave del almacén de claves queda en espera: abrir contenido cifrado, una reclamación o la verificación de una pieza compilada.
Consulte al propio OpenBao, dentro de cada pod. Este es el desbloqueador:
kubectl -n nexus exec openbao-unsealer-0 -c openbao -- \
bao status -format=json -address=https://127.0.0.1:8200 \
-ca-cert=/openbao/tls/ca.crt -tls-server-name=openbao-unsealer
echo "exit $?"Ejecute el mismo comando contra openbao-0 con -tls-server-name=openbao para el almacén de claves. bao status devuelve el código de salida 0 cuando el servidor está desellado, 2 cuando está sellado y 1 cuando no pudo responder. Un código de salida 1 no es concluyente, porque es posible que el pod aún no esté activo. Espere un minuto y vuelva a consultar. Si el desbloqueador está desellado y el almacén de claves sigue sellado, el almacén de claves se está desellando a sí mismo y usted no tiene que hacer nada.
Desellado
El chart incluye unseal.sh, en su carpeta files/custody/, idéntico byte por byte en cada versión. Un custodio lo ejecuta en su propia máquina. Lee el Secret cifrado, lo descifra una vez con la identidad del custodio (una identidad de Secure Enclave solicita Touch ID una vez), envía los fragmentos al desbloqueador y confirma que está desellado. Ningún fragmento se escribe jamás en un archivo ni se pasa por una línea de comandos.
Harrow lo ejecuta en modo directo, a través de un reenvío de puertos:
kubectl -n nexus get secret openbao-unsealer-tls -o jsonpath='{.data.ca\.crt}' | base64 -d > unsealer-ca.crt
kubectl -n nexus port-forward pod/openbao-unsealer-0 28200:8200 &
AGE_IDENTITY=<path-to-your-custodian-identity> \
OPENBAO_NS=nexus \
UNSEAL_ADDR=https://127.0.0.1:28200 \
UNSEAL_CACERT=unsealer-ca.crt \
UNSEAL_RESOLVE=openbao-unsealer.<namespace>.svc \
UNSEAL_SECRET_JSON_CMD='kubectl -n nexus get secret openbao-unseal-shares-encrypted -o json' \
bash unseal.sh<path-to-your-custodian-identity> es el archivo de identidad age del custodio, la mitad privada de uno de los destinatarios en keys.custody.recipients. UNSEAL_RESOLVE es el nombre que lleva el certificado del desbloqueador (<namespace> es el espacio de nombres en el que está instalado Nexus, nexus de forma predeterminada), por lo que TLS se verifica contra la propia CA del desbloqueador aunque la conexión vaya a 127.0.0.1. El script nunca desactiva la verificación de certificados.
| Salida | Última línea | Significado |
|---|---|---|
| 0 | UNSEALED nexus/openbao-unsealer-0 |
Desellado. Si ya lo estaba, no se envió nada |
| 1 | STILL-SEALED … |
Sigue sellado, o falló una llamada de desellado |
| 2 | UNSEAL-REFUSED … |
Falta un requisito previo, indicado en el mensaje |
| 3 | UNSEAL-REFUSED … |
Esta identidad no puede descifrar los fragmentos, por lo que no es un custodio de esta instalación. No se envió nada |
En el transcurso de un minuto, el almacén de claves le sigue por sí solo. Compruebe con kubectl -n nexus get deploy,statefulset que todo esté listo de nuevo.
Los custodios se eligen antes de la instalación, y cada uno crea su propia clave en su propia máquina. El chart solo ve la mitad pública:
age-keygen -o custodian.key
age-plugin-se keygen --access-control=any-biometry -o custodian.keyEl primer comando crea una identidad age ordinaria; su destinatario es la línea # public key: age1... del archivo. El segundo crea una guardada en el Secure Enclave de un Mac, con un destinatario que comienza por age1se1. Cualquiera de los destinatarios va en keys.custody.recipients. El archivo de identidad permanece con su custodio, sin conexión.
Copia de seguridad y restauración
Copia de seguridad y restauración muestra cada almacén con su última copia de seguridad y la última vez que se probó realmente una restauración del mismo. Una copia de seguridad solo queda demostrada una vez que se ha restaurado, por lo que la página registra ambos datos. Se realiza copia de seguridad de seis almacenes. La base de datos principal contiene las personas y la configuración; los trabajos y el registro de auditoría. Junto a ella se encuentran el grafo de conocimiento y el índice de búsqueda, seguidos del almacén de archivos y el almacén de memoria. Las claves son el sexto, selladas y mantenidas aparte de los datos. Las copias de seguridad van a su propio almacenamiento, cifradas con sus propias claves, y Adverant no puede leerlas. Cuando no se ha probado la restauración de un almacén dentro del plazo de su regla, la página muestra el aviso RESTORE_TEST_OVERDUE con un botón Probar ahora. Una restauración de prueba se ejecuta en un espacio separado y nadie lo nota.
Las mismas dos acciones están disponibles desde la línea de comandos:
nexusctl backup now
nexusctl backup verifybackup now realiza una copia de seguridad de todos los almacenes a la vez. backup verify comprueba la última copia de seguridad. Ejecute ambos antes de realizar cualquier cambio que le preocupe.
Para restaurar, indique el nombre de la copia de seguridad:
nexusctl restore --from <backup-id><backup-id> proviene de la lista en Copia de seguridad y restauración. Una restauración necesita la aprobación de una segunda persona y, mientras se ejecuta, la franja de progreso la muestra con la hora en que comenzó y quién la aprobó. Todo el mundo pasa a modo de solo lectura durante la restauración, lo cual es distinto de quedar bloqueado: los usuarios pueden iniciar sesión y leer. Los trabajos no se inician (las programaciones esperan y se ponen al día) y la búsqueda vuelve a estar disponible cuando se recupera el índice de búsqueda. Todo lo escrito después de que se tomara la copia de seguridad se pierde, por lo que el informe de restauración lo enumera por propietario para que puedan volver a hacerlo.
Guarde una cosa más con sus copias de seguridad: el Secret nexus-generated en el espacio de nombres nexus. El chart crea las contraseñas generadas y las claves de cifrado de la instalación en la primera instalación y las vuelve a leer de ese Secret en cada actualización. Los datos sellados bajo EXTERNAL_KEY_ENCRYPTION_KEY se abren únicamente con esa clave. Guarde una copia del Secret dondequiera que conserve el material más confidencial que tenga, porque cualquiera que lo posea tendrá esas claves.
Actualizaciones
Tomás actualiza en dos pasos. Primero consulta qué cambiará:
nexusctl upgrade plan --bundle nexus-alpha-1.0.0-alpha.2-enterprise.tarEl plan enumera lo que cambia en la versión, cualquier cambio en la estructura de la base de datos y si se puede deshacer. Luego lo aplica:
nexusctl upgrade apply --bundle nexus-alpha-1.0.0-alpha.2-enterprise.tarLa aplicación realiza primero una copia de seguridad y ejecuta las comprobaciones previas. A continuación, actualiza los motores en oleadas, y cada oleada espera hasta que la anterior haya permanecido en buen estado durante 10 minutos. La página Actualizar muestra cada oleada a medida que avanza y el estado de salud de la instalación mientras tanto. También indica hasta cuándo permanece abierta la vuelta atrás; después de esa fecha, volver atrás requiere una restauración. Si un paso falla, Nexus revierte cada motor a la versión anterior y los comprueba. El aviso UPGRADE_ROLLED_BACK indica entonces el paso que falló y confirma que los datos no sufrieron cambios. La solución se muestra antes de Intentar de nuevo, y el paquete de soporte está a un botón de distancia.
Para una instalación sin conexión externa, el paquete llega en un soporte físico. Importar desde soporte comprueba la firma de la versión contra la clave de versiones de Adverant instalada en la instalación y verifica que las versiones solo avancen. Los archivos firmados por cualquier otra entidad son rechazados con MEDIA_SIGNATURE_INVALID: no se carga nada y la versión en ejecución sigue funcionando.
Qué ocurre internamente
nexusctl upgrade apply ejecuta helm upgrade contra el chart. Si actualiza con Helm usted mismo, se aplican las mismas reglas:
helm upgrade nexus oci://registry.adverant.ai/nexus/charts/nexus --version <version> -n nexus -f harrow-values.yaml
kubectl -n nexus wait --for=condition=Available deploy --all --timeout=900sEl esquema avanza antes de que se desplieguen los nuevos pods. Las migraciones del chart son hooks previos a la actualización que se ejecutan en orden: primero el arranque de la base de datos, luego las migraciones de cada servicio y, por último, las del backend para frontend (BFF) de la consola. El Job de custodia también se ejecuta y, en una instalación que ya está inicializada, lo confirma y no cambia nada. Cada Job de hook tiene un límite de reintentos de 0, por lo que una migración que falla detiene la actualización y nunca se reintenta de forma silenciosa: lea su registro con kubectl -n nexus logs job/<hook-job> antes de volver a intentarlo.
El pod de cada servicio espera en un contenedor de inicialización, wait-for-schema, hasta que el registro de versiones muestra sus migraciones aplicadas para la imagen de la nueva versión. Tras una reversión, o una actualización que solo cambió valores, un pod reiniciado encuentra su fila y se inicia de inmediato.
Antes de actualizar
Vale la pena planificar teniendo en cuenta tres puntos de las notas de la versión:
- Actualice en un período de baja actividad. En la primera actualización de una instalación creada a partir de un chart anterior, el trabajo de arranque retira los antiguos permisos predeterminados de las tablas, y cada servicio recupera los suyos a partir de su propia migración. Hasta que se ejecuta esa migración, un servicio no puede usar sus tablas. El intervalo dura segundos. Si los segundos importan, escale primero los servicios a cero y vuelva a escalarlos una vez que hayan terminado los trabajos de migración.
- Asigne una organización a cada clave de interfaz de programación de aplicaciones (API). Una clave sin organización es rechazada con
403 TOKEN_ORG_MISSINGpor cada servicio que verifica claves a través de nexus-auth, incluido nexus-graphrag. Antes de actualizar, asigne una organización a cada una de esas claves o emita una clave nueva. Las claves bcrypt antiguas siguen funcionando hasta su fecha de revocación definitiva. - Vacíe después las claves de API en caché. Hasta una hora de entradas de claves en caché contienen el nombre de aplicación incorrecto hasta que lo haga. Ejecute esto contra la caché de nexus-auth, el Valkey de la instalación (
nexus-valkey, contraseña en el Secretnexus-generatedbajoVALKEY_PASSWORD):
pw=$(kubectl -n nexus get secret nexus-generated -o jsonpath='{.data.VALKEY_PASSWORD}' | base64 -d)
kubectl -n nexus exec nexus-valkey-0 -- sh -c \
'valkey-cli -a "$1" --scan --pattern "apikey:prefix:*" | xargs -r valkey-cli -a "$1" del' _ "$pw"Eso es para el almacén predeterminado dentro del clúster. Con dataTier.valkey.mode: external no existe dicho pod: ejecute el mismo escaneo y eliminación contra su propio host Valkey, con la contraseña del Secret indicado en dataTier.valkey.external.existingSecret.
Reversión
Dentro del plazo que muestra la página Actualizar, Volver atrás devuelve todos los motores a la versión anterior. Pasado ese plazo, volver atrás implica restaurar la copia de seguridad que la actualización tomó al principio.
Dos valores no deben cambiar nunca entre una actualización o una reversión.
keys.installationName es permanente. El primer arranque del almacén de claves acuña la identidad de la instalación bajo él, y esa identidad es la que figura en su licencia. Utilice exactamente el mismo valor en cada archivo de valores que aplique a esta instalación.
El Secret nexus-generated debe permanecer tal como está. En cada actualización, el chart lee EXTERNAL_KEY_ENCRYPTION_KEY de él y comprueba su formato. Un valor que no sea ni base64 de 32 bytes ni la clave sin procesar de 32 bytes de una instalación anterior detiene el renderizado con EXTERNAL_KEY_ENCRYPTION_KEY_INVALID, y el chart nunca imprime el valor. Esto significa que alguien editó o reemplazó el Secret. Vuelva a colocar la clave bajo la cual están sellados los datos de esta instalación, en formato base64 de sus 32 bytes (printf %s "$OLD" | base64), y actualice de nuevo. Una clave aleatoria nueva dejaría ilegible todo lo sellado bajo la antigua.
Escalado
Cada componente tiene un interruptor y un tamaño en el archivo de valores. Los componentes obligatorios no se pueden desactivar: el chart los ejecuta independientemente de lo que indique su interruptor. A los demás se les pueden asignar más réplicas y más recursos.
# harrow-values.yaml (Helm values): scaling
components:
gateway:
replicas: 2
resources: { requests: { cpu: 400m, memory: 1Gi }, limits: { memory: 3Gi } }
graphrag:
replicas: 2
workflows:
replicas: 2
workflows:
concurrency: "8"
dataTier:
qdrant:
resources: { requests: { cpu: 200m, memory: 512Mi }, limits: { memory: 4Gi } }Aplíquelo con helm upgrade como se indicó anteriormente. El tamaño de los volúmenes se define bajo dataTier.<store>.size; compruebe que su clase de almacenamiento pueda ampliar un volumen antes de aumentarlo. Estado de la instalación muestra en gráficos cuán ocupados han estado los procesadores y la memoria del clúster, junto con el margen disponible en cada uno. Amplíe primero el que se agote antes.
Paquetes de soporte
Cuando Harrow necesita la ayuda de Adverant, Tomás genera un paquete de soporte:
nexusctl support-bundle --out harrow-support-4471.tar.gzLa página Paquete de soporte de la consola genera el mismo archivo. Recopila los registros de los motores de las últimas 24 horas con detalles de estado y versión. La configuración se incluye sin sus secretos, junto con los informes de comprobaciones previas e instalación. Antes de que se escriba nada, la ocultación de datos reemplaza los nombres y secretos por marcadores de posición, y usted puede leer una vista previa de exactamente lo que saldrá. El contenido propio de los usuarios nunca se recopila. El paquete se envía a Adverant ya sea subiéndolo a la página Soporte y paquetes de soporte de su cuenta o como un archivo transportado en un soporte físico. Solo los ingenieros de soporte nombrados en la solicitud pueden abrirlo, y se borra transcurridos 30 días.
Exportación de evidencias
Los auditores y su propio equipo de cumplimiento normativo suelen requerir pruebas de que la plataforma se comporta según lo descrito. nexusctl evidence export las genera:
nexusctl evidence export --out harrow-evidence-2027-01Junto con los registros que exporta, el comando ejecuta las sondas de aceptación de la plataforma: el enrutador de inteligencia artificial (IA) es accesible y responde, un trabajo UNO se envía y se completa, y se rechaza una lectura entre organizaciones. Sus resultados se encuentran en probes.json, en la carpeta de salida.
Estado de un vistazo
nexusctl status --json responde si la instalación está en buen estado y en qué estado se encuentra cada componente. También informa del estado de la licencia con su fecha de vencimiento, la edición y la versión en ejecución. Cada pieza compilada se enumera con su resumen criptográfico y su firma. Es el comando indicado para integrar en su propio sistema de monitorización.
Desinstalación
nexusctl uninstall --profile <profile-file><profile-file> es el perfil de despliegue para el clúster, el mismo archivo que pasó a nexusctl handoff --profile <profile-file> --out <dir> si su equipo de plataforma administra el clúster. La entrega genera, para ese equipo, una lista en lenguaje claro de lo que Nexus necesita del clúster y los manifiestos para cumplirlo. La desinstalación elimina los espacios de nombres de Nexus y nada más, y conserva sus copias de seguridad. La identidad de la instalación desaparece con ella. Una instalación posterior en el mismo clúster es una instalación nueva con una identidad nueva, por lo que su reclamación es una reclamación nueva y su licencia es una licencia nueva.
Las páginas de Esta instalación
Los operadores de la instalación tienen su propio grupo en el menú, Esta instalación, y sus páginas son donde transcurre la mayor parte de este capítulo en la consola. Un miembro que abre una de ellas ve la página No es un administrador, que indica quién puede actuar.
| Página | Para qué sirve |
|---|---|
| La licencia y lo que desbloquea | La licencia y sus grupos de funciones (capítulo 2.13, Licencias) |
| Si la licencia vence | La escala de vencimiento explicada con palabras, con las fechas de esta licencia |
| Partes compiladas | Cada módulo con licencia con su verificación de firma nocturna |
| Declaración de uso para Adverant | Los contadores anuales, legibles antes de enviarse |
| Versiones y actualizaciones | Cada versión instalada, con quién la instaló y cuándo |
| Actualizar | La actualización por fases y la vuelta atrás |
| Copia de seguridad y restauración | Cada almacén, su última copia de seguridad y su última restauración probada |
| Estado de la instalación | Nodos, capacidad y coste de ejecución, con advertencias |
| Claves y borrado | La clave de cada organización, y Borrar con un motivo y una segunda persona |
| Incidentes | Problemas abiertos y cerrados, con lo que se hizo |
| Próxima retirada | Funciones que se van a desactivar, con fechas, exportación y reemplazo |
| Estado | Cada parte de Nexus ahora y durante 30 días, en palabras que cualquiera puede entender |
| Paquete de soporte | Qué se envía a Adverant y cómo |
Dos de estas páginas merecen una mención. Piezas compiladas comprueba cada noche todos los módulos con licencia contra la firma de Adverant. Una copia modificada de un módulo es rechazada y nunca se carga, mientras que la copia firmada sigue ejecutándose, y la página contabiliza los rechazos por mes para que una copia manipulada no pueda pasar desapercibida. Estado está redactada para que cualquier persona de la organización pueda leerla. Muestra cada parte de Nexus ahora y durante los últimos 30 días como una franja de días, con el mantenimiento programado y los incidentes recientes, y un operador puede añadir un incidente o una ventana de mantenimiento desde la misma página.
Una instalación Community tiene una página, Esta instalación (Community), con su versión, estado de salud y actualizaciones. Las páginas Enterprise aparecen en ella como avances que indican quién puede activarlas.




