Instantáneas de Sui: formal vs RocksDB y restauración de nodo completo

El modelo mental de instantáneas particionadas por época

Una instantánea de la base de datos de Sui es una vista puntual del almacén de un nodo capturada al final de una época. Sui está particionado por épocas: las épocas son la unidad del protocolo para el cambio y la reconfiguración del conjunto de validadores, por lo que cada artefacto de instantánea se direcciona por época, nunca por una altura de bloque arbitraria. Esta es la diferencia más importante con las herramientas de instantáneas y restauración al estilo EVM, donde los operadores suelen razonar en números de bloque y rebobinar a una altura. En Sui, la pregunta siempre es a qué época estás restaurando y si el artefacto que tienes es el que el comité comprometió para esa época.

La documentación de instantáneas de la base de datos de Sui es la fuente autoritativa para los dos tipos de artefacto y sus procedimientos de restauración. La documentación de nodo completo cubre la configuración, monitorización y actualización del nodo, que es donde viven los ajustes de producción de instantáneas. La documentación de gestión de datos explica la poda y los almacenes de archivo, y afirma por qué las instantáneas formales no son adecuadas para nodos RPC históricos. Lee esas tres páginas junto con este artículo; el comportamiento de la plataforma descrito aquí está documentado allí, mientras que las recomendaciones operativas son nuestras.

Dado que las instantáneas se direccionan por época, una restauración también es una comprobación de identidad de cadena. Debes saber qué red estás restaurando (mainnet, testnet u otra), qué blob de génesis usa esa red y a qué época pretendes llegar. Una instantánea de la red equivocada o de una época obsoleta fallará la verificación o dejará el nodo muy por detrás de la época actual, y ninguno de los dos resultados es obvio solo con el listado de archivos.

• Unidad de instantánea: vista al final de la época, direccionada por número de época.
• Identidad de cadena: la red y el blob de génesis deben coincidir con la instantánea.
• Objetivo de restauración: alcanzar la época de la instantánea y luego ponerse al día con la cabeza de la red en vivo.

Instantáneas formales frente a RocksDB y su compensación

Una instantánea RocksDB es una vista puntual del almacén de la base de datos, incluidos datos no podados, índices adicionales y otros datos que mantiene el nodo. Es un artefacto más grande, pero conserva los índices que un nodo RPC necesita para responder consultas históricas e indexadas. Una instantánea formal es independiente de la base de datos: contiene solo el conjunto de objetos vivos al final de la época, es decir, el conjunto de todas las versiones de objetos elegibles como objetos de entrada para transacciones futuras. Tiene una huella de almacenamiento mucho menor y se restaura más rápido, y es compatible de forma nativa con el protocolo Sui y verificable criptográficamente contra un compromiso firmado por el comité en la época que se restaura.

La restricción que más importa en producción está documentada claramente: las instantáneas formales no son adecuadas para un nodo RPC que realiza búsquedas de datos históricos, porque no contienen índices. La elección entre los dos tipos se decide, por tanto, por el trabajo, no por el tamaño del artefacto. Los validadores y los nodos completos de sincronización de estado pueden partir de una instantánea formal. Un nodo que debe servir lecturas históricas y consultas indexadas no debe hacerlo; necesita el artefacto RocksDB o una sincronización completa que reconstruya los índices por sí misma.

Esta es la misma división operativa descrita en Nodos de archivo de Sui y RPC histórico: los roles de archivo y de servicio histórico dependen de los datos e índices retenidos, mientras que un participante de sincronización de estado solo necesita el conjunto de objetos vivos para validar hacia adelante. Si aún estás decidiendo qué interfaz debe exponer tu nodo, la guía Configuración del endpoint RPC de nodo completo de Sui cubre el enlace y la configuración, y la guía gRPC de Sui cubre la interfaz de consulta más reciente.

• Instantánea RocksDB: vista completa del almacén, incluye índices y datos no podados, más grande, necesaria para RPC histórico.
• Instantánea formal: solo conjunto de objetos vivos, independiente de la base de datos, más pequeña y rápida, verificable contra el compromiso de época, sin índices.
• Regla de decisión: elige según las consultas que el nodo debe responder, no según el tamaño de descarga.

Restaurar un nodo completo desde una instantánea RocksDB

La ruta de restauración de RocksDB es deliberadamente simple: colocas un directorio donde el nodo espera su almacén en vivo. Descarga el directorio de la época desde el bucket de instantáneas gestionado con herramientas de almacenamiento de objetos en la nube a un directorio temporal, luego colócalo en <db_path>/live, corrige la propiedad para que el proceso sui-node pueda leerlo y escribirlo, e inicia sui-node. Los buckets de instantáneas de base de datos gestionados por Mysten Labs son Requester Pays, lo que significa que el operador paga la salida, por lo que un lector que necesite una instantánea RocksDB debe presupuestar esa transferencia.

