cloud-path

CloudPath（云径）は、ローカル環境およびパブリッククラウドの両方で動作するセルフホスト型のIoT制御プラットフォームです。特定の開発ボード専用の上位機ではなく、「デバイスの接続、状態確認、リモート制御」を汎用的なコントロールプレーンとして提供することを目指しています。プロジェクトはMITライセンスでオープンソース化されており、主に3つのコンポーネントで構成されています：単一バイナリの中心サービス「cloudpath-server」、各PCやサイトで動作するゲートウェイ「cloudpath-edge」、およびプラグインRegistryのコントロール面を管理するコマンドラインツール「cloudpath」です。技術スタックはバックエンドにGo、フロントエンドにReactを採用し、WebUIのビルド成果物はサーバー側に組み込まれています。データベースにはSQLiteのWALモードを使用しており、CGOなしでLinuxやarm64へのクロスコンパイルが可能です。 権限の区分 中心サービスは、期待状態、テナント、および監査の唯一の権威であり、RBAC、トークン、レート制限、保持期間、プラグインディレクトリと実行インスタンスの期待状態、および操作の配信と回執（レシート）の決済を担当します。ゲートウェイは観測状態の唯一の権威であり、最後に正常に適用（applied）されたスナップショットを保存し、デバイスの監視、バックオフ再接続、およびオフラインイベントのバッファリングを担当します。ネットワーク断絶後も動作を継続し、再接続時には最終的なスナップショットのみを適用し、途中の副作用をリプレイしません。デバイスのアイデンティティは「テナント・ゲートウェイ・デバイス」の三元組で決定され、オンライン伝送キーはedge_idとdevice_idの組み合わせとなります。アカウントセッション下では、ゲートウェイからサーバー、そしてブラウザへのリアルタイムリンクにWebSocketを使用し、RESTは履歴クエリと管理操作を担います。 プラグイン体系 プロジェクトでは3種類のプラグインを定義しています。「Driver」はデフォルトでゲートウェイ側で動作し、デバイスの発見、接続、プロトコル解析、能力マッピング、およびデバイスアクションを担当します。「Application」は中心サービス側で動作し、ビジネスオブジェクト、バインディング、ルール、タスク、およびドメインAPIを担当します。「Connector」はゲートウェイまたは中心サービスで動作し、MQTTやWebhookなどの通知およびデータ出力に使用される計画であり、現在は目標状態（ロードマップ）にあります。コア部分は特定のハードウェア向けにコードを書かず、新しいデバイスはDriverプラグインとして追加されます。参考ドライバのstcbおよびいくつかのアプリケーションプラグインは独立したリポジトリで公開されており、リポジトリ内にはGoプラグインテンプレート、サンプルアプリケーション、およびバイナリからホストまでのE2Eテスト用スキャフォールディングが提供されています。プラグインのインストール前には、Manifest、互換範囲、Releaseアセットとダイジェストの検証が行われ、バージョン、digest、ソースがロックファイルに記録されます。 クイックスタート Go、Node、pnpm、およびオプションでtaskをインストールした後、「task setup」で依存関係をプルし、「task build」で2つのバイナリを生成します。サーバーはデフォルトで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設定をそのまま公網に公開しないよう警告しています。認証情報には2つのモードがあります。共有サービストークンは互換パスであり、アカウントモードではセッションCookieによるログイン、admin/operator/viewerの3段階のロール、およびcp_で始まるテナントトークンを提供します。スコープはread、write、admin、edgeのサブセットであり、平文は作成時のレスポンスで一度だけ返され、データベースにはSHA-256と短いプレフィックスのみが保存されます。Secretはsecret://nameというハンドルの形式でサーバー設定と監査に現れ、平文はターゲットゲートウェイのローカルでプロバイダーによってのみ解析されます。プラグインはmanifestで明示的に権限を宣言する必要があり、サーバーは平文を保存せず、転送もしません。このほか、操作ホワイトリスト、パラメータの長さと文字制限、リクエストボディの上限、WebSocket読み取り上限、SPAパストラバーサル防止、操作およびログインのレート制限、および一連のセキュリティレスポンスヘッダーが実装されています。 デプロイとマルチゲートウェイ接続 公式ではコンテナに依存しない公網デプロイ手順を提供しています。まずビルド成果物のアーキテクチャをアサーションし（リリース行列にLinux arm64を含む）、systemdユニットを使用して専用の非rootアカウントでサービスを実行し、機密情報を0600の環境ファイルに配置します。最後にnginxリバースプロキシでHTTPSとWSSを提供し、WebSocket用にアップグレードヘッダーと長めの読み取りタイムアウトを設定します。認証は本製品自身が担当するため、リバースプロキシ層は公開状態を維持します。コンテナやCompose形式も利用可能ですが、ホストアーキテクチャがイメージと一致している必要があります。複数のPCを1つのサーバーに接続するのが一般的な用法です。管理者が各PC向けにedgeスコープのテナントトークンを作成し、WSSエンドポイント、トークン、および合意したedge_idをユーザーに渡します。ユーザーはReleaseから対応プラットフォームのバイナリをダウンロードし、checksumsで検証後、ローカル設定ファイルを記入して実行します。ゲートウェイは指数バックオフ再接続を備えており、オフラインイベントは有界バッファに入り、再接続後にリプレイされます。テナントを跨いだデバイス、イベント、操作、インスタンスは互いに不可視であり、1台のゲートウェイの切断が他方に影響することはありません。 テストとリリース テストはGoのユニットテスト、レース検出、フロントエンドの凍結インストールと型チェック、プラグインテンプレートフロー、および集約ゲートコマンドをカバーしています。リリースはバージョンタグによってトリガーされ、6つのプラットフォーム行列のビルドと統一されたchecksumsファイルの生成が行われます。リポジトリには、公開境界監査、Markdownリンクチェック、workflow構造チェックなどのスクリプトゲートも提供されています。 現在の境界 READMEでは現状と目標状態を明確に区別しています。Connectorと通知ランタイム、MQTTおよびModbus接続、リモートOTA、時系列集約、中心キー管理、分散クォータおよびマルチサーバーは未実装です。テナントトークンセッションはRESTのみで、ブラウザのリアルタイムチャネルはありません。同一の外部ドライバで複数の実機ボードを駆動し、抜き差しや操作回執をカバーする現場E2Eも未完了であるため、マルチボードリンクはプロトコルと実機での証拠が揃うまで検証済みとはみなされません。プロジェクトの原則として、「未実装の機能は現状として記載しない」としています。