Ubuntu 22.04 安装部署 Apache Kylin 5.0.4 指南

Ubuntu 22.04 安装部署 Apache Kylin 5.0.4 指南：覆盖 JDK 8、PostgreSQL 14、ZooKeeper、Hadoop 3.2.1 伪集群与 Hive 3.1.3 前置搭建，Kylin 官方包下载校验、核心配置、启动检查项十步排障实录与验证，全部命令真实执行。

Apache KylinKylinApache安装部署Ubuntu 22.04大数据2026/10/15

Ubuntu 22.04 安装部署 Apache Kylin 5.0.4 指南

本文在 Ubuntu 22.04（12 核 CPU、31GB 内存、300GB 磁盘）服务器上从零完成 Apache Kylin 5.0.4 的部署：先搭建 ZooKeeper、Hadoop 3.2.1 伪集群与 Hive 3.1.3 元数据服务，再安装 Kylin 本体并逐项通过启动自检。文内全部命令与回显均真实执行，其中 Spark 环境检查的十步排障实录是 5.0.4 部署最有价值的经验。

一、部署规划与环境准备

1.1 组件构成与版本选型

Kylin 5.0.4 自身是一个 Java Web 服务（内置 Tomcat，发行包 spark/ 目录内置定制版 Spark，实测 RELEASE 标识为 Spark 3.3.0-kylin-5.2.2），启动前需要四类外部依赖：元数据库（本文选 PostgreSQL 14）、ZooKeeper（3.5.9）、Hadoop 3.2.1（HDFS 与 YARN）与 Hive 3.1.3（元数据服务）。Kylin 服务端进程实测运行在 JDK 8 之上，因此基础环境安装 OpenJDK 8：

$ apt-get install -y openjdk-8-jdk
$ java -version 2>&1 | head -n 1
openjdk version "1.8.0_412"

先理解每个依赖「为什么必须存在」，部署时才知道每一步在验证什么：

  • 关系元数据库：模型、索引、段、作业、权限、会话等全部结构化状态都存这里，服务启动时第一件事就是连库建表。它的可用性直接决定 Kylin 的可用性，因此生产上应独立部署并配置常规备份；
  • ZooKeeper：承担分布式锁（多实例互斥）、服务发现与 Leader 选举三件事。哪怕单机部署也需要一个实例——这不是「集群才需要」的可选项；
  • HDFS：预计算产出的 Parquet 索引文件、元数据备份、Spark 事件日志的落点，同时是构建作业的中间数据交换地；
  • YARN：构建作业与查询应用 Sparder 都是 Spark 程序，以 client 模式向 YARN 申请资源。YARN 可分配内存上限（yarn.scheduler.maximum-allocation-mb 与 NodeManager 可用内存）直接约束 4.1 节要配置的 executor 参数；
  • Hive Metastore：数据源的表结构从 Hive 元数据读取，Hive 本身不参与计算，只要 metastore 服务与库表定义可访问即可。

资源预算参考（本文实测机：12 核 CPU、31GB 内存）：ZK 512MB 堆 + 五个 Hadoop 守护进程各 512MB + Hive metastore 1GB + Kylin 服务 512MB 堆，再加 Spark executor（2×4GB）与操作系统页缓存，31GB 可以稳定跑通全链路；若只为验证安装，也可以把 executor 降到 2GB。

1.2 主机名与网络

伪集群通过主机名互访，固定一个可解析的主机名（本文 node1.kylin.example）并写入 hosts：

$ hostnamectl set-hostname node1.kylin.example
$ echo "127.0.0.1 node1.kylin.example node1" >> /etc/hosts

该主机名后续会作为 spark.driver.host 的配置值出现（见 5.2 节第 9 步）。

1.3 PostgreSQL 14 安装与账号准备

Kylin 5.0 的元数据与用户数据存放在关系库中，安装 PostgreSQL 14 后创建 kylin 与 hive 两个库及账号，并允许 md5 口令认证：

$ su - postgres -c "psql -c \"CREATE USER kylin WITH PASSWORD 'kylin123';\""
$ su - postgres -c "psql -c \"CREATE USER hive WITH PASSWORD 'hive123';\""
$ su - postgres -c "psql -c \"CREATE DATABASE kylin OWNER kylin;\""
$ echo "host all all 127.0.0.1/32 md5" >> /etc/postgresql/14/main/pg_hba.conf
$ systemctl reload postgresql

验证远程（本机 TCP）连通性：

$ PGPASSWORD=kylin123 psql -h localhost -U kylin -d kylin -c "select version();" | head -n 3
PostgreSQL 14.13 (Ubuntu 14.13-1.pgdg22.04+1) on x86_64-pc-linux-gnu

