Kyligence 3.4部署、Cube设计与API自动化

简介：《Kyligence Enterprise 3.4》中文版PDF面向使用Apache Kylin/Kyligence进行大数据分析的开发者、数据分析师与平台运维人员，重点解决从集群安装、系统配置到模型Cube设计、SQL查询及BI集成的查阅需求。压缩包仅含1个PDF文件，约96.06MB，内容为完整中文产品文档，适合按目录检索或系统通读。已有529人学习下载，具备一定参考热度。文档从快速开始、CDH/HDP/MapR/FusionInsight等环境安装与集群、读写分离、多租户部署讲起，覆盖RDBMS元数据存储、Cube存储引擎与Spark资源动态配置、Hive/Kafka/RDBMS/Impala等数据源导入，并深入模型设计、维度聚合组、TopN与精确/近似去重度量、Cube优化器、SQL规范与函数、查询下压、JDBC/ODBC驱动及Tableau、Power BI、FineBI等BI工具集成，还涉及用户组、行列级权限与LDAP/Kerberos安全控制。可作为Kylin平台搭建、性能调优与日常排错的案头参考。

1. 一份 3.4 版 PDF 的真实用法：从装环境到调 kylin api 文档里的接口

很多团队第一次接触这类平台，是在一台只有 4 核 10G 内存的沙箱机上，照着零散帖子拼命令，装到一半被 HBase 权限错误卡住，页面刷不出来，Cube 建完查询又没命中，最后归因成“这东西有点玄学”。问题不在运气，而在于没人把整条链路理清：先确认资源门槛，再跑通单机，接着换掉默认元数据存储，最后用 kylin api 文档里的接口把构建和查询自动化。Kyligence Enterprise 3.4 这份中文文档刚好把这几段都写全了：前置条件、单机五步安装、元数据迁移、模型与 Cube 设计、查询下压、REST 接口清单，一样不缺。它适合三类人——给业务搭 OLAP 平台的工程师、要写自动化构建脚本的开发者、以及被 Kerberos 和权限体系卡过的运维。下面按“能不能装、装完怎么验、验完怎么自动化”的顺序拆开看。

2. 装之前的硬门槛：JDK8、YARN 内存与 HDFS 权限自检

安装章节里最少被认真读、却最容易让后面所有步骤失败的部分，就是前置条件。文档在这块很明确：建议把平台单独跑在一个独立 Hadoop 集群上，每台机器要装 HDFS、YARN、MapReduce、Hive、Kafka，其中 HDFS、YARN、MapReduce、Hive、Zookeeper 是必需组件，Kafka 只在做流式数据源时才需要。Java 环境统一是 JDK 8 64 位以上，如果底层集群还停留在 JDK 7，文档另有一节专门给低版本兼容的配置步骤，别硬上。

2.1 组件清单与两条资源红线

资源这块文档给了两组数字，一组是 Hadoop 集群的参数下限，一组是沙箱虚拟机的最低配置，两组的用途不一样，混用就会出问题。集群参数决定的是“提交上去的任务能不能被容器接住”，沙箱配置决定的是“进程能不能起来”。我一般先看 YARN 的两个内存项，因为它们直接决定构建任务会不会卡在 ACCEPTED 状态。

检查这几个值不用记路径，直接在集群节点上抓配置就行：

# 在 NodeManager 所在节点上确认内存与 vCore 的实际生效值 grep -E "resource.memory-mb|maximum-allocation-mb|cpu-vcores" \ /etc/hadoop/conf/yarn-site.xml # reduce 侧参数在 mapred-site.xml grep -E "reduce.memory.mb|reduce.java.opts" /etc/hadoop/conf/mapred-site.xml

