Skip to Content
Acesso RemotoConfigurando Portas

Configurando Portas

Defina quais serviços seu app expõe para acesso remoto criando um arquivo port-template.yml no diretório .ironflock/.

Exemplo Básico

ports: - name: Web Interface port: 5000 main: true protocol: https

Isso torna a porta 5000 disponível para acesso remoto. Instalar o app em um dispositivo de produção ativa o túnel dessa porta; usuários com o privilégio de rede podem desativá-lo e ativá-lo novamente nas configurações do app no dispositivo.

Exemplo Completo

ports: - name: Web Interface port: 1100 main: true protocol: http - name: Video Stream port: 1200 protocol: http - name: Remote Desktop port: 5900 protocol: tcp - name: LoRaWAN Gateway port: 1700 protocol: udp

Referência de Campos

CampoObrigatórioDescrição
nameSimRótulo exibido nas configurações do app no dispositivo
portSimNúmero da porta local em que o serviço escuta
mainNãoSe true, esta porta é usada para o ícone de acesso rápido na lista de apps do dispositivo
protocolNãohttp (padrão), https, tcp ou udp
remote_port_environmentNãoApenas TCP e UDP: um nome de variável adicional sob o qual o agente de dispositivo anuncia a porta remota do túnel, além de REMOTE_PORT_FOR_<port>. Agentes de dispositivo anteriores à 0.19.8 a anunciam apenas sob este nome

Variáveis de Ambiente Injetadas

Para cada porta que você declara, a plataforma injeta variáveis de ambiente nos containers do seu app, para que seu código possa descobrir onde o serviço está realmente acessível — sem endereços fixos no código:

VariávelDescrição
DEVICE_LAN_IPO endereço IP do dispositivo na rede local
DEVICE_PORT_FOR_<port>A porta no dispositivo em que sua porta declarada é publicada na rede local
REMOTE_PORT_FOR_<port>A porta pública alocada pelo servidor de túnel enquanto o túnel está ativo (TCP e UDP; agente de dispositivo 0.19.8 e posteriores). 0 significa ainda não atribuída
REMOTE_PORT_FOR_<port>_CLOUDA porta voltada à internet quando o dispositivo roda em uma instância IronFlock que encaminha túneis através da nuvem (TCP e UDP)
TUNNEL_DOMAINO domínio sobre o qual as URLs de túnel do dispositivo são compostas: app.ironflock.com na nuvem, o domínio do appliance em um appliance on-premises, e localhost em um dispositivo de borda de um appliance instalado sem domínio (modo simples)
INSTANCE_KEYDefinida apenas em um dispositivo que pertence a um appliance on-premises (instância): a chave que as URLs de túnel dele encaminhadas pela nuvem carregam

<port> é o número da porta que você declarou em port-template.yml. Para o exemplo de Remote Desktop acima, o app receberia DEVICE_PORT_FOR_5900 e — enquanto seu túnel estiver ativo — REMOTE_PORT_FOR_5900. Os SDKs do IronFlock compõem a URL de acesso remoto de uma porta a partir dessas variáveis com getRemoteAccessUrlForPort. A plataforma não define CLOUD_TUNNEL_DOMAIN: as URLs encaminhadas pela nuvem usam app.ironflock.com, a menos que o seu app defina essa variável por conta própria.