生产场景还应关注三项 PostgreSQL 侧的工程实践：

  • 连接数规划：Kylin 的查询历史回写、权限校验、会话管理都会借用到元数据库连接，并发报表场景把 max_connections 规划在 200 以上更稳妥，同时确认默认的 idle 超时与 Kylin 侧连接池参数匹配；
  • 备份策略：Kylin 自带的 metastore.sh backup 导出的是逻辑备份（8.1 节实测），与数据库级 pg_dump 备份互为补充——前者覆盖「误删模型/项目」类逻辑事故，后者覆盖「实例损毁」类故障，恢复演练时要两条通道都验证；
  • 版本匹配：PostgreSQL 14 是 Kylin 5.0.4 官方兼容验证的版本线。官方发布笔记同时声明支持 Hive 3.x、ZooKeeper 3.5.9+、Hadoop 3.2.4/2.10 与 Spark 3.2.2 以上（发行包内置的 Spark 实际为更高的定制版）。

1.4 目录规划

统一目录约定：安装包统一放在 /opt/downloads，解压安装到 /opt/apache 下，日志与运行数据随之集中在 /opt/apache/<组件> 内，卸载时只需删除对应目录。

磁盘容量应按数据类别分别预估：预计算 Parquet 索引随模型与分区数线性增长，是最大头；HDFS 的 history 目录（Spark 事件日志）与 Hive 暂存次之；PostgreSQL 元数据相对稳定但会随查询历史缓慢膨胀（可定期归档）。单机验证环境 300GB 富余，生产则建议数据盘与系统盘分离。

二、依赖组件安装

2.1 ZooKeeper 3.5.9

$ cd /opt/downloads
$ wget https://archive.apache.org/dist/zookeeper/zookeeper-3.5.9/apache-zookeeper-3.5.9-bin.tar.gz
$ sha256sum apache-zookeeper-3.5.9-bin.tar.gz | cut -c1-16
9623007 ...（大小 9,623,007 字节，与官方清单比对一致）
$ tar -zxf apache-zookeeper-3.5.9-bin.tar.gz -C /opt/apache
$ mv /opt/apache/apache-zookeeper-3.5.9-bin /opt/apache/zookeeper
$ cp /opt/apache/zookeeper/conf/zoo_sample.cfg /opt/apache/zookeeper/conf/zoo.cfg
$ /opt/apache/zookeeper/bin/zkServer.sh start
$ echo ruok | nc localhost 2181
imok

2.2 Hadoop 3.2.1 伪集群

下载校验后解压到 /opt/apache/hadoop，核心配置四个文件。core-site.xml：

<property><name>fs.defaultFS</name><value>hdfs://localhost:9000</value></property>

hdfs-site.xml 设置副本数为 1；yarn-site.xml 设置 shuffle 服务：

<property><name>yarn.nodemanager.aux-services</name><value>mapreduce_shuffle</value></property>

四个配置文件各自只保留「能跑通的最小集合」，但要知道每个参数对 Kylin 链路意味着什么：

  • fs.defaultFS：Kylin 的 kylin.env.hdfs-working-dir（/kylin）建在这个文件系统上，预计算产物、元数据备份、Spark 事件日志都落在这里。改端口或改主机后，Kylin 配置要同步；
  • dfs.replication=1：单机只能如此；生产三副本时预计算存储占用按 3 倍估算；
  • yarn.nodemanager.aux-services=mapreduce_shuffle：Shuffle 服务是 MR 与 Spark on YARN 的运行前提，缺了它作业在 Node 侧启动即失败；
  • yarn.scheduler.maximum-allocation-mb 与 yarn.nodemanager.resource.memory-mb：决定单个 Spark executor 能申请到的内存上限。Kylin 5 默认的 executor 配置（含堆外内存）在这两项之上时，构建作业会一直 PENDING 或被拒绝——这是后文 Spark 检查排障实录里多种「executor 起不来」现象的根源；
  • yarn.resourcemanager.hostname：Kylin 通过 kylin.env.hadoop-conf-dir 读取同一套配置来定位 YARN，确保这个目录里的配置与实际启动的一致（见 3.3 节）。

关键易漏点：Hadoop 3.x 各守护进程默认以占位用户运行，root 部署时必须逐个补齐 hadoop-env.sh 的用户变量，否则启动报 ERROR: but there is no HDFS_NAMENODE_USER defined：

$ printf 'export HDFS_NAMENODE_USER=root\nexport HDFS_DATANODE_USER=root\nexport HDFS_SECONDARYNAMENODE_USER=root\nexport YARN_RESOURCEMANAGER_USER=root\nexport YARN_NODEMANAGER_USER=root\n' >> /opt/apache/hadoop/etc/hadoop/hadoop-env.sh

