サーバーに接続

Add Server Wizard は、RoqueOSフロントエンド（https://roqueos.com.br/app）をRoqueOS Serverに接続するための公式パスです。Settings → Server → サーバーを追加 にあります。

ユーザーがブラウザで <server>:27021/admin を開く必要があった古いフローを置き換えます。今、すべてがアプリ内で行われます。

いつ使用するか

• ✅ 新しくインストールされたサーバー（install.sh 実行済み、API Keys まだなし） — wizardが最初のadminキーを作成
• ✅ 既に使用中のサーバー（apiKey + apiSecret 保存済み） — wizardが検証してリストに追加
• ✅ サーバー切り替え — 2番目のサーバーを追加、メニューバーのスイッチャーで切り替え

ブートストラップフロー（ゼロのサーバー）

7ステップ。合計時間: ~1分。

Step 1 — URL

サーバーのURLを貼り付けます。受け入れる:

• http://localhost:27021（マシンで実行中のDocker — loopback経由で動作）
• https://server.example.com（Cloudflare TunnelまたはTLS証明書の後ろ）

Wizardはプロトコルを正規化（server.example.com → 自動的に https://server.example.com）し、進む前に既存のサーバーを検出します。

⚠️ HTTP vs HTTPS — ブラウザの制限

フロントエンド roqueos.com.br/app はHTTPSで実行されます。モダンブラウザの設計（Mixed Contentポリシー）により、HTTPSページは HTTP APIを呼び出せません — ブラウザはマシンを離れる前にリクエストを静かにブロックします。

これは http://192.168.1.50:27021（LAN）または http://server.com:27021（パブリック）への接続を試みると 「connectできない」で失敗 することを意味し、サーバーのバグのように見えますが、実際にはブラウザがブロックしています。

Wizardはこれをあなたのために検出 し、リクエストが実行される前に問題を説明する黄色のバナーを表示します。優先順位の3つの解決策:

1. Cloudflare Tunnel経由のHTTPS（推奨）

無料、プラグアンドプレイ。install.sh には組み込みサポートがあります:

curl -fsSL https://roqueos.com.br/install.sh | bash -s -- --update
# その後: Settings → Server → Cloudflare Tunnel → 接続

結果: サーバーは https://<id>.cloud.roqueos.com.br またはあなた自身のドメインになります。自動TLS、firewallをいじる必要なし、パブリックIP必要なし。

install.sh + Cloudflare Tunnelの完全ガイド →

2. デスクトップまたはモバイルアプリを使用

ネイティブラッパー（Microsoft Store、Play Store、App Store）には 混合コンテンツ制限がありません — 厳格なHTTPSのwebページではなく、ネイティブコードを実行します。

• 🪟 Microsoft Store (Windows)
• 🍎 App Store (iOS/macOS)
• 🤖 Google Play (Android)

適しているのは: tunnelを設定したくない/できないホームラボ環境。

3. localhost上のサーバー（loopback）

http://localhost:27021、http://127.0.0.1:27021、http://[::1]:27021 は、モダンブラウザによって Secure Contexts spec を介して 安全なコンテキストとして扱われます — そのため、HTTPSフロントエンドでも動作します。

適しているのは: ローカル開発、実際のサーバーにアップロードする前のテスト。

Step 2 — Detect

Wizardは2つの匿名エンドポイントを並列でヒット:

• GET /health/version-info — バージョン + minClientVersion
• GET /admin/setup — { needsSetup: true } を返す場合、サーバーゼロ

ここでバージョンの互換性もチェック。サーバーが v1.0.10 だがクライアント（フロントエンド）が v1.0.13+ を要求する場合、「最初にサーバーを更新」の友好的な警告 + install.sh --update へのリンクを表示。

Step 3 — Bootstrap（ゼロのサーバー）

「adminキーを作成」ボタン → POST /admin/setup（セットアップレースを避けるためサーバーでIPによってレート制限）。

{ apiKey, apiSecret } を返し、wizardが次のステップで表示します。

レース処理: 2つのブラウザが同時にセットアップを試みると、2番目は error: 'Setup already completed' を受け取り、wizardはステップ5（手動credentials）に移行します。

Step 4 — keyCreated

