企业官网建设流程全解析

简介：这份《Kyligence Enterprise 3.4》中文PDF文档，面向大数据分析工程师、数据仓库开发者及BI集成人员，系统讲解Apache Kylin的API接口与使用方式，帮助读者在批处理、微批处理、Kafka流处理等场景中高效构建与查询Cube。文档内容覆盖安装与配置、元数据存储、系统配置、数据源导入、模型与Cube设计、SQL查询规范、驱动与BI工具集成、安全控制等模块，并针对CDH、HDP、MapR、华为FusionInsight等环境给出部署指引，还涉及查询下压、Spark资源动态配置、TopN与精确去重计数等实用知识点。资源包共1个PDF文件，大小约96.06MB，目录层级完整，便于按章节检索查阅。目前已有525人学习下载，适合需要系统掌握Kylin API与大数据处理流程的中高级读者参考。

1. 从一份 3.4 版 PDF 说起：Kyligence Enterprise 到底解决什么问题

如果你手头正躺着一份Kyligence_Enterprise_3_4-zh.pdf，翻了几页发现全是安装、建模、Cube、REST API 的目录树，大概率会犯两个难：一是这玩意儿到底跟我用过的 Apache Kylin 差在哪，二是文档这么厚，从哪一节开始动手才不至于白折腾。我第一遍拆这份文档时也这样，目录里从 CDH、HDP、MapR 一路排到 FusionInsight，光安装章节就够看半天。

先把定位说清楚：Kyligence Enterprise 是基于 Apache Kylin 核心做的企业级 OLAP 分析平台，主打 PB 级数据集上的亚秒级查询响应和高并发访问，面向的是业务分析师、数据科学家和 IT 工程师这类角色。它跟裸 Kylin 最大的区别不在查询引擎，而在企业级能力——多租户、读写分离、资源组、行列级权限、Kerberos/Sentry 集成、REST API 全套管理接口，这些在开源版里要么没有，要么得自己拼。

这份 3.4 中文文档的价值就在这：它把「装起来 → 接数据源 → 建模型 → 构建 Cube → 查 SQL → 接 BI → 管权限 → 调 API」整条链路写全了。适合两类人：一类是要在已有 Hadoop 集群上落地一套加速层、又不想从零啃英文文档的工程师；另一类是已经用了 Kylin、想搞清楚企业版在部署模式和 API 上多了哪些东西的熟手。下面按我实际拆文档的顺序，把能直接抄作业的部分挑出来讲。

2. 安装前置条件与多平台部署：别急着解压，先把账算清

2.1 前置条件不是走过场，资源不够直接卡在构建阶段

文档里「安装前置条件」这一节看着像例行公事，实际是翻车高发区。核心几条：Java 环境要求 JDK 8（64 位）或以上，整个 Hadoop 环境所有节点都要满足；运行 Kyligence Enterprise 的 Linux 账户必须具备 HDFS 读写、Hive 表创建读取、HBase 表操作（用 JDBC 存元数据时可忽略）、提交 MapReduce 任务这几项权限。

集群资源分配这几项建议直接对照检查，低于这个线后面构建 Cube 会莫名其妙失败：

沙箱或虚拟机环境另有一条硬线：处理器不少于 4 核、内存不少于 10 GB。推荐的硬件配置是 32 vCore、128 GB 内存、至少一块 1TB SAS 盘（7200RPM，RAID1）、至少两个 1GbE 网口。Linux 推荐 RHEL 6.4+/7.x 或 CentOS 6.4+/7.x。

权限验证别跳过，文档给了一套手工验证流程，我一般会照着跑一遍：

# 切到 hdfs 用户创建 Kyligence 工作目录并授权 su hdfs hdfs dfs -mkdir /kylin hdfs dfs -chown KyAdmin /kylin hdfs dfs -mkdir /user/KyAdmin hdfs dfs -chown KyAdmin /user/KyAdmin # 验证 KyAdmin 的 HDFS 读写权限 hdfs dfs -put <any_file> /kylin hdfs dfs -put <any_file> /user/KyAdmin