为控制资源，给每个守护进程固定 512MB 堆（在对应 env 脚本中设 HDFS_NAMENODE_OPTS="-Xmx512m" 等）。格式化并启动：

$ hdfs namenode -format
$ start-dfs.sh && start-yarn.sh
$ jps | sort -k2
DataNode
NameNode
NodeManager
ResourceManager
SecondaryNameNode

用官方自带作业验证 YARN 可用：

$ hadoop jar /opt/apache/hadoop/share/hadoop/mapreduce/hadoop-mapreduce-examples-3.2.1.jar pi 2 4
Job ... completed successfully
Raw Counters: {Job Counter: ...}
Pi = 3.5000...

2.3 Hive 3.1.3 与元数据库初始化

解压至 /opt/apache/hive。实测必改点：发行包自带的 guava-19.0 与 Hadoop 3.2.1 的 guava 冲突，schematool 初始化直接失败，必须用 Hadoop 的 guava 覆盖：

$ rm /opt/apache/hive/lib/guava-19.0.jar
$ cp /opt/apache/hadoop/share/hadoop/common/lib/guava-27.0-jre.jar /opt/apache/hive/lib/

在 hive 账号对应的 PostgreSQL 库中初始化元数据结构并启动 metastore（9083 端口）：

$ /opt/apache/hive/bin/schematool -dbType postgres -initSchema --verbose
Starting metastore schema initialization to 3.1
Initialization script hive-schema-3.1.postgres.sql
schemaTool completed
$ nohup /opt/apache/hive/bin/hive --service metastore > /opt/apache/hive/metastore.log 2>&1 &

metastore 只需这一个常驻进程（HiveServer2 在 Kylin 5 的链路里并非必需）。启动后监听确认三件套，顺带覆盖 ZK 与 Kylin 端口：

$ netstat -tln | grep -E "9083|2181|7070" | awk '{print $4}'
:::2181
:::7070
:::9083

全栈进程用 jps 一次看清，Kylin 主进程名是 jar（newten.jar 的调用形态），Hive metastore 是 RunJar：

$ jps | sort -k2
83397 jar
11940 RunJar
10269 NodeManager
9584  NameNode
5419  QuorumPeerMain
10147 ResourceManager
9916  SecondaryNameNode
9703  DataNode

再对 HDFS 做一次真实读写验证（Kylin 构建作业会在 /kylin 下频繁读写）：

$ echo -n "kylin-write-check" | hadoop fs -put - /kylin/root/put-test.txt
$ hadoop fs -cat /kylin/root/put-test.txt
kylin-write-check

两个小细节：hadoop fs -rm 不支持 -q 选项（hdfs dfs -rm 才有），删除验证文件用 hadoop fs -rm -f -skipTrash 即可；读写时日志出现 SaslDataTransferClient: SASL encryption trust check 的 INFO 行属正常提示，非异常。

建一张表做插入与查询验证，确认 Hive→HDFS→PostgreSQL 三方链路畅通：

$ hive -e "create table t_demo(id int); insert into t_demo values (42); select * from t_demo;"
42

三、Kylin 下载、校验与解压

3.1 官方下载与校验和

5.0.4 的二进制包在 Apache 发行目录 dlcdn.com/kylin/apache-kylin-5.0.4/，官方同名 .sha256 文件给出校验值。实测下载 676,933,976 字节，校验和比对一致：

$ cd /opt/downloads
$ wget https://dlcdn.apache.org/kylin/apache-kylin-5.0.4/apache-kylin-5.0.4-bin.tar.gz
$ sha256sum apache-kylin-5.0.4-bin.tar.gz
17572bb4413b920096d6ab3e05dfad9501cb2daf7f22e7a9a5dbc2db37f548f6  apache-kylin-5.0.4-bin.tar.gz

与官方 .sha256 完全一致后解压安装：

$ tar -zxf apache-kylin-5.0.4-bin.tar.gz -C /opt/apache
$ mv /opt/apache/apache-kylin-5.0.4 /opt/apache/kylin
$ ls /opt/apache/kylin/server/jars | wc -l
475

发行包 server/jars 下共 475 个 jar；另有一个显著特征是 server/lib/libch.so——Kylin 5 的 Native 引擎库，正是它引发了 5.2 节的多步排障。

3.2 首次准备：环境检查与 Spark 运行时

启动前可手工跑一次环境检查脚本观察前置条件：

$ bash /opt/apache/kylin/bin/check-env.sh

首次 kylin.sh start 会探测到内置 Spark 运行时缺失并自动下载 spark-newten-3.2.2.tgz（约 430MB）解压到 /opt/apache/kylin/spark，日志中打印 SPARK_USER_OK 表示就绪。服务器需能访问 Apache 镜像，或提前手动放置该包。

