よくある質問

「まずバージョン、次にデータソース、最後に資格情報とキャッシュ」の順で切り分けます。エラーメッセージにパスワード・セッション・Agent 導入コマンド・第三者シークレットが含まれる場合、公開 Issue には貼り付けないでください。

システム更新に HTTP 429 が表示される

Worker が公式 GitHub Raw マニフェストの読み取りで上流のレート制限に当たった状態で、Agent の障害ではありません。1.0.38 以降、更新チェックは 6 時間の成功キャッシュ・並行リクエストのマージ・15 分の失敗バックオフを使用します。公式ソースが利用不可のときは直近の成功キャッシュを使い、コールドスタートではデプロイに同梱された信頼できる manifest を使います。

• 「現在のデプロイ版・キャッシュ結果を使用」は安全な降格です。
• 連続リフレッシュや再試行頻度の引き上げはしないでください。
• /api/health・/update-manifest.json・/bin/VERSION が同じバージョンか確認します。
• セルフホストの更新はデプロイリポジトリの NIE-SLA Online Update ワークフローで行われます。GitHub Token の入力欄は不要です。

*.workers.dev へのアクセスについて

セルフホストのデプロイは既定で *.workers.dev アドレスをそのまま利用できます — 新しいワンクリックデプロイには通常まだドメインがなく、これが主な入口です。カスタムドメインを接続したあと、この並行入口を残したくない場合（カスタムドメインのレート制限や保護を迂回するため）は、Worker → Settings → Variables and Secrets でテキスト変数 ALLOW_WORKERS_DEV = false を追加して保存してください。公式の本番サイトはさらに設定レベルで workers.dev ルートを無効化しています。パスも確認してください：公開ステータスページは /、管理画面の入口は設定した ADMIN_PATH（/admin ではありません）。

管理パス変更後に 404

ADMIN_PATH を保存すると、古い入口は即座に無効になります。「Worker URL + 新しいパス」で開き直してください。パスは認証ではありません。本当の境界はパスワード・短期セッション・任意の TOTP です。

Agent は公開済みなのにノードのバージョンが変わらない

Agent は更新ポリシーをポーリングするため、リリース作成と同時に全ノードが更新されるわけではありません。管理画面で agent_version・オンライン状態・Manager 状態を確認し、ノードで次を実行します。

sudo cftz status
sudo cftz log 100

極端に古いバージョンは現在の Manager や完全な検証チェーンを持たないことがあります。そのノード向けに生成された最新の導入コマンドを再実行してください。他のノードのコマンドは使い回さないでください。トークンは単一ノード専用です。

BusyBox ノードで NQ/IP が setpriv 引数エラーになる

1.0.49〜1.0.50 は GNU の setpriv --reuid/--regid 引数を BusyBox に渡していました。後の直接降権で起動は直りましたが、NQ の raw socket・遅延・ルートプローブの権限が失われ、「タスクは成功、遅延はすべて 0、戻り経路は NoData」となりました。v1.0.58+ へアップグレードしてください。NQ と IP アンロックは root 専用の Manager が直接実行し、nstatus-task・no_new_privs・ユーザー名前空間は使いません。通常メトリクス収集は非特権の nstatus サービスが実行します。Manager は固定 2 アクションのみ受け付け、スクリプト SHA-256・プライベートディレクトリ・シンボリックリンク禁止・固定 PATH・タイムアウト・出力上限を強制します。

v1.0.59 は NQ の深度チェック上限を 30 分から 60 分へ引き上げ、低速ディスクの VPS が HardwareQuality のディスク段階で早期終了しないようにしました。IP アンロックは 10 分のままです。

v1.0.64 以降、管理画面から NQ を実行するときは HardwareQuality（y/f/v/n）、IPQuality（y/n）、NetQuality（y/l/n）、戻り経路（y/n）をタスクごとに選択できます。単一ノード・バッチともリクエストに含まれます。NQ タスクに外部タイムアウトはなく、キュー期限は 7 日の猶予を保持します。

v1.0.66 は旧 Agent で一括 NQ が約 600 秒で exit 124 により終了する問題を修正しました。Worker は v1.0.64 より前の Agent へ 3600 秒の互換上限を再送し、v1.0.64+ の Agent は引き続き外部タイムアウトを持ちません。

v1.0.67 は一括 NQ/IP アンロックで「キューを確認」後にダイアログが閉じない・右下の通知がない・リフレッシュ後に一部 VPS が開始しない問題を修正しました。一括作成は 5 台ずつの並行に変わり、フロントエンドは直ちにダイアログを閉じてキュー投入中の通知を表示し、一括リクエストのタイムアウトは 60 秒に引き上げられました。

