インフラヘルスボード — InfraGuard マニュアル

概要 — 何をする画面か

インフラ ▸ ヘルス（/infra/health）は、稼働中の全ノードの健全性をカードグリッドで一目で示す可用性運用ダッシュボードです。stats-design の ./server/stat 画面を再実装したもので、性質の異なる2つのデータ経路を1枚のカードに統合します。

メトリクススナップショット — run_report コレクターが約5分ごとに server_status（レガシーテーブル）へ書き込む、最新の負荷／CPU／メモリ／ディスクの値です。アプリは20秒キャッシュから読み取ります（リモートへの直接接続はありません）。
ライブサービスプローブ — 各ノードに配置された tlx.php エージェントをリアルタイムに呼び出し、nginx / php / mysql / mongo のデーモンが起動しているかをその場で確認し、Docker コンテナを一覧します（TlxClient）。

ノード一覧とエイリアス（ALIAS_MAP）は、管理 ▸ コレクターにある run_report コレクターの設定（infr_collector.config）から自動的に読み込まれます — サーバーごとの設定は不要です。

各カードは、ヘッダーに小さくノード情報、その下に CPU リングゲージ（中央にロードアベレージ）、MEM／DISK バー、最下部にサービス状態のドットを表示します。

この画面は読み取り専用の運用画面です。ノード・エイリアス・tlx api_key をここで編集することはありません — いずれもコレクターにあります。

利用シーン

朝の点検 — 全ノードがオンラインで、負荷／メモリ／ディスクが健全な範囲にあるかを30秒でスキャンします。
インシデント対応 — 特定のサーバーで nginx や mysql が停止していないかを、ライブプローブで即座に確認します。
キャパシティ監視 — ディスク使用率がしきい値（80%／92%）に近づいているノードを色で見つけます。
Docker ホストの点検 — プローブ結果フッターの Docker コンテナ数バッジでコンテナの生存を確認します。

推移（時系列）の分析はサーバー時系列、RAID コントローラーの健全性と物理ディスクマップはストレージ・RAID を参照してください。

レイアウト

ヒーロー（上部バー）

要素	意味
コレクターバッジ	`run_report` コレクターのタイトル＋ノード数＋ ALIAS マッピング数
鍵アイコン	`tlx api_key` が設定されているか。🔑（緑）＝設定済み · 🔑❗（グレー）＝未設定のためサービスプローブは利用不可
コレクター設定ボタン	コレクター（`/admin/collectors`）へ移動します
更新ボタン	メトリクスを再読み込みし、全ノードのライブプローブを再実行します

run_report コレクターが存在しない場合は、カードグリッドの代わりに「run_report コレクターが登録されていません」という案内と設定ボタンが表示されます。

ノードカード

┌──────────────────────────────────────┐
│ ⠿ ●  glory                     ⟳(probe)│  ← ヘッダー: グリップ · オンラインドット · ラベル/エイリアス/IP
│      glory · 203.0.113.10              │
│                                        │
│            ╭───────────╮               │
│            │    0.84    │  ← CPU リング (色=CPU%)、中央=load
│            │    load    │
│            │  CPU 12%   │
│            ╰───────────╯               │
│  🧠 MEM  ▓▓▓▓▓▓░░░░  63%                 │  ← MEM バー
│  💽 DISK ▓▓▓▓▓▓▓▓░░  81%                 │  ← DISK バー
│  ● nginx ● php ● mysql ● mongo          │  ← サービスドット (ライブプローブ)
│  🐳 4                                   │  ← Docker コンテナ数 (プローブ成功時)
└──────────────────────────────────────┘

オンラインドット（ヘッダー左） — 直近2回の収集サイクル以内にノードが loadavg を報告していればオンラインです。そうでない場合、カードは暗くなり（is-offline）、「オフライン（最近の報告なし）」と表示されます。
CPU リングゲージ — リングの塗りと色は CPU us%、中央の大きな数値はロードアベレージ（1分）、その下の小さな文字が CPU % です。
MEM／DISK バー — 使用率（%）で、しきい値に応じて色が付きます。
サービスドット — nginx / php / mysql / mongo の4つです。色はプローブ結果に従います（表を参照）。
Docker バッジ — プローブが成功しコンテナがある場合はコンテナ数を、失敗した場合は「プローブ失敗（到達不可）」を表示します。

