Os projetos do Node-RED transformam seus fluxos em um repositório git, de modo que cada alteração fica registrada em commit, pode ser revisada e pode ser revertida. Neste tutorial você vai ativar o modo de projetos, criar um projeto, fazer commit e push para um remoto, cloná-lo em outra máquina e, o mais importante, manter as credenciais do seu broker MQTT criptografadas e fora do repositório.
Por que versionar seus fluxos
Sem projetos, o Node-RED guarda tudo em um único arquivo flows.json no diretório de usuário. Quando alguém implanta uma alteração quebrada, não há histórico para consultar nem um jeito fácil de voltar. Cópias dos fluxos circulam por e-mail ou chat como JSON exportado, e ninguém tem certeza de qual versão está rodando em produção.
Os projetos resolvem isso com ferramentas que os desenvolvedores já conhecem:
- Histórico. Cada commit registra quem mudou o quê e quando.
- Diffs. O editor mostra as diferenças no nível dos nodes antes do commit.
- Branches. Teste uma mudança arriscada em uma branch e faça o merge quando funcionar.
- Remotos. Faça push para GitHub, GitLab, Gitea ou Azure DevOps para backup e colaboração.
- Dependências. Cada projeto tem um
package.jsonlistando os nodes de que precisa, para que uma máquina nova saiba o que instalar.
Pré-requisitos
Os projetos dependem da linha de comando do git e, para remotos SSH, do ssh-keygen. Verifique se ambos estão instalados na máquina que roda o Node-RED:
git --version
ssh-keygen -h 2>&1 | head -1
No Debian, Ubuntu ou Raspberry Pi OS, instale o git com sudo apt install git. A imagem Docker oficial já inclui o git.
Ative os projetos do Node-RED
O modo de projetos vem desativado por padrão. Abra o settings.js no seu diretório de usuário (~/.node-red/settings.js, ou /data/settings.js no Docker), encontre a seção editorTheme e ative-o:
editorTheme: {
projects: {
enabled: true,
workflow: {
// "manual": você faz o commit explicitamente
// "auto": o Node-RED faz commit a cada deploy
mode: "manual"
}
}
},
Reinicie o Node-RED. Na primeira vez que você abrir o editor, uma tela de boas-vindas oferece criar um projeto, clonar um repositório ou pular. O modo manual é o melhor padrão para equipes: você faz deploy quantas vezes quiser enquanto testa e só faz commit quando a alteração estiver pronta, com uma mensagem significativa.
Crie seu primeiro projeto
- Escolha Create Project na tela de boas-vindas ou, depois, em Projects → New no menu principal.
- Informe seu nome de usuário e e-mail do git, se solicitado; eles aparecem no histórico de commits.
- Dê um nome ao projeto, por exemplo
plant-telemetry. - Escolha um nome para o arquivo de fluxo. O padrão
flow.jsonserve. - Configure a criptografia das credenciais. Escolha "Enable encryption" e informe uma chave forte. Guarde-a no seu gerenciador de senhas.
- Clique em Create Project.
O Node-RED cria uma pasta em projects/ no diretório de usuário com esta estrutura:
~/.node-red/projects/plant-telemetry/
.git/
.gitignore
README.md
package.json
flow.json
flow_cred.json
O arquivo de credenciais é criptografado com a chave do passo 5, e essa chave fica nas configurações locais do runtime do Node-RED, não no repositório. É esse o design que mantém as senhas do broker fora do git: o repositório contém apenas texto cifrado, e só as máquinas a que você entregar a chave conseguem descriptografá-lo.
Monte um fluxo e faça o commit
Adicione um fluxo MQTT simples para ter algo a versionar. Configure um node de broker para o servidor MQTT público gratuito (apenas para testes) com o servidor broker.connectmq.com, a porta 1883 e um client ID exclusivo, como nr-proj-a19e. Faça um node mqtt in assinar connectmq/demo/a19e/# e ligue-o a um node de debug. Faça o deploy.
Abra a aba Project history na barra lateral (o ícone do git). Em Local Changes, você verá o arquivo de fluxo listado como modificado. Clique nele para ver um diff visual dos nodes que você adicionou. Coloque o arquivo em stage, escreva uma mensagem de commit como "Add telemetry subscriber" e faça o commit.
Agora faça uma alteração, talvez renomeando o node de debug, e faça o deploy de novo. A aba de histórico mostra um diff novo exatamente dessa alteração. É aqui que os projetos do Node-RED se pagam: em uma revisão, você vê que uma propriedade mudou, em vez de um bloco de JSON ilegível.
Faça push para um repositório remoto
Crie um repositório vazio no seu host git. No Node-RED, abra Projects → Project Settings → Settings → Git remotes e adicione a URL do remoto.
Para remotos SSH, gere uma chave dentro do Node-RED em User Settings → Git config → SSH Keys → Add key. O Node-RED mostra a chave pública; adicione-a ao seu host git como deploy key com permissão de escrita. Remotos HTTPS com um token de acesso pessoal também funcionam, e o Node-RED vai pedir as credenciais no primeiro push.
De volta à aba de histórico, a seção Commit History agora mostra setas de push e pull. Faça o push dos seus commits. No terminal, você pode verificar o conteúdo do repositório:
git clone git@github.com:your-org/plant-telemetry.git
cd plant-telemetry
cat flow_cred.json # imprime texto cifrado, como {"$":"8f2c..."}
Mantenha as credenciais do broker fora do git
As credenciais exigem uma estratégia deliberada. Você tem três opções razoáveis:
| Estratégia | O que vai para o git | Gestão da chave | Bom para |
|---|---|---|---|
| Arquivo de credenciais criptografado (padrão) | flow_cred.json como texto cifrado |
Chave informada uma vez por máquina | A maioria das equipes |
| Ignorar o arquivo de credenciais | Nada | Credenciais digitadas em cada instância | Políticas rígidas contra qualquer segredo no git |
| Variáveis de ambiente | Apenas referências ${VAR} em campos não secretos, segredos no ambiente |
Definidas por ambiente | Contêineres e pipelines de CI |
Para a segunda opção, adicione flow_cred.json ao .gitignore e informe de novo o username e a senha MQTT em cada instância depois de clonar. Para a terceira, defina valores como o host do broker ou o prefixo do client ID como variáveis de ambiente e leia-os nas propriedades dos nodes com ${MQTT_HOST} ou em function nodes com env.get().
Seja qual for a escolha, siga duas regras. Nunca cole uma senha em um function node ou em um node inject, porque eles são guardados em texto puro no arquivo de fluxo. E use credenciais de broker separadas por ambiente, para que uma instância de desenvolvimento nunca consiga publicar em topics de produção; com o ConnectMQ, isso pode ser tão simples quanto um broker separado para cada ambiente. Nosso checklist para proteger o Node-RED cobre as demais medidas de hardening.
Clone um projeto em outra máquina
Em uma segunda instância do Node-RED com projetos ativados, escolha Projects → New → Clone Repository, informe a URL do remoto e, se o arquivo de credenciais estiver criptografado, a chave das credenciais. O Node-RED clona o repositório, lê o package.json e informa quais nodes estão faltando. Instale-os pelo aviso ou com npm na pasta do projeto e faça o deploy.
Com Docker, clone na pasta montada /data/projects para que o projeto sobreviva à recriação do contêiner; veja nosso guia de Node-RED com Docker para a configuração do volume.
Checklist de fluxo de trabalho com projetos do Node-RED
- Ative os projetos no modo manual e reinicie o Node-RED.
- Crie um projeto por aplicação implantável, não um por aba.
- Ative a criptografia das credenciais e guarde a chave em um gerenciador de senhas.
- Liste cada node da comunidade no
package.jsoncom uma faixa de versão. - Faça commits pequenos e descritos; revise os diffs antes do commit.
- Use branches para experimentos e faça o merge depois de testar.
- Faça push para um remoto após cada commit relevante.
- Mantenha valores específicos de cada ambiente em variáveis de ambiente, não no fluxo.
- Use credenciais MQTT separadas para os brokers de desenvolvimento e de produção.
Lógica reutilizável fica mais fácil de versionar quando vive em subflows do Node-RED, porque uma alteração em um template aparece como um único diff claro. A documentação oficial de projetos cobre as configurações avançadas e toda a interface do editor. Se você está começando com MQTT no Node-RED, comece pelo tutorial de MQTT no Node-RED.
Versione seus fluxos e deixe o ConnectMQ cuidar do broker
Os projetos dão aos seus fluxos histórico e implantações repetíveis; o broker ao qual eles se conectam deve ser igualmente confiável. O ConnectMQ é um broker MQTT gerenciado com MQTT 3.1.1 e 5.0, TLS na 8883 e credenciais por broker, então é simples criar brokers separados para desenvolvimento e produção e manter as credenciais de cada ambiente apartadas. Comece pelo plano Serverless gratuito em app.connectmq.com, sem cartão de crédito. Para comparar abordagens de hospedagem, veja nossa visão geral sobre como rodar um broker MQTT na nuvem.
Perguntas frequentes
Como ativo os projetos no Node-RED?
Defina editorTheme.projects.enabled como true no settings.js, garanta que o git esteja instalado e reinicie o Node-RED. O editor então oferece criar ou clonar um projeto.
As senhas MQTT ficam guardadas no git com os projetos do Node-RED?
Apenas de forma criptografada, se você ativar a criptografia das credenciais. O arquivo de credenciais contém texto cifrado, e a chave fica em cada máquina. Você também pode adicionar o arquivo de credenciais ao .gitignore.
Posso usar o GitHub com os projetos do Node-RED?
Sim. Adicione o repositório como remoto usando SSH com uma chave gerada no Node-RED ou HTTPS com um token e depois faça push e pull pela barra lateral Project history.
Qual a diferença entre os modos de fluxo de trabalho manual e auto?
No modo manual, você faz o commit explicitamente quando uma alteração está pronta. No modo auto, o Node-RED cria um commit a cada deploy, o que é mais simples, mas gera um histórico mais poluído.
