Ejecutar un nodo completo de Sui: configuración y verificación del endpoint RPC

El rol del nodo completo de Sui en la arquitectura de la red

Sui separa las autoridades de consenso (validadores) de los nodos completos. Los validadores participan en el consenso y ejecutan transacciones, pero generalmente no sirven tráfico RPC público. Los nodos completos replican el libro mayor, ejecutan e indexan transacciones y sirven API de lectura a los clientes. Esta separación es la razón por la que un operador que desea servir RPC debería ejecutar un nodo completo en lugar de intentar exponer un validador.

Un nodo completo puede servir la API JSON-RPC directamente. Cuando se configura como indexador, también puede respaldar superficies de consulta más ricas que requieren trabajo de indexación adicional. La guía del nodo completo de Sui documenta el flujo de trabajo del operador para ejecutar un nodo y configurar sus interfaces; considere esa guía como la referencia autorizada para su versión de Sui.

Para obtener contexto a nivel de red y endpoints disponibles, consulte la página de la red Sui. Si prefiere no operar infraestructura, un nodo RPC de Sui gestionado elimina la carga operativa, pero las técnicas de verificación a continuación siguen aplicándose a cualquier endpoint que consuma.

• Validadores: consenso y ejecución; no son proveedores de RPC público.
• Nodos completos: replican el libro mayor, ejecutan e indexan, sirven API de lectura.
• Modo indexador: opcional, habilita superficies de consulta más ricas.
• Exposición de RPC público: una preocupación del nodo completo, no del validador.

Dos decisiones al exponer la interfaz RPC

La primera decisión es qué interfaces habilitar. La interfaz HTTP JSON-RPC es la superficie principal para llamadas de lectura. Opcionalmente, se puede habilitar una interfaz WebSocket o de streaming para suscripciones y flujos de eventos. Habilitar solo lo que necesita reduce la superficie de ataque y el consumo de recursos.

La segunda decisión es a qué enlazar esas interfaces. Enlazar a localhost es la opción predeterminada segura para un nodo privado detrás de un proxy inverso. Enlazar a una dirección enrutable solo es apropiado cuando hay un firewall y terminación TLS implementados. Exponer la interfaz RPC directamente a internet sin proxy ni TLS no es seguro y es una causa común de compromiso del nodo.

Estas decisiones son independientes: puede habilitar HTTP JSON-RPC en localhost mientras deja WebSocket deshabilitado, o habilitar ambos detrás de un proxy. Documente la superficie elegida para que los pasos de verificación coincidan con su configuración.

• Habilite HTTP JSON-RPC para llamadas de lectura estándar.
• Habilite WebSocket/streaming solo si necesita suscripciones.
• Enlace a localhost para nodos privados detrás de un proxy.
• Enlace a una dirección enrutable solo con firewall y TLS implementados.

Superficie de configuración documentada y deriva entre versiones

El archivo de configuración del nodo contiene secciones para JSON-RPC y métricas, junto con la ruta de la base de datos y la selección de génesis/red. Los nombres exactos de los campos y los valores predeterminados cambian entre versiones de Sui. Un tutorial antiguo puede hacer referencia a campos que ya no existen o que se han movido. El operador debe reconciliar con la guía actual del nodo completo de Sui en lugar de copiar una configuración obsoleta.

La selección de génesis y red determina qué cadena sigue el nodo. Un nodo de mainnet debe usar el génesis de mainnet; un nodo de testnet usa el génesis de testnet. Mezclar estos produce un nodo que sirve la red incorrecta, por lo que la verificación de la identidad de la cadena es obligatoria antes de servir tráfico.

La ruta de la base de datos determina el uso de disco y las características de E/S. La sincronización completa desde el génesis puede consumir un disco y un tiempo significativos. Planifique la capacidad en consecuencia y supervise el crecimiento del disco durante la sincronización inicial.

