Los proyectos de Node-RED convierten tus flujos en un repositorio git, de modo que cada cambio queda registrado en un commit, se puede revisar y se puede revertir. En este tutorial activarás el modo proyectos, crearás un proyecto, harás commit y push a un remoto, lo clonarás en otra máquina y, sobre todo, mantendrás las credenciales de tu broker MQTT cifradas y fuera del repositorio.
Por qué versionar tus flujos
Sin proyectos, Node-RED guarda todo en un único archivo flows.json dentro del directorio de usuario. Cuando alguien despliega un cambio defectuoso, no hay historial que consultar ni una forma fácil de volver atrás. Las copias de los flujos viajan por correo o por chat como JSON exportado, y nadie sabe con certeza qué versión se ejecuta en producción.
Los proyectos lo solucionan con herramientas que los desarrolladores ya conocen:
- Historial. Cada commit registra quién cambió qué y cuándo.
- Diffs. El editor muestra las diferencias a nivel de nodo antes de hacer commit.
- Ramas. Prueba un cambio arriesgado en una rama y fusiónalo cuando funcione.
- Remotos. Haz push a GitHub, GitLab, Gitea o Azure DevOps para tener copia de seguridad y colaborar.
- Dependencias. Cada proyecto tiene un
package.jsoncon los nodos que necesita, así que una máquina nueva sabe qué instalar.
Requisitos previos
Los proyectos dependen de la línea de comandos de git y, para los remotos SSH, de ssh-keygen. Comprueba que ambos están instalados en la máquina que ejecuta Node-RED:
git --version
ssh-keygen -h 2>&1 | head -1
En Debian, Ubuntu o Raspberry Pi OS, instala git con sudo apt install git. La imagen oficial de Docker ya incluye git.
Activa los proyectos de Node-RED
El modo proyectos está desactivado por defecto. Abre settings.js en tu directorio de usuario (~/.node-red/settings.js, o /data/settings.js en Docker), busca la sección editorTheme y actívalo:
editorTheme: {
projects: {
enabled: true,
workflow: {
// "manual": haces commit explícitamente
// "auto": Node-RED hace commit en cada despliegue
mode: "manual"
}
}
},
Reinicia Node-RED. La primera vez que abras el editor, una pantalla de bienvenida te ofrecerá crear un proyecto, clonar un repositorio u omitir el paso. El modo manual es la mejor opción predeterminada para equipos: despliegas tantas veces como quieras mientras pruebas y solo haces commit cuando un cambio está listo, con un mensaje significativo.
Crea tu primer proyecto
- Elige Create Project en la pantalla de bienvenida, o más adelante mediante Projects → New en el menú principal.
- Introduce tu nombre de usuario y correo de git si se te piden; aparecen en el historial de commits.
- Da un nombre al proyecto, por ejemplo
plant-telemetry. - Elige un nombre para el archivo de flujo. El predeterminado,
flow.json, está bien. - Configura el cifrado de credenciales. Elige "Enable encryption" e introduce una clave robusta. Guárdala en tu gestor de contraseñas.
- Haz clic en Create Project.
Node-RED crea una carpeta en projects/ dentro del directorio de usuario con esta estructura:
~/.node-red/projects/plant-telemetry/
.git/
.gitignore
README.md
package.json
flow.json
flow_cred.json
El archivo de credenciales se cifra con la clave del paso 5, y esa clave se guarda en la configuración local de ejecución de Node-RED, no en el repositorio. Ese es el diseño que mantiene las contraseñas del broker fuera de git: el repositorio solo contiene texto cifrado, y solo las máquinas a las que des la clave pueden descifrarlo.
Crea un flujo y haz commit
Añade un flujo MQTT sencillo para tener algo que versionar. Configura un nodo broker para el servidor MQTT público gratuito con el host broker.connectmq.com, el puerto 1883 y un client ID único como nr-proj-a19e. Suscribe un nodo mqtt in a connectmq/demo/a19e/# y conéctalo a un nodo debug. Despliega.
Abre la pestaña Project history de la barra lateral (el icono de git). En Local Changes verás el archivo de flujo marcado como modificado. Haz clic en él para ver un diff visual de los nodos que añadiste. Prepara el archivo (stage), escribe un mensaje de commit como "Add telemetry subscriber" y haz commit.
Ahora haz un cambio, por ejemplo renombrar el nodo debug, y vuelve a desplegar. La pestaña de historial muestra un nuevo diff exactamente de ese cambio. Aquí es donde los proyectos de Node-RED compensan: en una revisión ves que cambió una propiedad en lugar de un bloque de JSON ilegible.
Haz push a un repositorio remoto
Crea un repositorio vacío en tu servidor git. En Node-RED, abre Projects → Project Settings → Settings → Git remotes y añade la URL del remoto.
Para remotos SSH, genera una clave dentro de Node-RED mediante User Settings → Git config → SSH Keys → Add key. Node-RED muestra la clave pública; añádela a tu servidor git como deploy key con permiso de escritura. Los remotos HTTPS con un token de acceso personal también funcionan, y Node-RED te pedirá las credenciales en el primer push.
De vuelta en la pestaña de historial, la sección Commit History muestra ahora flechas de push y pull. Haz push de tus commits. Desde la terminal, puedes verificar el contenido del repositorio:
git clone git@github.com:your-org/plant-telemetry.git
cd plant-telemetry
cat flow_cred.json # muestra texto cifrado como {"$":"8f2c..."}
Mantén las credenciales del broker fuera de git
Las credenciales necesitan una estrategia deliberada. Tienes tres opciones razonables:
| Estrategia | Qué va a git | Gestión de la clave | Adecuada para |
|---|---|---|---|
| Archivo de credenciales cifrado (predeterminado) | flow_cred.json como texto cifrado |
La clave se introduce una vez por máquina | La mayoría de los equipos |
| Ignorar el archivo de credenciales | Nada | Las credenciales se escriben en cada instancia | Políticas estrictas contra cualquier secreto en git |
| Variables de entorno | Solo referencias ${VAR} en campos no secretos; los secretos, en el entorno |
Se definen por entorno | Contenedores y pipelines de CI |
Para la segunda opción, añade flow_cred.json a .gitignore y vuelve a introducir el usuario y la contraseña MQTT en cada instancia tras clonar. Para la tercera, define valores como el host del broker o el prefijo del client ID como variables de entorno y léelos en las propiedades de los nodos con ${MQTT_HOST} o en los nodos function con env.get().
Elijas la que elijas, sigue dos reglas. Nunca pegues una contraseña en un nodo function ni en un nodo inject, porque se guardan en texto plano en el archivo de flujo. Y usa credenciales de broker distintas por entorno, para que una instancia de desarrollo nunca pueda publicar en topics de producción; con ConnectMQ puede ser tan sencillo como tener un broker independiente para cada entorno. Nuestra lista para asegurar Node-RED cubre el resto de pasos de bastionado.
Clona un proyecto en otra máquina
En una segunda instancia de Node-RED con los proyectos activados, elige Projects → New → Clone Repository, introduce la URL del remoto y, si el archivo de credenciales está cifrado, la clave de credenciales. Node-RED clona el repositorio, lee package.json y te indica qué nodos faltan. Instálalos desde el aviso o con npm en la carpeta del proyecto y despliega.
Con Docker, clona en la carpeta montada /data/projects para que el proyecto sobreviva a la recreación del contenedor; consulta nuestra guía de Node-RED en Docker para la configuración del volumen.
Lista del flujo de trabajo con proyectos de Node-RED
- Activa los proyectos en modo manual y reinicia Node-RED.
- Crea un proyecto por cada aplicación desplegable, no uno por pestaña.
- Activa el cifrado de credenciales y guarda la clave en un gestor de contraseñas.
- Incluye todos los nodos de la comunidad en
package.jsoncon un rango de versiones. - Haz commits pequeños y descritos; revisa los diffs antes de confirmar.
- Usa ramas para los experimentos y fusiónalas cuando estén probadas.
- Haz push a un remoto tras cada commit significativo.
- Mantén los valores específicos de cada entorno en variables de entorno, no en el flujo.
- Usa credenciales MQTT distintas para los brokers de desarrollo y de producción.
La lógica reutilizable es más fácil de versionar cuando vive en subflujos de Node-RED, porque un cambio en una plantilla aparece como un único diff claro. La documentación oficial de proyectos cubre los ajustes avanzados y toda la interfaz del editor. Si estás empezando con MQTT en Node-RED, comienza por el tutorial de Node-RED MQTT.
Versiona tus flujos y deja el broker en manos de ConnectMQ
Los proyectos dan a tus flujos historial y despliegues repetibles; el broker al que se conectan debería ser igual de fiable. ConnectMQ es un broker MQTT gestionado con MQTT 3.1.1 y 5.0, TLS en el 8883 y credenciales por broker, así que es sencillo crear brokers separados para desarrollo y producción y mantener aisladas las credenciales de cada entorno. Empieza con el plan Serverless gratuito en app.connectmq.com, sin tarjeta de crédito. Para comparar enfoques de alojamiento, consulta nuestra visión general sobre cómo ejecutar un broker MQTT en la nube.
Preguntas frecuentes
¿Cómo activo los proyectos en Node-RED?
Define editorTheme.projects.enabled como true en settings.js, asegúrate de que git está instalado y reinicia Node-RED. El editor te ofrecerá entonces crear o clonar un proyecto.
¿Se guardan las contraseñas MQTT en git con los proyectos de Node-RED?
Solo de forma cifrada, si activas el cifrado de credenciales. El archivo de credenciales contiene texto cifrado y la clave se queda en cada máquina. También puedes añadir el archivo de credenciales a .gitignore.
¿Puedo usar GitHub con los proyectos de Node-RED?
Sí. Añade el repositorio como remoto mediante SSH con una clave generada en Node-RED o mediante HTTPS con un token, y haz push y pull desde la barra lateral Project history.
¿Cuál es la diferencia entre el modo de trabajo manual y el automático?
En modo manual haces commit explícitamente cuando un cambio está listo. En modo automático, Node-RED crea un commit cada vez que despliegas, lo que es más sencillo pero genera un historial más ruidoso.