Dos detalles causan la mayoría de los fallos. Primero, la estructura del directorio: el nodo espera el contenido de la época bajo <db_path>/live, no una copia anidada de la ruta del bucket, así que verifica la estructura antes de iniciar el nodo. Segundo, la propiedad y los permisos: un almacén copiado como root y luego leído por una cuenta de servicio sin privilegios fallará al inicio de formas que parecen corrupción. Corrige la propiedad antes del primer inicio y mantén el directorio de descarga temporal en un volumen con suficiente espacio libre tanto para el archivo como para el almacén extraído.

Dado que el artefacto RocksDB es una vista del almacén en lugar de un objeto verificable por el protocolo, tu comprobación de integridad es estructural y operativa: confirma que el directorio de la época está completo, confirma que el nodo arranca sin errores de almacén y confirma que avanza más allá de la época de la instantánea. La historia de verificación criptográfica pertenece a las instantáneas formales, que se describen a continuación.

• Descarga el directorio de la época a una ruta temporal con tu CLI de almacenamiento de objetos en la nube.
• Coloca el contenido en <db_path>/live y corrige la propiedad antes del primer inicio.
• Presupuesta la salida de Requester Pays en los buckets de instantáneas de base de datos gestionados.
• Verifica mediante un arranque limpio y un progreso hacia adelante más allá de la época de la instantánea.

Restaurar un nodo completo desde una instantánea formal con sui-tool

Las instantáneas formales se restauran con sui-tool download-formal-snapshot. Usa --latest o un --epoch explícito, apunta --genesis al genesis.blob de la red, establece --network y establece --path al directorio de base de datos de destino. Para los buckets gratuitos sin permisos, usa --no-sign-request; para un bucket explícito, pasa --snapshot-bucket y --snapshot-bucket-type junto con las variables de entorno de credenciales en la nube documentadas. Mantén la configuración de poda de checkpoints y transacciones a la vista para que el nodo arranque con la retención que pretendes en lugar de la predeterminada.

La restauración formal realiza la verificación por defecto contra el compromiso de época y revierte el nodo si la verificación falla. Ese comportamiento es la razón por la que las instantáneas formales son la ruta de incorporación más segura para los participantes de sincronización de estado: la herramienta comprueba el artefacto contra el compromiso firmado por el comité para la época que se restaura, de modo que una descarga corrupta o de época equivocada no se convierte silenciosamente en el estado de tu nodo. Después de que la herramienta termine, inicia sui-node y observa cómo se pone al día.

# Restore the latest formal snapshot for mainnet into a target db path.
# Run from the sui-tool binary matching your sui-node release.
sui-tool download-formal-snapshot \
  --latest \
  --genesis /opt/sui/config/genesis.blob \
  --network mainnet \
  --path /opt/sui/db \
  --no-sign-request

# Pin a specific epoch instead of --latest:
#   --epoch 742
#
# Use an explicit bucket instead of the free permissionless bucket:
#   --snapshot-bucket <bucket-name> \
#   --snapshot-bucket-type <gcs|s3> \
#   (plus the documented cloud credential environment variables)
#
# Then start the node with your intended pruning configuration:
#   sui-node --config-path /opt/sui/config/fullnode.yaml

El modelo de coste y acceso para los buckets de instantáneas

Los buckets de instantáneas de base de datos gestionados por Mysten Labs son Requester Pays: el operador que descarga paga la salida. Existen buckets gratuitos sin permisos solo para instantáneas formales y se sirven a través de Cloudflare R2, que es la razón por la que la bandera --no-sign-request aparece en los ejemplos de restauración formal. La asimetría es la consecuencia práctica de los tipos de artefacto: las instantáneas formales son lo suficientemente pequeñas y verificables por el protocolo como para ofrecerse sin permisos, mientras que las instantáneas RocksDB son grandes vistas del almacén cuyo coste de transferencia corre a cargo del solicitante.

Para la planificación, trata esto como una cuestión de presupuesto en lugar de una cuestión técnica. Un lector que necesite una instantánea RocksDB debe presupuestar la salida desde el bucket gestionado. Un lector que solo necesite unirse como nodo completo de sincronización de estado o validador puede usar la ruta formal gratuita. Si estás eligiendo un proveedor gestionado en lugar de ejecutar tu propio nodo, la página de redes de Sui enumera las opciones de red, y Precios de RPC y el servicio de API describen las alternativas alojadas al autoalojamiento.

