简介：这份文档面向大数据分析工程师、Kylin 运维及 BI 集成人员，围绕 Kyligence Enterprise 3.4 与 Apache Kylin 的接口使用和大数据处理展开，可用于接口查阅、安装部署、数据建模与查询优化。资源包为 1 个 PDF 文件，约 96.06MB，便于本地留存和按目录检索；目前已有 529 人学习。内容覆盖多种 Hadoop 环境安装、集群与读写分离/多租户部署、RDBMS 元数据存储、系统参数与队列配置，以及 Hive、Kafka、RDBMS、Impala 等数据源导入。模型与 Cube 章节涉及维度聚合组、度量设计、TopN、精确/近似去重和优化器；查询部分包含 SQL 规范、查询下压、异步查询，并延伸到 JDBC/ODBC 驱动及 Tableau、Power BI 等 BI 工具集成，适合作为案头参考手册。

1. 先想清楚要不要预计算，再谈用哪个引擎

做大作业和做交付方案，最容易被跳过的一步是先判断「查询到底要不要预计算」。这次要梳理的是一份 Kyligence Enterprise 3.4 中文文档，它几乎可以当成一份完整的 Kylin API 文档合集来读：从安装前置条件、元数据存储、Cube 设计，一直写到 SQL 规范、REST API 和 BI 工具对接。它针对的问题很具体：一张亿级到千亿级的明细表，业务方要求十几个维度随便切、报表秒级返回、几十路并发同时进；靠现查明细库基本没戏，只能把聚合结果提前算好。适合三类人：正在做大数据分析平台毕设或课设的学生、要给团队出一份 OLAP 选型方案的工程师、以及接手了一套 Kylin 系集群要补运维文档的人。

2. 总体架构与选型：四层结构和两类元数据存储怎么定

方案能不能站住，第一步看架构分层清不清楚；第二步看元数据放在哪里。这两件事定错了，后面 Cube 建得再漂亮也是白搭。这一章把这两块单独拆开说，配套的部署模式和资源参数一并给出来，方便直接往方案文档里搬。

2.1 四层结构：数据源层、预计算层、查询服务层、接入层

我一般把这类平台画成四层，从上往下依次是接入层、查询服务层、预计算层、数据源层。接入层负责收口，BI 工具、JDBC 客户端、REST API 调用方都从这里进来，对外只暴露一个项目和一套认证；查询服务层做 SQL 解析、路由和结果拼装，判断一条 SQL 能不能命中已经算好的 Cube，命中就直读，不命中看有没有开下压；预计算层是整个方案的核心，把明细按维度和度量的组合提前物化成 Cube，构建任务跑在 Spark 或 MapReduce 上；数据源层就是 Hive 表、Kafka 流、RDBMS 外表这些原始数据。

分层清楚之后，职责边界才好切。比如「查询变慢」这个现象，落在查询服务层可能是没命中 Cube、落在预计算层可能是聚合组设计得太细、落在数据源层可能是 Hive 小文件太多。没有分层，排查就变成靠感觉猜，这也是我做这类项目最怕的状态。下面这张表是我写方案时会附在架构图后面的说明，验收时也按这张表逐条对。

2.2 部署模式：单机、集群、读写分离、多租户怎么选

文档里给了五种部署姿态，实际做方案时不需要全写上，按并发和数据量选一种主模式加一种兜底就行。单机适合沙箱和课程演示，一台 4 核 10G 的虚拟机就能把样例 Cube 跑起来；集群部署是生产常态，多个实例前面挂一个负载均衡，任务引擎单独拉出来避免构建任务把查询线程吃满；读写分离是把「接收构建请求」和「响应查询」拆到不同实例上，构建高峰期不至于把报表卡死。

多租户部署和资源组部署是同一个问题的两种解法：多租户是按项目隔离，每个项目有自己的用户组和 Cube 空间；资源组是按队列隔离，把不同类型任务的 YARN 队列分开，防止一个大 Cube 构建把整个集群的容器占光。给学校做课程设计，用单机加资源组就够了；给公司出方案，一般写成「集群 + 读写分离 + 资源组」三件套，多租户留到二期再上，因为它会牵出一整套权限模型。

