メインコンテンツへスキップ
ウェブターミナルは、WebSocket 経由で対話型の clickhouse-client セッションを提供する、実験的なブラウザ内インターフェイスです。任意の ClickHouse HTTP ポートの /webterminal パスで提供されます。
ウェブターミナルは実験的な機能であり、デフォルトでは無効になっています。詳細については、以下の機能の有効化を参照してください。

​
機能を有効にする

/webterminal エンドポイントは、allow_experimental_webterminal サーバー設定で制御されます。この設定が false (デフォルト) の場合、/webterminal へのリクエストには HTTP ステータス 403 Forbidden が返されます。 これを有効にするには、サーバー構成に次の内容を追加します。 
<clickhouse>
    <allow_experimental_webterminal>true</allow_experimental_webterminal>
</clickhouse>
有効化したら、任意の ClickHouse の HTTP ポートで /webterminal (たとえば http://localhost:8123/webterminal) にアクセスして、ターミナルを開きます。

​
認証

ウェブターミナルは、HTTPプロトコルと同じ Session およびアクセス制御のチェックでユーザーを認証しますが、credentials は HTTP のアップグレードリクエスト経由ではなく、確立済みの WebSocket connection 上でインバンドにやり取りされます。WebSocket ハンドシェイクが完了すると、ブラウザーは最初のメッセージを JSON として送信します。 
{"type": "auth", "user": "<user>", "password": "<password>"}
これにより、認証情報を URL のクエリパラメータや、アップグレードリクエストに付与された Authorization ヘッダーに含めずに済みます。こうした場所に含めると、認証情報がブラウザの履歴、サーバーのアクセスログ、リバースプロキシのログに残るおそれがあります。アップグレードリクエストの URL パラメータ、HTTP Basic、および X-ClickHouse-User/X-ClickHouse-Key ヘッダーは、/webterminal では意図的に 参照されません。 無効な認証情報が指定されると、サーバーはコード 1008 で WebSocket を閉じ、ブラウザの UI は認証情報の再入力を求めます。

​
セッションの動作

認証が完了すると、サーバーは擬似端末に接続した clickhouse-client を実行し、その入出力を WebSocket 経由で中継します。このセッションでは、以下を含む clickhouse-client の完全な操作環境を利用できます。
  • シンタックスハイライト。
  • 自動補完。
  • 複数行クエリ。
  • コマンド履歴 (セッションの継続中はサーバー側に保存されます) 。
端末の描画には xterm.js を使用しています。すべてのアセットは ClickHouse バイナリ自体から配信され、サードパーティの CDN は読み込まれません。

​
/play とのインテグレーション

/play Web SQL UI には、ウェブターミナルがドッキング可能なパネルとして組み込まれています。表示は、サイドバーの端末アイコンで切り替えるか、クエリエディタが空の状態で ~ キーを押して切り替えます。/play ページは読み込み時に /webterminal が利用可能かどうかを判定し、エンドポイントが利用できない場合 (たとえば、実験的な設定が有効になっていない場合) には端末コントロールを非表示にします。

​
セキュリティに関する考慮事項

ウェブターミナルは、ClickHouse の HTTP エンドポイントに対して認証できるすべてのユーザーに、対話型のシェルのようなセッションを提供するため、HTTP プロトコルに当てはまるのと同じ注意点がここにも当てはまります。
  • 信頼できない環境では、認証情報とセッショントラフィックを保護するため、常に /webterminal を HTTPS 経由で提供してください。
  • HTTP プロトコルへのアクセスを制限するのと同様に、ネットワークレベル (ファイアウォール、リバースプロキシ、または listen_host 設定) でアクセスを制限してください。
  • このエンドポイントは、クロスオリジン WebSocket ハイジャックを防ぐために、Origin ヘッダーを Host と照合して検証します。外部で TLS を終端する場合は、それに応じてリバースプロキシを設定してください。
  • TLS を終端するリバースプロキシの背後では、ブラウザが https を使用していても、ClickHouse への上流接続は平文の http になるため、厳密な same-origin チェックによって正当な接続が拒否されます。このようなデプロイメントでは、WebSocket セッションを開くことを許可する完全なオリジンのカンマ区切りリストとして webterminal_allowed_origins を設定してください。この設定が空でない場合、デフォルトの same-origin チェックの代わりに使用されます。例: <webterminal_allowed_origins>https://example.com,https://app.example.com:8443</webterminal_allowed_origins>。
このハンドラーは、RFC 6455 に従って WebSocket プロトコル準拠も強制します。マスクされていないクライアントフレーム、予約済みオペコード、サイズ超過または断片化された制御フレーム、および予約済み RSV ビットは、protocol-error の close code で拒否されます。

​
プラットフォーム対応状況

このハンドラーは、ClickHouse がサポートするすべてのプラットフォームでコンパイルされます。埋め込み clickhouse-client ランナーで使用される擬似端末レイヤーは、移植性のある POSIX プリミティブ (posix_openpt/grantpt/unlockpt) をベースに実装されており、Linux 固有のパスではスレッドセーフな ptsname_r を使用します。ClickHouse のスタートページおよび /play の /webterminal へのリンクは、エンドポイントを利用できない場合 (たとえば、allow_experimental_webterminal が有効になっていない場合) に自動的に非表示になります。
最終更新日 2026年6月10日