• Buckets de instantáneas de base de datos gestionados: Requester Pays, el operador paga la salida.
• Buckets gratuitos sin permisos: solo instantáneas formales, servidos a través de Cloudflare R2.
• Los ejemplos de restauración formal usan --no-sign-request contra el bucket gratuito.

Producir instantáneas desde tu propio nodo completo

Los nodos completos no toman instantáneas por defecto. Para producirlas, habilita db-checkpoint-config con perform-db-checkpoints-at-epoch-end más un bloque object-store-config, o state-snapshot-write-config con object-store-config más object-store-connection-limit, en fullnode.yaml, y luego reinicia el nodo. El primero produce el checkpoint de base de datos al estilo RocksDB; el segundo escribe instantáneas de estado formales. Trata las credenciales del bucket en estos bloques como secretos con ámbito de escritura y limítalas solo al prefijo de instantáneas.

Sui anima explícitamente a la comunidad a alojar instantáneas adicionales para la disponibilidad de datos, por lo que producirlas es una contribución legítima, no solo una comodidad interna. La disciplina operativa es la misma que al consumirlas: sabe qué época escribiste, mantén el artefacto direccionable por época y publica lo que tienes. El artículo Streaming de checkpoints de Sui y el servicio de ledger cubre el mecanismo adyacente de streaming de checkpoints si estás construyendo infraestructura de disponibilidad de datos en torno a instantáneas.

• db-checkpoint-config: perform-db-checkpoints-at-epoch-end más object-store-config.
• state-snapshot-write-config: object-store-config más object-store-connection-limit.
• Reinicia después de editar fullnode.yaml; usa credenciales de bucket con ámbito de escritura.
• Registra la época escrita y publica el nombre del bucket y la retención.

Verificar una restauración contra la cadena y la cabeza esperadas

Una comprobación honesta de restauración tiene dos partes. Primero, confirma que se ejecutó la verificación de la instantánea formal: la herramienta verifica contra el compromiso de época por defecto y revierte en caso de fallo, por lo que una restauración completada sin reversión es evidencia de que la comprobación del compromiso pasó. Segundo, confirma que el nodo reiniciado está en la cadena esperada y que su cabeza de checkpoint avanza. No enrutes tráfico hasta que ambas sean verdaderas.

El script siguiente consulta el endpoint JSON-RPC de un nodo para obtener el identificador de cadena y el último número de secuencia de checkpoint, muestrea dos veces e informa si la cabeza avanzó. Usa solo métodos JSON-RPC estándar y fetch integrado de Node, por lo que se ejecuta en cualquier lugar donde esté instalado Node 18 o posterior. Apúntalo al endpoint de tu propio nodo, no a uno público, al validar una restauración.

// verify-restore.mjs — confirm chain identity and advancing checkpoint head.
// Usage: node verify-restore.mjs http://127.0.0.1:9000 <expected-chain-id>
const endpoint = process.argv[2] || "http://127.0.0.1:9000";
const expectedChainId = process.argv[3];

async function rpc(method, params = []) {
  const res = await fetch(endpoint, {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params }),
  });
  const body = await res.json();
  if (body.error) throw new Error(`${method}: ${body.error.message}`);
  return body.result;
}

const chain = await rpc("sui_getChainIdentifier");
console.log("chain identifier:", chain);
if (expectedChainId && chain !== expectedChainId) {
  console.error(`MISMATCH: expected ${expectedChainId}`);
  process.exit(1);
}

const first = await rpc("sui_getLatestCheckpointSequenceNumber");
console.log("checkpoint head (sample 1):", first);
await new Promise((r) => setTimeout(r, 15000));
const second = await rpc("sui_getLatestCheckpointSequenceNumber");
console.log("checkpoint head (sample 2):", second);

if (BigInt(second) > BigInt(first)) {
  console.log("OK: checkpoint head is advancing");
} else {
  console.error("WARN: head did not advance in the sample window");
  process.exit(2);
}

Una tabla de resultados para tus propias mediciones

El tamaño de la instantánea, el tiempo de descarga y la duración de la restauración dependen del entorno y no deben afirmarse como hechos fijos. Mídelos en tu propia infraestructura y registra los resultados. La tabla siguiente es una plantilla para rellenar por artefacto y por ejecución; mantén la época, el tipo de artefacto y la red en cada fila para que las comparaciones sigan siendo honestas.

Realiza cada medición al menos dos veces, en la misma clase de host y ruta de red, y anota si la fuente fue el bucket formal gratuito o un bucket gestionado Requester Pays. Si publicas los números, publica el método junto con ellos.