四、Kylin 核心配置

4.1 kylin.properties 必要项

六个必配项各管一段链路，改动任何一项都要同步检查关联方：

  • kylin.env.apache-hadoop-conf-dir / apache-hive-conf-dir：告诉 Kylin 去哪里读 Hadoop/Hive 配置，Spark 提交、HDFS 访问、metastore 定位全部走这里；这两个目录必须真实存在且内容与运行中的组件一致；
  • kylin.env.hdfs-working-dir：预计算数据与备份的根目录，切集群时是第一个要跟着变的项；
  • kylin.env.zookeeper-connect-string：多实例部署时写 ZK 集群串（host1:2181,host2:2181,host3:2181），服务发现与锁都依赖它；
  • kylin.metadata.url：元数据库 JDBC 串。url/username/password 三要素写成一行，改口令时只动这里，注意串内的逗号是参数分隔符不可省略；
  • kylin.server.port：HTTP 端口，与防火墙、负载均衡配置联动。

在 conf/kylin.properties 末尾追加以下实测生效的配置（键名以 5.0.4 为准）：

kylin.env.apache-hadoop-conf-dir=/opt/apache/hadoop/etc/hadoop
kylin.env.apache-hive-conf-dir=/opt/apache/hive/conf
kylin.env.hdfs-working-dir=/kylin
kylin.env.zookeeper-connect-string=localhost:2181
kylin.metadata.url=kylin_metadata@jdbc,driverClassName=org.postgresql.Driver,url=jdbc:postgresql://localhost:5432/kylin,username=kylin,password=kylin123
kylin.server.port=7070

Spark 构建资源三项按集群实际容量调整（默认 executor 内存 12288m 在 31GB 内存机器上会超 YARN 上限，实测改为 4096m、2 核、2 实例；堆外内存默认 12288m 同样超出，改为 1g）：

kylin.engine.spark-conf.spark.executor.memory=4096m
kylin.engine.spark-conf.spark.executor.cores=2
kylin.engine.spark-conf.spark.executor.instances=2
kylin.engine.spark-conf.spark.memory.offHeap.size=1g

4.2 setenv.sh 与 lib/ext

conf/setenv.sh 控制 Kylin 服务端 JVM 与本地库加载：

export JAVA_VM_XMS=512m
export JAVA_VM_XMX=512m
export LD_PRELOAD=/opt/apache/kylin/server/libch.so

LD_PRELOAD 一行的来龙去脉见 5.2 节第 4 步。lib/ext 目录用于放服务端启动强制检查的第三方驱动——5.0.4 启动会硬性要求 lib/ext 中存在 mysql-connector 系列 jar，即使元数据库用的是 PostgreSQL 也要放一个，实测从 Maven 坐标 com.mysql:mysql-connector-j:8.0.33 下载 2,481,560 字节的 jar 放入即可（旧坐标 mysql:mysql-connector-java 的 8.0.33 路径已 404）：

$ cp mysql-connector-j-8.0.33.jar /opt/apache/kylin/lib/ext/

4.3 配置生效与变更管理

kylin.properties 全部为启动时一次性读取，任何修改都要走「改文件 → kylin.sh restart → get-properties.sh 抽查」的闭环确认，例如改完 Spark 资源后：

$ bin/get-properties.sh kylin.engine.spark-conf.spark.executor.memory
4096m

同一参数往往需要在多个命名空间（kylin.engine.spark-conf、kylin.storage.columnar.spark-conf、kylin.query.async-query.spark-conf）重复出现，原因在 5.2 节第 8 步已实证：构建作业、存储访问与查询应用是三条独立的 Spark 提交路径，各自组装自己的 SparkConf。漏配某个命名空间的典型症状是「某一条链路正常、另一条偶发失败」，排查时先比对三个命名空间的同名参数是否一致。

五、启动流程与检查项排障实录

5.1 启动命令与检查项清单

启动用 bin/kylin.sh start（自检通过后输出 Kylin is starting 并给出 PID 与日志路径；stop/restart 是仅有的另外两个子命令，5.0.4 不支持 kylin.sh status，状态查询看 pid 文件与端口）。启动自检按固定顺序逐项执行并打印结果：

Checking OS info                        PASS
Checking Hadoop basic environment       PASS
Checking Java environment               PASS
Checking Configurations                 PASS
Checking Ports                          PASS
Checking Spark directory                PASS
Checking Spark Queue                    SKIP（未配置队列）
Checking Metadata Accessibility         PASS
Checking Spark Availability             PASS / FAIL
Checking Spark Driver Host              WARN（未显式配置时提示）

