> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-fix-nav-issues.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> Web 终端文档：通过 WebSocket 在浏览器中提供 `clickhouse-client` 会话

# Web 终端

Web 终端是一个实验性的浏览器内界面，可通过 WebSocket 提供交互式 `clickhouse-client` 会话。它通过任意 ClickHouse HTTP 端口上的 `/webterminal` 路径提供。

<Note>
  Web 终端是一项实验性功能，默认禁用；请参阅下方的[启用该功能](#enabling-the-feature)。
</Note>

<div id="enabling-the-feature">
  ## 启用此功能
</div>

`/webterminal` 端点由 `allow_experimental_webterminal` 服务器设置控制。当该设置为 `false` (默认值) 时，对 `/webterminal` 的请求会返回 HTTP 状态码 `403 Forbidden`。

要启用此功能，请将以下内容添加到您的服务器配置中：

```xml theme={null}
<clickhouse>
    <allow_experimental_webterminal>true</allow_experimental_webterminal>
</clickhouse>
```

启用后，访问任意 ClickHouse HTTP 端口上的 `/webterminal` (例如 `http://localhost:8123/webterminal`) 即可打开终端。

<div id="authentication">
  ## 身份验证
</div>

Web 终端会依据与 HTTP 协议相同的 `Session` 和访问控制机制对用户进行身份验证，但凭据是在已建立的 WebSocket 连接内传输的，而不是通过 HTTP 升级请求传递。WebSocket 握手完成后，浏览器会将第一条消息以 JSON 格式发送：

```json theme={null}
{"type": "auth", "user": "<user>", "password": "<password>"}
```

这样可以避免将凭据放在 URL 查询参数中，或放在随升级请求发送的 `Authorization` 请求头中，因为这些信息可能会出现在浏览器历史记录、服务器访问日志以及反向代理日志里。`/webterminal` 会有意**忽略**升级请求中的 URL 参数、HTTP Basic 认证，以及 `X-ClickHouse-User`/`X-ClickHouse-Key` 请求头。

无效的凭据会导致服务器以代码 `1008` 关闭 WebSocket；浏览器 UI 会重新提示输入凭据。

<div id="session">
  ## 会话界面
</div>

完成身份验证后，服务器会运行附加到伪终端上的 `clickhouse-client`，并通过 WebSocket 转发其输入和输出。该会话支持完整的 `clickhouse-client` 使用体验，包括：

* 语法高亮。
* 自动补全。
* 多行查询。
* 命令历史记录 (在会话持续期间存储在服务器端) 。

终端使用 [xterm.js](https://xtermjs.org/) 进行渲染。所有资源都由 ClickHouse 二进制文件本身提供，不会加载任何第三方 CDN。

<div id="play-integration">
  ## 与 `/play` 集成
</div>

[`/play`](/zh/concepts/features/interfaces/http) Web SQL UI 将 Web 终端嵌入为可停靠面板。你可以通过侧边栏中的终端图标切换它，或者在查询编辑器为空时按 `~` 键。`/play` 页面会在加载时检测 `/webterminal` 是否可用，并在端点不可用时隐藏终端控件 (例如，未启用 Experimental 设置时) 。

<div id="security">
  ## 安全注意事项
</div>

Web 终端会向任何能够通过 ClickHouse HTTP 端点完成身份验证的人暴露一个类似交互式 shell 的会话，因此，适用于 HTTP 协议的相同注意事项在这里同样适用：

* 在不受信任的环境中，始终通过 HTTPS 提供 `/webterminal`，以保护凭据和会话流量。
* 在网络层限制访问 (防火墙、反向代理或 `listen_host` 配置) ，方式应与限制 HTTP 协议访问相同。
* 该端点会将 `Origin` 请求头 与 `Host` 进行校验，以降低跨源 WebSocket 劫持风险；如果你在外部终止 TLS，请相应配置反向代理。
* 在由反向代理终止 TLS 的场景下，尽管浏览器使用的是 `https`，到 ClickHouse 的上游连接仍是明文 `http`，因此严格的同源检查会拒绝合法连接。对于这类部署，请将 `webterminal_allowed_origins` 设置为允许发起 WebSocket 会话的完整源列表，多个源之间用逗号分隔；当此设置非空时，它会替代默认的同源检查。示例：`<webterminal_allowed_origins>https://example.com,https://app.example.com:8443</webterminal_allowed_origins>`。

该 handler 还会依据 RFC 6455 强制检查 WebSocket 协议是否合规：未加掩码的客户端帧、保留操作码、过大的或分片的控制帧，以及保留的 RSV 位，都会以协议错误关闭码被拒绝。

<div id="platform">
  ## 平台可用性
</div>

该 handler 可在 ClickHouse 支持的所有平台上编译。嵌入式 `clickhouse-client` 运行器使用的伪终端 layer 基于可移植的 POSIX 基本类型 (`posix_openpt`/`grantpt`/`unlockpt`) 实现；同时还提供了一个 Linux 特定的 path，使用线程安全的 `ptsname_r`。当端点不可用时 (例如，未启用 `allow_experimental_webterminal`) ，ClickHouse 起始页和 `/play` 中指向 `/webterminal` 的链接会自动隐藏。