Transporte entre ambientes — /transports

A integração é montada e testada num CMS de teste e depois precisa existir igual no CMS de produção. Redigitar cadastro por cadastro é lento e é onde nasce o erro: um campo esquecido, um Transformador da versão errada, um encaminhamento que ficou para trás. O transporte leva a configuração de um CMS para outro num pacote, e o CMS de destino só grava depois que uma pessoa confere e aprova.

Três regras valem sempre:

• Nada é aplicado sozinho. O pacote chega como pendente. Ele só grava depois da prévia e da aprovação de alguém que tem permissão no destino.
• Tudo nasce inativo. Entregas, Coletas, Conexões, Transformadores, Alertas, Gatilhos e Roteadores criados pelo transporte nascem desligados. Um checklist diz o que falta antes de ligar.
• Segredo não viaja. Credenciais e Conexões Externas vão sem senha e sem usuário, e a Aplicação vai sem URL e sem certificado. Esses dados são de cada ambiente e são preenchidos no destino.

O menu Transportes fica logo depois do Laboratório, porque é o passo seguinte do mesmo caminho:

Tipo do ambiente

Em Parâmetros › Aparência, o campo Tipo deste ambiente (Desenvolvimento, Teste ou Produção) mostra uma faixa colorida no topo de todas as telas e no login, para ninguém trabalhar no ambiente errado. O transporte usa esse valor:

• Produção não envia. Em Produção, Gerar pacote e Pacotes gerados somem do menu, e o servidor recusa a geração.
• Produção não recebe de Produção. Pacote cuja origem se declara Produção é recusado.
• Origem com tipo Não informado é aceita, com aviso na prévia.

Gerar pacote

A página tem três passos, de cima para baixo.

1. O que transportar. Há dois grupos:

• Estrutura — uma Aplicação inteira, uma ou mais Interfaces da mesma Aplicação, uma Entrega ou uma Coleta avulsa. Vai junto o que elas usam: encaminhamentos, condições, Transformadores, Erros de Negócio, Alertas, Gatilhos, as Credenciais e Conexões (sem segredo) e todas as variáveis da Aplicação (só o nome).
• Itens avulsos — Transformador, Erro de Negócio, Gatilho, Regra de Criptografia, Alerta ou Roteador. Aqui vai só o que você marcar. É o caminho para corrigir um Transformador ou levar um Gatilho novo sem reenviar a Interface inteira. O que o item aponta (a Entrega do Gatilho, a Chave da Regra de Criptografia, as Entregas do Roteador) precisa existir no destino.

2. Conteúdo do pacote. É calculado no servidor antes de gerar qualquer coisa:

• as contagens por tipo e o tamanho do pacote;
• Vai sem segredo — os cadastros que vão pedir senha, usuário ou URL no destino;
• Precisa existir no destino — o que o pacote referencia mas não leva. Se faltar lá, a prévia acusa e o transporte não pode ser aprovado;
• Variáveis usadas — viajam só pelo nome. A Calculada leva a expressão;
• Avisos — pontos para conferir. Não impedem o envio.

3. Destino. Há duas opções: Baixar arquivo, que gera um .json para importar no destino, ou um ou mais ambientes cadastrados para envio direto (veja Envio direto). O campo Observação aparece para quem aprova no destino. Use-o para dizer o que muda.

Todo pacote sai assinado com a chave deste CMS (veja Assinatura do pacote).

Os ícones de transporte nas linhas de Aplicação, Interface, Entrega e Coleta são atalhos: abrem esta página com o item já escolhido.

Pacotes gerados

O histórico de tudo que saiu deste CMS: quando, o quê, para onde (arquivo ou ambiente) e o resultado, por exemplo “Transferido #12” ou “Falha no envio” com o motivo. Baixar pacote baixa de novo o arquivo de qualquer linha. Isso serve quando o envio direto falhou e o caminho é importar o arquivo. O ícone em Quem gerou abre os dados de contato de quem montou o pacote e o resumo dele, para facilitar a conversa entre os responsáveis dos dois lados.

Situação no destino

No envio direto, a coluna Situação no destino mostra o que aconteceu lá: Pendente, Aplicado, Ativado, Recusado (com o motivo), Desfeito ou Expirado. A origem pergunta ao destino com o mesmo token do envio; o destino nunca chama a origem. A tela pergunta sozinha ao abrir, só pelo que ainda pode mudar, e Atualizar situação pergunta de novo na hora. Destino apagado ou desligado não é consultado: a linha guarda a última situação conhecida. Pacote baixado como arquivo não tem como ser consultado e fica com ”—”. O combo Qualquer situação no destino filtra a grade por essa coluna, com os mesmos ícones da caixa do destino.

