Ir para o conteúdo

Topologia de Implantação em VM — HDT-AF (Docker + Hyperledger Fabric)

Este documento descreve detalhadamente a topologia de implantação da plataforma HDT-AF na máquina virtual remota (192.168.10.198), especificando a arquitetura de contêineres, as redes Docker integradas, mapeamentos de portas, montagens de volumes persistentes e os fluxos de inicialização e governança federada.


1. Visão Geral da Topologia (PlantUML)

O diagrama abaixo detalha a separação entre as redes Docker hdt-net e fabric_test, evidenciando o contêiner hdt-af-admin com multihoming (dupla interface de rede) para permitir comunicação transparente com o gateway do Hyperledger Fabric e o broker MQTT.

Diagrama PlantUML 1

Ver código-fonte PlantUML
    @startuml "HDT-AF - VM Deployment Topology"
    !theme plain
    skinparam shadowing false
    skinparam packageStyle rectangle
    skinparam componentStyle uml2

    node "Host VM (Debian Linux 6.8.12-43-pve x86_64 · 192.168.10.198)" as VM_HOST {

        artifact "Host Storage Volumes\n(/home/josedaniel/hdt-af)" as HOST_FS {
            folder "fabric-credentials/\n(Admin@org1 cert/key, tlsca)" as VOL_FABRIC
            folder "deploy/mqtt/tls/\n(mqtt-truststore, mqtt-client.p12)" as VOL_MQTT
            folder "data/\n(datasets locais)" as VOL_DATA
            folder "target/artifacts/\n(modelos e relatórios off-chain)" as VOL_ART
            folder "static/\n(fallback templates HTML)" as VOL_STATIC
            folder "docker/mosquitto/mosquitto.conf" as VOL_CONF
        }

        package "Docker Network: hdt-net (Bridge)" as NET_HDT {
            component "hdt-af-mosquitto-1\n[eclipse-mosquitto:2]\nBroker MQTT 5" as MOSQ {
                portin "1883 (TCP Plain)" as P_1883
                portin "8883 (TLS 1.3 / mTLS)" as P_8883
                portin "9001 (WebSocket)" as P_9001
            }

            component "hdt-af-postgres-1\n[postgres:16-alpine]\nLocal CDM Persistence" as PG {
                portin "5432 (Interna)" as P_PG_INT
            }
        }

        package "Docker Network: fabric_test (Bridge Externa)" as NET_FABRIC {
            component "peer0.org1.example.com\n[hyperledger/fabric-peer:latest]\nOrg1 Peer Gateway" as PEER_ORG1 {
                portin "7051 (gRPC TLS)" as P_7051
            }

            component "peer0.org2.example.com\n[hyperledger/fabric-peer:latest]\nOrg2 Peer" as PEER_ORG2 {
                portin "9051 (gRPC TLS)" as P_9051
            }

            component "orderer.example.com\n[hyperledger/fabric-orderer:latest]\nRaft Ordering Service" as ORDERER {
                portin "7050 (gRPC TLS)" as P_7050
            }

            component "chaincode: federated-governance\n[v1.1 seq 2]\nChannel: federated-channel" as CC_GOV
        }

        component "hdt-af-hdt-af-admin-1\n[hdt-af:latest · OpenJDK 25]\nAdminWebServer & Orchestrator\nMAIN_CLASS: AdminWebApp" as ADMIN {
            portin "8088 (HTTP Dashboard & REST)" as P_8088
        }
    }

    actor "Pesquisador / Operador" as USER
    actor "Dispositivo IoT / Cliente Federado" as CLIENT

    ' Conexões de Rede do Admin (Multihoming)
    ADMIN -down-> NET_HDT : Conecta a mosquitto (ssl://mosquitto:8883)\ne postgres:5432
    ADMIN -down-> NET_FABRIC : Conecta via Fabric Gateway gRPC\n(peer0.org1.example.com:7051)

    ' Mapeamento de Portas para o Host
    P_8088 <.. USER : HTTP http://192.168.10.198:8088/
    P_8883 <.. CLIENT : MQTTS ssl://192.168.10.198:8883
    P_1883 <.. CLIENT : MQTT tcp://192.168.10.198:1883
    P_PG_INT <.. VM_HOST : Mapeada como 15432:5432\n(evita colisão com porta 5432 local)

    ' Montagem de Volumes
    VOL_FABRIC --> ADMIN : /app/fabric:ro
    VOL_MQTT --> ADMIN : /app/mqtt-tls:ro
    VOL_DATA --> ADMIN : /app/data:rw
    VOL_ART --> ADMIN : /app/artifacts:rw
    VOL_STATIC --> ADMIN : /app/static:ro
    VOL_CONF --> MOSQ : /mosquitto/config/mosquitto.conf:ro
    VOL_MQTT --> MOSQ : /mosquitto/config/tls:ro

    ' Relações Fabric
    PEER_ORG1 --> CC_GOV
    PEER_ORG2 --> CC_GOV
    PEER_ORG1 ..> ORDERER
    PEER_ORG2 ..> ORDERER

    @enduml

2. Diagrama de Arquitetura em Formato Mermaid

Para visualização interativa e suporte nativo em visualizadores Markdown (GitHub, IDEs e navegadores):

graph TD
    subgraph Host["Host VM (192.168.10.198 · Debian Linux x86_64)"]
        subgraph PortMapping["Portas Mapeadas no Host"]
            PortAdmin["Porta 8088:8088"]
            PortMqttTLS["Porta 8883:8883 (TLS 1.3)"]
            PortMqttPlain["Porta 1883:1883"]
            PortMqttWS["Porta 9001:9001 (WS)"]
            PortPg["Porta 15432:5432 (PostgreSQL)"]
        end

        subgraph DockerNets["Redes Docker"]
            subgraph hdt_net["Rede: hdt-net (Bridge Interna)"]
                Mosquitto["hdt-af-mosquitto-1
(Eclipse Mosquitto 2)
Broker MQTT 5"] Postgres["hdt-af-postgres-1
(PostgreSQL 16)
Local CDM DB"] end subgraph fabric_test["Rede: fabric_test (Bridge Externa)"] PeerOrg1["peer0.org1.example.com
(Fabric Peer Org1 :7051)"] PeerOrg2["peer0.org2.example.com
(Fabric Peer Org2 :9051)"] Orderer["orderer.example.com
(Raft Orderer :7050)"] Chaincode["Chaincode Container
(federated-governance v1.1 seq 2)"] end Admin["hdt-af-hdt-af-admin-1
(hdt-af:latest · JDK 25)
AdminWebServer & Fabric Gateway"] end subgraph Storage["Volumes Host (/home/josedaniel/hdt-af)"] VolFabric["fabric-credentials/
(Admin Cert/Key + TLS CA)"] VolMqtt["deploy/mqtt/tls/
(Certificados mTLS PKCS12)"] VolData["data/
(Dados de Experimento)"] VolArtifacts["target/artifacts/
(Artefatos Off-chain)"] VolStatic["static/
(Templates HTML)"] end end User["Pesquisador / Operador
(Web Browser / REST)"] -->|HTTP :8088| PortAdmin ClientIoT["Clientes Federados / IoT
(Smartphones / Sensores)"] -->|MQTTS :8883| PortMqttTLS ClientIoT -->|MQTT :1883| PortMqttPlain PortAdmin --> Admin PortMqttTLS --> Mosquitto PortMqttPlain --> Mosquitto PortMqttWS --> Mosquitto PortPg --> Postgres Admin -.->|Dual Network Join| hdt_net Admin -.->|Dual Network Join| fabric_test Admin -->|ssl://mosquitto:8883| Mosquitto Admin -->|JDBC :5432| Postgres Admin -->|gRPC TLS :7051| PeerOrg1 PeerOrg1 --> Chaincode PeerOrg2 --> Chaincode PeerOrg1 --> Orderer VolFabric -->|Mount /app/fabric:ro| Admin VolMqtt -->|Mount /app/mqtt-tls:ro| Admin VolData -->|Mount /app/data:rw| Admin VolArtifacts -->|Mount /app/artifacts:rw| Admin VolStatic -->|Mount /app/static:ro| Admin VolMqtt -->|Mount /mosquitto/config/tls:ro| Mosquitto

3. Fluxo de Inicialização e Governança na VM (Sequence Diagram)

O diagrama a seguir apresenta o ciclo de vida completo durante o startup da aplicação na VM: inicialização dos serviços auxiliares (healthcheck), instanciação do AdminWebServer, conexão com o Fabric Gateway, verificação de chaincode e atendimento a requisições HTTP do monitor.

Diagrama PlantUML 2

Ver código-fonte PlantUML
    @startuml "HDT-AF - VM Startup and Verification Sequence"
    !theme plain
    skinparam shadowing false
    autonumber

    actor "Operador (Docker Compose)" as OP
    participant "PostgreSQL\n(hdt-af-postgres-1)" as PG
    participant "Mosquitto MQTT\n(hdt-af-mosquitto-1)" as MOSQ
    participant "HDT-AF Admin\n(hdt-af-hdt-af-admin-1)" as ADMIN
    participant "Fabric Peer Org1\n(peer0.org1.example.com)" as PEER1
    participant "Hyperledger Fabric\n(federated-governance)" as CC
    actor "Navegador Web / API" as USER

    == 1. INICIALIZAÇÃO DE INFRAESTRUTURA E HEALTHCHECKS ==
    OP -> PG : docker compose up -d (inicia postgres)
    OP -> MOSQ : docker compose up -d (inicia mosquitto)
    PG -> PG : Executa healthcheck: pg_isready -U hdt_af
    PG --> OP : Status: healthy
    MOSQ -> MOSQ : Executa healthcheck: mosquitto_pub -p 8883/1883
    MOSQ --> OP : Status: healthy

    == 2. STARTUP DO HDT-AF ADMIN COM MULTIHOMING ==
    OP -> ADMIN : docker compose up -d hdt-af-admin
    note over ADMIN
      Entrada no hdt-net (IP interno)
      Entrada no fabric_test (IP interno)
      Carrega variáveis de ambiente e segredos LGPD
    end note

    ADMIN -> ADMIN : Inicializa Spring/Javalin/JDK 25 (AdminWebApp)
    ADMIN -> MOSQ : Conexão MQTTS (ssl://mosquitto:8883) via hdt-net
    MOSQ --> ADMIN : Conexão MQTT 5 TLS Estabelecida

    == 3. CONEXÃO FABRIC GATEWAY & GOVERNANÇA ==
    ADMIN -> ADMIN : Carrega credenciais (/app/fabric/Admin@org1... cert + key)
    ADMIN -> PEER1 : Conecta via gRPC TLS a peer0.org1.example.com:7051 (via fabric_test)
    PEER1 --> ADMIN : Gateway gRPC Estabelecido (TLS Server Name: peer0.org1.example.com)
    ADMIN -> CC : Query: querycommitted -C federated-channel
    CC --> ADMIN : Confirmação: federated-governance v1.1 seq 2 ativo
    ADMIN -> CC : Sincroniza / Audita Contratos Iniciais de Experimento

    == 4. BINDING HTTP E ATENDIMENTO OPERACIONAL ==
    ADMIN -> ADMIN : AdminWebServer vincula porta 0.0.0.0:8088
    ADMIN -> ADMIN : Valida ADMIN_STATIC_ROOT (/app/static -> ativa server-side dashboard)
    ADMIN --> OP : Container em estado RUNNING (Up)

    == 5. CONSUMO DE MONITORAMENTO E EXPERIMENTOS ==
    USER -> ADMIN : GET http://192.168.10.198:8088/
    ADMIN --> USER : Retorna HTTP 200 (Dashboard HTML do Monitor Federado)

    USER -> ADMIN : GET http://192.168.10.198:8088/api/experiments
    ADMIN -> CC : Consulta estado imutável dos experimentos na Blockchain
    CC --> ADMIN : Retorna contratos auditados (exp-dt, exp-har, exp-ecg)
    ADMIN --> USER : Retorna JSON com lista de experimentos e status on-chain
    @enduml

4. Tabela de Alocação de Recursos e Conectividade

Serviço Contêiner Imagem Redes Docker Porta Host Porta Interna Finalidade
Admin Web & Orchestrator hdt-af-hdt-af-admin-1 hdt-af:latest (Linux/amd64) hdt-net, fabric_test 8088 8088 Dashboard web, API REST, orquestrador federado e Gateway Fabric
Broker MQTT 5 hdt-af-mosquitto-1 eclipse-mosquitto:2 hdt-net 1883, 8883, 9001 1883, 8883, 9001 Barramento de telemetria IoT, rodadas e distribuição de modelos
Banco Local CDM hdt-af-postgres-1 postgres:16-alpine hdt-net 15432 5432 Persistência relacional/séries temporais do CDM
Peer Org1 peer0.org1.example.com hyperledger/fabric-peer:latest fabric_test 7051 7051 Ponto de entrada de auditoria e governança (Org1MSP)
Peer Org2 peer0.org2.example.com hyperledger/fabric-peer:latest fabric_test 9051 9051 Endosso e validação cruzada (Org2MSP)
Orderer orderer.example.com hyperledger/fabric-orderer:latest fabric_test 7050 7050 Serviço de ordenação Raft do consórcio
Chaincode federated-governance Fabric CCAAS / Container fabric_test N/A Dinâmica Contratos inteligentes de governança federada (v1.1 seq 2)

5. Invariantes de Segurança e Isolamento

  1. Isolamento de Portas Conflitantes: O PostgreSQL do HDT-AF foi mapeado na porta 15432 no host da VM, garantindo coexistência sem interferência com o PostgreSQL existente do host (vaideferry-db na porta padrão 5432).
  2. Resolução de Nomes Interna (Sem Hacks de /etc/hosts): A anexação do contêiner hdt-af-admin à rede externa fabric_test permite resolução nativa de nomes DNS (peer0.org1.example.com, orderer.example.com) gerenciada pelo daemon Docker.
  3. Comunicação Criptografada:
  4. Fabric Gateway utiliza gRPC com TLS mútuo (mTLS) e validação do CA Root (tlsca.org1.example.com-cert.pem).
  5. Broker MQTT opera na porta 8883 com protocolo TLS 1.3 obrigatório para clientes federados remotos.
  6. Governança Imutável Fail-Closed: Toda transação de rodada, consentimento de cliente e registro de versão de modelo global é ancorada no ledger do Hyperledger Fabric através do chaincode federated-governance.