这里KyAdmin是文档假设的运行账户，实际替换成你自己的账户。/kylin是默认工作目录，对应conf/kylin.properties里的kylin.env.hdfs-working-dir。如果这一步put报权限拒绝，后面所有构建都会失败，所以先在这里把权限问题解决掉。

Hive 权限验证同理，需要手工建一个数据库（文档示例叫kylinDB），并在conf/kylin.properties里设置kylin.source.hive.database-for-flat-table=kylinDB：

-- 在 hive 客户端执行，验证建库建表删表权限 CREATE DATABASE kylinDB LOCATION "/kylin"; USE kylinDB; CREATE TABLE t1(id string); DROP TABLE t1;

如果集群启用了 Sentry 管理 Hive 数据权限，还得额外授权当前用户访问 Kyligence Enterprise 的 HDFS 工作目录和临时目录，文档指向「与 Kerberos + Sentry 集成」那一节。用 HBase 作 Metastore 的话，kylin.metadata.url要配成XXX_NS:XXX_instance@hbase这种格式，命名空间和实例名按集群唯一标识来。

2.2 四个平台的安装差异，其实就卡在账户和组件启动上

文档覆盖了 CDH、HDP、MapR、华为 FusionInsight 四个平台。我拆下来发现，安装步骤本身大同小异，真正的差异在账户选择和组件启动顺序。

CDH 环境推荐用默认账户cloudera访问沙箱，访问 Cloudera Manager（默认http://<host_name>:7180/）确认 HDFS、Yarn、Hive、HBase、Zookeeper 都正常无告警。HDP 环境推荐用root账户，需要先手动启动 Ambari：

# HDP 环境启动 Ambari ambari-agent start ambari-server start

注意 HBase 不在 HDP 默认启动项里，得手动拉起来。MapR 环境推荐用mapr账户（默认密码mapr），集群节点不能直接 SSH，要以 MapR Installer 为跳板，SSH 密钥在/opt/mapr/installer/data目录下，访问集群资源前还得生成 ticket：

# MapR 环境生成 ticket maprlogin password

沙箱配置上，文档反复强调用 Bridged Adapter 模型替代 NAT 模型，这样沙箱能拿到独立 IP，本地和远程都能访问 GUI。这个建议很实在，NAT 模式下端口转发配起来容易出玄学问题。

四个平台都会遇到同一个报错：org.apache.hadoop.hbase.security.AccessDeniedException: Insufficient permissions for user 'root' (auth:SIMPLE)。这是 HBase 写入权限不足。文档给的解法是关闭 HBase 权限检查——把hbase.coprocessor.region.classes和hbase.coprocessor.master.classes设为 empty，hbase.security.authentication设为simple。生产环境慎用这个做法，沙箱里图省事可以。

2.3 快速安装与启动验证

前置条件过了之后，安装本身很快。文档「快速开始」章节给的流程：

# 解压到安装路径 cd /usr/local tar -zxvf Kyligence-Enterprise-{version}.tar.gz # 设置环境变量 export KYLIN_HOME=/usr/local/Kyligence-Enterprise-{version} # 启动 $KYLIN_HOME/bin/kylin.sh start # 观察启动日志 tail -f $KYLIN_HOME/logs/kylin.log # 检查进程 ps -ef | grep kylin

{version}替换成实际版本号。启动后访问http://{host}:7070/kylin/，默认用户名ADMIN、密码KYLIN，首次登录强制改密码，要求至少 8 位且包含数字、字母、特殊字符。

文档准备了两套出场配置：profile_prod（默认，生产环境）和profile_min（资源有限环境）。沙箱资源紧张的话切到 min：

rm -f $KYLIN_HOME/conf/profile ln -sfn $KYLIN_HOME/conf/profile_min $KYLIN_HOME/conf/profile

导入样例数据用$KYLIN_HOME/bin/sample.sh，跑完在系统页面点「重载元数据」，然后进learn_kylin项目构建kylin_sales_cube验证功能。查询验证用：

SELECT PART_DT, COUNT(*) FROM KYLIN_SALES GROUP BY PART_DT

查询限制有两条要记住：仅支持 SELECT 查询；未开启查询下压时，Cube 数据满足不了的查询不会重定向。查询成功后状态下方会显示命中的 Cube。

3. 元数据存储与系统配置：RDBMS 迁移和参数重写