Pacotes recebidos

É a caixa de entrada. A tela abre em Pendentes, e o combo de status troca para Aplicados, Recusados, Desfeitos, Com falha, Expirados ou todos. Cada opção mostra quantos pacotes tem, com o mesmo ícone e a mesma cor da coluna Status. Dá para combinar com a busca (sigla, origem, quem gerou ou número), o tipo e o período. Importar arquivo, no título, deposita um .json como pendente e não grava mais nada.

O ícone em Remetente abre quem gerou o pacote. A pessoa é do CMS de origem, então o popup mostra o que o pacote trouxe dela (nome, login e e-mail, com o botão de copiar), de que CMS veio, quantos pacotes dela já chegaram aqui e o resumo deste pacote. O mesmo vale no cabeçalho do pacote.

Cada pessoa só vê os pacotes das Aplicações que alcança. Um pacote que não envolve Aplicação nenhuma (um Transformador avulso, por exemplo) só aparece para quem tem acesso irrestrito.

Contador e aviso por e-mail

O item Transportes do menu mostra um contador âmbar com os pacotes pendentes que a pessoa enxerga, atualizado a cada minuto. Quando um pacote chega, por arquivo ou envio direto, o CMS também manda e-mail a quem pode aprová-lo: usuários ativos com a permissão de aprovar (/transports/approval), com e-mail cadastrado, que alcançam a Aplicação do pacote. O e-mail traz a origem, quem gerou, a observação e o link para o pacote. Sem SMTP configurado, o aviso não sai, mas o pacote está na caixa e no contador do mesmo jeito.

O pacote

O cabeçalho mostra de onde o pacote veio, quem o gerou, o hash do conteúdo, a assinatura e a observação. Relatório (PDF) gera o documento para auditoria: origem, quem gerou, id do envio, hash, assinatura, quem decidiu, item a item o que foi criado ou substituído (com os campos alterados) e a linha do tempo inteira.

Prévia

A prévia compara cada item do pacote com o que existe neste CMS:

Outras pendências que bloqueiam a aprovação: uma referência que não existe aqui (uma Entrega de encaminhamento, uma Chave de Criptografia), uma Interface existente com outro tipo de fila, uma Aplicação fora do alcance de quem aprova ou, com “Exigir assinatura” ligada, um pacote sem assinatura de origem confiável.

Credenciais e Conexões têm de-para. Em vez de criar uma nova (sem segredo), dá para apontar para uma que já existe aqui, da mesma direção ou do mesmo tipo. O de-para fica lembrado para os próximos pacotes da mesma origem. Salve-o antes de aprovar, porque a aprovação usa o de-para salvo.

Deixar itens de fora

Algumas exigências do pacote podem ser resolvidas na hora de aprovar, sem gerar outro pacote. Quem aprova pode deixar de fora os itens que nada no pacote usa: Regra de Criptografia, Erro de Negócio, Alerta e Gatilho. Na linha do item, Não trazer este item o tira do pacote. Ele vai para o grupo Deixado de fora, com Trazer de volta, e a prévia é recalculada sem ele. Por exemplo, uma Regra de Criptografia cuja Chave não existe aqui deixa de bloquear a aprovação.

O que fica de fora entra no hash da prévia e na aprovação. A linha do tempo e o relatório em PDF registram o evento Itens deixados de fora na aprovação, com cada item. Interface, Entrega, Coleta, Transformador e os demais itens não podem ser deixados de fora, porque outros itens dependem deles.

Trocar siglas

Quando a Interface, a Entrega ou a Coleta tem outro nome neste ambiente (MES_QAS no teste, MES_PRD aqui), abra Trocar siglas (opcional) no de-para e informe a sigla daqui. A troca vale para o item e para toda referência a ele: encaminhamentos, condições, Erros de Negócio, Gatilhos, Alertas, Regras de Criptografia, escopo de Transformador, o grafo do Roteador e a URL de recebimento, que é recalculada. Scripts e templates não são alterados. Se um script cita a sigla, ajuste à mão.

A sigla nova pode ser uma que já existe aqui. Nesse caso o item é comparado com o daqui, em vez de criado. A prévia mostra cada troca como aviso. Duas siglas que viram a mesma são pendência, porque o pacote juntaria dois itens num só. A troca fica lembrada para os próximos pacotes da mesma origem.

Aprovação

Aprovar e criar inativo grava tudo numa transação. Antes do commit, o CMS relê cada item gravado e compara com o que a prévia mostrou. Se algo não bater, nada é gravado e o transporte fica como Falhou. Se a configuração do destino mudou entre a prévia e a aprovação, a aprovação é recusada e pede uma prévia nova.