返された apiKey + apiSecret を コピーボタン付きの読み取り専用フィールド で表示。

⚠️ 重要なUXガード:

• モーダルに closeOnBackdrop=false（外側をクリックしても閉じない）
• Xボタンが確認サブモーダルを開く（「credentialsを保存しましたか？」）
• 必須のチェックボックス 「credentialsを保存しました」 がNextボタンを有効化
• 保存せずに閉じると、キーはサーバーに残りますがあなたには失われます — リカバリーは /admin HTMLレガシー経由のみ

Step 5 — credentials（サーバーが既に設定されている）

ステップ2で検出がセットアップが既に行われたことを指摘した場合、ここに直接スキップ:

• フィールド apiKey
• フィールド apiSecret
• リンク「サーバーのadminパネルを開く ↗」（新しいタブで <server>/admin HTMLレガシーを開く）

レガシーページは引き続きリカバリーと自動化のバックドアとして機能します。

Step 6 — 名前

唯一のフィールド: サーバーの友好的な名前（メニューバーのServer Switcherに表示）。

提案されたデフォルト: URL.hostname（例: demo.level-hard.com または localhost）。

Step 7 — 最終化

Wizardが呼び出す:

• addBackendService({ name, url }) — backendSettings.services リストに保存
• setApiCredentials(apiKey, apiSecret, serviceId) — Firestoreに認証情報を保存
• setActiveBackendService(serviceId) — アクティブにする

モーダルが閉じます。サーバーが接続されています。あなたはServer Modeにいます。

Server Switcher（メニューバー）

2つ以上のサーバーが登録されている場合、メニューバー（左上隅）にアクティブなサーバーを表示するドロップダウンが表示されます。クリックして切り替え。

現在のステータス（2026年5月）: コンポーネント ROSServerSwitcher は以前のセッション後にまだ再構築されていません — 機能は計画されていますが、まだ出荷されていません。今のところ、サーバー間の切り替えは Settings → Server → 目的のサーバーをクリック経由です。

公開デモサーバー

マシンに何もインストールせずにServer Modeをテストするには、RoqueOSにはすでに 事前構成された公開デモサーバー が付属しています:

1. https://roqueos.com.br/app でログイン
2. Settings → Server に移動
3. DEMO サーバーがすでにリストに表示されます — クリックしてアクティブ化

URL、apiKey、apiSecretを貼り付ける必要はありません — credentialsはクライアントに埋め込まれており、直接動作します。

デモとは: RoqueOS Serverの実際のインスタンスで、設立者によって更新され、毎日のクリーンアップ（孤立コンテナ、>24hのagents/sessions、ぶら下がっているボリューム）。制限:

• 非管理者はServer Admin Panelを見ません（セキュリティゲート）
• Cloud Gamingはゾンビセッションをパージできます
• コンテナはpruneの前に~24h残ります
• すべての訪問者間で共有

適しているのは: Containers、Terminal、組み込みVS Code、Filesの探索。適していないのは: 長期持続性、機密または重要なデータ — RoqueOSにログインしている誰かが同じデモを並行して使用している可能性があります。

実際の使用には、one-liner で自分のサーバーをインストールしてください。

トラブルシューティング

症状	解決策
「サーバーにアクセスできません」	curl <url>/health が200を返すことを確認。おそらくポート27021が解放されていないか、Dockerが停止
「サーバーは既に登録されています」	Wizardが重複を検出。Settings → Server に移動し、既存のものを選択
「サーバーが古い」	サーバーで --update を実行: curl -fsSL https://roqueos.com.br/install.sh | bash -s -- --update
「Setup already completed」だが設定したことがない	リセット: docker exec roqueos-server sqlite3 /app/data/roqueos.db "DELETE FROM api_keys;"（注意 — 既存のすべてのキーが削除されます）
サーバーが追加されたがSettingsが空に戻る	おそらくFirestoreログインが欠落。DevTools consoleで Firestore: PERMISSION_DENIED が表示されるか確認

参考

• install.sh ワンライナー — 事前にサーバーを起動
• Server Admin Panel — 接続後の管理
• Volumes & バックアップ — 永続性を理解
• 内部Composable: src/composables/useAddServerWizard.js（状態 + フロー）