★ FEATURED ARTICLE 简介《Kyligence Enterprise 3.4》中文PDF是一份面向大数据分析工程师、BI实施人员与数据平台运维者的Kylin API与工程实践查阅手册重点解决Kylin在部署配置、数据接入、模型Cube设计、SQL查询及BI集成中的查阅需求。内容从快速开始与安装前置条件讲起覆盖CDH、HDP、MapR、FusionInsight等环境部署、RDBMS元数据存储、系统配置与Spark/Hadoop资源调度并延伸到Hive、Kafka、RDBMS、Impala等数据源导入、模型与Cube设计、维度聚合组、度量设计、SQL规范与查询下压以及JDBC/ODBC驱动和Tableau、Power BI等BI工具集成、安全权限管理。包内共1个PDF文件压缩包约96.06MB目录层级清晰便于按安装、配置、建模、查询、集成与安全等模块检索。已有529人学习可作为Kylin API速查、平台方案设计与日常问题排查的参考手册。1. 一份 3.4 版中文手册真正的用法先查参数再谈架构下载区里躺着的这份 kylin api文档全名是某个基于 Apache Kylin 内核的企业级 OLAP 产品 3.4 版中文手册六百多页目录从安装前置条件一路排到权限 API。翻它的人多半不是为了通读而是为了查三件事某个参数到底该写在哪一层、Cube 构建卡住时日志去哪看、REST 接口的认证怎么带。它更像一本字典而不是教程——知道要找什么答得又快又准不知道找什么翻十页也落不到地上。我把它当三样东西用装机清单、参数速查表、故障对照表。它面向的是要在 Hadoop 集群上把离线 OLAP 跑起来的人——数仓工程师、BI 实施、以及需要把构建流程接进调度系统的平台开发。单机沙箱能跑生产集群也能照着配。下面按实际落地顺序拆先跑通再谈设计。2. 单机跑通前置条件核对、profile 切换与样例 Cube 验证这一章的目标很具体在一台机器上把服务拉起来能看到 7070 端口的登录页并且用一个自带样例 Cube 跑出第一条查询。走完这一步后面所有配置才有对照物。2.1 集群侧先过四道门组件、JDK、账号、资源手册把依赖写得很直白HDFS、YARN、MapReduce、Hive、Zookeeper 是必需组件Kafka 只有在做流式数据源时才需要。JDK 必须是 8 的 64 位版本或以上如果集群还停在 JDK 7手册附录里有一节专门讲低版本 JDK 的兼容配置但那是补丁路线不是推荐路线。账号权限是最容易被跳过的一步。运行服务的 Linux 账号需要同时具备HDFS 工作目录读写、Hive 建表和读表、HBase 建表和操作走 RDBMS 元数据时可忽略、提交 MapReduce 任务。这四项缺一项表现都不是报权限错误这么友好而是启动到某个阶段静默卡住。资源侧有几个硬门槛低于这个值构建任务会以各种奇怪的方式失败配置项最低值说明yarn.nodemanager.resource.memory-mb8192 MB单节点可分配容器内存总量yarn.scheduler.maximum-allocation-mb4096 MB单容器上限小于 executor 内存会被直接拒绝mapreduce.reduce.memory.mb700 MBMR 任务 reduce 阶段内存mapreduce.reduce.java.opts512 MB对应 JVM 堆大小yarn.nodemanager.resource.cpu-vcores8沙箱环境下的核数下限沙箱或虚拟机至少要给到 4 核、10 GB 内存否则连样例 Cube 都构不完。生产侧手册给的推荐值是 32 vCore、128 GB 内存、一块 1 TB SAS 盘做 RAID1外加两个千兆网口——这个配置对应的是中等数据量下的构建与查询并发不是起步门槛评估时别被吓退。2.2 解压、环境变量与 HDFS 工作目录装之前先定两件事装在哪个路径、用哪个 Linux 账号跑。手册示例假设装在/usr/local/、用root跑实际环境里通常换成各平台默认账号比如 CDH 用cloudera。路径定了之后写进环境变量后续所有脚本都靠它定位。# 1) 解压到约定目录包名按实际版本替换 cd /usr/local tar -zxvf Kyligence-Enterprise-3.4.tar.gz # 2) 指向解压后的目录建议写进 ~/.bashrc export KYLIN_HOME/usr/local/Kyligence-Enterprise-3.4 # 3) 建 HDFS 工作目录属主给运行账号 su hdfs hdfs dfs -mkdir /kylin hdfs dfs -chown kyadmin /kylin hdfs dfs -mkdir /user/kyadmin hdfs dfs -chown kyadmin /user/kyadmin exit # 4) 验证读写两个目录各传一个文件 hdfs dfs -put /etc/hostname /kylin hdfs dfs -put /etc/hostname /user/kyadmin这段脚本的关键在第三步和第四步。/kylin对应配置项kylin.env.hdfs-working-dir的默认值如果改了这个配置HDFS 上的目录也要同步改否则启动时会在创建工作目录阶段报路径不存在。/user/账号是 Hadoop 的默认用户目录很多临时文件会落在这里缺了它后面构建会报一个跟权限看起来毫无关系的错。第四步的上传验证不是走过场——有权限和看起来有权限是两回事Sentry 或 Kerberos 环境下尤其明显。提示没有 HDFS 超级用户权限时先su hdfs再执行建目录和 chown比找管理员提工单快得多。2.3 profile_min 与 profile_prod 怎么选$KYLIN_HOME/conf/下预置了两套出场配置profile_prod和profile_min通过一个名为profile的符号链接指向其中之一。前者是默认按生产环境的内存与并发给参数后者压缩资源占用给沙箱和单机演示用。# 查看当前指向 ls -l $KYLIN_HOME/conf/profile # 切到省资源模式 rm -f $KYLIN_HOME/conf/profile ln -sfn $KYLIN_HOME/conf/profile_min $KYLIN_HOME/conf/profile判断标准很简单机器内存低于 16 GB或者 YARN 上还有别的业务在跑就用profile_min。用profile_prod跑在小内存机器上典型现象是服务能起来但一构建就 OOM或者 Spark executor 一直处于等待资源的状态。反过来生产上误用了profile_min查询延迟会莫名其妙地高因为并行度和缓存都被压下去了。这套切换是符号链接而不是复制文件改完不需要重启配置中心但需要重启服务才生效。2.4 启动、样例数据与第一条查询启动命令本身没什么好说的值得说的是启动成功的判定标准。控制台打出提示信息只代表进程拉起来了真正的就绪要看日志里 Web 服务器开始监听的那一行。# 启动 $KYLIN_HOME/bin/kylin.sh start # 盯日志看到服务器启动完成的日志再访问页面 tail -f $KYLIN_HOME/logs/kylin.log # 确认进程 ps -ef | grep kylin # 改端口后端口 7070 偏移量 $KYLIN_HOME/bin/kylin-port-replace-util.sh set PORT_OFFSETPORT_OFFSET这个机制值得记住。默认端口 7070 被占用时不要去改 Tomcat 配置文件用这个工具设偏移量实际端口变成 7070 加偏移量前后端会一起调。设完之后记得同步防火墙规则否则本地 curl 通、浏览器打不开。浏览器访问http://host:7070/kylin/默认账号ADMIN、密码KYLIN首次登录强制改密码要求至少 8 位且同时包含数字、字母和特殊字符。这一步别用弱口令敷衍后面接 LDAP 或第三方认证时本地账号往往是兜底入口。样例数据用自带脚本导入 Hive# 导入样例表到 Hive 的 learn_kylin 库 $KYLIN_HOME/bin/sample.sh跑完之后必须去系统页面点一次重载元数据否则数据源列表里看不到新表——这是新手最常卡住的地方脚本明明执行成功界面就是没有。重载完成后进入learn_kylin项目构建kylin_sales_cube构建成功后执行-- 按分区日期统计订单数验证 Cube 是否命中 select PART_DT, count(*) from KYLIN_SALES group by PART_DT;查询结果返回后状态栏下方的查询引擎条目会显示命中的 Cube 名称这是判断到底走没走预计算的唯一可靠依据。还有两条限制要提前知道只支持 SELECT 查询如果没有开启查询下压凡是 Cube 数据满足不了的查询不会被重定向到 Hive而是直接报错。很多人以为是 SQL 写错了其实是下压开关没开。3. 元数据与系统配置把 HBase 换成 MySQL 的迁移路径与参数分层跑通之后紧接着要处理的是元数据放哪。默认走 HBase能跑但在需要定期备份、跨集群迁移、按项目导入导出的场景里关系型库明显更顺手。3.1 从 HBase 迁到 RDBMS 的三个现实理由第一个是备份与恢复。HBase 上做元数据备份要么整表快照要么走产品自带的导出功能恢复时对版本一致性要求高换成 MySQL 或 SQL Server 之后DBA 现有的物理备份、主从、时间点恢复全都能直接套用。第二个是排查效率。元数据出问题时能直接用 SQL 查表定位和在 HBase shell 里翻 rowkey 完全不是一个体验。第三个是迁移成本。跨集群搬一套环境RDBMS 导一份 dump 比搬 HBase 表简单得多。手册提供了从 HBase 迁移至 RDBMS 的专门章节思路是先把元数据导出再在目标库建表、导入、改连接串、重启验证。顺序不能反——先改配置再导数据服务会因为连不上新库起不来回滚还得再改一次。3.2 MySQL 库、账号与连接串的落地写法数据库侧的准备动作很标准字符集一定要用 utf8mb4元数据里存项目名、模型名、中文描述utf8 在三字节之外的字上会出问题。-- 元数据库与专用账号 CREATE DATABASE kylin_metadata DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci; CREATE USER kylin_meta% IDENTIFIED BY ChangeMe_2024; GRANT ALL PRIVILEGES ON kylin_metadata.* TO kylin_meta%; FLUSH PRIVILEGES;连接串写在conf/kylin.properties里kylin.metadata.url这一项同时承载库名和 JDBC 参数格式是标识名 jdbc, 后面跟键值对。这里的标识名会成为元数据表的表名前缀改它等于换了一套元数据已有项目会全部消失所以从 HBase 迁过来时标识名要和导出文件里的保持一致。# 元数据改走 MySQLdriverClassName 按实际驱动包填 kylin.metadata.urlkylin_metadatajdbc,urljdbc:mysql://mysql-host:3306/kylin_metadata,usernamekylin_meta,passwordChangeMe_2024,driverClassNamecom.mysql.jdbc.Driver,maxActive10,maxIdle10 # HDFS 工作目录与 2.2 节建的目录保持一致 kylin.env.hdfs-working-dir/kylin # 中间表落地的 Hive 库需提前建好并授权 kylin.source.hive.database-for-flat-tablekylinDB三个参数各有各的坑。driverClassName要和$KYLIN_HOME/ext下实际放的驱动 jar 版本匹配MySQL 8 的驱动类名和 5.x 不同填错的表现是启动时报找不到驱动而不是连接失败。maxActive默认值在并发构建多个 Cube 时可能不够会出现等待连接超时。kylin.source.hive.database-for-flat-table指向的库必须存在且当前账号有建表权限否则构建到平表阶段失败日志里是一句很含糊的 Hive 执行异常。3.3 kylin.properties 的分层与多级配置重写配置不是只有全局一层。手册里提到的多级配置重写机制允许在项目级、甚至 Cube 级覆盖全局参数。这个能力在混合负载环境里非常实用默认给所有构建任务分配 8 GB executor 内存某个大 Cube 单独提到 16 GB其余不动。实际使用时的优先级从低到高大致是全局配置、项目配置、Cube 配置。排查为什么这个参数没生效时按这个顺序往上查最后落在具体 Cube 的配置页上。血泪经验是改完全局参数发现没效果八成是被上层的旧配置覆盖了而不是配置没加载。注意多级配置重写只对支持的参数生效不是所有kylin.properties里的项都能被覆盖。改之前先在手册对应章节确认这个参数是否在可重写列表里。3.4 Spark 资源、YARN 队列与查询缓存的联动Cube 构建走 Spark 引擎时资源参数本质上是在拼一个 spark-submit 命令。这些参数可以直接写在配置文件里# 构建引擎走 YARN 集群模式 kylin.engine.spark-conf.spark.masteryarn kylin.engine.spark-conf.spark.submit.deployModecluster # 指定队列避免和线上离线任务抢资源 kylin.engine.spark-conf.spark.yarn.queueroot.kylin # executor 规格 kylin.engine.spark-conf.spark.executor.memory8g kylin.engine.spark-conf.spark.executor.cores4 # 开启动态资源分配按数据量伸缩 kylin.engine.spark-conf.spark.dynamicAllocation.enabledtrue参数之间的约束关系比数值本身重要。spark.executor.memory加上 overhead 必须小于yarn.scheduler.maximum-allocation-mb否则应用提交后被 YARN 直接拒掉日志里只有一行Container 超出最大分配。spark.yarn.queue指向的队列要确认当前账号有提交权限没有权限时的报错是队列不存在容易误导成配置写错。动态资源分配开启后小 Cube 不会占满资源但spark.dynamicAllocation.maxExecutors建议显式设一个上限避免一个大 Cube 把整个队列吃干净。查询缓存是另一个容易被忽视的点。缓存以 Cube 和 Segment 为单位Segment 一旦刷新对应缓存自动失效不需要手工清。真正要调的是缓存容量和过期时间——容量给小了高频查询反复穿透到 HBase 扫描给大了堆内存压力上来GC 时间变长。常见做法是先按堆内存的三分之一给跑一周看命中率再调。4. 模型与 Cube 设计聚合组、Rowkey 顺序与度量选型的取舍配置调顺之后真正决定查询性能的是模型和 Cube 设计。这部分手册写得最厚从基本模型、流式模型、缓慢变化维度一路讲到可计算列和模型推荐但落到实操就是几个决策点。4.1 建模前先量基数与粒度动手建模型之前我会先对每张事实表跑一遍基数和粒度统计。维度基数量错后面的聚合组怎么配都是白费。-- 维度基数与事实表粒度摸底 select count(distinct user_id) as uv, -- 高基数维度谨慎进聚合组 count(distinct city) as city_cnt, -- 低基数维度适合做层级 count(*) as rows_cnt, min(part_dt) as min_dt, max(part_dt) as max_dt from dwd_order_detail;这段 SQL 的三个输出决定后续设计。uv在千万级以上时这个维度不适合和高基数维度放进同一个聚合组否则 Cube 体积会失控。city_cnt在几千以内适合配成层级维度国家-省-市让 Cube 自动裁剪组合。min_dt和max_dt决定增量构建的起始分区直接关系到第一次构建要跑多久。手册里还有基于查询历史的自动建模和模型检测功能。自动建模适合从零起步时给个初稿模型检测适合上线前扫一遍明显问题。但这两个功能都替代不了人工判断——它们看到的是历史查询模式看不到未来三个月的业务需求。4.2 聚合组、最大维度组合数与 Rowkey 顺序聚合组解决的是维度组合爆炸。一张表有 20 个维度全组合是 2 的 20 次方不可能全物化。做法是把经常一起查询的维度放进同一个聚合组组内再按必需维度、层级维度、联合维度做裁剪把组合数压到可控范围。Rowkey 顺序的影响同样直接。Cube 的存储是按 Rowkey 排序的查询过滤条件命中 Rowkey 前缀时才能跳过数据块。所以排序原则是过滤频率高的放前面基数高的放前面范围查询的维度放前面。把低基数的是否有效放第一位几乎等于放弃前缀裁剪。最大维度组合数是聚合组的兜底阀。设得太小部分查询组合没有被物化命中不了 Cube设得太大构建时间和存储一起爆。经验值是按预估的组合数上浮 30% 左右然后看构建日志里的实际组合数回头修正。4.3 度量选型精确去重、近似去重与 TopN 的取舍度量类型选错是最难在事后补救的一类问题因为改度量意味着重建整个 Cube。手册里列了几种主流的度量设计实际选择时按这张表对照度量类型适用场景主要代价精确去重计数用户数、设备数等 UV结果必须可对账构建内存和体积随基数上升明显近似去重计数超大基数、可接受 1%~2% 误差结果不可回溯为精确值TopN高频取值排行只需要前 N 名N 设大后收益迅速下降近似 Percentile延迟、金额等分位数统计分位点需要提前固定Sum Expression比率类指标拆解如转化率分母必须本身可加选型的判断标准不是哪个先进而是业务能不能接受误差。财务对账类的 UV 必须精确哪怕构建慢一倍流量分析类的 UV 用近似去重完全够用省下来的资源可以多物化两个聚合组。TopN 的 N 值要和业务方确认清楚从 100 改到 1000 通常要重构建不是改个配置的事。手册里还提到明细表索引和半累加度量这类进阶能力。明细表索引适合先聚合再下钻明细的场景配了它之后明细查询不用回源到 Hive。半累加度量处理的是库存、余额这类不能简单按时间求和的指标用之前要确认业务口径它解决的是计算方式问题不是数据问题。4.4 构建方式与 Segment 管理构建方式有五种全量、按日期/时间、流式、按文件、自定义增量。选择逻辑很清楚历史数据一次性回刷用全量日常调度用按日期增量实时性要求高的走流式外部系统给文件触发用按文件特殊的业务分批逻辑用自定义增量。日常运维里真正花时间的是 Segment 治理。每次增量构建产生一个 SegmentSegment 数量到几十个之后查询要扫的片段变多性能开始下降。手册里给的解法是合并——把相邻的小 Segment 合成大 Segment合并后原有的 Segment 失效查询计划自动指向新 Segment。注意合并操作会重写数据在业务高峰期执行会抢占构建资源。常见做法是放在凌晨调度窗口且合并前确认没有正在运行的构建任务两者并发会争抢同一批 HDFS 文件。自动合并的阈值要结合数据量定。每天增量很小但 Segment 数量增长快的场景把自动合并的触发条数调低每天增量很大、单个 Segment 已经几百 MB 的场景可以适当放宽避免频繁合并带来的写放大。5. 避坑与排查五条从日志里抠出来的故障链这一章记录的是实际部署里反复出现的五类问题。共同点是界面上的报错信息和真实原因距离很远必须回到日志里找。5.1 服务起来了但 7070 打不开现象kylin.sh start返回成功ps -ef | grep kylin能看到进程浏览器访问超时。原因通常有三种。一是服务还没真正就绪进程在初始化元数据连接这段时间端口不监听。二是端口偏移被之前的操作改过实际端口不是 7070。三是主机名解析问题服务绑定的是主机名而不是 0.0.0.0从别的机器访问不通。解决顺序先tail -f $KYLIN_HOME/logs/kylin.log看到 Web 服务器启动完成的那一行再netstat -tlnp | grep java确认实际监听端口最后从本机curl http://127.0.0.1:port/kylin/验证。本机通、远程不通就去查防火墙和主机名绑定别在应用层浪费时间。5.2 HBase 写入被拒Insufficient permissions现象安装或首次启动时报org.apache.hadoop.hbase.security.AccessDeniedException: Insufficient permissions for user。原因是当前 Linux 账号没有 HBase 表的写权限。这在 CDH 和 HDP 沙箱里尤其常见因为默认账号和 HBase 的 ACL 不是一套。解决有两条路。正规做法是让 HBase 管理员执行grant 账号,RWXCA授权权限最小化。应急做法是关掉 HBase 的权限检查把hbase.coprocessor.region.classes和hbase.coprocessor.master.classes两个配置项置空hbase.security.authentication设为simple然后重启 HBase。第二条路只适合沙箱和验证环境生产上关权限检查等于把元数据裸露出来不要这么干。5.3 样例脚本跑完了界面上还是没有表现象sample.sh执行无报错进入项目后发现数据源里空空的。原因基本是两个没有点重载元数据或者脚本导入的库和界面读取的库不是同一个。前者是操作遗漏后者多见于kylin.source.hive.database-for-flat-table被改过、而样例脚本仍按默认库导入的情况。解决先去系统页面点重载元数据刷新后再看。仍然没有就用 Beeline 连上 Hive 执行show databases;和show tables;确认learn_kylin库和其中的表真实存在再对照配置里的库名是否一致。5.4 Cube 构建卡在 Spark 阶段不动现象任务状态长时间停在某一步日志里反复出现等待资源最终超时失败。原因在 YARN 侧。要么yarn.scheduler.maximum-allocation-mb小于 executor 申请的内存容器根本申请不下来要么指定的队列没有提交权限要么集群整体资源被其他任务占满。解决先看 YARN ResourceManager 页面上这个应用的状态和诊断信息它比应用日志直白得多。内存不足就调小 executor 内存或提高队列上限队列无权限就换队列或申请授权资源被占满就和调度方协调时间窗。有一个隐蔽情况动态资源分配开启但没有设上限应用会不断申请 executor看起来像卡住实际是在缓慢扩张。5.5 查询结果对但没有命中 Cube现象SQL 能查出正确结果查询引擎一栏显示的是 Hive 或其他引擎不是 Cube 名称。原因有四种。一是没有开启查询下压Cube 满足不了的查询不会重定向直接报错或走别的路径。二是 SQL 里用了 Cube 不支持的函数或写法比如某些窗口函数组合。三是维度组合超出了聚合组的最大维度组合数Cube 里没有这个组合。四是过滤条件和 Rowkey 前缀完全不匹配虽然能查但走了全扫。解决先确认下压开关状态再把 SQL 里的函数对照手册的 SQL 规范参考逐个核对然后去 Cube 的聚合组配置里看维度组合是否覆盖最后看查询计划里扫描的 Segment 数量。四步走完基本能定位。查询命中不了 Cube 不一定是坏事有些查询走 Hive 反而更快关键是知道它为什么没命中而不是看到数字对了就收工。6. REST API 闭环验收用一条脚本串起构建、轮询与命中检查界面上点一遍能跑通不代表这套环境可以被调度系统接管。验收的真正标准是用 REST API 从零触发一次构建轮询到成功再跑一条 SQL 确认命中 Cube。整个过程不碰浏览器。认证先拿会话 cookie后续所有请求带着它# 1) 认证cookie 落盘复用 curl -s -c /tmp/kylin.cookie -X POST \ -H Content-Type: application/json \ -d {userName:ADMIN,password:改过的密码} \ http://${KYLIN_HOST}:7070/kylin/api/user/authentication # 2) 触发构建body 里给时间区间和构建类型 curl -s -b /tmp/kylin.cookie -X PUT \ -H Content-Type: application/json \ -d {startTime:1735660800000,endTime:1738339200000,buildType:BUILD} \ http://${KYLIN_HOST}:7070/kylin/api/cubes/${CUBE_NAME}/build # 3) 轮询任务状态直到 FINISHED 或 ERROR curl -s -b /tmp/kylin.cookie \ http://${KYLIN_HOST}:7070/kylin/api/jobs/${JOB_ID} # 4) 提交 SQL 验证看是否命中 curl -s -b /tmp/kylin.cookie -X POST \ -H Content-Type: application/json \ -d {sql:select part_dt,count(*) from KYLIN_SALES group by part_dt,project:learn_kylin} \ http://${KYLIN_HOST}:7070/kylin/api/query几个参数要留心。startTime和endTime是毫秒时间戳对应增量构建的分区区间给错区间会构建出一个空 Segment任务显示成功但查不到数据。buildType除了BUILD还有MERGE和REFRESH合并和重刷走同一个入口。轮询不要写死固定间隔构建时长和数据量强相关常见做法是前 2 分钟每 10 秒一次之后退避到 60 秒同时设一个总超时。接口路径和字段名在不同小版本间会有微调Web 界面的 REST API 页签里能看到当前版本的全部端点以那里为准比我凭记忆写更可靠。我习惯把第 4 步的返回结果里是否带 Cube 名称作为验收通过的唯一标准——只看 HTTP 200 是不够的200 只代表 SQL 执行了不代表走了预计算。从那以后我每次交付前都强制走一遍这个闭环哪怕只是改了一个维度。界面能点通是给人看的API 能跑通才是给调度看的。希望帮到你。本文还有配套的精品资源点击获取
阅读完成 · 觉得有帮助？