しきい値（配色ルール）

メトリクス	good（緑）	warn（アンバー）	crit（赤）
CPU us%（リング）	< 60	≥ 60	≥ 85
MEM %（バー）	< 80	≥ 80	≥ 92
DISK %（バー）	< 80	≥ 80	≥ 92

値が欠けている場合（—）はグレー（na）で描画されます。

サービスドットのトーン

トーン	条件
`up`（緑）	プローブ成功＋そのデーモンのプロセス数が 0 より大きい
`down`（赤）	プローブは成功したがプロセス数が 0、またはプローブ失敗
`unknown`（グレー）	未プローブ、または応答にそのサービスキーが含まれない

使い方

1. メトリクスの更新（自動＋手動）

カードのメトリクスは30秒ごとに自動ポーリングされます（GET /infra/health/refresh）。サーバー側の20秒キャッシュにより負荷は軽微です。
上部の更新ボタン（⟳）は、メトリクスを再読み込みし、全ノードのライブプローブを時間差の順序で再実行します。

2. 単一ノードのライブプローブ

カードヘッダー右のパルス（⟐）ボタンは、そのノードだけを即座にプローブします（POST /infra/health/probe、ボディは {alias}）。ページの初回読み込み時に tlx api_key が設定されていれば、全カードが250 ms 間隔の時間差で自動プローブされます（バーストを避けるためです）。

プローブが成功すると、カードはサービスドットだけでなく、応答に含まれるその時点の負荷／CPU／MEM／DISK の値も反映します。

サービスドットがすべてグレー（unknown）の場合、たいていは tlx api_key が未設定です。ヒーローの鍵アイコンを確認してください — 🔑❗ であればプローブはまったく実行されません。

3. カードの並べ替え（ドラッグ）

カードヘッダー左のグリップ（⠿）をつかんでドラッグすると並べ替えられます。順序はブラウザーの localStorage（infr:order:infra-health）に保存され、再訪時も維持されます。カードは高さが可変のメーソンリーレイアウトで、1ページあたり10件でページングされます。

データソース

メトリクス — `server_status`（レガシー・読み取り専用）

HealthService::metricsByAlias() は legacy 接続から読み取ります。スロークエリを避けるため、テーブル全体を集計せず、直近の seq ウィンドウに絞り込みます。

-- 1) 直近3件の seq のみ（distinct = インデックススキャン）
SELECT DISTINCT seq FROM server_status ORDER BY seq DESC LIMIT 3;

-- 2) それらの seq について、対象の part のみ
SELECT server_alias, part, value, seq, created_at
  FROM server_status
 WHERE seq IN (:s1, :s2, :s3)
   AND part IN ('loadavg','free','top','df-','df-data','df-home')
 ORDER BY seq;   -- 昇順 → 後の行ほど新しい

run_report コレクターの格納規約は次のとおりです。

part	意味	形式	カードへの対応
`loadavg`	負荷（1分）	数値	load（ゲージ中央）
`top`	CPU us%	`"NN%"`	CPU リングの塗り
`free`	メモリ %	`"NN%"`	MEM バー
`df-data` / `df-` / `df-home`	ディスク	JSON `{p,u,a}`	DISK バー（p=%、u=使用量、a=容量）

オンライン判定 — 直近2件の seq のなかに loadavg が現れればオンラインです。
ディスクの優先順位 — df-data → df- → df-home の順で、最初に有効だったものを採用します。
キャッシュキーは infr:health:metrics:v1、TTL は 20秒です。クエリ中に例外が発生した場合は空配列へグレースフルに縮退します。

ノードの解決 — `infr_collector.config`

HealthService::resolveNodes() は run_report コレクター（InfrCollector::where('key','run_report')）からノードを導出します。

優先度	ソース（`node_source`）	説明
1	`config`	`config.nodes[]` があればそのまま使用します（各ノードは `url`·`alias`·`label`·`ip`）
2	`instance`	空の場合はインスタンス台帳（`infr_instance`、60秒キャッシュ）から実行時に導出します
—	`none`	どちらも空ならノードはありません