• Archivo de configuración: sección JSON-RPC, sección de métricas, ruta de base de datos, génesis/red.
• Los nombres de los campos y los valores predeterminados varían según la versión de Sui; verifique con la documentación actual.
• La selección de génesis determina la identidad de mainnet vs testnet.
• La ruta de la base de datos afecta el uso de disco y la E/S; planifique el crecimiento de la sincronización completa.

Modos de sincronización y planificación de disco para un nodo completo de Sui

Los nodos completos de Sui admiten diferentes modos de sincronización que intercambian el tiempo hasta el primer checkpoint útil por la huella de disco y la E/S. Una sincronización completa desde el génesis reproduce todo el historial del libro mayor y, por lo tanto, requiere el mayor disco y la ventana de puesta al día inicial más larga. Los operadores que necesitan un nodo que sirva datos actuales rápidamente pueden considerar una sincronización basada en snapshot o en checkpoints si su versión de Sui lo admite, pero los nombres exactos de los modos y su disponibilidad cambian entre versiones y deben confirmarse con la guía actual del nodo completo de Sui.

La planificación del disco no se trata solo del tamaño final del libro mayor. Durante la sincronización, el nodo escribe checkpoints, efectos de transacciones y datos de índice, y puede retener temporalmente más datos que la huella en estado estacionario. Aprovisione margen por encima del tamaño final esperado para que la compactación, la indexación y el crecimiento futuro del libro mayor no agoten el volumen. Supervise el uso del disco continuamente durante la sincronización inicial, porque un disco lleno puede detener el nodo y producir el mismo síntoma de checkpoint obsoleto que un problema de red.

Las características de E/S importan tanto como la capacidad bruta. Un nodo que se está sincronizando y sirviendo RPC al mismo tiempo compite por el rendimiento del disco, lo que puede ralentizar tanto la sincronización como la latencia de las consultas. Si planea servir tráfico de producción, dimensione el almacenamiento para la carga de lectura esperada además de la carga de sincronización, y evite compartir el volumen con procesos no relacionados de alta E/S.

La ruta de la base de datos en el archivo de configuración determina dónde residen estos datos. Manténgala en un volumen dedicado cuando sea posible y documente la ruta para que los pasos de verificación y monitoreo puedan hacer referencia a la ubicación correcta. Debido a que los nombres de los campos y los valores predeterminados cambian entre versiones, vuelva a verificar la configuración relacionada con la base de datos y la sincronización después de cada actualización en lugar de asumir que su configuración anterior sigue siendo válida.

• Sincronización completa desde el génesis: disco máximo y puesta al día más larga.
• Sincronización basada en snapshot o checkpoints: más rápida para servir datos actuales, si su versión lo admite.
• Aprovisione margen por encima del tamaño final esperado del libro mayor para compactación y crecimiento.
• Supervise el uso del disco durante la sincronización inicial; un disco lleno puede detener el nodo.
• Separe la E/S de sincronización de la E/S de consultas al servir tráfico de producción.
• Mantenga la ruta de la base de datos en un volumen dedicado y vuelva a verificar la configuración después de las actualizaciones.

Verificación del estado del nodo y la identidad de red

Antes de poner un nodo frente al tráfico, verifique que esté sano y sirviendo la red correcta. Llame a sui_getLatestCheckpointSequenceNumber para confirmar que el nodo está produciendo checkpoints, y llame a sui_getChainIdentifier para confirmar la identidad de la red. Las referencias JSON-RPC de Sui documentan estos métodos y sus tipos de retorno.

Confirme que el número de checkpoint avanza con el tiempo. Un nodo que aún se está poniendo al día devolverá checkpoints obsoletos; un nodo que está atascado no avanzará en absoluto. Contraste el identificador de cadena con el identificador oficial de mainnet de Sui para no servir datos de testnet en un endpoint de mainnet.

Estas comprobaciones son económicas y deben formar parte de su puerta de despliegue. Si alguna de las comprobaciones falla, no enrute tráfico al nodo.