• Columnas: fecha, red, época, tipo de artefacto, bucket de origen, tamaño del artefacto, duración de descarga, duración de restauración, resultado de verificación, cabeza de checkpoint final.
• Registra la clase de host, la región y la ruta de salida para que los números sean reproducibles.
• Trata cualquier ejecución única como anecdótica hasta repetirla.

Limitaciones, compensaciones y modos de fallo

La limitación central es la brecha de índices: una instantánea formal restaura un nodo que puede validar hacia adelante pero no puede responder consultas históricas indexadas, porque no contiene índices. Si tu contrato de servicio incluye lecturas históricas, la ruta formal es la herramienta equivocada por mucho más rápida que sea. La ruta RocksDB conserva los índices pero cuesta más almacenamiento y salida, y no es verificable criptográficamente de la misma manera, por lo que tu comprobación de integridad es estructural.

El direccionamiento por época es una segunda limitación. Una instantánea solo es válida para la época en que se tomó, y un artefacto obsoleto deja el nodo muy atrás. No hay comodidad de rebobinar a una altura. Tercero, el modelo de acceso es asimétrico: buckets formales gratuitos frente a buckets de base de datos Requester Pays significa que la ruta más barata es también la más restringida. Por último, producir instantáneas requiere cambios de configuración y un reinicio, y las credenciales de bucket mal configuradas son una causa común de no producción silenciosa.

• Las instantáneas formales no pueden servir consultas históricas indexadas.
• Las instantáneas RocksDB cuestan más almacenamiento y salida y carecen de verificación a nivel de protocolo.
• Las instantáneas están ligadas a la época; los artefactos obsoletos implican una larga puesta al día.
• Los buckets gratuitos cubren solo instantáneas formales.
• La producción de instantáneas es opcional y requiere un reinicio.

Solución de problemas comunes de restauración

Cuando una restauración formal falla la verificación, la herramienta revierte el nodo. Las causas habituales son un blob de génesis de la red equivocada, una época que no existe en el bucket o una descarga truncada. Vuelve a comprobar --network y --genesis primero, luego reintenta la misma época; si vuelve a fallar, prueba --latest para distinguir un artefacto defectuoso de una configuración local defectuosa.

Cuando una restauración RocksDB arranca pero el nodo da error en el almacén, inspecciona la estructura del directorio bajo <db_path>/live y la propiedad de los archivos. Un directorio anidado o archivos propiedad de root son las causas más comunes. Cuando el nodo arranca pero la cabeza de checkpoint no avanza, comprueba la conectividad de pares y si el nodo aún se está poniendo al día desde la época de la instantánea; una cabeza que avanza lentamente es normal inmediatamente después de la restauración, mientras que una cabeza congelada no lo es. Para problemas a nivel de interfaz después de que el nodo esté sano, la guía gRPC de Sui y el artículo Configuración del endpoint RPC de nodo completo de Sui cubren la configuración del endpoint.

• Fallo de verificación: comprueba red, blob de génesis, existencia de la época e integridad de la descarga.
• Error de arranque del almacén: comprueba la estructura de <db_path>/live y la propiedad.
• Cabeza congelada: comprueba los pares y el estado de puesta al día antes de asumir corrupción.

Asesorar a otros operadores y próximos pasos

Dado que Sui anima a las instantáneas alojadas por la comunidad, lo más útil que puede hacer un operador es publicar con claridad: qué nivel (gestionado Requester Pays frente a R2 gratuito), el nombre del bucket, el rango de épocas disponible y la política de retención. Los consumidores necesitan saber si pueden usar --no-sign-request o deben presupuestar la salida, y necesitan saber hasta dónde llegan las épocas antes de planificar una restauración.

Para tus propios próximos pasos, decide primero el trabajo del nodo, luego elige el tipo de artefacto y después mide tu restauración con la tabla de resultados anterior. Si estás comparando el autoalojamiento con un endpoint gestionado, empieza por la página de redes de Sui, revisa Precios de RPC y el servicio de API, y explora el centro de aprendizaje de OnFinality para guías operativas adyacentes. Para nodos que sirven datos históricos, el artículo Nodos de archivo de Sui y RPC histórico y el artículo Nodo de archivo de Base y RPC histórico muestran cómo la misma lógica de retención se aplica en otra cadena.

• Publica el nivel, el nombre del bucket, el rango de épocas y la retención de tus instantáneas.
• Elige el tipo de artefacto según las consultas que el nodo debe responder.
• Mide y publica tus propios números de restauración con el método adjunto.