Quando o pacote cria Interfaces, a aprovação pergunta como o agendamento delas nasce:

• Desligado, ligar em “Ativar transporte” — liga junto com as Entregas e Coletas;
• Desligado, eu ligo depois — fica desligado até alguém ligar em Agendadores;
• Ligado desde já — roda desde a aprovação, sem processar nada enquanto Entregas e Coletas estiverem inativas.

Recusar pede um motivo, que fica na linha do tempo, na auditoria e na situação que a origem vê.

Por padrão, quem aprova não pode ser quem montou o pacote na origem (Aprovador diferente de quem enviou, em Parâmetros › Configurações). Em Produção essa regra vale sempre.

Ativação

Depois de aprovado, o pacote mostra o checklist do que falta antes de ligar:

• Credencial ou Conexão aguardando segredo, com link para o cadastro;
• Aplicação sem URL ou sem Conexão de Keep Alive;
• variável criada vazia;
• Interface de entrada sem API Key que a cubra, com atalho para gerar;
• Roteador cujo acesso precisa ser liberado;
• Alerta novo sem destinatários (só aviso).

Ativar transporte fica habilitado quando não sobra pendência bloqueante. Ele liga só o que este transporte criou e continua igual ao criado: Conexões, Transformadores, Entregas, Coletas, Erros de Negócio, Alertas, Roteadores e, por último, Gatilhos. O que alguém já ligou à mão fica como está. Regras de Criptografia pedem senha e são ligadas na tela delas.

A seção O que este transporte gravou lista cada item criado ou substituído. Para os substituídos, a configuração original fica guardada: dá para ver e baixar.

Desfazer

O que não pode sair (foi alterado depois, já tem mensagens ou é usado por outro cadastro, como um Erro de Negócio que alguém vinculou à mão) fica desligado e aparece listado no resultado. Os conectores sempre ligados dos itens restaurados reconectam com a configuração original. O desfazer respeita a ordem: com um transporte aplicado depois deste, desfaça primeiro o mais recente, porque ele pode apontar para o que este criou.

Expiração

Um pacote que ninguém aprova nem recusa expira depois de Pendentes expiram em (dias), em Parâmetros › Configurações (padrão 30 dias, de 1 a 365, alterado só pelo administrador). A limpeza diária muda o status para Expirado, e o evento vai para a linha do tempo. Nada é apagado: o pacote só sai da fila de aprovação. Se ainda for preciso, gere e envie de novo.

Atualizar o que já existe

Por padrão, o transporte só cria. Um item que já existe com outro conteúdo é conflito e bloqueia o pacote. Para levar uma correção de algo que já está em produção, três coisas precisam valer ao mesmo tempo:

1. Permitir atualização por transporte ligado em Parâmetros › Configurações. Só o administrador liga, e ligar pede confirmação;
2. quem aprova tem a permissão de atualizar (/transports/update), que nenhum perfil padrão recebe;
3. na prévia, quem aprova marca Atualizar este item, item a item. Conflito não marcado continua bloqueando.

Podem ser atualizados: Interface, Entrega, Coleta (com encaminhamentos e condições), Transformador, Alerta, Gatilho e Roteador.

Se o item foi alterado neste CMS depois do último transporte, ou foi criado aqui à mão, a prévia mostra a diferença em três colunas (último transporte, este CMS, pacote) e pede uma segunda marcação: Sobrescrever o que foi alterado aqui.

Algumas coisas nunca são atualizadas por transporte, nem com a chave ligada: Aplicação, Credencial, Conexão Externa, o valor de variável, Chave de Criptografia, Regra de Criptografia e Erro de Negócio. O transporte também nunca remove o que existe só no destino.

Conectores sempre ligados

Algumas Coletas e Entregas mantêm uma sessão aberta: assinatura MQTT e Sparkplug, gatilho OPC UA, polling Modbus, varredura de arquivo, listener de IDoc e o gate de escrita OPC UA/Modbus da Entrega. Quando o pacote atualiza uma delas enquanto está ligada, a configuração nova só vale depois que a sessão reconecta. A aprovação mostra esses conectores agrupados por Aplicação e pede a decisão:

• Reconectar agora — a sessão cai e volta em seguida já com a configuração nova. Pode haver alguns segundos sem coleta;
• Manter a conexão atual — nada cai agora; a configuração nova vale na próxima reconexão (edição da Coleta ou Entrega na tela, ou reinício do serviço).

A decisão fica na linha do tempo do transporte.

Assinatura do pacote