服务发现和高可用这两块容易被忽略。集群里实例地址会变，靠配置文件里写死 IP 迟早出问题，通常的做法是接一个服务注册组件，让查询请求按健康状态分发。高可用不只看实例数量，元数据存储也得是高可用的，否则实例挂了一个能切换，数据库挂了整个平台就停摆。

2.3 元数据存储：HBase 与 RDBMS 的选择和迁移

元数据存的是项目、模型、Cube 定义、任务记录这些东西，量不大但极其关键，丢了就是灾难。早期默认用 HBase，好处是和 Hadoop 生态天然亲和、写入快；问题是查起来不直观，出问题只能靠工具翻，运维排障时基本是个黑匣子。3.x 之后主推 RDBMS，MySQL 和 Microsoft SQL Server 都支持，好处是能直接用 SQL 查、能接现成的备份体系、迁移和扩容都简单。

配置改起来就一行，但配套动作不少：

# $KYLIN_HOME/conf/kylin.properties # 元数据地址：RDBMS 模式下是 JDBC 串，HBase 模式下是 命名空间:实例名@hbase kylin.metadata.url=kylin_metadata@jdbc,url=jdbc:mysql://db-host:3306/kylin,username=kylin,password=******,maxActive=20 # 中间表落地的 Hive 库，需要提前建好并授权 kylin.source.hive.database-for-flat-table=kylin_flat # Cube 数据在 HDFS 上的工作目录 kylin.env.hdfs-working-dir=/kylin

这段配置里有三个点值得单独说。第一，maxActive连接池上限别拍脑袋写大，实例数乘上这个值不能超过数据库的最大连接数，否则启动时就会报连接耗尽。第二，database-for-flat-table指向的库必须先手工建，构建时不会帮你建库，权限不够就会在第一步失败。第三，hdfs-working-dir对应的目录要由 HDFS 超级用户创建并 chown 给运行账户，自己 mkdir 出来的目录属主是当前用户，换个账户跑就废了。

从 HBase 迁到 RDBMS 有专门的迁移工具，通常的做法是先停写、导出、导入、改配置、启动验证五步走，中间不要跳步。迁完之后别急着删 HBase 里的老数据，留一周做对照，确认项目、模型、Cube 都能正常打开再清理。这块我踩过一次坑：迁移完只验证了登录，没验证历史任务的日志，结果一周后要查某次构建失败原因，发现任务记录不全。

3. 环境落地：安装前置条件与三项权限检查

装不上的原因九成不在产品本身，而在 Hadoop 侧的准备没做全。这一章按「检查清单 → 安装步骤 → 验证」的顺序走，每一步都给可复现的命令，照着跑一遍基本能定位到卡点在哪。

3.1 前置条件清单：JDK、账户与集群资源参数

Java 环境要求 JDK 8 的 64 位版本，集群里所有节点都要一致。如果手上是一套只装了 JDK 7 的老集群，文档里有单独的降级运行配置，但我不建议在新方案里沿用，JDK 8 已经是这类平台的事实底线。

运行账户的权限是最容易漏的。这个 Linux 账户需要能读写 HDFS 上的文件、能建和读 Hive 表、能提交 MapReduce 或 Spark 任务，如果用 HBase 存元数据还得能建表删表。文档给的验证方法很土但很有效：直接往工作目录 put 一个文件，在 Hive 里建一张临时表再删掉。跑不通就别往下走，后面一定会以更难看的方式失败。

集群资源这块有几个硬指标，我做成表格贴在方案的环境章节里，评审时逐条打勾：

硬件上，官方推荐 32 vCore、128 GB 内存、至少一块 1 TB 的 SAS 盘做 RAID1、双千兆网口。做课程设计用不到这个规格，但虚拟机的底线是 4 核 10 GB，低于这个数 YARN 起不来容器，构建任务会一直排队，表现出来的现象是「点了构建没反应」，很容易误判成产品卡死。

3.2 安装步骤：解压、环境变量与 HDFS 目录准备

安装本身很轻，解压加设环境变量就完事，重活都在目录和权限上：

# 1. 解压到安装路径，KYLIN_HOME 指向解压出来的目录 cd /usr/local tar -zxvf Kyligence-Enterprise-3.4.tar.gz export KYLIN_HOME=/usr/local/Kyligence-Enterprise-3.4 # 2. 准备 HDFS 工作目录和运行账户的家目录，两个都要 # 工作目录存 Cube 数据，家目录是很多组件的默认落点 hdfs dfs -mkdir /kylin hdfs dfs -chown kyadmin /kylin hdfs dfs -mkdir /user/kyadmin hdfs dfs -chown kyadmin /user/kyadmin

