Exportar archivos a SFTP en Node.js con ssh2-sftp-client

Kevin van Zonneveld

Cofundador · Ámsterdam, Países Bajos · Mostrar bio

Las transferencias seguras de archivos son cruciales para proteger datos sensibles. SFTP (Secure File Transfer Protocol) es un método confiable para transferir archivos de forma segura a través de una red. En este DevTip, exploraremos cómo usar Node.js y la biblioteca de código abierto ssh2-sftp-client para gestionar de forma eficiente las transferencias de archivos hacia y desde un servidor SFTP. ssh2-sftp-client es un envoltorio práctico basado en promesas de la potente biblioteca ssh2, lo que simplifica las operaciones SFTP.

Introducción a SFTP

SFTP es un protocolo seguro construido sobre SSH (Secure Shell) que ofrece transferencias de archivos cifradas. Garantiza la integridad y la confidencialidad de los datos, lo que lo hace ideal para transferir información sensible.

Configurar tu entorno de Node.js

Este ejemplo usa ssh2-sftp-client 12.x con Node.js 22 o superior. Puedes verificar tu instalación ejecutando:

node -v
npm -v

Instalar y configurar ssh2-sftp-client

Instala la biblioteca ssh2-sftp-client con npm:

npm install ssh2-sftp-client@12

Conectar, subir, descargar y gestionar errores

Así puedes establecer una conexión, subir un archivo, descargar un archivo y gestionar errores de forma robusta. Define SFTP_HOST, SFTP_USERNAME, SFTP_PASSWORD y SFTP_HOST_SHA256 a través de tu entorno. Obtén la huella de la clave de host del servidor de manos de su administrador a través de un canal confiable. SFTP_HOST_SHA256 debe ser el resumen hexadecimal SHA-256 de 64 caracteres en minúsculas de los bytes sin procesar de la clave pública SSH, no el formato base64 SHA256: que muestran muchas herramientas SSH. No obtengas este valor de una primera conexión sin verificar.

const Client = require('ssh2-sftp-client')
const fs = require('fs') // Required for the dummy file creation

async function main() {
  const { SFTP_HOST, SFTP_USERNAME, SFTP_PASSWORD, SFTP_HOST_SHA256 } = process.env
  if (!SFTP_HOST || !SFTP_USERNAME || !SFTP_PASSWORD || !/^[a-f0-9]{64}$/.test(SFTP_HOST_SHA256 || '')) {
    throw new Error('SFTP credentials and a verified SHA-256 host-key fingerprint are required')
  }
  const sftp = new Client()
  const config = {
    host: SFTP_HOST,
    port: 22, // Use an integer for the port
    username: SFTP_USERNAME,
    password: SFTP_PASSWORD,
    hostHash: 'sha256',
    hostVerifier: (fingerprint) => fingerprint === SFTP_HOST_SHA256,
    readyTimeout: 10000,
  }

  const localPath = './local-file.txt'
  const remotePath = '/remote/path/file.txt'
  const localDownloadPath = './downloaded-file.txt'

  // Create a dummy file for upload example if it doesn't exist
  if (!fs.existsSync(localPath)) {
    fs.writeFileSync(localPath, 'This is a test file for SFTP upload.')
    console.log(`Created dummy ${localPath} for testing.`)
  }

  try {
    await sftp.connect(config)
    console.log('Connected successfully to SFTP server.')

    // Uploading files
    console.log(`Attempting to upload ${localPath} to ${remotePath}...`)
    await sftp.put(localPath, remotePath)
    console.log('File uploaded successfully.')

    // Downloading files
    console.log(`Attempting to download ${remotePath} to ${localDownloadPath}...`)
    await sftp.get(remotePath, localDownloadPath)
    console.log('File downloaded successfully.')
  } finally {
    await sftp.end()
  }
}

main().catch(() => {
  console.error('SFTP transfer failed; check configuration, host identity, and permissions')
  process.exitCode = 1
})

En el ejemplo anterior, envolvimos nuestras operaciones SFTP dentro de una función async llamada main. Esta función se encarga de conectarse al servidor, subir un archivo y luego descargarlo. El bloque try...finally garantiza que la conexión SFTP se cierre con sftp.end(), independientemente de si las operaciones tuvieron éxito o se produjo un error. También creamos un archivo local-file.txt de prueba para que el ejemplo de subida se pueda ejecutar. Elige rutas remotas y locales de descarga que sea seguro reemplazar; estos métodos de transferencia pueden sobrescribir archivos existentes. Los fallos de transferencia producen un estado de salida distinto de cero, de modo que una tarea programada no informe éxito de forma incorrecta.

El cliente ssh2⁠ subyacente acepta claves de host de forma predeterminada si no se proporciona un verificador. El cifrado por sí solo no es autenticación del servidor; la comprobación explícita de la huella es esencial para detectar una clave de servidor inesperada.

Buenas prácticas para transferencias de archivos seguras y eficientes

• Usa siempre métodos de autenticación robustos. Para mayor seguridad, se recomienda ampliamente usar autenticación basada en claves SSH. Para ello puedes emplear la opción privateKey en la configuración de connect. Consulta la documentación de ssh2-sftp-client y ssh2 para ver ejemplos detallados.
• Actualiza con regularidad tus bibliotecas y dependencias.
• Valida las rutas de archivos y los permisos.
• Implementa registro y monitoreo de las transferencias de archivos.

Conclusión y casos de uso prácticos

Usar ssh2-sftp-client simplifica las transferencias seguras de archivos en aplicaciones de Node.js. Este enfoque es ideal para copias de seguridad automatizadas, sincronización de datos e intercambios seguros de archivos entre sistemas.

Para una solución simplificada, considera el 🤖 Robot /sftp/store de Transloadit como parte de nuestro servicio de exportación de archivos.