アーキテクチャ

NIE-SLA は、収集・プローブ・保存・表示・第三者拡張をそれぞれ異なる信頼ゾーンに分けています。この境界を理解することで、「VPS がオンライン」「Cloudflare から到達可能」「外部ノードの遅延」を同じデータとして混同しなくなります。初めての方はプロジェクト概要からお読みください。

コンポーネント

コンポーネント	実行場所	役割
Rust Agent	監視対象 VPS	秒単位サンプリング、TCP/HTTP プローブ、バッチアップロード
Latency Agent	独立した Linux ノード	他のネットワークから公開 TCP ターゲットをプローブ
Worker	Cloudflare エッジ	ルーティング、認証、スケジューリング、集約、アラート、公開 API
Durable Objects	Cloudflare	リージョンプローブの調整、Agent ごとのテレメトリバッファ
D1	Cloudflare	設定、状態、集約、イベント、インデックス
R2	Cloudflare	高頻度履歴、スナップショット、アーカイブ、テーマパッケージ
Worker Static Assets	Cloudflare	公開ステータスページ、管理 UI、同一オリジンの API

本番は 1 つの Worker が API と Static Assets を同一オリジンで提供します。別途 Pages プロジェクトは不要です。公開ワンクリックリポジトリはサニタイズ済みの公開ソースであり、Worker・Frontend・Agent のソース境界を維持し、アーカイブや公開コピーから本番ソースを上書きしないでください。

データ経路

Rust Agent --scoped token--> Worker --> D1 / R2 --> 公開ステータス
                                     |
Cloudflare プローブ ----------------+
                                     |
Latency Agent --scoped token--------+

サンプリング・アップロード・Ping・更新チェックはそれぞれ別のスケジューラで動作します。VPS は毎秒サンプリングできますが、Worker が受け取るのはバッチ単位です。ネットワークが遅くてもローカルのサンプリングはブロックされません。

4 種類の遅延とオンライン状態

ソース	開始元	答える質問
Cloudflare プローブ	Worker / Durable Object	Cloudflare エッジからターゲットへ接続できるか、遅延はいくらか
Agent オンライン状態	監視対象 VPS	メトリクス Agent が直近に報告を続けているか
Agent ネットワークプローブ	監視対象 VPS	ホストから TCP/HTTP ターゲットへのネットワーク品質
外部 Latency	独立ノード	追加リージョン・プロバイダから公開 TCP ターゲットへの遅延

クライアントはソースラベルを保持してください。Agent がオンラインでも Cloudflare プローブが成功するとは限らず、ポートが開いていてもメトリクス Agent が動いているとは限りません。

ストレージ戦略

毎秒の生メトリクスを D1 に書き込むことはしません。

• 現在状態とインデックスは D1 に置きます。
• 高頻度履歴はまず R2 へ。
• SLA 履歴は固定バケットに集約して D1 へ。
• トラフィックは現在の期間行に累積し、日をまたぐときは Agent ごとに日次台帳を 1 行封鎖します。リセット日の変更は日次台帳から再集計します。
• 状態エンドポイントは短いキャッシュを使います。
• クリーンアップはリクエストごとではなくスケジュールで実行します。

これにより公開状態の鮮度を保ちつつ、Worker リクエスト・D1 書き込み・R2 操作の量を抑えています。

生のロスデータと任意の時系列エクスポート

R2 は Agent が報告した生のプローブポイントを保持します。通常の遅延カーブは公開 API の上限に従ってダウンサンプリングされます。include_loss=1 はすべてのロスイベントをコンパクトな runs として無損失で返すため、長時間の障害でもブラウザで秒単位のオブジェクトを展開する必要がありません。

外部時系列エクスポートは既定でオフです。TIMESERIES_EXPORT_URL を設定すると、Worker が Agent と完了時間ごとに R2 からバッチをエクスポートします。TIMESERIES_EXPORT_FORMAT は victoriametrics（既定）または influx で、Bearer 資格情報は TIMESERIES_EXPORT_TOKEN で任意指定します。URL は資格情報を埋め込まない HTTPS でなければなりません。これらの値は Worker Secret またはデプロイ環境からのみ提供され、フロントエンド・Agent コマンド・公開 API・バックアップ・ソースに一切入りません。

