跳转到主要内容
Web 终端是一个实验性的浏览器内界面，可通过 WebSocket 提供交互式 clickhouse-client 会话。它通过任意 ClickHouse HTTP 端口上的 /webterminal 路径提供。
Web 终端是一项实验性功能，默认禁用；请参阅下方的启用该功能。

​
启用此功能

/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) 即可打开终端。

​
身份验证

Web 终端会依据与 HTTP 协议相同的 Session 和访问控制机制对用户进行身份验证，但凭据是在已建立的 WebSocket 连接内传输的，而不是通过 HTTP 升级请求传递。WebSocket 握手完成后，浏览器会将第一条消息以 JSON 格式发送： 
{"type": "auth", "user": "<user>", "password": "<password>"}
这样可以避免将凭据放在 URL 查询参数中，或放在随升级请求发送的 Authorization 请求头中，因为这些信息可能会出现在浏览器历史记录、服务器访问日志以及反向代理日志里。/webterminal 会有意忽略升级请求中的 URL 参数、HTTP Basic 认证，以及 X-ClickHouse-User/X-ClickHouse-Key 请求头。 无效的凭据会导致服务器以代码 1008 关闭 WebSocket；浏览器 UI 会重新提示输入凭据。

​
会话界面

完成身份验证后，服务器会运行附加到伪终端上的 clickhouse-client，并通过 WebSocket 转发其输入和输出。该会话支持完整的 clickhouse-client 使用体验，包括：
  • 语法高亮。
  • 自动补全。
  • 多行查询。
  • 命令历史记录 (在会话持续期间存储在服务器端) 。
终端使用 xterm.js 进行渲染。所有资源都由 ClickHouse 二进制文件本身提供，不会加载任何第三方 CDN。

​
与 /play 集成

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

​
安全注意事项

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 位，都会以协议错误关闭码被拒绝。

​
平台可用性

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