命令本身没什么技术含量，关键在解读：resource.memory-mb如果只有 4096，那maximum-allocation-mb设成 4096 也没意义，因为总量不够分；这种情况构建大 Cube 时会出现任务排队很久然后超时。沙箱环境下限是 4 个处理器、10 GB 内存，文档还特别提了一句：虚拟机必须能拿到这些资源，不是说宿主机有就算数。生产侧推荐配置是 32 vCore、128 GB 内存、至少一块 1 TB 的 7200 转 SAS 盘做 RAID1、两块千兆网口，这个量级对应的是 PB 级数据集上做亚秒级响应的目标，评估机器时按这个比例折算。

2.2 三连权限自检：HDFS、Hive、HBase

比资源更容易出问题的是账号权限。文档要求运行平台的 Linux 账号具备四类能力：读写 HDFS 文件、建读 Hive 表、建操作 HBase 表（用 JDBC 存元数据时可跳过）、提交 MapReduce 任务。这三项建议在装之前就手工验一遍，别等启动脚本报错再回头查。假设账号叫KyAdmin，工作目录用默认的/kylin：

# 切到 HDFS 超级用户建目录并授权 su hdfs hdfs dfs -mkdir /kylin hdfs dfs -chown KyAdmin /kylin hdfs dfs -mkdir /user/KyAdmin hdfs dfs -chown KyAdmin /user/KyAdmin # 回到 KyAdmin，验证读写 hdfs dfs -put any_file /kylin hdfs dfs -put any_file /user/KyAdmin

这里有个细节很多人忽略：/user/KyAdmin这个用户目录必须存在且有权限，否则后续提交任务时临时文件写不进去，报错信息往往指向任务失败而不是权限，排查方向很容易跑偏。工作目录位置不是死的，在$KYLIN_HOME/conf/kylin.properties里改kylin.env.hdfs-working-dir就能换。

Hive 侧同样要建库并测一遍增删：

-- 中间表落库的位置，需要与 kylin.properties 中的配置一致 create database kylinDB location "/kylin"; use kylinDB; create table t1(id string); drop table t1;

对应配置项是kylin.source.hive.database-for-flat-table=kylinDB。如果集群开了 Sentry 管理 Hive 权限，还得给当前账号授权访问工作目录和临时目录，文档在 Kerberos 与 Sentry 集成那节有具体赋权方式。HBase 侧如果继续用默认元数据存储，需要测建表删表，并且记住一条授权命令：grant 'KyAdmin','RWXCA'，权限位涵盖读、写、执行、创建、管理，缺一个都可能在建元数据表时报拒绝。

2.3 从解压到第一颗 Cube：五条命令加一个 profile

前置条件过了，单机安装本身很快。文档给的路径假设是/usr/local，账号是 root，实际用的时候替换成自己的：

cd /usr/local tar -zxvf Kyligence-Enterprise-3.4.tar.gz # 环境变量指向解压目录 export KYLIN_HOME=/usr/local/Kyligence-Enterprise-3.4 # 建 HDFS 工作目录 hdfs dfs -mkdir /kylin hdfs dfs -chown root /kylin

KYLIN_HOME建议写进 shell 的 profile 文件里，不然每次开新终端都要重设，后面所有脚本都依赖这个变量。装完别急着启动，先看配置方案：conf目录下有两套出厂配置，profile_prod面向生产，profile_min面向资源有限的沙箱。切换靠软链，不是改文件名：

# 沙箱或本地虚拟机切到最小资源方案 rm -f $KYLIN_HOME/conf/profile ln -sfn $KYLIN_HOME/conf/profile_min $KYLIN_HOME/conf/profile # 启动并观察日志 $KYLIN_HOME/bin/kylin.sh start tail -f $KYLIN_HOME/logs/kylin.log

启动后用ps -ef | grep kylin确认进程，浏览器访问http://{host}:7070/kylin/，默认账号ADMIN、密码KYLIN，首次登录强制改密码，长度至少 8 位且必须包含数字、字母和特殊字符。这一步别图省事设成弱口令，后面接 LDAP 或做权限对接时会来回折腾。