3.1 从 HBase 迁到 RDBMS，什么时候值得做

默认元数据存 HBase，文档专门给了「将元数据从 HBase 迁移至 RDBMS」一节，支持 MySQL 和 Microsoft SQL Server。什么时候该迁？我的判断是：元数据量大了之后 HBase 的运维复杂度上来了，而 RDBMS 备份恢复、查询排查都更顺手，尤其是团队里没有专职 HBase 运维的时候。

迁移本身文档给了步骤，核心是先把 RDBMS 配好、建库建表，再执行迁移工具，最后改kylin.metadata.url指向新的 RDBMS 连接。迁移前务必备份原 HBase 元数据，这个没有后悔药。用 JDBC 连元数据存储之后，前面提到的 HBase 读写权限检查就可以忽略了，这也算个附带好处。

3.2 多级配置重写：改参数不用重启的实用机制

系统配置这块，文档列了基本配置参数、多级配置重写、Cube 存储引擎配置、Spark 资源动态配置、Hadoop 队列配置、Beeline 连接 Hive、查询缓存、压缩配置、日志滚动等。其中「多级配置重写」是最值得先搞懂的机制——它允许在不同层级覆盖配置，不用改全局文件。

实际用起来，我一般把跟具体 Cube 相关的参数放在 Cube 级别覆盖，集群通用的放全局。这样调优时不会因为改了一个全局参数影响到其他业务线。Spark 资源动态配置和 Hadoop 队列配置这两项，在多租户场景下是必调的，否则一个业务的大查询会把整个队列占满。

Beeline 连接 Hive 的配置在文档里有独立小节，主要是为了让 Kyligence Enterprise 通过 Beeline 方式访问 Hive 元数据，跟直接 JDBC 连 Hive 是两条路，具体选哪条看集群的 Hive 版本和认证方式。

3.3 查询下压：把算不动的部分推回数据源

查询下压是这份文档里技术含量较高的一节，分了下压至原生 SparkSQL、下压至 Hive、下压至外部 SparkSQL、下压至 Impala 几个方向。原理不复杂：当查询无法完全由 Cube 满足时，把剩余部分下推到数据源执行，而不是直接报错返回。

配置上，下压至原生 SparkSQL 和外部 SparkSQL 的区别在于用哪个 Spark 集群跑——内置的还是集群上已有的。下压至 Hive 适合 Hive 侧资源充足、SQL 兼容性好的场景；下压至 Impala 则看集群有没有 Impala 且版本匹配。

这里有个容易踩的点：下压不是开了就万事大吉，SQL 方言差异会导致下压后的语句在数据源侧执行失败。文档在「查询 FAQ」里有相关排查思路，实际遇到下压失败，先看日志里下压后的 SQL 长什么样，再对照数据源的方言改。

4. 模型与 Cube 设计：从数据源导入到构建的完整链路

4.1 数据源导入的几种姿势

文档支持的数据源挺全：Hive、Kafka、RDBMS（Greenplum、MySQL、MS SQL Server、gbase、Oracle）、Impala、文件数据源。Hive 是默认输入数据源，样例数据也是导进 Hive 的。

Kafka 数据源对应的是流式场景，文档在「基于流式数据的模型设计」和「基于流式数据的 Cube 设计」两节里讲了怎么处理。RDBMS 系列数据源各有各的导入配置，Greenplum、Oracle 这些的 JDBC 连接参数在对应小节里。文件数据源适合临时导入一批数据做验证。

数据导入方式上，文档区分了全量导入、按日期/时间导入、流式导入、按文件导入、自定义增量构建几种。全量适合小表或首次导入；按日期/时间适合有分区字段的事实表；流式对应 Kafka 场景；自定义增量构建则给了开发者指南，适合有特殊增量逻辑的场景。

4.2 模型设计的几个关键决策

模型设计这块，文档从基本模型设计讲到基于流式数据的模型设计、缓慢变化维度、可计算列、模型推荐、模型检测。几个实际会影响后续构建的决策点：