• sui_getLatestCheckpointSequenceNumber: confirma la producción de checkpoints.
• sui_getChainIdentifier: confirma la identidad de la red.
• El checkpoint debe avanzar en llamadas sucesivas.
• El identificador de cadena debe coincidir con el valor oficial de su red objetivo.

Secuencia de sonda ejecutable con curl

El sobre JSON-RPC 2.0 está definido por la especificación JSON-RPC 2.0. Una sonda es una solicitud POST con un cuerpo JSON que contiene jsonrpc, method, params e id. La siguiente secuencia parte de un nodo que ya ha lanzado con la superficie de interfaz elegida y luego lo sondea con curl.

Reemplace la URL con la dirección y el puerto enlazados de su nodo. Si enlazó a localhost, use http://127.0.0.1:<port>. Si enlazó detrás de un proxy, use la URL del proxy. Las respuestas confirman que el nodo es accesible y sirve los métodos esperados.

# Probe 1: latest checkpoint sequence number
curl -s -X POST http://127.0.0.1:9000 \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"sui_getLatestCheckpointSequenceNumber","params":[]}'

# Probe 2: total transaction blocks
curl -s -X POST http://127.0.0.1:9000 \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"sui_getTotalTransactionBlocks","params":[]}'

# Probe 3: chain identifier
curl -s -X POST http://127.0.0.1:9000 \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":3,"method":"sui_getChainIdentifier","params":[]}'

Sondeador Node.js para la tasa de crecimiento de checkpoints

Una sola lectura de checkpoint no es suficiente; necesita saber si la altura del checkpoint está avanzando. El siguiente fragmento de Node.js sondea sui_getLatestCheckpointSequenceNumber a un intervalo fijo e imprime la tasa de crecimiento. Ejecútelo contra la URL RPC de su nodo.

El script utiliza la API fetch integrada disponible en Node.js moderno. Ajuste el intervalo y la duración según sus necesidades de monitoreo. Una tasa de crecimiento cercana a cero durante una ventana sostenida indica un nodo atascado o que aún se está sincronizando.

const RPC_URL = process.env.SUI_RPC_URL || 'http://127.0.0.1:9000';
const INTERVAL_MS = 5000;
const DURATION_MS = 60000;

async function getCheckpoint() {
  const res = await fetch(RPC_URL, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      jsonrpc: '2.0',
      id: 1,
      method: 'sui_getLatestCheckpointSequenceNumber',
      params: []
    })
  });
  const json = await res.json();
  if (json.error) throw new Error(JSON.stringify(json.error));
  return Number(json.result);
}

(async () => {
  const start = Date.now();
  let first = await getCheckpoint();
  let last = first;
  console.log(`start checkpoint: ${first}`);
  while (Date.now() - start < DURATION_MS) {
    await new Promise(r => setTimeout(r, INTERVAL_MS));
    last = await getCheckpoint();
    const elapsed = (Date.now() - start) / 1000;
    const rate = (last - first) / elapsed;
    console.log(`checkpoint: ${last} | elapsed: ${elapsed.toFixed(1)}s | rate: ${rate.toFixed(2)} cp/s`);
  }
  console.log(`final checkpoint: ${last}`);
})();

Tabla de resultados para una verificación reproducible

Registre sus resultados de verificación en una tabla para poder comparar entre nodos, versiones y tiempo. La siguiente tabla es una plantilla; complétela con sus propias mediciones. No confíe en los números de este artículo, ya que no son valores medidos.

Use la misma secuencia de sonda para cada fila para que las comparaciones sean significativas. Si cambia la versión de Sui o la superficie de interfaz, agregue una nueva fila en lugar de sobrescribir la anterior.

• Versión de Sui: la versión que está ejecutando.
• Interfaces habilitadas: HTTP JSON-RPC, WebSocket o ambas.
• Dirección enlazada: localhost o dirección enrutable y puerto.
• ¿Expuesto públicamente?: sí/no, y si hay un proxy y TLS implementados.
• Identificador de cadena: el valor devuelto por sui_getChainIdentifier.
• ¿Checkpoint avanzando?: sí/no, según sondas repetidas.
• Retraso de sincronización: diferencia entre su checkpoint y la punta de la red, si se conoce.

