cloud-path

CloudPath es una plataforma de control de IoT autohospedada que puede ejecutarse localmente o desplegarse en la red pública. Su objetivo es convertir la «conexión de dispositivos, visualización de estado y control remoto» en un plano de control universal, en lugar de ser una aplicación superior específica para una placa de desarrollo. El proyecto es de código abierto bajo la licencia MIT y consta principalmente de tres partes: el servicio central de binario único cloudpath-server, el gateway cloudpath-edge que se ejecuta en cada computadora o sitio, y la herramienta de línea de comandos cloudpath responsable del plano de control del Registry de plugins. Técnicamente, el backend utiliza Go, el frontend React, los artefactos de construcción de la WebUI están embebidos en el servidor y la base de datos utiliza el modo WAL de SQLite, permitiendo la compilación cruzada para Linux o arm64 sin necesidad de CGO. División de Autoridad El servicio central es la única autoridad para el estado deseado, los inquilinos y la auditoría, encargándose del RBAC, tokens, limitación de tasa, periodos de retención, el estado deseado del directorio de plugins y las instancias en ejecución, así como del envío de operaciones y la liquidación de acuses de recibo. El gateway es la única autoridad para el estado de observación, guardando la última instantánea aplicada con éxito, y es responsable de la supervisión de dispositivos, el reinicio con retroceso y el almacenamiento en búfer de eventos offline; continúa funcionando tras una pérdida de red y, al reconectarse, solo aplica la instantánea final sin reproducir efectos secundarios intermedios. La identidad del dispositivo se determina mediante la tríada inquilino, gateway y dispositivo, y la clave de transmisión en línea es una combinación de edge_id y device_id. Bajo una sesión de cuenta, el enlace en tiempo real desde el gateway al servidor y luego al navegador utiliza WebSocket, mientras que REST se encarga de las consultas históricas y las operaciones de gestión. Sistema de Plugins El proyecto distingue tres tipos de plugins: Driver, que se ejecuta por defecto en el lado del gateway y se encarga del descubrimiento de dispositivos, conexión, análisis de protocolos, mapeo de capacidades y acciones del dispositivo; Application, que se ejecuta en el servicio central y se encarga de objetos de negocio, vinculaciones, reglas, tareas y API de dominio; y Connector, planeado para ejecutarse en el gateway o el servicio central para notificaciones y salida de datos como MQTT y Webhook, siendo actualmente un estado objetivo. El núcleo no escribe código para ningún hardware específico; un nuevo dispositivo equivale a un plugin Driver. Los controladores de referencia stcb y varios plugins de aplicación se publican en repositorios independientes, que proporcionan plantillas de plugins en Go, aplicaciones de ejemplo y un andamiaje de pruebas E2E desde el binario hasta el host. Antes de instalar un plugin, se validan el Manifest, el rango de compatibilidad, los activos de Release y el resumen, registrando la versión, el digest y la fuente en un archivo de bloqueo. Inicio Rápido Tras instalar Go, Node, pnpm y opcionalmente task, se utiliza task setup para obtener dependencias y task build para generar los dos binarios. El server escucha por defecto en 127.0.0.1:8080 y proporciona un chequeo de salud en /healthz. Sin hardware, se puede usar el adaptador demo integrado para verificar la conexión de dispositivos, ejecución de operaciones y reconexión; para dispositivos serie reales, primero se instala y activa el plugin Driver correspondiente, y luego se habilita plugin_host en el archivo edge.yaml local especificando el puerto serie y el adaptador. Tras la primera instalación de la cuenta de administrador, el servicio entra inmediatamente en modo de cuenta, requiriendo credenciales para todo excepto el chequeo de salud, recursos estáticos e interfaces de autenticación. Consola de Administración Tras iniciar sesión, se puede acceder a la vista general, lista y detalles de dispositivos, registros de ejecución (eventos), aplicaciones y plugins con detalles de instancia, lista y detalles de gateways, y configuración; el administrador tiene además páginas de miembros, permisos y tokens de acceso. El panel de operaciones en la página de detalles del dispositivo genera botones según la lista blanca declarada por el adaptador; también se pueden enviar comandos vía API y consultar el flujo de eventos y el estado online del gateway. Los estados de operación son pending, sent, ok, failed y timeout; las operaciones sin acuse de recibo prolongado son marcadas como timeout por una tarea de limpieza en segundo plano, y los eventos y operaciones finales se conservan por defecto durante 30 días. Diseño de Seguridad El README divide la superficie de exposición en tres niveles: L0 máquina única, L1 red interna o proxy inverso, y L2 red pública, advirtiendo que no se debe colocar la configuración L0 directamente en la red pública. Existen dos modos de credenciales: los tokens de servicio compartido son una ruta de compatibilidad, mientras que el modo de cuenta ofrece inicio de sesión mediante cookies de sesión, tres niveles de roles (admin, operator y viewer), y tokens de inquilino con prefijo cp_, cuyo scope es un subconjunto de read, write, admin y edge; el texto plano solo se devuelve una vez en la respuesta de creación, y en la base de datos solo se almacena el SHA-256 y un prefijo corto. Los Secret aparecen en la configuración del servidor y auditoría como handles de tipo secret://name, y el texto plano solo es resuelto localmente en el gateway objetivo por el provider; los plugins deben declarar explícitamente los permisos en el manifest, y el servidor no guarda ni reenvía el texto plano. Además, cuenta con listas blancas de operaciones, límites de longitud y caracteres de parámetros, límites de cuerpo de solicitud, límites de lectura de WebSocket, protección contra salto de rutas SPA, limitación de tasa en operaciones e inicios de sesión, y un conjunto de encabezados de respuesta de seguridad. Despliegue y Acceso Multi-gateway Se proporcionan pasos de despliegue público sin dependencia de contenedores: primero se realiza una aserción de arquitectura sobre los artefactos (la matriz de publicación incluye Linux arm64), luego se ejecuta el servicio con una cuenta no root dedicada mediante unidades de systemd, colocando los secretos en un archivo de entorno con permisos 0600, y finalmente se usa nginx como proxy inverso para proporcionar HTTPS y WSS, configurando encabezados de actualización y tiempos de espera de lectura prolongados para WebSocket; se aclara que la autenticación es responsabilidad del producto, manteniendo la capa de proxy pública. También se pueden usar contenedores y Compose, siempre que la arquitectura del host coincida con la de la imagen. El uso de varias computadoras conectadas a un mismo servidor es el flujo habitual: el administrador crea un token de inquilino con scope edge para cada computadora, entregando el endpoint WSS, el token y el edge_id acordado al usuario; el usuario descarga el binario correspondiente, lo verifica mediante checksums, completa la configuración local y lo ejecuta. El gateway incluye reconexión con retroceso exponencial, y los eventos offline entran en un búfer acotado que se reproduce tras la reconexión. Los dispositivos, eventos, operaciones e instancias entre diferentes inquilinos son invisibles entre sí, y la caída de un gateway no afecta a otro. Pruebas y Publicación Las pruebas cubren tests unitarios de Go, detección de condiciones de carrera, congelación de instalación y chequeo de tipos en el frontend, flujo de plantillas de plugins y comandos de puerta de enlace agregados; la publicación es activada por tags de versión, realizando la construcción en una matriz de seis plataformas y generando un archivo de checksums unificado. El repositorio también incluye scripts de puerta de enlace para auditoría de límites públicos, chequeo de enlaces Markdown y chequeo de estructura de workflows. Límites Actuales El README distingue claramente entre el estado actual y el objetivo: el runtime de Connector y notificaciones, el acceso MQTT y Modbus, OTA remoto, agregación de series temporales, gestión central de claves, cuotas distribuidas y multi-Server aún no se han implementado; las sesiones de tokens de inquilino solo existen para REST, no para canales en tiempo real del navegador; y el E2E de campo que cubra la conexión de múltiples placas reales con un mismo driver externo, incluyendo desconexión y acuses de recibo, no se ha completado, por lo que el enlace multi-placa no se considera verificado hasta que se completen el protocolo y la evidencia física. El principio del proyecto es «no escribir capacidades no implementadas como estado actual».