Web 终端是一个浏览器内界面，可通过 WebSocket 提供交互式 clickhouse-client 会话。它通过任意 ClickHouse HTTP 端口上的 /webterminal 路径提供。
访问任意 ClickHouse HTTP 端口上的 /webterminal (例如，http://localhost:8123/webterminal) 即可打开终端。
/webterminal 端点默认启用，由 enable_webterminal 服务器设置控制。要禁用它，请将该设置设为 false；之后，对 /webterminal 的请求将返回 HTTP 状态码 403 Forbidden。
enable_webterminal 已取代原先的 allow_experimental_webterminal 设置。如果未设置 enable_webterminal，为保持向后兼容，仍会识别旧名称。
Session 和访问控制机制对用户进行身份验证，但凭据是在已建立的 WebSocket 连接内传输的，而不是通过 HTTP 升级请求传递。WebSocket 握手完成后，浏览器会将第一条消息以 JSON 格式发送：
user 字段是可选的：省略或留空时，用户名将使用 default_session_user 服务器设置 (或可组合协议配置中针对各端点的覆盖值) ，如未另行配置，则为 default。如果 default_session_user 设为空字符串，则不允许未提供用户名的连接：auth 消息中省略或留空 user 将导致身份验证失败，服务器会以代码 1008 关闭 WebSocket；如果服务器配置中启用了 session_log 部分，此拒绝会以 user 为空的 LoginFailure 事件记录在 system.session_log 中。
这样可以避免将凭据放在 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 Web SQL UI 将 Web 终端嵌入为可停靠面板。你可以通过侧边栏中的终端图标切换它，或者在查询编辑器为空时按 ~ 键。/play 页面会在加载时检测 /webterminal 是否可用，并在端点不可用时隐藏终端控件 (例如，当 enable_webterminal 设置为 false 时) 。
该文档网站在页面底部的窄开发者托盘中嵌入了同一个终端，并以只读 play 用户身份连接到 ClickHouse playground，因此无需离开当前页面即可试用其中的示例。固定托盘会在页面末尾预留相应空间，以免遮挡页脚控件。终端打开时，文档页面会被锁定，滚动条也会隐藏。在终端上滚动时，滚动仅发生在其回滚缓冲区内，不会带动后方的文档页面。点击“ClickHouse 终端”栏或按 ~ 键，可打开该栏上方带内边距的面板。再次点击该栏、点击其折叠箭头、按 ~ 或 Escape，或向下拖动面板顶部边缘，均可将其折叠；该顶部边缘还可用于调整面板大小。结束会话 (使用 exit 或 Ctrl+D) 同样会折叠面板。
关闭面板后，会话及其回滚缓冲区仍会保留：重新打开终端时会回到同一提示符。会话存储在页面中，因此在文档页面之间导航时仍会保留，但在重新加载浏览器选项卡后不会保留——重新加载后，面板会以新会话重新出现。
终端托盘是网站桌面布局的一部分，在窄视口下不可用。
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。当端点不可用时 (例如，enable_webterminal 设置为 false) ，ClickHouse 起始页和 /play 中指向 /webterminal 的链接会自动隐藏。 