缓慢变化维度（SCD）的处理方式直接决定维度表怎么建。可计算列支持一系列函数，文档列了具体支持哪些，用之前先对照，别写完发现函数不支持。模型推荐和模型检测是两个辅助功能，推荐帮你生成初始模型，检测帮你发现模型里的问题，新手可以先用推荐再手工调。

度量设计是 Cube 性能的核心。文档覆盖了 TopN、精确去重计数、近似去重计数、近似 Percentile、相关函数 CORR（Beta）、半累加度量（Beta）、Sum Expression（Beta）、明细表索引。精确去重和近似去重的选择是个经典权衡：精确去重（如 Bitmap）准确但占空间，近似去重（如 HyperLogLog）省空间但有误差。文档把两者都列出来，实际选哪个看业务对准确率的容忍度。

4.3 Cube 设计与构建

Cube 设计涉及维度、聚合组、最大维度组合数、Cube 优化器。聚合组是把经常一起查询的维度放一组，减少组合爆炸；最大维度组合数控制 Cube 的膨胀程度，设太大构建慢且占空间，设太小查询命中率低。Cube 优化器会根据查询历史自动调整。

构建方式文档给了全量构建、按日期/时间构建、流式构建、按文件构建、自定义增量构建。构建完在「Cube 与 Segment 管理」里能看到 Segment 状态。文档还有「Cube 设计最佳实践与示例」和「自动建模」两节，自动建模会基于查询历史推荐模型，适合已经有查询负载的场景。

验证 SQL 这一节别跳过，构建完先用验证 SQL 确认 Cube 能正常命中，再去接 BI 工具。我见过构建成功但查询命中不了的案例，问题往往出在维度组合或度量配置上。

5. 查询、BI 集成与安全控制：API 文档真正落地的地方

5.1 SQL 查询与函数参考

查询部分文档讲了基本原理、查询下压、在用户界面执行 SQL 查询、异步查询、为查询指定 Cube 优先级。异步查询适合跑长查询，不用干等。指定 Cube 优先级在多 Cube 场景下有用，能让查询优先命中你期望的那个。

SQL 规范参考这块内容很厚，运算符（比较、逻辑、算术、字符串）、函数（算数、字符串、日期、条件、类型转换、窗口、分组、交集、差集、聚合、Bitmap）都列了。Bitmap 函数是做精确去重时常用的，跟度量设计里的精确去重计数对应。写 SQL 前先翻一遍函数列表，能省不少试错时间。

5.2 与 BI 工具集成：驱动是第一步

文档的 BI 集成章节覆盖了 Tableau（Desktop/Server）、Power BI（Desktop/Service）、MicroStrategy、IBM Cognos、Qlik（Sense/Sense Enterprise/View Desktop/View Server）、OBIEE（11g/12c）、SAP BusinessObjects、SmartBI Insight、FineBI、FineReport、Apache Zeppelin、Yonghong BI、Excel、Python。

集成的第一步都是装驱动。文档给了 Kyligence JDBC 驱动和 ODBC 驱动（Windows/Linux/Mac 三个版本）。JDBC 驱动用于 Java 系工具，ODBC 用于 Tableau、Power BI、Excel 这类。装完驱动配连接串，再在 BI 工具里建数据源。

这里有个常见坑：不同 BI 工具对 SQL 方言的支持程度不一样，有些工具生成的 SQL 会带 Kyligence 不支持的语法。文档在「查询 FAQ」里有相关说明，实际遇到就在 BI 工具里改用自定义 SQL 或调整生成策略。

5.3 安全控制与 REST API

安全控制管理覆盖用户管理、用户组管理、数据访问权限（项目级、表级、行级、列级）、加载表时的 Hive 权限映射、与 LDAP 集成、与 Kerberos 集成、Kafka 与 Kerberos 集成、CDH 与 Kerberos+Sentry 集成、与第三方用户认证系统集成、与第三方权限系统集成。

行列级权限是企业版相对开源版的明显增强，行级权限能控制用户只能看到符合条件的数据行，列级权限控制可见列。这两项在数据合规要求高的场景里是刚需。

REST API 是这份文档里对开发者最有价值的部分，覆盖访问与安全认证 API、项目 API、数据源 API、模型 API、Cube API（查看信息、构建、管理）、Segment 管理 API、任务 API、查询 API、缓存 API、异步查询 API、Cube 元数据导出/导入 API、访问控制权限 API（用户管理、用户组管理、项目级/表级/行级/列级访问控制权限）。