验证功能最省事的办法是跑自带样例：执行$KYLIN_HOME/bin/sample.sh把样例数据导进 Hive，然后在系统页面点一次“重载元数据”，进入learn_kylin项目构建kylin_sales_cube。构建成功后跑一条聚合查询，状态栏的查询引擎会显示命中的 Cube：

select PART_DT, COUNT(*) from KYLIN_SALES group by PART_DT;

这条 SQL 能出结果且显示命中，说明安装、元数据、Hive 数据源、构建引擎、查询引擎整条链是通的。查不出结果先别怀疑安装，看两个地方：一是查询是否只用了 SELECT（文档明确只支持 SELECT），二是是否没开查询下压——没开下压时，Cube 满足不了的查询不会被重定向到源库，直接返回空或报错是正常行为。

3. 元数据落 MySQL：连接串、迁移顺序与部署模式的取舍

单机验证完，下一步基本都是换元数据存储。默认走 HBase，好处是零依赖，坏处是排障成本高——元数据出问题时排查手段少，备份恢复也没那么直观。文档给了两条 RDBMS 路线：MySQL 和 Microsoft SQL Server，同时提供了一条从 HBase 迁到 RDBMS 的路径。这个改动量不大，但顺序错了会丢 Cube 定义，属于典型的“省一步、赔一天”。

3.1 为什么把元数据从 HBase 挪到 RDBMS

元数据里存的是项目、模型、Cube 定义、度量、权限配置这些“定义类”信息，不是业务数据。放 HBase 时它是几张宽表，靠 rowkey 设计支撑读写，运维侧要改一条配置得走 HBase shell，审计和备份都别扭。换到关系库之后，最直接的变化是可以用标准 SQL 做备份、比对、跨环境导入导出，文档里元数据备份与恢复、项目级元数据导入导出这两节的能力才真正好用起来。

代价是引入了一个外部依赖：数据库本身要高可用，连接池要配好，驱动包要放对位置。文档在 JDBC 连接元数据存储时特别标注过一句——如果用 JDBC 存元数据，HBase 表读写权限那项可以忽略，这其实反过来提示了很多人：换库成功之后，HBase 就不是必需组件了，机器上那套 HBase 可以评估是否下线。

判断要不要换，我给一个粗略标准：单机试用、数据量小、只有一个人在折腾，HBase 默认值够用；一旦涉及多环境（开发、测试、生产）、多人协作、需要定期备份 Cube 定义，就该换。因为跨集群迁移和元数据导出这类操作，在关系库上是一条命令的事，在 HBase 上要写脚本。

3.2 迁移的六个动作：停、备、建、改、启、验

顺序不能乱。停服务是为了让元数据不再写入，备是把 HBase 里的实例导出留底，建是在关系库里准备库和账号，改是改配置，启是重启并观察日志，验是打开页面确认项目、模型、Cube 数量对得上。

准备库和账号这一步，不同数据库语法有差异，以 MySQL 为例的常见做法：

-- 元数据库与专用账号，字符集按业务需求选 CREATE DATABASE kylin_meta DEFAULT CHARACTER SET utf8mb4; CREATE USER 'kylin'@'%' IDENTIFIED BY '强密码'; GRANT ALL PRIVILEGES ON kylin_meta.* TO 'kylin'@'%'; FLUSH PRIVILEGES;

配置改的是kylin.metadata.url。HBase 形态的取值长这样：XXX_NS:XXX_instance@hbase，其中XXX_NS是命名空间、XXX_instance是实例名，两者一起构成集群唯一标识；换成 RDBMS 后这个值改为 JDBC 连接串形态，具体拼法文档在“使用 MySQL 作为元数据存储”那节给了完整模板，照模板填主机、端口、库名、参数即可，用户名密码按文档要求单独配置。这里我不贴具体串，因为不同版本对参数顺序敏感，抄错一个useSSL之类的开关就会连不上，反而浪费时间。