v1.1.0 は十進のバージョン番号へ移行し、1.1.0 を直接公開しました。バックアップのプレビュー/復元に低頻度の D1 レート制限を追加し、タスクタイムアウトの案内に「リクエストがサーバー側で実行中の場合があります。後でリフレッシュしてください」を追加しました。

v1.1.1 は NQ/IP アンロックタスクに強制停止を追加しました。キュー中のタスクは即時キャンセルされ、実行中タスクは新しい Agent がキャンセルフラグを検出するとスクリプトのプロセスグループ全体を終了します。テーブルと詳細ダイアログに「強制停止」ボタンと「停止中」状態を表示します。

v1.1.2 は公開ステータスと管理画面のアンロック情報も NodeQuality レポートを優先します。NQ がすべて解除済みでも古い IP.Check.Place の失敗表示に戻ることはありません。中国 は赤で表示され、ブロック・失敗・会員限定などのステータスも赤いバッジ内に表示されます。

v1.1.3 は Tencent Cloud など GitHub から NQ コンポーネントをダウンロードできない環境を修正しました。静的スクリプトは公式 GitHub ソースを維持し、ダウンロード失敗時は実測済みミラーへフォールバック、SHA-256 検証に失敗したら自動でソースを切り替えます。Agent タスク Runner にインスタンス帰属と 30 分のハートビートを追加し、重複した /api/agent/tasks GET ルートも修正しました。

v1.1.4 は NQ ダイアログに加速源（auto / EdgeOne 中国 / Cloudflare 海外）を追加しました。監査済みスクリプトは公開 NIE-Proxy 加速サービスを優先し、公式ソース・ミラーへ自動フォールバックします。SHA-256 検証は変わりません。

v1.1.5 は HardwareQuality が内部でダウンロードする Geekbench 5 パッケージも選択中の NIE-Proxy 加速経路を使用します。ホワイトリストに cdn.geekbench.com を追加しました。

v1.1.6 は NQ ダイアログから EdgeOne を削除し、「既定」と「Cloudflare 海外」だけを残しました。履歴の eo タスクは自動的に既定へフォールバックします。

v1.1.7 はアップロード API が本文解析前に認証するようになりました。当時の静的予算テストは基本トラフィックのみを対象としており、その後の本番データで Probe、Durable Objects、スケジューラ実行時間の過小評価が判明しました。100 台を保証する根拠にはできません。

v1.1.8 は & を含むターゲット ID を修正しました。Worker は元の ID・正規化 ID・スキャン一致の 3 層でターゲットを解決し、metrics、pings、config、location が元のターゲットに正しく反映されます。

v1.1.9 はメトリクス範囲を素早く切り替えたときのグラフ入れ替わりを修正し、TCP Ping と Latency の曲線をパケットロスで断線させ、管理画面のプローブ一覧を再レイアウトしました。

v1.1.10 はグラフツールバーに「端点連続」切り替えを追加しました。Latency と TCP Ping は既定でロス・失敗箇所で断線し、オンにすると空値をまたいで接続します。選択はブラウザに保存されます。

v1.1.11 は管理画面のプローブ一覧を従来のテーブル形式に戻し、前バージョンの過度に広い監視ブロックと余白を除去しました。情報密度と操作領域は 1.1.8 以前の状態に戻ります。

v1.1.12 はプローブ戦略全体を低頻度化しました：単発タイムアウト 3 秒、状態スナップショット 2 分ごと、地域遅延 3 分ごと、連続失敗ターゲットは 10 分ごとに自動降格。NQ レポート画像はエッジキャッシュを利用し、Agent タスクのキャンセルポーリングは固定 2 秒から 5〜10 秒のバックオフに変更、D1 集計キャッシュと新インデックスが導入されました。

v1.1.18 では 300 秒表示、WS 再利用、毎時 R2 バッファ、キャッシュ/304 をリリースし、v1.1.22 ではバッチ Ping API を追加しました。公開パネルは 1 回のリクエストで全 VPS の Ping 履歴を取得できます。実際の機能は対象デプロイの Manifest とリリース記録を優先してください。

IPv6 と Cloudflare プローブ

「Agent はオンラインなのに CF Latency が失敗する」のは通常、方向の問題です。Agent の報告は VPS の出方向ネットワークしか証明せず、Cloudflare が VPS のポートに接続できるかは別の経路です。要点：

