cloud-path

CloudPath(云径)는 로컬 실행 및 공인 네트워크 배포가 모두 가능한 셀프 호스팅 IoT 제어 플랫폼입니다. 특정 개발 보드의 전용 상위 컴퓨터가 아닌, '장치 접속, 상태 확인, 원격 제어'를 범용 제어면으로 만드는 것을 목표로 합니다. 프로젝트는 MIT 라이선스로 오픈 소스화되었으며, 단일 바이너리 중심 서비스인 cloudpath-server, 각 컴퓨터나 사이트에서 실행되는 게이트웨이 cloudpath-edge, 그리고 플러그인 Registry 제어면을 담당하는 명령줄 도구 cloudpath의 세 부분으로 구성됩니다. 기술적으로 백엔드는 Go, 프론트엔드는 React를 사용하며, WebUI 빌드 결과물은 서버사이드에 내장되어 있습니다. 데이터베이스는 SQLite의 WAL 모드를 사용하여 CGO 없이도 Linux 또는 arm64로 교차 컴파일이 가능합니다. 권한 구분 중심 서비스는 기대 상태, 테넌트 및 감사의 유일한 권위체로서 RBAC, 토큰, 속도 제한, 보존 기간, 플러그인 디렉토리와 실행 인스턴스의 기대 상태, 그리고 작업 하달 및 회신 결산을 담당합니다. 게이트웨이는 관측 상태의 유일한 권위체로, 마지막으로 성공적으로 적용(applied)된 스냅샷을 저장하며 장치 감독, 백오프 재시작 및 오프라인 이벤트 버퍼링을 담당합니다. 네트워크 단절 후에도 계속 작동하며, 재연결 시 중간의 부작용을 재생하지 않고 최종 스냅샷만 적용합니다. 장치 식별자는 테넌트, 게이트웨이, 장치의 삼원조로 결정되며, 온라인 전송 키는 edge_id와 device_id의 조합입니다. 계정 세션 하에서 게이트웨이-서버-브라우저로 이어지는 실시간 링크는 WebSocket을 사용하며, REST는 이력 조회 및 관리 작업을 담당합니다. 플러그인 체계 프로젝트는 세 가지 유형의 플러그인을 구분합니다. Driver는 기본적으로 게이트웨이 측에서 실행되며 장치 발견, 연결, 프로토콜 해석, 능력 매핑 및 장치 동작을 담당합니다. Application은 중심 서비스 측에서 실행되며 비즈니스 객체, 바인딩, 규칙, 작업 및 도메인 API를 담당합니다. Connector는 게이트웨이 또는 중심 서비스에서 실행될 예정이며 MQTT, Webhook 등의 알림 및 데이터 출구를 위해 사용됩니다(현재 목표 상태). 코어는 특정 하드웨어에 대해 코드를 작성하지 않으며, 새 장치는 곧 하나의 Driver 플러그인을 의미합니다. 참고 드라이버인 stcb와 여러 애플리케이션 플러그인은 독립 저장소로 배포되며, 저장소 내에는 Go 플러그인 템플릿, 예제 애플리케이션 및 바이너리부터 호스트까지의 E2E 테스트 스캐폴딩이 제공됩니다. 플러그인 설치 전에는 Manifest, 호환 범위, Release 자산 및 체크섬을 검증하며, 버전, digest 및 출처를 락 파일에 기록합니다. 빠른 시작 Go, Node, pnpm 및 선택적으로 task를 설치한 후, task setup으로 의존성을 가져오고 task build로 두 개의 바이너리를 생성합니다. 서버는 기본적으로 127.0.0.1:8080을 리스닝하며 /healthz 상태 확인을 제공합니다. 하드웨어가 없는 경우 내장된 demo 어댑터를 사용하여 장치 온라인, 작업 실행 및 단선 재연결을 검증할 수 있습니다. 실제 시리얼 장치를 연결할 때는 먼저 해당 Driver 플러그인을 설치 및 활성화한 후, 로컬 edge.yaml에서 plugin_host를 켜고 시리얼 및 어댑터 정보를 입력합니다. 관리자 계정을 처음 설치하면 서비스는 즉시 계정 모드로 진입하며, 상태 확인, 정적 리소스 및 인증 인터페이스를 제외한 모든 요청에 자격 증명이 필요합니다. 관리 콘솔 로그인 후 개요, 장치 목록 및 상세 정보, 실행 기록(이벤트), 애플리케이션 및 플러그인과 인스턴스 상세 정보, 게이트웨이 목록 및 상세 정보, 설정에 접근할 수 있습니다. 관리자는 별도로 멤버, 권한 및 액세스 토큰 페이지를 가집니다. 장치 상세 페이지의 조작 패널은 어댑터가 선언한 화이트리스트에 따라 버튼이 생성됩니다. 또한 API를 통해 직접 명령을 하달하고 이벤트 스트림 및 게이트웨이 온라인 상태를 조회할 수 있습니다. 작업 상태는 pending, sent, ok, failed, timeout으로 구분되며, 장시간 회신이 없는 경우 백그라운드 정리 작업에 의해 타임아웃으로 표시됩니다. 이벤트와 최종 상태 작업은 기본적으로 30일간 보존됩니다. 보안 설계 README에서는 노출 면을 L0 단일 머신, L1 내부망 또는 리버스 프록시, L2 공인 네트워크의 3단계로 나누며, L0 설정을 그대로 공인 네트워크에 노출하지 말 것을 경고합니다. 자격 증명은 두 가지 모드가 있습니다. 공유 서비스 토큰은 호환 경로에 해당하며, 계정 모드는 세션 쿠키 로그인, admin/operator/viewer 3단계 역할, 그리고 cp_ 접두사가 붙은 테넌트 토큰을 제공합니다. scope는 read, write, admin, edge의 부분 집합이며, 평문은 생성 응답 시에만 한 번 반환되고 DB에는 SHA-256과 짧은 접두사만 저장됩니다. Secret은 secret://name 형태의 핸들로 서버 설정 및 감사에 나타나며, 평문은 대상 게이트웨이 로컬에서 provider에 의해 해석됩니다. 플러그인은 manifest에 권한을 명시적으로 선언해야 하며, 서버는 평문을 저장하거나 전달하지 않습니다. 이 외에도 작업 화이트리스트, 파라미터 길이 및 문자 제한, 요청 바디 상한, WebSocket 읽기 상한, SPA 경로 트래버스 방지, 작업 및 로그인 속도 제한 및 보안 응답 헤더 세트가 적용되어 있습니다. 배포 및 다중 게이트웨이 접속 공식적으로 컨테이너에 의존하지 않는 공인 네트워크 배포 단계를 제공합니다. 먼저 빌드 결과물에 대해 아키텍처 단언(배포 매트릭스에 Linux arm64 포함)을 수행하고, systemd 유닛을 통해 전용 비루트(non-root) 계정으로 서비스를 실행하며, 기밀 정보는 0600 권한의 환경 파일에 둡니다. 마지막으로 nginx 리버스 프록시를 통해 HTTPS 및 WSS를 제공하고, WebSocket을 위해 업그레이드 헤더와 긴 읽기 타임아웃을 별도로 설정합니다. 인증은 제품 자체적으로 처리하므로 리버스 프록시 계층은 공개 상태를 유지합니다. 컨테이너 및 Compose 형태도 사용 가능하지만, 호스트 아키텍처가 이미지와 일치해야 합니다. 여러 대의 컴퓨터를 하나의 서버에 연결하는 것이 일반적인 사용법입니다. 관리자는 각 컴퓨터를 위해 edge scope의 테넌트 토큰을 생성하고, WSS 엔드포인트, 토큰 및 약속된 edge_id를 사용자에게 전달합니다. 사용자는 Release에서 플랫폼에 맞는 바이너리를 다운로드하여 checksums로 검증하고, 로컬 설정 파일을 작성한 후 실행합니다. 게이트웨이는 지수 백오프 재연결 기능을 갖추고 있으며, 오프라인 이벤트는 유한 버퍼에 저장되었다가 재연결 후 재생됩니다. 테넌트 간의 장치, 이벤트, 작업 및 인스턴스는 서로 보이지 않으며, 한 대의 게이트웨이가 오프라인이 되어도 다른 게이트웨이에 영향을 주지 않습니다. 테스트 및 배포 테스트는 Go 유닛 테스트, 레이스 탐지, 프론트엔드 동결 설치 및 타입 체크, 플러그인 템플릿 프로세스 및 집계 게이트 명령을 포함합니다. 배포는 버전 태그에 의해 6개 플랫폼 매트릭스 빌드가 트리거되며 통합 checksums 파일이 생성됩니다. 저장소는 공개 경계 감사, Markdown 링크 체크 및 workflow 구조 체크 등의 스크립트 게이트도 제공합니다. 현재 경계 README는 현재 상태와 목표 상태를 명확히 구분합니다. Connector 및 알림 런타임, MQTT 및 Modbus 접속, 원격 OTA, 시계열 집계, 중심 키 관리, 분산 쿼터 및 다중 Server는 아직 구현되지 않았습니다. 테넌트 토큰 세션은 REST만 지원하며 브라우저 실시간 채널은 없습니다. 동일한 외부 드라이버로 여러 대의 실제 보드를 구동하고, 탈착 및 작업 회신을 커버하는 현장 E2E 테스트도 아직 완료되지 않았으므로, 다중 보드 링크는 프로토콜 및 실제 보드 증거가 보완되기 전까지 검증된 것으로 간주하지 않습니다. 프로젝트의 원칙은 '구현되지 않은 능력을 현재 상태로 작성하지 않는다'는 것입니다.