Limitaciones y compensaciones operativas

La sincronización completa desde el génesis puede llevar mucho tiempo y un disco significativo. Un nodo que aún se está poniendo al día devolverá checkpoints obsoletos, lo que puede engañar a los clientes si enruta tráfico demasiado pronto. El retraso de checkpoints es una condición normal en estado estacionario que debe monitorearse en lugar de asumirse cero.

Exponer la interfaz RPC sin proxy ni TLS no es seguro. Incluso con un proxy, la limitación de velocidad y la autenticación son su responsabilidad. Un nodo autooperado rara vez iguala a un proveedor gestionado en disponibilidad o distribución geográfica. Si su aplicación necesita lecturas globales de baja latencia, un endpoint gestionado puede ser más apropiado; consulte Precios de RPC y el Servicio de API para conocer las opciones.

Para temas operativos más profundos, consulte Latencia de RPC de Sui, Límites de velocidad y unidades de cómputo de RPC de Sui, Flujo de checkpoints y servicio de libro mayor de Sui y Nodos de archivo y RPC histórico de Sui.

• Sincronización completa: larga duración y uso significativo de disco.
• Checkpoints obsoletos: esperado durante la puesta al día; no sirva tráfico antes de tiempo.
• Retraso de checkpoints: estado estacionario normal; supervise en lugar de asumir cero.
• Riesgo de exposición: el proxy y TLS son obligatorios para endpoints públicos.
• Disponibilidad: los nodos autooperados rara vez igualan la distribución de un proveedor gestionado.

Solución de problemas comunes de verificación

Si curl devuelve un error de conexión rechazada, el nodo no está escuchando en la dirección y el puerto que sondeó. Confirme la dirección de enlace en su configuración y que el proceso del nodo se está ejecutando. Si enlazó a localhost, asegúrese de estar sondeando desde el mismo host.

Si la respuesta JSON-RPC contiene un objeto de error, lea el código y el mensaje de error. Un error de método no encontrado puede indicar que la interfaz está deshabilitada o que el nombre del método cambió en su versión de Sui. Reconcilie con las referencias JSON-RPC de Sui.

Si el número de checkpoint no avanza, el nodo puede estar sincronizándose, atascado o desconectado de sus pares. Revise los registros y las métricas del nodo. Si el identificador de cadena no coincide con su red objetivo, está ejecutando el génesis incorrecto; deténgase y reconfigúrelo antes de servir tráfico.

• Conexión rechazada: verifique la dirección de enlace, el puerto y el estado del proceso.
• Método no encontrado: verifique que la interfaz esté habilitada y el nombre del método para su versión.
• Checkpoint sin avanzar: verifique el estado de sincronización, los registros y la conectividad con pares.
• Identificador de cadena no coincidente: génesis incorrecto; reconfigúrelo antes de servir.

Próximos pasos para la preparación de producción

Una vez que la verificación pase, coloque el nodo detrás de un proxy inverso con TLS y limitación de velocidad. Agregue monitoreo para la altura del checkpoint, el retraso de sincronización y el uso de recursos. Alerte sobre checkpoints atascados y presión de disco.

Si necesita datos históricos más allá de la retención de su nodo, considere un nodo de archivo o un servicio gestionado. Revise el centro de aprendizaje de OnFinality para guías operativas relacionadas, y compare las opciones gestionadas en la página de la red Sui y Precios de RPC.

Mantenga su versión de Sui actualizada y vuelva a ejecutar la secuencia de verificación después de cada actualización, ya que los campos de configuración y los valores predeterminados pueden cambiar entre versiones.

• Despliegue detrás de un proxy inverso con TLS y limitación de velocidad.
• Monitoree la altura del checkpoint, el retraso de sincronización y el uso de recursos.
• Alerte sobre checkpoints atascados y presión de disco.
• Vuelva a ejecutar la verificación después de cada actualización de Sui.