Uma execução de desenvolvimento, iniciada com Executar no Cloud IDE, recebe um túnel para cada porta do template enquanto seu container está rodando. Só usuários com o privilégio Desenvolver no dispositivo podem abrir o túnel de uma porta http ou https, e ele não pode ser alternado para público. Abra-o pelo botão da porta no menu lateral do IDE. Como todo túnel TCP e UDP, o túnel de uma porta tcp ou udp não tem login na frente. Ele só começa depois do container, então sua porta remota não está na variável de ambiente: o agente a escreve em /data/env/REMOTE_PORT_FOR_<port>.txt enquanto o túnel está ativo e remove o arquivo quando o túnel cai. Os SDKs leem esse arquivo primeiro, então getRemoteAccessUrlForPort(port, 'udp') retorna o endereço da execução de desenvolvimento assim que o túnel está ativo. Leia-o de novo quando precisar, pois ele pode mudar entre execuções. Para uma porta http ou https, getRemoteAccessUrlForPort retorna a URL própria da execução de desenvolvimento, cujo rótulo termina em -dev (https://<device_key>-<app_name>-8080-dev.app.ironflock.com), então ela nunca colide com a da instalação de produção.

Apps podem rodar simultaneamente no mesmo dispositivo, portanto as portas declaradas são mapeadas automaticamente para uma porta livre no dispositivo. Sempre componha os endereços de rede local a partir dos valores injetados, em vez de assumir a porta declarada:

import os lan_ip = os.environ.get("DEVICE_LAN_IP") lan_port = os.environ.get("DEVICE_PORT_FOR_5900") # o serviço está acessível na rede local em {lan_ip}:{lan_port}

As variáveis são definidas quando o container inicia. As portas de túnel podem mudar enquanto o app está rodando (por exemplo, quando um túnel reconecta), então as variáveis de porta de túnel (REMOTE_PORT_FOR_<port>, sua variável _CLOUD correspondente e um nome personalizado definido em remote_port_environment) também são mantidas atualizadas como arquivos em /data/env/<VARIABLE_NAME>.txt — os SDKs do IronFlock leem esses arquivos automaticamente. As demais variáveis só mudam quando o container reinicia.

O agente de dispositivo remove um arquivo _CLOUD quando a porta na nuvem deixa de existir (encaminhamento pela nuvem desligado). Enquanto os arquivos do agente estão presentes, um arquivo _CLOUD ausente ou vazio significa, portanto, que não há porta na nuvem, e os SDKs não recorrem ao valor desatualizado com que o container iniciou.

Todos os usuários do container podem ler esses arquivos. Versões mais antigas do agente de dispositivo tornavam /data/env legível apenas pelo root: nelas, um container que roda como outro usuário vê apenas os valores com que iniciou — nenhuma porta de túnel que tenha mudado desde então — e os SDKs registram um aviso uma única vez.

Como os Protocolos Funcionam

HTTP / HTTPS

Para serviços baseados na web. O IronFlock cria uma URL no domínio do túnel que faz proxy do tráfego para a porta local do dispositivo. Os usuários abrem a URL no navegador. Ela é privada: apenas usuários autenticados no IronFlock com acesso ao dispositivo podem abri-la, a menos que a porta seja alternada para Public.

TCP

Para protocolos como VNC (Remote Desktop) ou conexões de socket diretas. O IronFlock aloca uma porta remota no servidor de túnel e a expõe ao seu app como REMOTE_PORT_FOR_<port>; o serviço fica então acessível em tcp://<TUNNEL_DOMAIN>:<remote port>.

UDP

Para protocolos como comunicação LoRaWAN ou túneis VPN. Semelhante ao TCP — uma porta remota é alocada e exposta como REMOTE_PORT_FOR_<port>.

Incorporando em Boards

Você pode incorporar o túnel de acesso remoto de um dispositivo diretamente em um board usando o Embed Widget. Isso cria uma experiência integrada em que os usuários podem:

  • Monitorar dados globais de todos os dispositivos
  • Interagir com dispositivos individuais por meio de interfaces web incorporadas

Tudo dentro do mesmo dashboard.

Instalar um app em um dispositivo de produção ativa o túnel de cada porta do seu port-template.yml. Túneis HTTP e HTTPS permanecem privados — apenas usuários autenticados no IronFlock com acesso ao dispositivo podem abri-los — a menos que uma porta seja alternada para Public. Túneis TCP e UDP são portas brutas no servidor de túnel, sem login na frente, então o app precisa autenticar seus clientes por conta própria. Usuários com o privilégio de rede no dispositivo podem desativar os túneis e ativá-los novamente; veja Gerenciando Túneis.

Last updated on