# $KYLIN_HOME/conf/kylin.properties 三个关键项 kylin.env.hdfs-working-dir=/kylin kylin.source.hive.database-for-flat-table=kylinDB kylin.metadata.url=<按文档 RDBMS 模板填写>

改完配置还有一件必做的事：把对应数据库的 JDBC 驱动放到$KYLIN_HOME/ext目录下。这一步漏了，启动日志里会出现 ClassNotFound，但报错位置在连接池初始化阶段，新手容易以为是配置写错。启动后先看日志里元数据初始化是否成功，再登录页面核对项目数量和 Cube 列表，最后随便挑一个 Cube 做一次全量构建，能跑通才算迁移完成。

3.3 部署模式：读写分离、多租户与资源组怎么选

文档在部署模式这章列了五种：集群部署与负载均衡、读写分离、多租户、资源组、服务发现及任务引擎，加上海外云端部署。这些不是都要开，按规模选。

集群部署与负载均衡解决的是单点问题。多个实例前面挂一个反向代理，查询请求分摊到各节点，构建任务由任务引擎统一调度。做这层的时候注意会话和元数据缓存的一致性，代理层不要做请求体改写。

读写分离适合构建和查询互相干扰的场景。构建期间 Spark 任务吃满 YARN 队列，查询响应会被拖慢，把查询节点和构建节点分到不同实例上，配置层面区分角色，是成本最低的隔离手段。多租户解决的是项目和项目之间的资源与权限隔离，适合一个平台服务多个业务线的组织。资源组解决的是“这个项目的任务必须跑在指定 YARN 队列上”，把队列绑定到项目或 Cube 级别，避免大任务把小任务饿死。

我的选择顺序是：先做负载均衡保证可用，再做资源组保证公平，最后才考虑读写分离和多租户。因为资源组的收益立竿见影，而读写分离需要额外的实例和配置维护成本，团队规模不到一定程度反而是负担。文档里“多级配置重写”这节是配套能力：全局配置、项目级配置、Cube 级配置可以逐层覆盖，同一个参数在不同粒度给不同值，做隔离时不用复制整套配置文件。

4. 模型与 Cube 设计：聚合组、最大维度组合数与下压开关

装好、换完元数据，真正的坑才开始。同一份数据，模型设计差一点，查询从亚秒变成几十秒；Cube 设计差一点，构建时长翻几倍，磁盘占用也翻几倍。文档在模型和 Cube 这两章给的工具很多，但得知道先用哪个、后调哪个。

4.1 模型设计的三类对象与模型检测

文档把模型分成基本模型、基于流式数据的模型、以及处理缓慢变化维度的模型。基本模型是绝大多数场景的起点：选事实表、挂维度表、定义连接关系、挑出要参与分析的列。流式模型面向 Kafka 这类持续写入的数据源，维度和度量在建模型时就要考虑后续增量构建的切分方式。缓慢变化维度处理的是维度属性会随时间变化的情况，比如客户等级调整、商品类目迁移，做不好会出现历史订单按新维度归属的错账。

设计完别直接拿去建 Cube，先跑模型检测。这个功能会检查连接类型是否合理、维度是否有循环依赖、事实表和维度表的关联键类型是否一致。我见过最常见的一类失败是维度表关联键类型不匹配，比如一边是 string 一边是 bigint，模型能保存，构建时 join 结果全空，最后查出来是零数据，排查半天。

可计算列是另一块值得用的能力。把常用的表达式（日期截断、字符串拼接、简单算术）固化成可计算列，查询时直接引用，避免每次在 SQL 里重算。文档给了可计算列支持的函数清单，用之前对一下，别用了不支持的函数然后疑惑为什么结果不对。

4.2 Cube 设计：聚合组、组合数上限与优化器