用 API 做自动化构建是常见需求，比如定时触发 Cube 构建、批量导出元数据。认证方式文档在「访问与安全认证 API」里讲了，一般是先拿 token 再带 token 调其他接口。调 API 时注意 Cube 构建是异步的，提交后要轮询任务状态，别提交完就以为完事了。

6. 运维排查与升级：几个我踩过的坑和收尾技巧

6.1 日常运维与诊断

系统运维章节覆盖日常维护、基本运维、日常运维工具、元数据检查、元数据备份与恢复、项目级元数据导入导出、垃圾清理、跨集群迁移、监控和诊断、系统日志、服务器状态监控、环境依赖服务检测、任务报警、系统诊断与任务诊断、守护进程。

元数据备份与恢复是保命操作，升级前、迁移前、大改模型前都该做一次。项目级元数据导入导出适合把一套模型从一个环境搬到另一个环境。垃圾清理清的是构建过程中产生的临时文件，不定期清会占满 HDFS。

诊断部分，系统诊断和任务诊断是两个入口。任务构建失败时，先看任务诊断里的日志，再对照「查询 FAQ」和「系统诊断」找原因。环境依赖服务检测能快速确认 HDFS、Yarn、Hive 这些依赖服务是否正常。

6.2 升级路径与许可证

升级章节覆盖升级至 3.x 最新版本、从 KAP 2.x 升级、从 Apache Kylin 升级、手动升级、内置组件。从 Apache Kylin 升级这条对开源用户比较有用，但要注意企业版和开源版的元数据格式可能有差异，升级前备份是铁律。

许可证和容量在文档里有独立小节，申请许可证在附录里。容量这块跟你的许可证类型挂钩，超容量会有相应限制。

6.3 几个具体踩坑记录

现象：Cube 构建任务卡在某个阶段不动。原因通常是 Yarn 资源不足或队列被占满。解决：先看 Yarn 队列状态，确认yarn.nodemanager.resource.memory-mb等参数是否达标，必要时调大或换队列。

现象：查询报错说找不到 Cube。原因可能是查询下压没开，且 Cube 数据满足不了该查询。解决：开启查询下压，或调整 Cube 的维度组合让查询能命中。

现象：BI 工具连不上。原因多为驱动版本不匹配或连接串参数错误。解决：确认 JDBC/ODBC 驱动版本与 Kyligence Enterprise 版本对应，检查连接串里的 host、port、认证方式。

现象：元数据迁移后部分模型丢失。原因可能是迁移过程中 HBase 里有未刷盘的数据。解决：迁移前先做一次元数据检查，确认所有模型都已持久化，迁移后逐个项目核对。

现象：启动时报 HBase 权限拒绝。原因就是前面说的AccessDeniedException。解决：沙箱环境可关闭 HBase 权限检查，生产环境找管理员授权。

6.4 一个收尾技巧：用 REST API 做构建状态巡检

最后分享一个我常用的技巧。Cube 多了之后，靠页面一个个看构建状态不现实，用 REST API 批量查任务状态更省事。思路是先调查询 API 拿到任务列表，再按状态过滤出失败和运行中的：

# 先认证拿 token（具体接口见「访问与安全认证 API」） curl -X POST "http://{host}:7070/kylin/api/user/authentication" \ -H "Content-Type: application/json" \ -d '{"userName":"ADMIN","password":"your_password"}' # 带 token 查任务列表，过滤失败任务 curl -X GET "http://{host}:7070/kylin/api/jobs" \ -H "Authorization: Basic {base64_token}" \ -H "Content-Type: application/json"

{host}和端口按实际环境替换，认证方式以文档「访问与安全认证 API」为准。拿到任务列表后按job_status字段过滤，失败的再逐个查详情。这套巡检脚本我一般配个定时任务，构建失败能第一时间发现，不用等业务方来问。

从那以后我每次升级或迁移前，都强制走一遍「元数据备份 → 元数据检查 → 升级 → 验证 SQL 命中」这个流程，少一步都可能出问题。希望帮到你。

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