• 管理画面のホスト欄に IPv6 を入れるときは [] を付けず、ポートはポート欄に入れます。
• リテラル IPv6 は Cloudflare に拒否されることがあります。同じアドレスで DNS-only の AAAA ドメインを試してください。
• オレンジ雲（プロキシ）は有効にしないでください。AAAA が Cloudflare プロキシアドレスを返し、Workers TCP Socket は Cloudflare IP への接続を禁止しています。
• 別のパブリック IPv6 から nc -6 -vz ドメイン ポート でリスニングとファイアウォールを確認します。

完全な切り分けはこのドキュメントの IPv6 トピックを参照してください。

NQ 画像が表示されない・古いデータのまま

• ネットワーク品質と戻り経路の画像は Worker がレンダリングしてアップロードします。画像ホストが失敗した場合、フロントエンドはテキストレポートにフォールバックし、タスクは失敗になりません。
• 公開画像 URL は同一オリジンのプロキシで、アップストリームの画像ホストは露出しません。
• 画像チェーンは公式の公益 Broker が担います。通常のデプロイは自前の NQ_IMGBED_URL/NQ_IMGBED_TOKEN を設定できませんし、設定も不要です。
• 設定が有効になった後に生成されたレポートだけが処理されます。古いレポートは自動再送されません。

External Latency ノードが「未報告」と表示される

ノードレコードの作成はデプロイではありません。確認するのは：そのノードの最新の完全なコマンドを正しいマシンで実行したか、インストール出力に accepted が含まれるか、サービスが active か、ログに 401/403/TLS/DNS エラーが続いていないか。旧ノードはサービス再起動ではなく、完全なコマンドで再インストールしてください。

ブラウザから公開 API を呼ぶと CORS エラー

curl は成功するのにブラウザだけ失敗する場合、オリジンが DEVELOPER_API_ORIGINS にありません。完全なオリジン（https://status.example.com）を、パスなし・* なしで追加してください。本番は HTTPS 必須で、HTTP はローカル開発アドレスのみ許可されます。

バックアップと復元

• 復元前は必ずプレビューし、確認語を入力します。マージと置換に対応しています。
• 復元前に Worker が R2 スナップショットを自動保存します。失敗時はスナップショットを保持してログを確認し、連打しないでください。
• 機密バックアップの Agent Token は復元時に再カプセル化されるため、アカウント移行後も元ノードは認証を継続できます。
• 通常バックアップに Token は含まれません。高頻度履歴は JSON に含まれないため、移行時は元の R2 を再利用します。

ディスク容量の表示

agent_metrics.vps_info.total_disk_gb はシステムのルートファイルシステム容量であり、マウントの合計ではありません。同一デバイスのバインドマウントは二重計上されません。

テーマと Canvas テーマ

現在のバージョンで開放されているのはテーマパッケージのみで、プラグインランタイムはありません。配色と余白だけの変更は CSS テーマ、公開ページのレイアウト・操作・チャートの全面書き換えは Canvas テーマを使います。Canvas テーマは同一オリジンアクセスのないサンドボックス iframe で動作し、メッセージプロトコル経由で公開状態のみ読み取れます。ネットワークやホストページへ直接アクセスできません。

• アップロード後は既定で無効化され、管理者が SHA-256 を確認して手動で有効化します。無効化するとすぐに元の UI に戻ります。
• type: "plugin" の ZIP は配布しないでください。旧チュートリアルのプラグインアップロードやプラグインメッセージプロトコルは、現在の本番機能として一度も開放されていません。
• 独立パネルは公開 v1 API を利用し、独立ドメインにデプロイして、正確な DEVELOPER_API_ORIGINS を設定してください。

無料枠

エコノミーモードは、正常ターゲットと Agent バッチを 15 分、タスク取得を 10 分、通常の更新確認を 1 日、障害ターゲットの再試行を約 2 分に設定します。旧 5 分モデルより 100 VPS の Requests と Unbound を大きく削減しますが、メトリクスは最大 15 分遅れることがあります。Workers・Durable Objects・D1・R2 のアラート監視は引き続き必要です。

現状（1.1.93）：Agent テレメトリバッファとプローブ履歴は共有 Durable Object に統合され、D1 書き込みはバッファ失敗時のフォールバックのみです。実際の 5 分間隔では Workers・Durable Objects・D1・R2 はすべて無料枠内に収まっています（最も厳しいのは D1 の行読み取り）。正確な比率は使用量モデルと対象デプロイの Cloudflare 請求で確認し、旧来の静的な 100 台予算で外挿しないでください。

Cloudflare / Fastly / Akamai に到達できないノード

一部のネットワークでは Cloudflare 系 CDN に到達できず、インストール・報告・自動更新が失敗します。サイトに到達できる任意のマシンで純粋な TCP リレーを立てます（TLS/SNI/Host はそのまま透過 — ドメイン・証明書・CDN は不要）：