Cube 的本质是预计算，把所有可能的维度组合提前算好，查询时直接命中。维度一多，组合数就是指数级增长，所以必须做裁剪。文档给的手段主要是三个：维度聚合组、最大维度组合数、Cube 优化器。

聚合组是把维度按查询习惯分组，同一个组内的维度才会互相组合。比如把“地区、省份、城市”放一组，“品类、品牌”放另一组，避免出现“城市 + 品牌”这种没人查的组合。层级维度（hierarchy）和联合维度（joint）是聚合组里的细化设置，前者表达上下级关系，后者表达必须同时出现的维度集合。

最大维度组合数是硬性上限，常见做法是控制在几千这个量级，具体取决于集群规模和构建时间预算。设太小会漏掉有用组合，设太大构建时间和存储都失控。我的经验是先按业务最常用的三到五个维度组合估算，把这个值卡在能覆盖 90% 查询的范围内，再用查询历史去补。

Cube 优化器是自动裁剪工具，它根据历史查询记录判断哪些维度组合值得保留。冷启动阶段没有历史数据，优化器没什么可依据的，所以正确顺序是先上线跑一段时间、积累查询记录，再启用优化器做二次裁剪。刚建完 Cube 就打开优化器，往往裁掉的是你以为没人查、实际上业务偶尔会查的组合。

自动建模和查询历史自动建模这两个功能，适合对 Cube 设计不熟的同学做起点参考：让系统根据表结构和查询日志生成一版设计，然后人工在聚合组上做调整。别把它当最终方案，生成的 Cube 通常偏保守，维度和度量都给得很全。

4.3 度量与明细表索引：去重计数怎么选

度量这部分的选型直接影响结果准确性，是必须搞清楚的一组概念。文档列了 TopN、精确去重计数、近似去重计数、近似 Percentile、CORR（Beta）、半累加度量（Beta）、Sum Expression（Beta）、明细表索引。

精确去重计数用 Bitmap 实现，结果准确，但基数高的列（比如用户 ID 上千万）会占用大量内存和存储，构建也慢。近似去重计数走 HyperLogLog 一类算法，误差在可接受范围内，资源占用低一个数量级。判断标准很朴素：报表要对外、数字要对得上账，用精确；内部看趋势、看量级，用近似。TopN 度量适合“取访问量前 N 的商品”这类固定形态的查询，比通用聚合快得多。

明细表索引解决的是“既要聚合结果，又要看明细”的场景。开了之后，查询可以下钻到原始行，代价是存储增加。文档把这个能力放在度量设计里，容易被当成一个可选项跳过，实际上对排查数据问题很有用。

最后提醒一个参数：Cube 存储引擎配置在系统配置那章，和 Spark 资源动态配置、Hadoop 队列配置放在一起。构建引擎选 Spark 时，Spark 的 executor 数量、内存要通过这几处配置对齐，配置和 YARN 队列容量不匹配会出现“任务提交成功但一直排队”。

4.4 查询下压的四种目标

查询下压是这套系统里最容易被误解的功能。它的作用是把 Cube 满足不了的查询，转交给底层引擎去算。文档列了四种目标：下压至原生 SparkSQL、下压至 Hive、下压至外部 SparkSQL、下压至 Impala。

不开下压时，Cube 命中不了的查询不会被重定向，直接返回空或者报错，这是很多人第一次用时的困惑来源。开了之后要接受一个事实：下压查询的响应时间取决于底层引擎，可能比 Cube 查询慢一到两个数量级，别拿它当性能优化手段，它是兜底。

5. 避坑与排查：五个把新手劝退的现象

这一节记录的是文档 FAQ 里散落、但实际排障中反复出现的五类问题。每一条都按现象、原因、解决三段写，遇到的时候可以直接对照。

5.1 现象：报 Insufficient permissions for user 'root'

启动或建 Cube 时日志里出现org.apache.hadoop.hbase.security.AccessDeniedException: Insufficient permissions for user 'root' (auth:SIMPLE)。原因很直接：账号对 HBase 没有写权限。CDH 和 HDP 沙箱环境下这条特别常见，因为沙箱默认账号和 HBase 授权体系没打通。