两个目录都要建，是因为有些组件默认往/user/<账户>下写临时文件，只建/kylin的话，构建到一半会报「临时目录不可写」，日志里还不会直接告诉你是哪个目录。执行hdfs dfs命令时如果提示没权限，先切到 hdfs 账户再跑一遍，别在运行账户上反复试。

配置文件在$KYLIN_HOME/conf/下，产品自带两套出厂配置：profile_prod面向生产，资源占用高但稳；profile_min面向沙箱，资源少。切换方式就是换一个软链：

# 沙箱/低配环境切到 min 配置，生产环境保持默认的 prod 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 # 观察启动进度，看到 started 再往下走 ps -ef | grep kylin # 确认进程在

默认端口 7070，如果和已有服务冲突，用自带的端口工具加偏移量，比如设 100，实际端口就变成 7170。这个偏移量是叠加而不是替换，很多人改成 8080 之后发现还是连不上，就是因为没意识到它是加法的。

3.3 安装验证：从样例数据到第一个 Cube

装完别急着写方案里的「已完成部署」，先用样例数据跑通一条完整链路。安装目录的bin下有样例脚本，它会把样例表导进 Hive：

$KYLIN_HOME/bin/sample.sh

跑完回到 Web 界面点一次「重载元数据」，然后进样例项目，选kylin_sales_cube点构建。构建成功的标志是状态变成 READY，接着在分析页面执行一条最简单的聚合：

-- 验证用：命中 Cube 时执行时间是亚秒级 SELECT PART_DT, COUNT(*) AS cnt FROM KYLIN_SALES GROUP BY PART_DT;

结果返回后看查询引擎那一栏，会标出这条 SQL 命中了哪个 Cube。这一栏是后面排查问题的起点：如果显示走了明细或者下压，说明 Cube 没覆盖住这个查询，需要回头改聚合组或者补维度。

Web 端默认账户是 ADMIN / KYLIN，第一次登录会强制改密码，规则是至少 8 位、必须含数字字母和特殊字符。这条规则在批量部署时是个小麻烦，自动化脚本里要预留改密步骤，否则下次登录直接被拦。

4. 模型与 Cube 设计：维度、度量与聚合组的具体取舍

这一步决定了方案的上限。同一个数据量，模型设计得好，Cube 体积能省一半、查询还能更快；设计得糙，构建跑八小时、查询照样打不中。文档里从基本模型一直讲到流式模型、缓慢变化维度和 Cube 优化器，内容很多，我按实际动手顺序重排一遍。

4.1 模型设计：事实表、维度表与可计算列

事实表只保留建模要用的列，粒度选最细的那一层，别在建模层提前做汇总，否则后面想加维度就得重来。分区字段用日期，命名统一，因为增量构建要靠它切时间段。维度表尽量做成扁平宽表，能提前 join 掉的关联就别留到查询时做。

-- 事实表：粒度到订单，按天分区 CREATE TABLE dwd_order_fact ( order_id string, part_dt string, user_id string, sku_id string, channel_id string, pay_amount decimal(18,2), is_paid tinyint ) PARTITIONED BY (dt string); -- 建完先跑一遍主查询，确认模型能覆盖最常用的那几条 SELECT part_dt, COUNT(DISTINCT order_id) AS ord_cnt, SUM(pay_amount) AS gmv FROM dwd_order_fact WHERE dt BETWEEN '2024-01-01' AND '2024-01-31' AND is_paid = 1 GROUP BY part_dt;

可计算列是个很实用的功能，能把表达式沉淀在模型层。比如「实付金额 = 应付 - 优惠」这种计算，写在模型里，BI 端直接用字段名就行；如果留在 BI 端写表达式，每条报表各写一遍不说，还容易导致 Cube 无法识别、查询直接打到明细上。我一般会跟业务方约定：凡是会在三个以上报表出现的计算，一律进模型。