sudo apt install -y socat
sudo systemd-run --unit=nie-sla-relay socat TCP-LISTEN:443,fork,reuseaddr TCP:sla.niekaixiang.com:443

ファイアウォールで 443 を対象ノードの IP だけに許可し、再起動後は同じユニットを再作成してください。制限されたノードで 2 つの公式ホスト名をリレー IP に向けてから、管理画面が生成したインストールコマンドを実行します：

echo "<relay-ip> sla.niekaixiang.com api-sla.niekaixiang.com" | sudo tee -a /etc/hosts
curl -fsS https://sla.niekaixiang.com/api/health

TLS 検証・Host・更新ダウンロード先はすべて公式ドメインのままなので、報告・タスク・WebSocket・自動更新がリレー経由で動作します。IPv6 か代替ポートのみ到達可能な場合は、先に curl -6 -fsS https://<domain>/api/health や curl -fsS https://<domain>:8443/api/health を試してください。

インストーラーは --token を受け付けなくなりました（1.1.65 以降）

トークンが ps やシェル履歴に残らないよう、setup.sh・install-mac.sh・quick-install.sh は --token を拒否し、環境変数か対話入力を使うよう案内します：

NIE_SLA_AGENT_TOKEN='...' sudo -E bash setup.sh --non-interactive

管理画面が生成するワンクリックコマンドは環境変数とワンタイム資格情報を使うため影響ありません。

プロキシ検測がずっとオフライン／タイムアウトする

まず対象の「実行 Agent」のバージョンを確認してください。1.1.53 以前には 1.1.57 の Reality ハンドシェイクバッファ修正が含まれず、Reality ノードはちょうど 5 秒で stage=connect / timeout になります（ハンドシェイクと初回バイトは -）。実行ノードを v1.1.57+ に更新する（生成されたデプロイコマンドを再実行）か、更新済みのノードに「実行 Agent」を変更してください。それでも全サンプルが失敗する場合は、共有リンクとパラメータ（Reality 公開鍵と Short ID は必須）を再確認してください。

管理画面に新バージョンが出ているのに更新されない

ワンクリックデプロイのオンライン更新は、デプロイリポジトリの GitHub Actions にある NIE-SLA Online Update ワークフローが実行し、6 時間ごとに公式安定版を確認します。Worker 内部では動作しないため Worker 自身は更新できず、管理画面の「システム更新」カードは現在のバージョンと最新バージョンを表示するだけです。

Actions ページが「Get started with GitHub Actions」（ワークフローが一つも無い）場合、ワンクリックデプロイがワークフローをリポジトリへコピーしていません。ブラウザで一度だけインストールしてください（更新ロジックは常に公式リポジトリ側にあるため、以後この作業は不要です）：

1. デプロイリポジトリの Actions タブを開き set up a workflow yourself をクリック；
2. 下記を貼り付けて Commit changes；
3. その後、左側で NIE-SLA Online Update を選び Run workflow。

name: NIE-SLA Online Update
on:
  workflow_dispatch:
  schedule:
    - cron: "17 */6 * * *"
permissions:
  contents: write
jobs:
  update:
    uses: 3257085208/NIE-SLA/.github/workflows/nie-sla-update.yml@main

古いバージョンのままの場合、順に確認してください：

1. Actions が有効か：リポジトリ → Settings → Actions → General でワークフローの実行を許可（新規・フォークしたリポジトリでは無効なことがあります）。
2. 実行履歴があるか：Actions タブに「NIE-SLA Online Update」の定期実行が表示されるはずです。まったく無い場合は上記のインストール手順を実施；インストール後は Run workflow で即時実行できます。
3. 失敗ログを確認（失敗した実行の最後のステップ）：
   • no online-update baseline：リポジトリの内容が公式の基準と一致していません。一度手動で同期してください；
   • Deployment files differ from the official … baselines：公式版以外の変更があります（wrangler.jsonc のみ差異が許可されます）；
   • 依存関係・ビルドのエラー：最新ブランチから再実行してください。
4. Cloudflare のビルドを待つ：ワークフローが push した後、Cloudflare Workers Builds のビルドに約 1〜3 分かかります。管理画面を強制再読み込みし「更新を確認」を押してください。

GitHub Actions を使わない場合は手動更新も可能です：リポジトリを最新の公式版へ同期して npm run deploy を実行するか、最新テンプレートでワンクリック再デプロイしてください（最新の Durable Object バインディングと内部シークレットも反映されます）。