Spark Availability 是 5.0.4 最容易失败的一项——它真实向 YARN 提交一个测试 Spark 作业。以下 10 步排障实录按踩坑顺序排列。

除 kylin.sh 内置自检外，sbin/check-env.sh 提供独立的环境体检入口，实测两条行为规则值得记住：其一，它是 fail-fast 的，首个 FAIL 即终止后续检查——例如服务已在运行时重跑它，端口检查项报 ERROR: Port 7070 is in use, another Kylin server is running? 后直接结束，看不到后面的 Spark 检查；其二，它依赖 PATH 里的 hadoop/hive 命令，裸环境下第一项就报 ERROR: Command 'hadoop' is not accessible，这不是环境坏了而是调用姿势问题。因此 check-env.sh 适合「启动前」的预检与排障比对，运行期巡检应改用端口探测与 REST 探活（6.1 节）。

5.2 十步排障实录

第 1 步：PATH 缺 hadoop 命令。 用精简环境启动时 hadoop: command not found，检查项连 Hadoop 都探不到。把 Hadoop/Hive 的 bin 加入 PATH 再启动。单独运行 check-env.sh 时对应的真实回显为：

$ bin/check-env.sh
Checking Ports Availability
...................................................[FAIL]
ERROR: Port 7070 is in use, another Kylin server is running?
Full log is at: /opt/apache/kylin/logs/check-env.out

补齐 PATH 后重跑，Kerberos（未启用则 SKIP）、OS Commands、Hadoop Configuration、HDFS Working Dir、Java Version、Kylin Config 各项依次 PASS，仅在端口项因服务运行而 FAIL——再次印证两条行为规则。

第 2 步：lib/ext 缺 mysql-connector。 启动立即失败，提示 lib/ext 目录必须包含 mysql-connector jar（硬编码检查），按 4.2 节放入后继续。

第 3 步：executor.memory 超限。 默认 spark.executor.memory=12288m 与 spark.executor.instances 相乘超出 YARN 单机资源，检查报 executor 无法分配。按 4.1 节调到 4096m。

第 4 步：libch.so 静态 TLS 加载失败。 自检或服务进程报 UnsatisfiedLinkError: /opt/apache/kylin/server/libch.so: cannot allocate memory in static TLS block。原因：libch.so 使用静态 TLS，dlopen 动态加载时预留不足；glibc 对进程启动时预加载的库不施加该限制。解决即 4.2 节的 LD_PRELOAD。注意检查脚本在 bootstrap 流程中先于 setenv.sh 的加载点执行，把 LD_PRELOAD=/opt/apache/kylin/server/libch.so 写进启动命令的环境变量前缀最可靠。

第 5 步：protobuf-java 缺失。 Spark 提交时报 NoClassDefFoundError: com/google/protobuf/...。Kylin 内置 Spark 的 jars 缺该依赖，把 Hadoop 自带的 protobuf 复制过去：

$ cp /opt/apache/hadoop/share/hadoop/common/lib/protobuf-java-2.5.0.jar /opt/apache/kylin/spark/jars/

第 6 步：offHeap 超 YARN 上限。 默认堆外 12288m 加堆内内存后超过 YARN 单个资源单元 8192MB 的内存上限，报资源超限。改 1g。

第 7 步：executor 端 libch.so 路径无效。 YARN executor 报 exit 50，诊断文件里可见 executor 尝试加载 //libch.so。把 libch.so 复制到根路径让该引用可解析：

$ cp /opt/apache/kylin/server/libch.so /libch.so

第 8 步：executor 端静态 TLS（关键修复）。 第 7 步后 executor 仍 exit 50——executor 是 YARN 拉起的独立 JVM，LD_PRELOAD 无法传递到 YARN 分配的执行单元里，executor 加载 filecache 分发的 libch.so 依旧触发静态 TLS 限制。修复是让 Kylin 把该环境变量注入 executor（发行版默认只在查询引擎命名空间配了它，构建引擎命名空间缺失，需手动补齐）：

kylin.engine.spark-conf.spark.executorEnv.LD_PRELOAD=/libch.so
kylin.storage.columnar.spark-conf.spark.executorEnv.LD_PRELOAD=/libch.so

第 9 步：spark.driver.host 告警。 自检 WARN 提示未显式配置 driver 主机。补一行消除告警并避免多网卡环境选错地址：

kylin.engine.spark-conf.spark.driver.host=node1.kylin.example
kylin.storage.columnar.spark-conf.spark.driver.host=node1.kylin.example

第 10 步：自检失败但服务可能已拉起。 实测一次启动在 Spark Availability FAIL 后服务进程仍被拉起并正常监听 7070——自检 FAIL 不必然等于启动失败，判断以进程、端口与日志为准，再回头修复 spark 环境即可。