缓慢变化维度要提前想清楚。维表数据会变（比如商品类目调整），用全量快照最简单但 Cube 要重建；用拉链表能保留历史但模型复杂度上一个台阶。做课程设计选全量快照完全够，做生产方案就得跟业务确认「历史口径要不要跟着变」，这个问题的答案直接决定要不要重建历史 Segment。

流式数据的模型是另一套逻辑。Kafka 进来的数据没有明确边界，需要定义分区策略和消费位点，建出来的模型配的是流式 Cube，构建方式和批处理完全不同。文档里对这一块有单独章节，做实时看板的方案绕不开。

4.2 Cube 设计：聚合组、最大维度组合数与度量选择

Cube 的本质是「所有可能的维度组合」的预计算结果。十几个维度全排列会产生几万个组合，构建时间和存储都受不了，所以要用聚合组把维度分组，只在组内组合。常见的做法是按查询场景分组：时间+地区一组、时间+渠道一组、商品+类目一组，组间不交叉。绑定方式有必需维度、层级维度、联合维度几种，层级维度最适合「省-市-区」这种天然上下级关系。

最大维度组合数是个保护性参数，控制单个 Cube 的 cuboid 上限。设太小会漏掉部分组合，查询打不中；设太大会让构建时间失控。我的经验值是先用优化器跑一遍推荐，看它给出的组合数量级，再在此基础上留 20% 余量。

度量这块的选择直接决定精度和体积：

写方案时我会把这张表原样放进去，并在旁边加一句：凡是涉及对外披露的数字，一律用精确去重；内部运营看板可以用近似，但报表页脚必须写明口径。这条约定能省掉后面无数次「为什么两个系统数字对不上」的争论。

Rowkey 顺序也有讲究。高基数、过滤频率高的维度放前面，能显著提升扫描效率。日期一般放最前，因为它几乎是所有查询的第一道过滤条件。

4.3 构建策略：全量、按日期增量、流式与按文件

全量构建适合数据量不大或者维表经常变的场景，一次算完最省心，代价是每次都要重跑。按日期或时间增量是生产上最常用的，每个时间段对应一个 Segment，只算新增的那一段，历史 Segment 不动。流式构建对接 Kafka，按微批持续追加。按文件构建适合外部系统定期丢一批文件过来的场景。

增量构建有两个参数必须调：自动合并的阈值和 Segment 保留策略。Segment 数量多了之后，查询要扫的元数据变多，HDFS 上小文件也多，元数据服务的压力会明显上升。通常的做法是按天构建、每 7 天合并一次、保留最近 12 个月的 Segment，更早的归档掉。这套策略写进方案里，运维照着执行就行，不然半年后没人记得当初怎么定的。

构建时间窗口也得规划。大 Cube 一次构建跑几小时是常事，如果放在业务高峰跑，查询会被拖慢。我一般把构建任务放到凌晨，用资源组把构建队列和查询队列分开，物理上隔开之后互不干扰。

4.4 查询入口：JDBC、REST API 与下压策略

对外提供查询有三条路。JDBC 驱动最通用，BI 工具基本都支持，连接串形如jdbc:kylin://host:7070/project_name，把项目名带上就自动路由到对应空间。REST API 适合嵌到自己的应用里，构建触发、任务状态、SQL 查询都有对应接口，这也是那份 Kylin API 文档最实用的部分。

import requests BASE = "http://host:7070/kylin/api" AUTH = ("ADMIN", "KYLIN") # 仅本地调试，生产必须用改过密码的专用账户 def run_sql(project, sql, limit=1000): """同步查询，适合调试；大结果集改用异步接口拿 query_id 轮询""" resp = requests.post( f"{BASE}/query", auth=AUTH, json={"sql": sql, "project": project, "limit": limit}, timeout=60, ) resp.raise_for_status() body = resp.json() # 返回体里的 cube 字段有值说明命中了预计算，为空说明走了明细或下压 return body.get("cube"), body.get("results", []) if __name__ == "__main__": cube, rows = run_sql("demo_project", "SELECT part_dt, COUNT(*) FROM dwd_order_fact GROUP BY part_dt") print("命中Cube:", cube, "返回行数:", len(rows))

这段脚本的重点不在语法，而在最后那行输出：cube字段为空就是一次失败的查询设计。接口路径和参数名以文档里的 API 章节为准，不同版本会有调整，写方案时别把路径写死成「永久有效」。

