Apache Kylin 5.0 CLI 命令与运维详解

Ubuntu 22.04 环境实测 Kylin 5.0.4 运维命令与 REST 接口，覆盖服务启停、配置读取、元数据备份、样例加载、诊断升级脚本与日志排障，命令回显均为真实执行。

Apache KylinKylinApache运维OLAP2026/10/15

Apache Kylin 5.0 CLI 命令与运维详解

本文承接《Ubuntu 22.04 安装部署 Apache Kylin 5.0.4 指南》，在已运行 Kylin 5.0.4 的 Ubuntu 22.04 服务器（12 核、31GB 内存）上系统实测安装目录 bin 下全部 14 个运维脚本与 REST 运维接口。Kylin 是通过预计算加速 OLAP 分析的引擎，安装完成只是起点，日常运维的重心在服务生命周期控制、配置核对、元数据安全、故障诊断与日志检索五件事上。本文全部命令与回显均在真实环境执行后照抄，可直接作为运维手册底稿使用。

一、脚本总览与执行环境

1.1 安装目录 bin 清单

安装完成后 /opt/apache/kylin/bin 下共 14 个脚本，实测列目录输出如下，按字母序排列：

$ ls -1 /opt/apache/kylin/bin/
admin-tool.sh
check-env-bypass
check-env.sh
create-table.sh
diag.sh
get-properties.sh
grafana.sh
guardian.sh
kylin.sh
metastore.sh
rollback.sh
sample.sh
sql-extract-tool.sh
upgrade.sh

按职责可分四类：服务控制类只有 kylin.sh 一个入口；配置读取类包括 get-properties.sh、check-env.sh 与旁路标记 check-env-bypass；元数据与数据类包括 metastore.sh、admin-tool.sh、create-table.sh、rollback.sh、upgrade.sh；辅助工具类包括 sample.sh、diag.sh、grafana.sh、sql-extract-tool.sh、guardian.sh。日常使用频率最高的是 kylin.sh、get-properties.sh 与 metastore.sh 三件套。

1.2 必须用 bash 执行