config.alias_map のエントリ数が、ヒーローの「ALIAS」バッジとして表示されます。

サービス状態 — `tlx.php` ライブプローブ（`TlxClient`）

HealthController::probe() はエイリアスでノードを検索し（任意ホストへのプロキシを防ぎます）、TlxClient::probe() を通じてそのノードの tlx.php を呼び出します。

モード — check_all（既定）または check_multi で、config.mode（旧 tlx_mode）によって決まります。
パス — config.path（旧 tlx_path）で、既定は /tlx.php です。
タイムアウト — 接続は最大4秒／全体で6秒です。到達不可・タイムアウト・JSON 解析失敗は、いずれも {ok:false, reason:...} へグレースフルに縮退します。

カード向けに正規化した tlx.php の check_all 応答の形は次のとおりです。

{
  "ok": true,
  "load": 0.84,
  "cpu_us": 12.0,
  "mem_pct": 63,
  "disks": [ { "mount": "/data", "pct": 81, "used": "1.6T", "size": "2.0T" } ],
  "services": { "nginx": {"count":4,"up":true}, "php": {"count":8,"up":true}, "mysql": {"count":1,"up":true}, "mongo": {"count":0,"up":false} },
  "docker": [ "web", "redis", "worker", "cron" ]
}

tlx api_key は infr_collector から（Laravel の Crypt で）復号され、サーバー側でのみ使用されます。ブラウザーへ返されることはなく、ハードコードもされません。リモートノードへ送られるのは署名済みの q の値だけです。

エンドポイント一覧

メソッド · パス	名前	用途
`GET /infra/health`	`infra.health`	ページ（ブートストラップ付き）
`GET /infra/health/refresh`	`infra.health.refresh`	メトリクススナップショットのポーリング（JSON）
`POST /infra/health/probe`	`infra.health.probe`	単一ノードのライブプローブ（`{alias}`）

アクセス権限

読み取り（表示・プローブ） — この画面は infr.auth グループの配下にあり、認証済みのコンソールユーザーであれば誰でもアクセスできます（レベル1以上／デモ）。インフラ役割領域の最小レベルは1です。
書き込みなし — ヘルス画面そのものに破壊的な操作はありません。ノード・エイリアス・tlx api_key の変更はコレクターで行い、**管理者（レベル5以上、admin=10）**に限定されています。
プローブは登録済みのノードエイリアスのみを対象とするため、任意のホストへのプロキシには利用できません（SSRF 安全）。

トラブルシューティングと FAQ

カードが1枚も表示されず、「run_report コレクターが登録されていません」と出る

キーが run_report のコレクターがありません。コレクターで access=web・key=run_report として登録してください。

「ノードが登録されていません」と出る

run_report コレクターは存在しますが、config.nodes が空で、infr_instance 台帳も空です。コレクターのノード配列を埋めるか、インスタンスにサーバーを登録してください（config.nodes が空のときはインスタンスからノードが自動導出されます）。

メトリクスが `—`（ダッシュ）ばかり表示される

server_status に直近のスナップショットがありません。run_report コレクターが実際に cron で動作していること、そしてノードのエイリアスが server_status.server_alias と一致していることを確認してください。オンライン判定は直近2件の seq で行われます。

サービスドットがすべてグレー

ヒーローの鍵アイコンが 🔑❗（未設定）であれば、コレクターで tlx api_key を設定してください — 未設定のあいだプローブは実行されません。
カードのプローブボタン（⟐）を押して応答を確認します。「プローブ失敗（到達不可）」であれば、ノードの url、ファイアウォール、tlx.php の配置を確認してください。

プローブだけが失敗し、負荷やメモリは正常に見える

メトリクス（server_status）とプローブ（tlx.php）は独立した経路です。コレクターの DB 取り込みは正常でも、ノードの tlx.php HTTP エンドポイントがブロックされています（ファイアウォール／パス）。config.path（既定 /tlx.php）とノードの url を確認してください。

ディスクの % が想定と違う

表示されるディスクは df-data → df- → df-home の優先順位で選ばれます。複数ボリュームがある場合はデータボリューム（df-data）が優先されます。