解决有两条路。计划长期用 HBase 存元数据的，走授权：在 hbase shell 里执行grant 'KyAdmin','RWXCA'，把读写执行创建管理一次给全。只是本地试装、不打算深究权限的，可以临时关掉 HBase 的权限检查：把hbase.coprocessor.region.classes和hbase.coprocessor.master.classes两项的值设为空，hbase.security.authentication设为simple。注意这是沙箱做法，生产环境走授权那条路，别为了省事把权限检查关掉。

5.2 现象：进程起来了，页面打不开

ps -ef | grep kylin能看到进程，日志也没有明显异常，但浏览器访问 7070 一直转圈或连接被拒。原因通常是端口冲突或者防火墙。7070 是个挺热门的端口，同机器上跑着别的 Web 服务时容易被占。

解决分两步。先在机器上确认端口占用情况，如果确实被占，用文档提供的端口工具改偏移量：

# 设置端口偏移，后端实际端口 = 7070 + 偏移量 $KYLIN_HOME/bin/kylin-port-replace-util.sh set PORT_OFFSET # 改完重启，然后用新端口访问 $KYLIN_HOME/bin/kylin.sh stop $KYLIN_HOME/bin/kylin.sh start

这里的关键是理解“偏移量”而不是“端口号”。设成 100，实际监听的是 7170，设成 0 就是回到 7070。文档写得很清楚，但很多人下意识以为填的是目标端口，填 8080 结果服务跑到 15150 上去了。端口没问题还打不开，检查一下是不是只监听了 127.0.0.1，远程访问要走宿主 IP。

5.3 现象：JDK 7 集群上启动直接退出

底层 Hadoop 集群还是 JDK 7，装完启动脚本没有任何提示就退出了，日志里只有几行看不懂的类加载错误。原因是产品本身要求 JDK 8 64 位以上，JDK 7 缺少部分 API。

文档专门有一节“如何在低版本 JDK 上运行”，按里面的配置步骤改启动参数和类路径即可。但我要给个更实际的建议：这属于兼容方案，不是推荐方案。如果集群有升级计划，优先推动 JDK 升级，因为低版本兼容模式在遇到 Spark 相关功能时限制更多，出问题时排查路径也更长。真要在 JDK 7 上长期跑，把这一节的配置项写进部署脚本，别靠手工改。

5.4 现象：Kerberos 环境下 Spark 任务全部失败

集群启用了 Kerberos，平台本身能启动、页面能打开、Hive 数据也能读，但一构建 Cube 就失败，报认证相关错误。原因在于平台自带的 Spark 需要单独配置才能安全访问集群资源，不是继承了系统级的 krb5 配置就自动生效。

解决要按集成章节走：给运行账号申请 principal 和 keytab，配置 Spark 访问集群的认证参数，Kafka 如果也开了 Kerberos，要单独做一遍 Kafka 与 Kerberos 的集成配置，两者不是一套。这块最忌讳的是“先把安全关掉试试”——生产集群关不掉，沙箱关了也验证不出真实问题。我的做法是在测试环境用同样的 Kerberos 配置跑一遍完整构建，确认 keytab 续期和过期行为，再上生产。

5.5 现象：查询返回空结果，但底层表里有数据

页面执行 SQL 返回空，或者提示无法下推。原因有两个常见分支：一是没开查询下压，Cube 命中不了的查询不会被重定向，直接返回空；二是 SQL 里用了不支持的写法，比如非 SELECT 语句、或者某些函数在 SQL 规范参考里没有。

