Última actualización: 11 de septiembre

Exportar archivos a MinIO: una guía completa de cURL

Tim Koschützki

Cofundador · Berlín, Alemania ·

Exportar archivos a MinIO con cURL ofrece una forma flexible y potente de gestionar las operaciones de almacenamiento de objetos desde la línea de comandos. MinIO es un sistema de almacenamiento de objetos de alto rendimiento y compatible con S3 que permite una gestión de archivos y unas soluciones de almacenamiento eficientes. Esta guía muestra cómo usar cURL con MinIO de forma eficaz, y cubre la instalación, la autenticación y las técnicas de automatización.

Introducción a MinIO y su propósito

MinIO es un sistema de almacenamiento de objetos de código abierto que ofrece alto rendimiento y compatibilidad con S3. Está diseñado para infraestructuras de datos a gran escala y aplicaciones nativas de la nube. MinIO admite funciones como el cifrado, la gestión de identidades y la replicación multisitio, lo que lo hace adecuado para despliegues empresariales.

Descripción general de cURL para transferencias de archivos

cURL es una herramienta de línea de comandos versátil para transferir datos mediante varios protocolos. Admite HTTP, HTTPS y FTP; la API compatible con S3 de MinIO usa HTTP o HTTPS. Sus amplias funciones y su gran compatibilidad con distintas plataformas lo convierten en una opción fiable para las operaciones con archivos.

Configurar tu entorno: MinIO y cURL

Requisitos previos

Usa un despliegue de MinIO en ejecución y un bucket existente. Instala el MinIO Client como mc en tu PATH, curl y Node.js 22 o posterior. En el directorio de tu script, instala el SDK de Node.js:

npm install minio@8

Configuración inicial

Define MINIO_ENDPOINT, MINIO_ACCESS_KEY y MINIO_SECRET_KEY en tu entorno y luego configura el cliente. Usa credenciales restringidas al bucket y a las operaciones necesarias. Un endpoint como http://localhost:9000 solo es adecuado para el desarrollo local; usa HTTPS para las conexiones remotas.

mc alias set myminio "$MINIO_ENDPOINT" "$MINIO_ACCESS_KEY" "$MINIO_SECRET_KEY"

Proteger el acceso a tu bucket de MinIO

Implementa estas medidas de seguridad para realizar operaciones con archivos de forma segura:

Habilita TLS/SSL para tener conexiones cifradas.
Usa variables de entorno para las credenciales.
Implementa políticas de bucket adecuadas.
Usa URL prefirmadas para el acceso temporal.

Exportar archivos a MinIO con cURL

Métodos de autenticación

MinIO admite tres enfoques principales de autenticación:

MinIO Client (mc) para operaciones directas
URL prefirmadas para acceso temporal
SDK oficiales para acceso programático

Generar URL prefirmadas

mc share upload genera un comando de subida con política POST, no una URL para una solicitud PUT. No extraigas su URL ni la reutilices con curl --upload-file. Para un PUT prefirmado, usa presignedPutObject del SDK. Guarda este script de CommonJS como presign.cjs:

const Minio = require('minio')

async function main() {
  const [bucket, objectName] = process.argv.slice(2)
  const { MINIO_ENDPOINT, MINIO_ACCESS_KEY, MINIO_SECRET_KEY } = process.env
  if (!bucket || !objectName || !MINIO_ENDPOINT || !MINIO_ACCESS_KEY || !MINIO_SECRET_KEY) {
    throw new Error('Provide a bucket, object name, endpoint, and credentials')
  }
  const endpoint = new URL(MINIO_ENDPOINT)
  if (!['http:', 'https:'].includes(endpoint.protocol)) {
    throw new Error('The endpoint must use HTTP or HTTPS')
  }
  const client = new Minio.Client({
    endPoint: endpoint.hostname,
    port: Number(endpoint.port || (endpoint.protocol === 'https:' ? 443 : 80)),
    useSSL: endpoint.protocol === 'https:',
    accessKey: MINIO_ACCESS_KEY,
    secretKey: MINIO_SECRET_KEY,
  })
  console.log(await client.presignedPutObject(bucket, objectName, 7200))
}

main().catch(() => {
  console.error('Unable to generate an upload URL; check configuration and bucket access')
  process.exitCode = 1
})

La URL es una credencial de portador válida durante dos horas. No la publiques ni la incluyas en los registros. Ejecuta este script en una máquina de confianza; nunca distribuyas la clave de acceso ni la clave secreta a clientes de navegador.

Ejemplo de automatización

#!/bin/bash
set -euo pipefail

BUCKET="mybucket"

upload_file() {
    local file_path="$1"
    local file_name
    local presigned_url
    file_name=$(basename "$file_path")

    echo "Generating pre-signed URL for ${file_name}..."
    presigned_url=$(node presign.cjs "$BUCKET" "$file_name") || return 1

    echo "Uploading ${file_name}..."
    if curl -X PUT \
        --upload-file "${file_path}" \
        --fail-with-body \
        --silent \
        --show-error \
        "${presigned_url}"; then
        echo "Uploaded ${file_name}"
        return 0
    else
        echo "Failed to upload ${file_name}" >&2
        return 1
    fi
}

upload_file "${1:?Usage: bash upload.sh /path/to/file}"

Técnicas avanzadas: manejo de estructuras de archivos complejas

Subidas de archivos grandes

Para archivos grandes, prefiere mc cp, que gestiona las subidas multiparte automáticamente en lugar de enviar un único PUT prefirmado. El tamaño de objeto admitido depende de la configuración del servidor:

mc cp large-file.zip myminio/mybucket/large-file.zip

Sincronización de directorios

Mantén sincronizados los directorios locales y los de MinIO:

mc mirror local/directory myminio/mybucket/

Problemas comunes y soluciones

Conexión rechazada:
- Verifica que el servidor de MinIO esté en ejecución.
- Revisa la configuración del firewall.
- Confirma que se usen el endpoint y el puerto correctos.
Acceso denegado:
- Verifica las credenciales.
- Revisa la política del bucket.
- Asegúrate de que los permisos estén configurados correctamente.
Errores de SSL/TLS:
- Usa el protocolo correcto (http o https).
- Verifica el certificado si usas SSL.
- Configura correctamente la opción useSSL en el SDK.

Monitoreo y registro

Haz un seguimiento del progreso de la subida y registra solo el estado HTTP. Este ejemplo de Bash conserva el fallo a lo largo del pipeline de registro:

set -euo pipefail
presigned_url=$(node presign.cjs mybucket large-file.zip)
curl --fail-with-body \
  --upload-file "large-file.zip" \
  --progress-bar \
  --write-out "%{http_code}\n" \
  --output /dev/null \
  "${presigned_url}" | tee -a upload.log

Usar Transloadit para exportaciones optimizadas a MinIO

Para el procesamiento avanzado de archivos y las exportaciones a MinIO, considera usar Transloadit. Transloadit ofrece sólidas capacidades de procesamiento de archivos e integración fluida con diversas soluciones de almacenamiento, incluida MinIO.

Conclusión

Esta guía cubrió los aspectos esenciales del uso de cURL con MinIO para exportar archivos: desde la instalación y el acceso seguro hasta la automatización y el manejo de estructuras de archivos complejas. Los scripts y ejemplos proporcionados demuestran operaciones con archivos seguras y eficientes. Si tienes necesidades de procesamiento de archivos más sofisticadas, explora las soluciones integrales de manejo de archivos de Transloadit en transloadit.com.