webman默认连不上clickhouse，因其内置数据库连接器基于pdo适配mysql/postgresql，而clickhouse的mysql兼容端口（9004）仅为bi工具设计，不支持事务、完整预处理及set names等语义，协议模拟不彻底导致报错。
Webman 本身不直接支持 ClickHouse 驱动，必须通过 PDO 或第三方客户端库桥接；强行用 MySQL 协议直连会失败，因为 ClickHouse 不兼容 MySQL wire protocol 的全部语义。
为什么 Webman 默认连不上 ClickHouse
Webman 基于 PHP 的 Swoole，其内置数据库连接器（如 webman/database）默认适配 PDO + MySQL/PostgreSQL。ClickHouse 虽然提供 MySQL 兼容端口（默认 9004），但它只是“协议模拟”，不支持事务、预处理语句绑定类型不全、SET NAMES 等行为常被忽略或报错。常见现象包括：
PDOException: SQLSTATE[HY000]: General error: 1002 Unknown setting 'names'- 插入含
DateTime64或JSON字段时报类型转换失败 - 长查询超时后连接卡死，无自动重试机制
根本原因：ClickHouse 的 MySQL 兼容层是为 BI 工具（如 Tableau、Metabase）设计的简化通道，不是为高并发 PHP 应用长期维持连接准备的。
推荐集成方式：用 clickhouse-php 客户端 + 连接池封装
官方维护的 clickhouse-php（GitHub: salsify/clickhouse-php）是目前最稳定的选择，它基于 HTTP 接口通信，绕过协议兼容问题，且支持：
Webman 2.2.0版本强化了 TCP/UDP 服务支持，优化路由组管理，并增强异步任务处理能力。结合协程与连接池技术，Webman 能轻松应对高并发场景，适用于网站、接口服务、即时通讯、物联网及游戏开发，兼具高性能、灵活扩展与稳定可靠，是多场景 PHP 服务开发的理想选择。
-
INSERT ... VALUES批量写入（建议每批 ≤ 10000 行） - 异步查询（配合 Swoole 的协程）
- 自动重试与错误码映射（如
241表示UNKNOWN_TABLE） - 原生类型支持：
DateTime64、Nullable、Array等
实操建议：
- 不要在
onWorkerStart中全局 new Client，应使用协程安全的连接池（如co\Channel管理 5–10 个复用连接） - 写入前务必调用
$client->ping()，HTTP 连接空闲超时默认 300 秒，需主动探测 - 避免在单次请求中执行多个
SELECT—— ClickHouse 不适合 OLTP 式多跳查询，应提前物化视图或预聚合
建表与写入必须匹配 Webman 的数据生命周期
Webman 常用于实时报表接口（如 /api/dashboard/pv-uv），这类请求依赖 ClickHouse 的秒级响应，但若表结构或写入方式没对齐，延迟会陡增：
- 分区键必须含时间字段（如
PARTITION BY toYYYYMMDD(event_time)），否则WHERE event_time >= now() - INTERVAL 1 HOUR无法裁剪分区 - 排序键（
ORDER BY）应把高频过滤字段放前面，例如ORDER BY (app_id, event_time)，而非(event_time, app_id)—— 后者导致按app_id查询时仍要扫描全分区 - 写入数据必须严格按
DateTime时区传入（推荐 UTC），Webman 请求头中的X-Timezone不能直接用于 ClickHouse 插入，需在应用层统一转换 - 禁用
ReplacingMergeTree的version字段做“更新”——Webman 接口不保证写入顺序，极易造成数据丢失
查询性能卡点：别让 Webman 成为 ClickHouse 的瓶颈
Webman 协程模型能并发跑几十个 ClickHouse 查询，但实际吞吐受限于几个隐性因素：
- HTTP 客户端默认超时是 30 秒，而 ClickHouse 复杂聚合可能耗时 5–8 秒，需显式设
timeout => 10并捕获ClickHouseException做降级（如返回缓存结果） - Webman 的
response()->json()会序列化整个结果集，若查出 10 万行，PHP 内存暴涨 —— 必须用LIMIT+ 分页参数控制，服务端绝不返回未分页原始明细 - 同一时刻大量请求触发相同
GROUP BY查询时，ClickHouse 会复用已计算的Query Cache，但 Webman 若带随机query_id参数（如埋点用的 trace_id），会导致缓存失效 - 不要在 Webman 中拼接 SQL 字符串做条件过滤（如
"WHERE app_id = '{$_GET['app']}'"），必须用参数化查询，否则app_id值含单引号时直接语法错误
最易被忽略的一点：ClickHouse 的 max_threads 默认是 CPU 核数，但 Webman 协程数往往远高于此。若 20 个协程同时发查询，ClickHouse 实际只并行 4 个（4 核机器），其余排队——应在 users.xml 中为 Webman 流量单独配置 profile，限制其 max_threads=2 并提高 priority，避免挤占后台 ETL 任务资源。