这批脚本混用 [[、function 等 bash 特有语法，用 sh 前缀调用会直接报语法错误，实测：

$ sh /opt/apache/kylin/bin/get-properties.sh
sh: 9: /opt/apache/kylin/bin/get-properties.sh: Syntax error: "(" unexpected

Ubuntu 22.04 的 /bin/sh 默认指向 dash，dash 不支持上述 bash 扩展。正确姿势是用 bash 显式执行，或脚本加执行位后直接运行。同时注意 diag.sh、sample.sh 等脚本内部会调用 hadoop、hive 命令，运维前统一导出环境变量：

$ export PATH=/opt/apache/hadoop/bin:/opt/apache/hive/bin:$PATH
$ export JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64

不导出 PATH 的后果在 diag.sh 与 sample.sh 的实测中最直观：脚本第一步就报 hadoop: command not found。这条提示信息可能出现在脚本输出里，也可能被重定向进 logs/shell.stderr，终端一闪而过时要去日志文件确认。

1.3 kylin.sh 的子命令体系

kylin.sh 是唯一的服务控制入口，也是工具类程序的统一启动器。实测非交互环境执行 interactive 子命令时打印的用法如下：

Usage: 'kylin.sh [-v] start' or 'kylin.sh [-v] stop' or 'kylin.sh [-v] restart'

无参数与带完整用法输出的场景合并起来，其子命令体系共五类：start/stop/restart 控制服务实例生命周期；org.apache.kylin.* 直接以类名运行 Kylin 内置工具（如 MetadataTool）；interactive 进入交互属性查询模式；-v 开启详细模式。实测两个关键行为：其一，5.0.4 没有 status 子命令，运行状态判断依赖 pid 文件、进程与端口三件套；其二，服务已运行时重复 start 会被拒绝：

$ bash bin/kylin.sh start
Kylin is running, stop it first, PID is 73562

interactive 模式需要交互终端支持，在无标准输入的自动化脚本环境里实测只回显用法随即退出（退出码 0）。因此脚本化运维读取配置应使用 get-properties.sh 的 -r 模式，而不是 interactive。-v 详细模式的价值在于把启动引导过程的每一步自检输出实时打到终端，排障时比默认模式信息量大得多，推荐首次部署与故障场景使用。

二、服务启停全流程实测

2.1 stop 的真实输出

$ bash bin/kylin.sh stop
2026-10-14 22:05:31 This user don't have permission to run crontab
2026-10-14 22:05:31 Stopping Kylin...
2026-10-14 22:05:31 Stopping Kylin: 73562

stop 读取 $KYLIN_HOME/pid 记录的进程号定向终止，随后删除 pid 文件，再次执行 ls 可以确认该文件已不存在。开头那条 crontab 提示是非 root 用户权限检查的告知信息，不影响停止动作；stop 还会顺带清理启动期生成的临时 Spark 作业目录。注意 stop 依赖 pid 文件，如果文件被手工删除，stop 将找不到目标进程，此时用 ps -ef | grep [j]ava 找到进程号后手工 kill（先普通信号，确认退出再考虑强杀）。

2.2 start 与自检序列

start 是异步的：脚本先跑完一轮自检（系统环境、Hadoop 命令、Java 版本、配置文件、端口占用、Spark 目录、元数据可达性、Spark 可用性），全部通过后拉起服务端 JVM 并立即返回。启动引导过程的真实输出保存在 logs/shell.stdout 中，实测其中的自检序列与最终启动行如下：

Checking Zookeeper role...
Checking Spark directory...
Create default user finished. The username of initialized user is [ADMIN], which password is [1|KY@%JR].
Please keep the password properly. And if you forget the password, you can reset it according to user manual.
Kylin is starting. It may take a while. For status, please visit http://node1.kylin.example:7070/kylin/index.html.

终端上 start 的输出只有最后一行。自检序列里最重要的信息是随机初始口令的生成行：全新元数据首次启动时，系统创建默认用户 ADMIN 并生成随机口令，明文只在这一处打印，后面跟着「请妥善保管口令」的英文提示。验证服务就绪用端口探测：

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

脚本内部把各子步骤的标准输出与错误流分别重定向到 logs/shell.stdout 与 logs/shell.stderr，终端看不到的细节都在这两个文件里。启动失败的根因十有八九在 shell.stderr 尾部，这是本文排障章节的第一入口。

2.3 重启后的会话与状态

实测 stop/start 循环后有三点结论。第一，服务端会话全部失效，REST 客户端保存的 cookie 需要重新认证获取；第二，注册到 ZooKeeper 的应用状态随停止动作清理，重启后自动重新注册，无需人工干预；第三，重启不触碰元数据，项目、模型与索引计划原样保留，构建作业队列也不丢失。内存层面服务端按 setenv.sh 的配置固定运行，重启只改变进程号，堆参数不变。

2.4 服务进程模型与堆配置实测

服务端进程是单个 JVM，进程名以 newten.jar 标识。实测 ps -ef | grep [j]ava 中 Kylin 服务进程的关键参数如下（完整命令行较长，此处按语义分段照抄）：

root  83397  1  42  22:06 ?  00:03:40 java
  -server -Xms512m -Xmx512m -XX:+UseG1GC -XX:MaxGCPauseMillis=200
  -XX:G1HeapRegionSize=16m -Xloggc:/opt/apache/kylin/logs/kylin.gc.%p
  -XX:+UseGCLogFileRotation -XX:NumberOfGCLogFiles=10 -XX:GCLogFileSize=64M
  -Dkylin.hadoop.conf.dir=/opt/apache/kylin/hadoop_conf
  -Dloader.path=/opt/apache/kylin/hadoop_conf,/opt/apache/kylin/conf,/opt/apache/kylin/lib/ext,/opt/apache/kylin/server/jars,/opt/apache/kylin/spark/jars
  -XX:OnOutOfMemoryError=sh /opt/apache/kylin/bin/guardian.sh kill
  -jar newten.jar --kylin.server.mode=all

逐段解读：堆固定为 512MB（-Xms512m -Xmx512m），垃圾收集器为 G1，目标暂停 200 毫秒；GC 日志开启轮转，最多 10 个文件、每个 64MB，落在 logs 目录下以进程号命名；loader.path 声明了五个扩展类加载目录，运维加装 jar 包时放入 lib/ext 即可被识别；OnOutOfMemoryError 指向 guardian.sh kill，即内存溢出时由守护脚本执行清理动作，这就是 guardian 与服务进程的联动机制；--kylin.server.mode=all 表示单进程同时承担查询与任务两种角色。同一台服务器上还并存活依赖组件进程：ZooKeeper 的 QuorumPeerMain（-Xmx1000m）、Hadoop 的 NameNode、DataNode、SecondaryNameNode 与 ResourceManager（各 -Xmx512m），全部 Java 进程用 ps -ef | grep [j]ava 一屏可见，是核查资源占用的第一个动作。

三、配置读取：get-properties.sh 与 check-env.sh

3.1 get-properties.sh 的真实用法

该脚本负责读取 kylin.properties 及其生效值，实测无参调用打印的用法如下（注意与直观猜测不同，三个选项的语义并不对称）：

Usage: get-properties <COMMAND>

Commands:
  -c        get properties from cache(local disk)
  -r        get properties in real time, this options support backwards config
  -e        [file_path]only export properties to cache(local disk)
  -h        print help
  interactive Enter to get kylin properties

三种读取模式实测。-c 从本地磁盘缓存读取属性，读端口属性返回：

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

-r 实时读取并支持继承链回溯，读元数据连接属性返回：

$ bash bin/get-properties.sh -r kylin.metadata.url
kylin_metadata@jdbc,driverClassName=org.postgresql.Driver,url=jdbc:postgresql://localhost:5432/kylin,username=kylin,password=kylin123

-e 的语义是「把属性导出到本地缓存文件」，属于启动流程内部使用的接口，需要提供目标文件路径参数。实测在不带参数直接调用时进程无任何输出、退出码为 1，详细的失败原因被记录到 logs/shell.stderr——这是该脚本族的一致设计：面向人的输出走终端，面向排障的细节进日志。脚本源码中定义了缓存文件路径变量 _KYLIN_CACHED_CONFIG_FILE，默认指向 $KYLIN_HOME/conf/._kylin_properties_，运维一般不需要手工触发 -e。

安全提示：-r 模式原样回显属性值，kylin.metadata.url 里的明文口令会直接打到屏幕，远程会话与录屏场景注意窗口内容，必要时改用查询数据库的方式核对连接信息。

3.2 check-env.sh 与旁路标记

check-env.sh 独立复跑启动自检的各检查项，输出与启动日志一致，适合在改完配置后做预检。实测环境检查中「Checking Spark Availability」一项会真实提交 Spark 测试作业到 YARN，完整耗时约两分钟，作业级诊断输出落在 logs/check-env.out。自检失败不必然阻止服务拉起，最终判断以端口与进程为准，但带病启动的风险要自担。

bin 目录下还有一个特殊文件 check-env-bypass：创建该标记文件可让启动流程跳过自检。它的用途是绕过临时性的检查故障（例如下游组件短暂不可达但确认不影响核心功能），属于快速恢复手段而非常规操作，用完应删除标记恢复检查。

四、元数据运维：metastore.sh 与 MetadataTool

4.1 metastore.sh 的定位

metastore.sh 是元数据工具的脚本封装，核心操作 backup/fetch/list/restore，底层统一通过 kylin.sh org.apache.kylin.tool.MetadataTool 调用真正的工具类。元数据是 Kylin 的命脉：项目、模型、索引计划、权限与系统配置全部存储其中，元数据损坏意味着全部设计成果丢失，因此备份与恢复是运维必修课。

4.2 一个 5.0.4 的真实缺陷链

实测 metastore.sh list / 无输出退出，返回码为 1。通过 kylin.sh -v 或查看 logs/shell.stderr 可以看到完整链条：

Caused by: class org.apache.commons.cli.UnrecognizedOptionException:
Unrecognized option: -target.
Usage: [-backup <arg> ...], [-fetch <arg> ...], [-list List children of
target folder], [-restore <arg> ...]

即 5.0.4 的 metastore.sh 给 list 操作传了 MetadataTool 已不支持的 -target 参数，属于脚本与工具类版本不匹配的真实缺陷。绕开方式是直接调用工具类，-list 选项接受 -dir 指定目录：

$ bash bin/kylin.sh org.apache.kylin.tool.MetadataTool -list -dir /

但实测服务运行中执行 -list 仍报 error execute org.apache.kylin.tool.MetadataTool——列表操作与服务端的元数据访问产生冲突。由此得到运维结论：元数据列表与恢复类操作应在服务停止后执行，避免读写竞争。

4.3 -backup 实测：不停服的热备份

与列表操作不同，备份操作实测在服务运行中直接成功：

$ bash bin/kylin.sh org.apache.kylin.tool.MetadataTool -backup /tmp/kylin_meta_backup

备份固定落在 $KYLIN_HOME/meta_backups/<时间戳>_backup/ 目录，实测备份目录结构完整清单如下：

$ ls -la /opt/apache/kylin/meta_backups/2026-10-14-22-00-29_backup/core_meta/
DATAFLOW   INDEX_PLAN   LAYOUT      MODEL       PROJECT
RESOURCE_GROUP   SEGMENT   SYSTEM   TABLE_INFO
TABLE_MODEL_RELATION   USER_GLOBAL_ACL   USER_GROUP   USER_INFO
kylin.properties

core_meta 内按资源类型分目录，共十三类资源外加一份 kylin.properties 快照：DATAFLOW 与 INDEX_PLAN 对应数据流与索引计划，LAYOUT 是索引布局，MODEL 与 SEGMENT 是模型与段，PROJECT 是项目定义，USER 系列四类是用户、组与权限，SYSTEM 存系统配置。每类资源下以资源 UUID 命名的 JSON 文件是纯文本，可直接审阅内容，这也是核查元数据是否完整的最直接方法。日常还应依赖自动备份：样例加载与构建过程会把元数据持续备份到 HDFS 的 hdfs://localhost:9000/kylin/kylin_metadata/_backup/<时间戳>_backup/core_meta，形成第二道保险。恢复对应 -restore <备份路径> 选项，执行前先停服务。

4.4 admin-tool.sh：口令重置

Usage: admin-tool.sh admin-password-reset

实测该工具交互式重置 ADMIN 口令，是随机初始口令机制的配套方案：先从启动日志找到初始口令完成首次登录，再立即用本工具改成自己的口令。口令找不到时也用它兜底。

五、样例与数据工具：sample.sh、create-table.sh

5.1 sample.sh 全流程

Usage: sample.sh [--client | --dir | --params | --conf | ...] <parameters>
--client    Indicate the sample data loading without MapReduce...
--dir       Directory of sample data...
--params    Parameters of sample...
--conf      Indicate the path of kylin.properties to read...

实测完整加载过程需要 PATH 含 hadoop 命令，关键回显如下：

$ bash bin/sample.sh
2026-10-14 21:53:02,575 INFO [main] ... Uploading sample data to hdfs://localhost:9000/kylin/sample_cube/data/ ...
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'.

（以上回显各行中的省略号均为日志原文自带。）加载流程分四段：样例 CSV 上传 HDFS 的 sample_cube 目录、Hive 建表、触发一次元数据自动备份、通过 SampleProjectTool 导入 learn_kylin 项目。完成之后 REST 侧立即可见，实测用 Python 解析接口返回核对项目、模型与索引三类资源：

$ curl -s -b /tmp/k3.cookie "http://localhost:7070/kylin/api/models?projectName=learn_kylin" | python3 -c "import json,sys; d=json.load(sys.stdin); m=d['data']['models'][0]; print(m['name'], m['uuid'], m.get('fact_table'))"
learn_kylin eccbdc7e-a229-3297-6a10-1ccb41d66382 SSB.P_LINEORDER

样例模型的名称与项目同名，事实表为 SSB 星型模式中的订单明细表 P_LINEORDER。重复加载前可清理 HDFS 的 /kylin/sample_cube 目录与对应的 Hive 表，否则第二次执行会因表已存在而报错。

5.2 create-table.sh 与数据导入

create-table.sh table_path 按「备份目录/项目/表」的路径格式，把备份包中的建表语句还原到 Hive。它与 MetadataTool 的 restore 配合，可将样例环境从备份整段重建：先 restore 元数据，再 create-table 还原 Hive 表，最后核对 HDFS 数据目录。三步全部来自备份内容，不依赖原始安装介质。

六、诊断、升级与守护：diag.sh、rollback.sh、upgrade.sh、guardian.sh

6.1 diag.sh：诊断包生成

Usage: diag.sh <time_range> <save_path> <dest_dir> <project_name> <(Optional) error id>...

diag.sh 按时间窗收集服务端日志、配置快照与查询记录打包，产出是提交社区问题的标准附件。实测在未导出 hadoop PATH 的环境下执行，引导阶段的真实回显如下：

KYLIN_HOME is:/opt/apache/kylin
KYLIN_CONFIG_FILE is:/opt/apache/kylin/conf/kylin.properties
SPARK_HOME is:/opt/apache/kylin/spark
/opt/apache/kylin/sbin/prepare-hadoop-env.sh: line 24: hadoop: command not found
/opt/apache/kylin/sbin/init-kerberos.sh: line 19: /opt/apache/kylin/bin/header.sh: No such file or directory
bin/diag.sh: line 74: cd: /opt/apache/kylin/influxdb: No such file or directory
ls: cannot access 'influxdb-*.rpm': No such file or directory
/
SLF4J: Class path contains multiple SLF4J bindings.

这三行报错依次说明：环境准备脚本找不到 hadoop 命令（PATH 未导出）、Kerberos 初始化脚本依赖的 header.sh 不存在、可选监控组件 influxdb 未安装。对最小化部署而言这三项都是预期内的缺失，不影响诊断包核心内容的生成，但会拖慢执行并留下噪音。导出 PATH 后再执行，前两条消失。诊断包默认收集指定时间窗内的 kylin.log、security 日志、配置文件与元数据摘要，体积可控。

6.2 rollback.sh 与 upgrade.sh

Usage: rollback.sh --time <YYYYMMDDHHmmss> --project <project> [--skip-check-data]
Usage: upgrade.sh <OLD_KYLIN_HOME> [--silent]

rollback 把指定项目回滚到时间戳对应的元数据备份，常用于误操作后的定点恢复；--skip-check-data 可跳过数据一致性校验，仅在确认数据未变时使用。upgrade 服务于跨版本升级场景，指向旧版本安装目录做元数据兼容性检查，实测 5.0.4 环境下不传旧目录时打印用法退出。两者的共同前提都是先停服务、后操作元数据。

6.3 guardian.sh、grafana.sh、sql-extract-tool.sh

Usage: 'guardian.sh start' or 'guardian.sh stop' or 'guardian.sh kill'

guardian 是进程守护脚本，start/stop/kill 三档动作。它与服务的联动点在 JVM 参数里：进程启动时注册了 OnOutOfMemoryError=sh /opt/apache/kylin/bin/guardian.sh kill，即内存溢出事件触发时由 JVM 回调 guardian 完成收尾清理，避免残留半死进程。grafana.sh 管理可选监控组件 grafana 的启停，最小化安装未包含该组件时脚本报目录缺失，属可选能力，需要监控面板时另行安装启用。sql-extract-tool.sh 从查询日志中批量提取 SQL 语句集合：

sql-extract-tool.sh -file <LOG_FILE_PATH>      # 从日志提取 SQL 集合

用途是性能分析前的语句归集：把一段时间内的查询日志喂给它，得到去重后的 SQL 清单，供索引设计与热点分析使用。

七、REST 运维接口

7.1 认证与会话

运维接口走统一认证，先以用户名口令换取会话：

$ curl -s -u "ADMIN:1|KY@%JR" -X POST http://localhost:7070/kylin/api/user/authentication -c /tmp/k3.cookie
{"code":"000","data":{"username":"ADMIN","authorities":[{"authority":"ROLE_ADMIN"},{"authority":"ALL_USERS"}],"disabled":false,"defaultPassword":true,"locked":false,"uuid":"f83f2fb9-95ea-2c22-f178-d40e842d76d4","last_modified":1792014756093,"create_time":1792013229743,"version":"5.0.4.0","mvcc":7,"locked_time":0,"wrong_time":0,"first_login_failed_time":0},"msg":""}

响应信封统一为 code/data/msg 三段，code 为 000 表示成功。data 中值得关注四个字段：authorities 给出角色（ADMIN 同时具备 ROLE_ADMIN 与 ALL_USERS 两组）；defaultPassword 为 true 说明仍在使用初始口令，应尽快用 admin-tool.sh 重置；locked 与 locked_time 反映账号锁定状态；version 直接给出系统版本 5.0.4.0。curl 的 -c 参数把会话写入 cookie 文件，后续请求用 -b /tmp/k3.cookie 携带。

未携带会话访问受保护接口时，实测返回完整的错误信封结构（访问 /kylin/api/version 的响应）：

code = "999"
data = null
msg = "KE-010003207: Can't authenticate. Please login again."
exception = "KE-010003207: Can't authenticate. Please login again."
url = "http://localhost:7070/kylin/api/version"
suggestion = ""
error_code = "KE-010003207"

信封中还包含一个 stacktrace 字段，内容为完整的 Spring Security 过滤链堆栈（百余行），排障时检索 error_code 比读堆栈高效。实测安全策略：认证失败触发递进限流，logs/kylin.security.log 中的真实日志行显示了等待时间的递进：

org.springframework.security.authentication.BadCredentialsException: Invalid username or password. Please try again after 30 seconds.
org.springframework.security.authentication.BadCredentialsException: Invalid username or password. Please try again after 1 minutes.

连续失败会升级为临时锁定，认证响应里的 locked 字段与 locked_time 字段随之变化。自动化脚本要控制重试节奏，避免把 ADMIN 账号锁死。

7.2 资源查询接口

两个旧版常用心智模型需要修正。其一，旧版本的 /kylin/api/version 与 /kylin/api/service/state 接口在 5.0.4 实测返回 404（响应体为 Spring 标准错误结构 {"timestamp":1792016149589,"status":404,"error":"Not Found","path":"/kylin/api/version"}），版本号改从认证响应的 data.version 字段获取；其二，作业列表接口 /kylin/api/jobs 的 timeFilter 参数为必传，实测漏传时返回：

{"code":"999","data":null,"msg":"KE-010043201: Request parameter \"timeFilter\" is empty or value is empty. Please check the request parameters.","stacktrace":"KE-010043201: Request parameter \"timeFilter\" is empty or value is empty. Please check the request parameters.\n\tat org.apache.kylin.rest.

回显在 stacktrace 字段内部截断，后续为标准异常堆栈，排错时取 msg 中的错误码即可。timeFilter 取整数枚举值，实测 0 到 4 均返回成功（样例项目尚无构建作业，返回空列表 {"code":"000","data":{"size":0,"jobs":[]},"msg":""}），传 5 时返回 KE-000000001(UNKNOWN ERRORCODE): Can not find the JobTimeFilterEnum by code: 5，传字符串报类型转换错误。据此脚本化调用固定传 0（全量语义）最稳妥。

项目与模型查询是日常核对的主力接口，实测项目接口返回 learn_kylin 项目的完整定义（节选关键字段）：

"name":"learn_kylin"  "owner":"ADMIN"  "status":"ENABLED"  "version":"5.0.2.0"
"default_database":"DEFAULT"  "maintain_model_type":"MANUAL_MAINTAIN"
"override_kylin_properties":{"kylin.metadata.semi-automatic-mode":"false",
  "kylin.query.metadata.expose-computed-column":"true",
  "kylin.source.default":"9","kylin.internal-table-enabled":"true"}
"segment_config":{"auto_merge_enabled":false,"auto_merge_time_ranges":["WEEK","MONTH","QUARTER","YEAR"],"volatile_range":{"volatile_range_number":0,"volatile_range_enabled":false,"volatile_range_type":"DAY"},"retention_range":{"retention_range_number":1,"retention_range_enabled":false,"retention_range_type":"MONTH"},"create_empty_segment_enabled":false}

三个信息点值得注意：项目元数据版本为 5.0.2.0（样例由旧版元数据导入，这正是第七节构建接口缺陷的背景）；override_kylin_properties 列出项目级覆盖的四个属性，排查配置不生效时先查这里；segment_config 中的 auto_merge_enabled 为 false，说明样例项目未开启段自动合并。索引查询接口返回 cubes 数组，实测解析出名称、状态与事实表三元组：

learn_kylin DISABLED SSB.P_LINEORDER 5.0.2.0

状态 DISABLED 表示索引尚无可用段，首个构建完成后转为 ACTIVE。

7.3 构建触发接口与已知缺陷

5.0.4 的构建入口是 POST /kylin/api/models/{model}/segments，请求体需包含 start 与 end 两个毫秒时间戳、项目名与构建开关，形如 {"start":<毫秒时间戳>,"end":<毫秒时间戳>,"project":"learn_kylin","buildAllIndexes":true}，model 取模型标识。但对 sample.sh 导入的样例模型（元数据版本 5.0.2.0 且未定义分区列），实测该接口抛出空指针异常：

NPE at ModelService.getPartitionColumnFormatById(ModelService.java:3821)

这是接口对无分区描述模型的兼容缺陷：服务端构建分区推导时未判空。样例环境的构建触发建议改走 WebUI 界面完成，或先为模型补充分区列定义再走接口。生产环境中自建模型定义了分区列时，该接口工作正常。

7.4 日志体系与关键文件

logs 目录实测清单（大小与文件名照抄，单位字节）：

8944   access_log.2026-10-14.log
204    check-env.error
269292 check-env.out
42     cluster.info
69972  jstack.timed.log.1792013337001
70782  jstack.timed.log.1792013936993
10984  kylin.build.log
636820 kylin.gc.pid73562.0.current
589068 kylin.gc.pid83397.0.current
2356151 kylin.log
441261 kylin.metadata.log
2000   kylin.out
0      kylin.query.log
8125   kylin.schedule.log
128924 kylin.security.log
4104   sample-run.log
620    security.log

运维侧需要分清七组文件：kylin.log 是服务主日志（两MB级，绝大多数问题在这里）；kylin.security.log 记录认证失败与限流事件；security.log（六百字节的小文件）记录服务启停操作事件，含操作者与时间；shell.stdout 与 shell.stderr 记录启动脚本内部过程，工具类报错与随机口令都在 stdout 里；check-env.out 保存 Spark 自检作业的 executor 级诊断；kylin.gc.pid<pid>.0.current 是 GC 日志，文件名里的进程号可区分上一代进程（73562）与当前进程（83397）；jstack.timed.log.<毫秒时间戳> 是系统定时生成的线程快照，每隔十分钟一份，排查线程堆积时直接对比相邻两份。kylin.query.log 与 kylin.schedule.log 分别记录查询与调度细节，查询日志在无查询流量时为空文件属正常。

八、运维排障实战

8.1 启动失败的标准排查路径

按「shell.stderr 尾部 → kylin.log → check-env.out」的固定顺序定位，可以覆盖实测中遇到的全部启动故障，共四类：脚本参数不匹配（Unrecognized option，metastore.sh 缺陷即属此类）、依赖缺失（NoClassDefFoundError，protobuf 缺失导致）、资源超限（executor 内存申请超过 YARN 资源单元上限，退出码 50）、本地库加载失败（UnsatisfiedLinkError 静态 TLS 限制）。前两类看 stderr 即可确诊；后两类要进 check-env.out 查 executor 诊断，处置方案与逐步实录见安装指南 5.2 节十步排障。

8.2 Spark 构建环境的运行时要点

服务端 Spark 为内置运行时（spark-newten-3.2.2，位于安装目录 spark 子目录），运维注意三点。第一，缺 protobuf 依赖时把 Hadoop 发行版的 protobuf-java-2.5.0.jar 复制进 spark/jars，否则构建作业启动即报类缺失。第二，本地库 libch.so 的预加载分两层：服务端进程通过 setenv.sh 的 LD_PRELOAD 注入，YARN 拉起的 executor 进程则要靠属性 spark.executorEnv.LD_PRELOAD 传递，且库文件需复制到 executor 可访问的根路径（实测 //libch.so 双斜杠路径与静态 TLS 是两个独立故障点）。第三，spark.driver.host 显式配置可消除告警并避免多网卡机器上地址错选。

8.3 安全机制的运维处置

三件事要形成肌肉记忆。第一，随机初始口令只在 shell.stdout 打印一次，启动完成就应登录改密；第二，认证失败限流是递进的（实测 30 秒、1 分钟逐级加码），脚本里加 sleep 而不是硬重试；第三，账号锁定后等待自动解锁或用 admin-tool.sh 重置，锁定状态与错误计数通过认证响应的 locked、locked_time、wrong_time 三个字段可查。

8.4 线程快照与 GC 日志的日常巡检

jstack 定时快照与 GC 日志是两个免配置的观测点。快照按固定间隔落盘，文件名即时间戳，巡检时对比相邻快照中线程数量与状态分布，可提前发现线程泄漏；GC 日志按 10 个文件轮转，巡检关注 Full GC 频率与暂停时长，512MB 堆在样例负载下运行平稳，生产负载则应结合堆水位评估是否调大 setenv.sh 中的堆参数。

九、FAQ

Q1：kylin.sh start 提示 "Kylin is running, stop it first"？ pid 文件里已有存活记录。确认进程归属后先 kylin.sh stop 再 start；若 pid 文件残留但进程已死，删除 $KYLIN_HOME/pid 后重新启动。

Q2：为什么没有 kylin.sh status？ 5.0.4 的 kylin.sh 只有 start/stop/restart、工具类执行与 interactive 五类入口。状态判断用 ps -ef | grep [j]ava 找 newten.jar 进程、核对 $KYLIN_HOME/pid、curl http://localhost:7070/kylin/ 探测端口，三者组合判断。

Q3：get-properties.sh 用 sh 执行报语法错误？ 脚本含 bash 语法而 Ubuntu 22.04 的 sh 指向 dash，改用 bash 执行。bin 下其余脚本同理，且多数要求 PATH 含 hadoop。

Q4：metastore.sh list 报 Unrecognized option: -target？ 5.0.4 的脚本与 MetadataTool 参数不匹配的真实缺陷，细节见 4.2 节。列表需求改用工具直调 MetadataTool -list -dir，并在服务停止后执行。

Q5：MetadataTool -list 在服务运行时报 error execute？ 列表操作与服务端的元数据访问冲突。停服后执行列表与恢复类操作；-backup 热备份实测可用，紧急备份不必停服。

Q6：ADMIN 初始口令在哪里？ 全新元数据首次启动时在 logs/shell.stdout 打印一次，真实格式为 Create default user finished. The username of initialized user is [ADMIN], which password is [口令].，随后两行是保管提示。找不回时用 admin-tool.sh admin-password-reset 交互式重置。

Q7：登录提示等待 30 秒或 1 分钟？ 递进限流机制，重试次数越多等待越久直至临时锁定，真实日志见 7.1 节。脚本化认证控制频率，锁定状态查认证响应的 locked 字段。

Q8：触发构建报空指针（getPartitionColumnFormatById）？ 构建接口对无分区描述的模型有兼容缺陷，样例模型必然触发（元数据版本 5.0.2.0 且无分区列）。改走 WebUI 构建或先补分区列定义。

Q9：sample.sh 第一步就失败？ hadoop: command not found。把 hadoop 与 hive 的 bin 目录加入 PATH 后重跑；重复加载前清理 HDFS 的 /kylin/sample_cube 与同名 Hive 表。

Q10：启动脚本打印的信息太少，怎么定位失败点？ 看 logs/shell.stderr（脚本内部过程与异常栈）与 logs/check-env.out（Spark 测试作业诊断）。kylin.sh -v 可把引导过程实时打到终端。

Q11：想改服务端口？ 修改 kylin.server.port（默认 7070）后重启，get-properties.sh -c kylin.server.port 核对生效值，防火墙同步放行。

Q12：元数据怎么灾备？ 三层保障：运行期自动备份到 HDFS 的 _backup 目录、MetadataTool -backup 手工热备份到 meta_backups 目录、rollback.sh 按时间戳定点回滚。恢复前停服，恢复后核对 core_meta 下十三类资源目录与 kylin.properties 快照的完整性。

Q13：jobs 接口报 timeFilter 为空？ 该参数必传且为整数枚举，实测 0 至 4 有效、5 起报 JobTimeFilterEnum 找不到、字符串报类型转换错误。脚本固定传 0。

Q14：/kylin/api/version 返回 404？ 5.0.4 已移除旧版本接口，实测 404。版本号从认证响应的 data.version 字段获取，服务健康用 7070 端口探测。

十、小结

Kylin 5.0 的命令行体系把日常运维收敛到四个入口：服务生命周期用 kylin.sh 三子命令加进程三件套判断；配置核对用 get-properties.sh 的缓存与实时两种模式；元数据安全用 MetadataTool 热备份加 rollback 定点回滚；故障定位遵循 shell.stderr、kylin.log、check-env.out 的固定路径。REST 侧以认证接口为总开关，项目、模型、作业三类查询接口覆盖资源核对，构建接口存在无分区模型的兼容缺陷需绕行。实测沉淀的三条铁律：脚本一律 bash 执行并先导出 Hadoop 环境；元数据列表与恢复停服执行、备份可在线；限流与锁定的安全机制要求登录操作有耐心、重试有间隔。全文命令与回显均在 5.0.4 环境真实执行，可直接作为生产运维手册底稿。

十一、参考链接