下压是另一条路。当一条 SQL 实在没法用 Cube 满足时，可以把它推回 Hive、原生 SparkSQL、Impala 或者外部 SparkSQL 去算。开了下压，查询不会直接失败，而是换个引擎跑，代价是延迟从亚秒变成几十秒。方案里我会明确写：下压只作为兜底，不承诺性能；如果某类查询长期走下压，说明 Cube 该补维度了。

查询本身有两条限制值得提前告知使用方：只支持 SELECT，写操作一律拒绝；没开下压时，命中不了 Cube 的查询不会重定向，直接返回空或者报错。这两条写在用户手册第一页，能挡掉一半的「系统是不是坏了」的工单。

5. 常见问题排查：装不上、构建卡住、查不到 Cube 的三类翻车现场

这一章按「现象 → 原因 → 解决」写，全是实际会遇到的。放在方案里也有价值，验收阶段多半会用上。

现象一：安装到最后一步报 HBase 权限不足，提示某个账户没有写权限。原因是集群开了 HBase 权限检查，而运行账户没被授权。正规解法是让管理员授权，把读写建删的权限都给到运行账户；如果只是本地沙箱想快点跑通，可以在测试环境关掉权限检查，把协处理器相关配置清空、认证方式改成 simple。血泪经验是：这个操作只能在沙箱做，生产上关掉权限检查等于把门锁拆了。

现象二：点了构建，任务一直停在等待状态，日志里没有任何报错。八成是 YARN 资源不够或者队列配错了。先看 YARN 界面里可用容器数，再看构建引擎配置的队列名和集群里实际存在的队列对不对得上。沙箱环境的常见情况是内存给得太少，容器起不来但也不报错，看起来就像卡死。把节点的可分配内存调到 8192 MB 以上，问题基本消失。

现象三：SQL 在界面上能查出结果，但查询引擎显示没命中 Cube，耗时好几秒。原因通常是三个之一：维度没进聚合组、度量类型不匹配（比如查询用了精确去重，Cube 里配的是近似）、过滤条件用了函数导致无法下推。排查方法是用建模页面里的验证 SQL 功能，它会直接告诉你缺哪个维度。这条我建议做成标准动作，每次改完 Cube 都跑一遍验证再上线。

现象四：元数据从 HBase 迁到 RDBMS 后起不来，日志里是连接相关的异常。常见原因是 JDBC 驱动没放进依赖目录、连接串里的库不存在、或者连接池上限超过了数据库的最大连接数。按顺序检查这三项，一般能定位。迁完别急着删老数据，跑一周对照再清理，这个后悔药很便宜。

现象五：增量构建跑了两个月，查询越来越慢。Segment 数量膨胀，元数据和 HDFS 小文件都在涨。解决靠策略不靠优化：设自动合并阈值、设保留窗口、定期做一次 compaction。这类问题不会自己好，只会在某天突然爆发。

6. 验收与答辩：用六个指标证明这套方案真的跑通了

方案写完只是纸面功夫，能不能交付看的是验收。我一般准备一张验收表，每项都对应一个可复现的操作，答辩时按顺序演示一遍，比讲十分钟架构图有用。

命中率这一项最容易被质疑，也最能体现设计水平。答辩时如果被问「为什么还有 10% 没命中」，正确回答不是「够用了」，而是指出这些未命中的查询是什么类型、是走了下压还是补了维度，有没有对应的优化计划。

演示环节我建议留一个对比：同一条 SQL，先在没建 Cube 的明细表上跑一次，再切到 Cube 上跑一次，两次的耗时差直接摆在屏幕上。这比任何架构描述都有说服力。另外提前准备好两个问题的答案——为什么不用即席查询引擎、Cube 占用多少存储，这两个几乎必问。

关于存储占用，给个量化说法：Cube 体积通常是原始明细的 10% 到 30%，取决于维度基数和聚合组设计，写方案时按 20% 估算，验收时用实际的 HDFS 目录大小校正。预估偏差太大就回去看聚合组是不是切得太碎。

从那以后我每次交这类方案，都强制自己先跑一遍「全新机器装一遍 + 样例 Cube 构建 + 一条 SQL 命中验证」这三步，再动笔写验收章节。文档写得再漂亮，装不上就是零分。希望这套结构能帮到你，照着填自己的数据就行。

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