Cada CMS tem um par de chaves próprio, gerado na primeira vez que ele assina um pacote. Todo pacote sai assinado. O destino confere a assinatura ao receber: pacote alterado depois de gerado é recusado na hora, por arquivo ou envio direto.

A chave pública aparece em Ambientes e tokens › Para onde envio › Chave deste CMS, com a impressão (oito grupos de quatro caracteres) e o botão para copiá-la. No destino, quem administra cola essa chave em Origens confiáveis e confere a impressão com quem está na origem, por telefone ou outro canal.

O detalhe do pacote recebido mostra a assinatura:

• Assinado por origem (verde) — a chave está em Origens confiáveis, ou é a chave presa no token que o depositou;
• Assinado por um CMS que este ambiente não conhece (âmbar), com a impressão. Quem administra pode usar Confiar nesta origem, que já preenche a chave;
• Sem assinatura — pacote de uma versão anterior do CMS.

Pacote de origem desconhecida ou sem assinatura tem aviso na prévia. Com Exigir assinatura de origem confiável ligada (Parâmetros › Configurações, só o administrador), ele vira pendência e não pode ser aprovado.

No envio direto, o primeiro pacote assinado que chega por um token prende a chave nele. Dali em diante, o token recusa pacote assinado com outra chave e pacote sem assinatura. A impressão da chave presa aparece na aba Quem envia para cá.

Envio direto

O envio direto leva o pacote de um CMS para a caixa de outro, sem baixar e importar arquivo. Do outro lado, ele cai em Pacotes recebidos como pendente e segue o mesmo caminho: prévia, aprovação e ativação.

A configuração fica em Transportes › Ambientes e tokens (Ferramenta /settings/transport, que nos perfis padrão só o administrador tem):

1. No destino (normalmente produção), na aba Quem envia para cá, gere um token (cmst_…). Ele aparece uma única vez: copie e entregue a quem administra a origem. O token fica preso ao primeiro CMS que depositar com ele, e à chave que assina os pacotes dele, e tem um limite de pacotes pendentes.
2. Na origem (teste), na aba Para onde envio, cadastre o destino com o endereço (o mesmo do navegador, sem /api) e o token. Se o destino usa certificado de CA própria, informe também o certificado. Use Testar conexão: ele confere o token e mostra o tipo de ambiente que o destino declara. Endereço com http:// é aceito, mas a tela avisa em vermelho: o token e o pacote trafegam sem criptografia.
3. A partir daí, Gerar pacote oferece o destino ao lado de Baixar arquivo.

O token fica cifrado e não aparece de novo na tela. Desativar ou excluir o token no destino corta o envio na hora. Se o envio falhar, o pacote continua em Pacotes gerados, de onde dá para baixar o arquivo e importar.

Várias plantas de produção

Um CMS de desenvolvimento ou teste pode alimentar vários CMS de produção, um por planta. Cada produção gera o próprio token, e a origem cadastra cada uma em Para onde envio. Em Gerar pacote, marque todos os destinos que devem receber: o pacote é montado uma vez e o mesmo conteúdo, com o mesmo hash, vai para todos. Em Pacotes gerados fica uma linha por destino, com o resultado e a situação de cada um. Se uma planta estiver fora do ar, as outras recebem do mesmo jeito, e o pacote daquela pode ser baixado e importado depois.

Do outro lado, cada planta decide sozinha: tem a sua caixa, os seus aprovadores, o seu de-para e o seu checklist. Senhas, URLs e valores de variáveis são preenchidos em cada planta. Se uma planta usa outras siglas, a troca de sigla fica lembrada lá. Uma produção não envia para outra: a configuração sai sempre do teste ou do desenvolvimento.

Veio do transporte

Nas listas de Interfaces, Entregas, Coletas e Transformadores, o item que veio por transporte mostra um pequeno ícone de pacote ao lado da sigla. Ao passar o mouse, aparece qual transporte o criou ou atualizou, de que origem, quando e quem aprovou; o clique abre o transporte. Só aparece para quem tem acesso a Pacotes recebidos, e só para transportes que continuam valendo (não desfeitos).

Permissões

Log

Cada transporte tem uma linha do tempo no detalhe: recebido, prévia, aprovado, cada item criado ou atualizado, decisão sobre os conectores, ativado, desfeito, expirado, com quem fez cada coisa. Ela nunca é apagada pela limpeza. As ações de usuário (gerar, enviar, aprovar, recusar, ativar, desfazer, confiar numa origem e as mudanças nas chaves de transporte) também vão para Log de Auditoria, como todo o resto.

→ Configurações · Cadastros · Conexões e credenciais · Segurança e criptografia