5.3 修复后的一次通过启动

三项 Spark 修复（第 5、7、8 步）到位后的完整启动：自检日志 Checking Spark Availability 通过，最终输出：

Kylin is starting. It may take a while. For status, please visit http://node1.kylin.example:7070
You may also check status via: PID:83397, or Log: /opt/apache/kylin/logs/kylin.log.

六、启动验证

6.1 进程与端口

全部 Java 进程与堆配置实测（7 个 512MB 的进程为 ZK、5 个 Hadoop 守护进程与 Kylin 服务端；1000MB 的是 Hive metastore）：

$ ps -ef | grep [j]ava | grep -oE "\-Xmx[0-9]+[mM]|newten.jar|NameNode|DataNode|SecondaryNameNode|ResourceManager|NodeManager|QuorumPeerMain|RunJar" | sort | uniq -c
      1 DataNode
      1 NameNode
      1 NodeManager
      1 QuorumPeerMain
      1 ResourceManager
      1 RunJar
      1 SecondaryNameNode
      1 newten.jar
      7 -Xmx512m
      1 -Xmx1000m

Kylin 启动过程中还会生成服务端专用的 Hadoop 配置目录 /opt/apache/kylin/hadoop_conf（内含 core-site.xml、hdfs-site.xml、hive-site.xml 等副本），排障时可对照检查实际生效值。

6.2 WebUI 与 REST 验证

$ curl -s -o /dev/null -w "%{http_code}\n" http://localhost:7070/kylin/
200
$ curl -s http://localhost:7070/kylin/api/projects
[]

200 与空项目数组说明服务与元数据链路正常。

再补三个更实质的探活与配置读取手段。其一，读一条生效配置确认配置文件被正确加载：

$ bin/get-properties.sh kylin.server.port
7070

其二，认证后的模型列表接口验证元数据读写（口令取自 6.3 节日志行，加载样例后）：

$ curl -s -u "ADMIN:1|KY@%JR" http://localhost:7070/kylin/api/projects
["learn_kylin"]

其三，观察服务主日志中的 Sparder 初始化行，确认查询引擎上下文就绪（首次查询前后均可能出现，可在 kylin.log 中 grep SparderEnv）：

2026-10-14T21:28:09,143 INFO  [SimpleAsyncTaskExecutor-1] sql.SparderEnv : Init spark.

6.3 随机管理员口令与登录限流

5.0.4 与旧版的重要差异：首次启动时 ADMIN 账号的口令是随机生成的，不做固定默认值，只在日志里出现一次。初始口令打印在 logs/security.log：

Create default user finished. The username of initialized user is [ADMIN], which password is [1|KY@%JR].

用该口令完成认证（POST Basic 认证返回 200、defaultPassword:true）。实测认证失败会触发 LimitLoginAuthenticationProvider 的递进式限流（间隔 30 秒、1 分钟…），连续失败还会临时锁定账号，登录验证时注意控制重试频率。

