API インタフェース設計

1. エージェント導入・セットアップ用 API

エージェント未導入のホストサーバーから、セットアップスクリプトを取得するための認証不要（No-Auth）のエンドポイントです。

1.1. インストールスクリプトの動的配信

GET /api/infra/nodes/install/:nodeId

対象サーバー上で cURL を用いて叩かれた際に、そのノード固有のIDと接続URLをパラメータに埋め込んだ Bash セットアップスクリプトをプレーンテキストで返却します。

1.2. 初期設定・APIキー取得

GET /api/infra/nodes/install/:nodeId/config

インストール中にスクリプトの内部処理から実行され、対象ノード向けに割り当てられた暗号化設定情報と API キー（一度限りの Raw データ）を返却します。

{
  "nodeId": "tokyo-db-01",
  "serverUrl": "https://meshconsole.example.com",
  "apiKey": "mc_key_9af3e16b710f7a9348e02b88137a89ff",
  "collectInterval": 10
}

2. エージェント向け API (Agent APIs)

エージェント(リモートノード)から送信され、認証にはノード用のAPIキーを使用します。 ヘッダに Authorization: Bearer <NODE_API_KEY> を付与します。

2.1. メトリクス・システム状態プッシュ

POST /api/agent/nodes/:id/metrics

システムのリソース使用率およびOS更新、VPN状態などのメタデータを報告します。

{
  "agent_version": "1.0.2",
  "cpu_percent": 12.45,
  "mem_percent": 45.12,
  "mem_used_gb": 3.61,
  "mem_total_gb": 8.0,
  "disk_percent": 62.4,
  "disk_used_gb": 124.8,
  "disk_total_gb": 200.0,
  "net_rx_mbps": 0.421,
  "net_tx_mbps": 1.254,
  "uptime_sec": 86400,
  "fail2ban": { "jail_count": 2, "banned_ips": 5 },
  "os_updates": { "security": 1, "regular": 4 },
  "ssh": { "active_sessions": 1 },
  "vpn": { "interfaces": ["wg0"], "active": true },
  "processes": [
    { "name": "node", "pid": 1234, "cpu": 4.2, "mem": 1.5 },
    { "name": "nginx", "pid": 567, "cpu": 0.2, "mem": 0.5 }
  ]
}

2.2. Docker コンテナ・イメージ状態プッシュ

POST /api/agent/nodes/:id/docker

エージェント上で動作している Docker コンテナとイメージのキャッシュ状態を報告します。

{
  "containers": [
    {
      "id": "a98b7c6d5e4f",
      "name": "web-nginx",
      "image": "nginx:alpine",
      "status": "running",
      "stateText": "Up 2 hours",
      "ports": [
        { "hostPort": 80, "containerPort": 80, "protocol": "tcp" }
      ],
      "composeProject": "my-web-app",
      "composeService": "nginx",
      "cpuPercent": 1.2,
      "memPercent": 8.5,
      "memUsedMb": 32.4
    }
  ],
  "images": [
    {
      "imageId": "sha256:7e01b3b5...",
      "repoTag": "nginx:alpine",
      "repository": "nginx",
      "tag": "alpine",
      "sizeMb": 23.5,
      "createdAt": "2026-06-01T00:00:00Z"
    }
  ]
}

2.3. 即時シグナル受信用 SSE 接続

GET /api/agent/nodes/:id/stream

エージェントが常時接続してサーバーからのコマンド実行通知を待機するストリームです。

3. コンソール (Frontend) 向け API

フロントエンド（ブラウザ）から送信され、ユーザー認証（JWT）が必要です。 ヘッダに Authorization: Bearer <USER_JWT_TOKEN> を付与します。

3.1. ノード一覧取得

GET /api/infra/nodes

3.2. ノード詳細情報・最新メトリクス取得

GET /api/infra/nodes/:id

3.3. セキュリティ & システム操作コマンド送信

一元管理タブから実行される各種セキュリティ/システム命令を、エージェントへキューイング・SSE送信します。

A. OSパッケージ更新の実行

POST /api/infra/nodes/:id/system/upgrade

B. SSH ログインセッションの強制切断

DELETE /api/infra/nodes/:id/system/ssh/sessions

C. Fail2ban IP ブロックの手動拒否 / 解除

POST /api/infra/nodes/:id/system/firewall/block (ブロック)
DELETE /api/infra/nodes/:id/system/firewall/block (解除)

D. VPN (WireGuard) 接続 of Up / Down 制御

POST /api/infra/nodes/:id/system/vpn/toggle