エクスポートは回数制限付きの再試行マーカーを使用します。リモートのタイムアウト・スロットリング・利用不可があっても R2 アーカイブと Agent ACK は成功し、再試行上限到達後はそのエクスポート試行だけが破棄されます。R2 データは失われません。エクスポート未設定なら外部リクエストは追加されず、100 VPS のストレージ経路は変わりません。

インターフェースと信頼境界

インターフェース	認証	できること
/api/v1/*	なし	サニタイズ済みの公開状態と履歴の読み取り
/api/agent/*	ノード scoped Token	対応する Rust Agent の報告とポリシー取得
/api/latency-agent/*	ノード scoped Token	遅延ノードのターゲット取得・報告・更新
管理 API	短期セッション、任意 TOTP	設定変更、テーマアップロード、管理データの読み取り

Canvas テーマと代替フロントエンドは公開 v1 API のみ使用できます。管理セッション・パスワード・TOTP・Agent マスタートークン・ノード scoped Token をテーマに渡さないでください。プラグインランタイムは開放されていません。

パスワードと GitHub OAuth チケットはログイン専用です。ログイン後の管理 UI は短命の x-admin-session を使用します。パスワードを API トークンとして保存したり、代替フロントエンドがプロキシしたりしてはいけません。Agent と遅延ノードはノード単位の scoped Token を使い、ノードを無効化するとトークンは機能しなくなります。

NodeQuality 画像の境界

NQ Network と Return Route の画像は、認証済みタスクの完了後に Worker がレンダリングしてアップロードします。アップロードチェーンは固定の S3 チャネル（フォルダは空）です。フロントエンド・Agent・管理 API はアップロード URL・トークン・チャネル・フォルダを読み取ることも上書きすることもできません。

• アップロード URL・トークン・任意のチャネル名は Worker Secret のみです。
• 管理者が作成し、対応する Agent 資格情報が引き受け、正常完了したタスクだけがアップロードを発火します。
• ブラウザ設定・テストアップロード・任意ファイルアップロードのエンドポイントはありません。
• 公開 NQ JSON は同一オリジンの画像プロキシのみを返します。実際のアップストリーム URL は Worker 内部で解決されます。
• 通常バックアップは古い画像ホストメタデータを含みません。機密バックアップはパスワード暗号化されます。
• セルフホストデプロイは画像ホスト資格情報なしで固定の公式公開 Broker を呼びます。共有資格情報は公式 Worker Secret にのみ存在し、ソース・ビルド成果物・チュートリアル・Broker リクエストには一切入りません。

Broker は上限付きの network/route テキストを受け付け、SVG をサーバー側で再レンダリングし、D1 経由でソース単位・グローバルにレート制限します。これによりセルフホスターは設定なしで NQ 画像バックアップを得られ、共有画像ホストが任意アップロード API 化することもありません。非公式インスタンスは自前のシークレットで固定の公開チェーンを上書きできません。

4 つの NQ タブは元の ANSI 内容を保持します。Network と Return Route は元テキストが存在する場合に従来のセグメントレンダラーを使い、Broker 画像はテキストのない古いデータを補完するだけです。モバイルは固定のコンパクト等幅フォント、モーダルは縦スクロールのみ、幅広ネットワークセグメントはコンテンツ領域内で横スクロール、Return Route ホップはレスポンシブグリッドです。公開ページと管理 UI は同じルールを共有します。

現在状態と長期 SLA

Cron は現在のプローブ・アラート状態を毎分更新します。長期 SLA と日次グリッドは 5 分バケットのままです。FAST_STATUS_ENABLED がオフの場合、アクティブプローブ状態はバケット粒度にフォールバックします。

「公開ページの最新状態」と「日次グリッドの新しいセル 1 つ」は同じ頻度である必要はありません。統合側は配列の長さから生存を推測するのではなく、checked_at・updated_at・ソースフィールドを読んでください。

テーマランタイム

CSS テーマは検証済みスタイルシートのみを読み込みます。Canvas テーマは同一オリジンアクセスのない sandbox="allow-scripts" iframe で動作し、CSP が直接のネットワーク・フォーム・トップレベルナビゲーションを遮断します。データは制限付きメッセージプロトコル経由で届きます。プラグインアップロード API とプラグインランタイムは開放されていません。テーマシステムとセキュリティとリリースを参照してください。