$ curl -s -u "ADMIN:1|KY@%JR" -X POST http://localhost:7070/kylin/api/user/authentication | head -c 200
{"code":"000","data":{"username":"ADMIN","authorities":[{"authority":"ROLE_ADMIN"},...,"defaultPassword":true,...

首次登录后应通过 bin/admin-tool.sh admin-password-reset 重置口令。

七、样例数据加载

官方样例一键加载 SSB 星型模型：上传样例数据到 HDFS、创建 Hive 表、导入 learn_kylin 项目元数据，并把元数据备份到 HDFS：

$ cd /opt/apache/kylin
$ bin/sample.sh
Sample hive tables are created successfully; Going to create sample project...
The metadata backup path is hdfs://localhost:9000/kylin/kylin_metadata/_backup/2026-10-14-21-55-43_backup/core_meta.
Sample model is created successfully in project 'learn_kylin'.

实测注意：sample.sh 同样要求 PATH 里有 hadoop 命令，否则第一步上传即失败退出。加载成功后 /api/projects 返回 ["learn_kylin"]，模型 fact 表为 SSB.P_LINEORDER。

7.1 样例加载后的验证点

三步快速确认样例完整可用。其一，元数据库出现模型记录（PostgreSQL 侧 kylin_metadata_model 表有一行，内容为 zlib 压缩的 JSON，普通 SQL 直读不可见，属正常现象）；其二，HDFS 的备份目录出现 sample.sh 打印的那个时间戳路径，说明项目级元数据备份成功；其三，用 6.2 节的认证方式访问模型相关接口返回 learn_kylin 的模型清单。

样例模型的设计意图值得在验证时读一遍：事实表 SSB.P_LINEORDER 外连 CUSTOMER、PART、SUPPLIER、DATES 四张维表，全部为 INNER 连接；模型初始只注册了一个默认度量 COUNT_ALL（COUNT(constant 1)），59 个候选列躺在「可用列」池里等待被声明为维度或度量；未配置分区列，段治理参数全部留空。这是一个刻意「未完成」的模型，恰好留给使用者完成从骨架到血肉的建模练习。

7.2 从样例到自有模型的迁移路径

把样例环境变成自有环境的改造清单，按依赖顺序排列：

  1. 用 create-table.sh 或 Hive 建自有库表并导入数据（Hive 侧验证 select 可读）；
  2. 在 WebUI 数据源页确认新表出现在候选列表（读取的是 Hive metastore）；
  3. 新建模型：选事实表、定 JOIN、挑维度度量，先小后大（维度从两三个开始）；
  4. 设定分区列与构建分区（推荐日期列），让后续构建可增量滚动；
  5. 提交首次构建，观察 kylin.build.log 与 YARN 应用，通过后用 REST 查询验证命中（realizations 字段非空）；
  6. 按查询历史迭代索引与聚合组（介绍篇 2.3 节的剪枝概念在此落地）。

八、日志体系与日常运维

8.1 元数据备份与恢复

metastore.sh backup 无参数执行即备份全量元数据到本地磁盘（默认 KYLIN_HOME/meta_backups/，也可显式指定路径）：

$ bin/metastore.sh backup
Backup at local disk succeed: /opt/apache/kylin/meta_backups/2026-10-14-22-45-10_backup/core_meta

备份目录按元数据命名空间分片存放（实测含 core_meta、favorite_rule、job_info、query_history_id_offset 等子目录），对应关系库中的同名逻辑分区；恢复用 metastore.sh restore <路径>（可选 --after-truncate 清空后导入），单项目迁移用 backup-project/restore-project。结合 1.3 节的数据库级备份，形成「逻辑事故用 metastore.sh、实例事故用 pg_dump」的双通道恢复策略。建议把 backup 挂到 cron（sbin/log-rotate-cron.sh 与 rotate-logs.sh 同目录，可一并参考其计划任务写法）。

8.2 日志文件体系

logs/ 目录实测包含 25 类文件，按职责分组认识它们，排障时才能直奔主题：

  • 主链路：kylin.log（服务主日志，查询与内部状态）、kylin.out（启动 stdout，进程级报错先看这里）、kylin.gc.pid*.current（GC 日志）；
  • 查询侧：kylin.query.log（查询执行详情）、kylin.history_server.log（Spark HistoryServer）、access_log.*.log（HTTP 访问）；
  • 构建侧：kylin.build.log（构建作业提交过程）、kylin.schedule.log（作业调度决策）、sample-run.log（样例加载）；
  • 安全与治理：kylin.security.log（认证事件，随机口令也在这里）、kylin.metadata.log（元数据操作）、diag.log（诊断命令输出）、jstack.timed.log.*（周期线程快照，进程卡死时直接可用）；
  • 自检与工具：check-env.out 与 check-env.error（check-env.sh 全量输出）、shell.stdout 与 shell.stderr（启动脚本控制台聚合输出，含首次口令）。

两个高频定位动作：服务起不来先看 shell.stderr 与 kylin.out；查询慢或失败先看 kylin.query.log 里对应 queryId 的 traces 与扫描量，再回到 6.2 节 REST 响应字段交叉验证。

8.3 日常巡检清单

  • 端口探活：curl 7070 返回 200；
  • YARN 侧：构建作业与 Sparder 应用状态正常（yarn application -list），无长期 ACCEPTED 的作业堆积；
  • 元数据库：连接数与 kylin_metadata_* 表膨胀情况（尤其 query_history 系列表，配置好归档）；
  • HDFS：/kylin 下五类目录（hive-scratch、kylin_metadata、root、sparder-history、spark-history）的容量增速与备份目录完整性；
  • 日志：ERROR 关键字扫描 + jstack.timed 快照文件是否按周期产出（守护进程是否僵死的旁证）。

九、卸载

Kylin 卸载按「停服务→删数据→删目录」三步：

$ bash /opt/apache/kylin/bin/kylin.sh stop
2026-10-14 22:05:31 Stopping Kylin...
2026-10-14 22:05:31 Stopping Kylin: 73562
$ hadoop fs -rm -r /kylin                      # HDFS 工作目录与元数据备份
$ rm -rf /opt/apache/kylin                     # 安装目录（含 /libch.so 可一并删除）

元数据库中的 kylin、hive 两个库按需保留或 DROP DATABASE，PostgreSQL、Hadoop、Hive、ZooKeeper 等前置组件按各自方式回收。stop 命令执行时会输出一条 This user don't have permission to run crontab 的提示，属非 root 计划任务权限检查的提示信息，不影响停止结果。

十、FAQ

Q1：启动报 hadoop: command not found？ PATH 未包含 /opt/apache/hadoop/bin。将 Hadoop 与 Hive 的 bin 目录加入 PATH 后再执行 kylin.sh；sample.sh、check-env.sh 有同样要求。

Q2：启动直接退出，提示 lib/ext 必须包含 mysql-connector？ 5.0.4 的硬性启动检查，与实际元数据库类型无关。放入 mysql-connector-j-8.0.33.jar（坐标 com.mysql:mysql-connector-j，注意旧坐标 404）即可。

Q3：Spark Availability 反复 FAIL，但 7070 端口却能访问？ 自检失败不必然阻止服务拉起（5.2 节第 10 步）。以进程与端口为准确认服务可用性，随后按第 5、7、8 步修复 Spark 环境让后续构建作业可用。

Q4：UnsatisfiedLinkError 提到 static TLS block 怎么处理？ libch.so 的静态 TLS 问题分两层：服务端用 LD_PRELOAD 预加载解决；YARN executor 层无法继承该变量，必须配置 spark.executorEnv.LD_PRELOAD=/libch.so（构建与存储两个命名空间都要配），并把 libch.so 放到 /libch.so 覆盖 executor 的加载路径。

Q5：executor 连续丢失、exit 50？ 按顺序核对三件事：executor 诊断文件（logs/check-env.out 或 YARN 日志目录）里加载的是哪个 libch 路径；protobuf 是否已在 spark/jars；executorEnv 是否已注入。本文实测 exit 50 的两类根因分别是 //libch.so 路径与静态 TLS，对应第 7、8 步。

Q6：提交构建时 YARN 资源超限报错？ 默认 executor 内存 12288m、堆外 12288m 均超出常规 YARN 配置。按 4.1 节改为 4096m 与 1g，kylin.engine、kylin.storage.columnar、kylin.query.async-query 三个命名空间同步修改。

Q7：登录 ADMIN 一直失败，甚至提示等待 30 秒/1 分钟？ 口令不是固定默认值，先查 logs/shell.stdout 里本次启动打印的随机口令（格式为 which password is [口令].）；失败重试有递进限流，连续错多次会临时锁定，间隔等待后再试或用 admin-tool.sh admin-password-reset 处理。

Q8：schematool 初始化失败？ guava 版本冲突。删除 Hive 自带的 guava-19.0，复制 Hadoop 3.2.1 的 guava-27.0-jre 到 hive/lib 后重跑（2.3 节）。

Q9：Hadoop 守护进程起不来，报 no HDFS_NAMENODE_USER defined？ Hadoop 3.x 要求显式配置运行用户。向 hadoop-env.sh 追加 5 个用户变量（2.2 节），root 部署时必做。

Q10：如何确认服务正在运行？ 5.0.4 的 kylin.sh 只支持 start/stop/restart，没有 status 子命令。用 pid 文件、ps -ef | grep newten.jar 与 7070 端口 curl 三件套判断；启动脚本输出里也直接给出 PID 与日志路径。

Q11：元数据误操作后如何回退？ sample.sh 与日常运行会把元数据备份到 hdfs://localhost:9000/kylin/kylin_metadata/_backup/，也可用 bin/kylin.sh org.apache.kylin.tool.MetadataTool -backup 主动备份（实测备份落在 $KYLIN_HOME/meta_backups/<时间戳>_backup/）；恢复用同工具的 -restore。

Q12：check-env.sh 一开始就报 Port 7070 is in use？ 该脚本用于启动前预检且 fail-fast：服务已在运行时端口项必然失败并终止后续检查。属正常现象，运行期巡检改用端口探活与 REST 接口（6.2 节），或在服务停止后运行 check-env.sh 完成完整体检。

Q13：查询样例 Hive 表报 Table is not an internal table？ 5.0 的 Gluten 向量化查询链路默认面向 Kylin 托管的内部表；对 Hive 外部表的明细下推会被该层拦截（实测报 [GLUTEN Exception] Table SSB.P_LINEORDER is not an internal table.）。预计算索引的查询不受影响；涉及明细下推的需求，需评估把热表迁移为内部表或调整查询引擎配置。

Q14：停机升级 Kylin 前要做哪些准备？ 按 8.1 节先做 metastore.sh backup 落到本地，再触发一次元数据备份到 HDFS，记录 get-properties.sh 的关键配置快照；升级后用 get-properties.sh 比对配置快照、检查 /kylin 目录与元数据库连接，最后通过 7.1 节的三步验证点确认样例或自有模型可查。