排查顺序是：先看查询详情里的“查询引擎”一栏，确认命中了哪个 Cube，没命中就说明 Cube 的维度组合覆盖不到这条查询；再去 SQL 规范参考里核对你用的函数和运算符是否在支持清单内，交集函数、差集函数、窗口函数、Bitmap 函数这些都有明确的支持范围。确认是覆盖问题，就回去调聚合组或补维度；确认是语法问题，改写 SQL。别一上来就改 Cube 定义，先定位清楚是覆盖不足还是语法不支持，这两类问题的修法完全不同。

6. 进阶：用 REST API 和 JDBC 拼一条验证闭环

手工点页面验证一次可以，天天点就不现实了。文档最后那部分 REST API 清单其实是整套文档里最适合做自动化的资产：项目 API、数据源 API、模型 API、Cube API、构建 Cube API、任务 API、查询 API、缓存 API、异步查询 API、元数据导出导入 API，加上访问控制权限、用户、用户组这一组接口，基本覆盖了日常运维的所有动作。接口统一走 HTTP，认证方式和页面登录一致，用 Basic Auth 就能调。

我通常按“拿项目 → 找 Cube → 触发构建 → 轮询任务 → 用 JDBC 验数”这个顺序串一条最小闭环。构建前先确认目标 Cube 存在，避免拼错名字白等一次排队：

# 认证信息建议从环境变量读，不要写死在脚本里 AUTH="-u ${KYLIN_USER}:${KYLIN_PASS}" BASE="http://${KYLIN_HOST}:7070/kylin/api" # 1. 列出项目，确认 learn_kylin 存在 curl -s $AUTH "${BASE}/projects" | head -c 500 # 2. 列出项目下的 Cube，拿到准确的 Cube 名 curl -s $AUTH "${BASE}/cubes?project=learn_kylin" | head -c 500 # 3. 触发一次全量构建，返回体里带 job id curl -s $AUTH -X PUT "${BASE}/cubes/kylin_sales_cube/build" # 4. 用 job id 轮询任务状态，直到 FINISHED 或 ERROR curl -s $AUTH "${BASE}/jobs/${JOB_ID}"

脚本里最值得注意的不是命令本身，而是两处细节：PUT触发构建是幂等的还是重复提交，取决于版本实现，生产上要在脚本里加一层“当前是否已有运行中任务”的判断；轮询要有超时和最大重试次数，别写成死循环，Cube 构建几十分钟很正常，但卡在 ACCEPTED 超过预期时间基本就是 YARN 队列资源不够，这时该去看队列而不是继续等。

验数这一步用 JDBC 驱动更直接。文档给 JDBC 和 ODBC 都列了驱动下载与配置说明，Windows、Linux、Mac 三个平台各有版本。连接串里的库名填项目名，认证同样走账号密码。拿到连接之后，用同一条聚合 SQL 在页面和驱动里各跑一次，比对行数和汇总值：

# 用 JDBC 驱动跑与页面相同的 SQL，比对结果是否一致 # 关键点：库名对应项目名，不是元数据库名 conn = jdbc.connect("jdbc:kylin://host:7070/learn_kylin", user=os.environ["KYLIN_USER"], password=os.environ["KYLIN_PASS"]) cur = conn.cursor() cur.execute("select PART_DT, COUNT(*) from KYLIN_SALES group by PART_DT") rows = cur.fetchall()

这条闭环跑通的意义在于：以后换集群、升版本、改元数据库，都可以用同一套脚本做回归，不用靠人肉点页面。数对不上时，问题范围也被压缩到“Cube 数据”或“查询路径”两段，比盲查快得多。

从踩过的坑来看，我最想强调的一点是：任何一次元数据迁移、配置重写、版本升级之后，都强制把这条 API 加 JDBC 的闭环完整跑一遍，而不是只看页面能不能打开。页面能开只说明进程活着，闭环跑通才说明构建链路和查询链路都正常。这个习惯帮我在好几次变更后第一时间发现了 Cube 定义没导全的问题，省下了业务方来投诉之后再去回溯的时间。希望帮到你。

本文还有配套的精品资源，点击获取