Apache Linkis 常用 CLI 命令与工具详解

本文基于 Apache Linkis 1.8.0 实测环境（部署目录 /appcom/Install/LinkisInstall，部署用户 hadoop）整理日常运维与任务提交常用的命令行工具，全部命令与回显均来自实测。约定：$LINKIS_HOME=/appcom/Install/LinkisInstall。

一、命令工具总览

1.1 bin 目录（任务提交客户端）

$LINKIS_HOME/bin/
├── linkis-cli                # 通用客户端（本文主角）
├── linkis-cli-hive           # Hive 专用包装（预设引擎标签，支持 -e/-f 习惯用法）
├── linkis-cli-pre            # 公共前置解析脚本（Map 参数解析）
├── linkis-cli-spark-sql      # Spark SQL 专用包装
├── linkis-cli-spark-submit   # Spark Submit 专用包装
└── linkis-cli-sqoop          # Sqoop 专用包装

linkis-cli-hive/spark-sql/sqoop 等包装脚本内置了 -e → -code、-f → -codePath 的参数映射（脚本内映射表：['-e']='-code'、['-f']='-codePath'），方便从 beeline/spark-sql 习惯迁移。

1.2 sbin 目录（服务管理）

$LINKIS_HOME/sbin/
├── linkis-start-all.sh        # 一键启动全部服务
├── linkis-stop-all.sh         # 一键停止全部服务
├── linkis-daemon.sh           # 单服务启停/状态管理
├── linkis                     # 服务名清单辅助脚本
├── common.sh                  # 公共函数库
├── clear-server.sh            # 清理服务残留进程
├── graceful-upgrade.sh        # 滚动升级辅助
├── kill-ec-process-by-port.sh # 按端口强杀引擎进程
├── kill-process-by-pid.sh     # 按 PID 强杀进程
├── kill-yarn-jobs.sh          # 清理 YARN 任务
└── ext/                       # 各服务启动参数定义（每服务一个文件）
    ├── linkis-common-start
    ├── linkis-mg-eureka
    ├── linkis-mg-gateway
    ├── linkis-cg-linkismanager
    ├── linkis-cg-entrance
    ├── linkis-cg-engineconnmanager
    ├── linkis-ps-publicservice
    └── linkis-et-monitor

1.3 运行前环境要求

linkis-cli 启动时自动探测 JDK 8：优先 JAVA_HOME，其次探测 /usr/java/jdk1.8* 等路径，找不到时报错退出：

No JDK 8 found. linkis-client requires Java 1.8

建议在 /home/hadoop/.bash_profile 中固化 JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64。客户端 JVM 固定为 -Xms32m -Xmx2048m，无需人工调整。

二、linkis-cli 提交任务

2.1 查看帮助与版本

sh $LINKIS_HOME/bin/linkis-cli --help
sh $LINKIS_HOME/bin/linkis-cli --version

--version 实测回显：

Version=1.8.0
############Execute Success!!!########

2.2 提交 shell 任务

sh $LINKIS_HOME/bin/linkis-cli \
  -codeType shell -labelMap engineType=shell-1 \
  -code "echo hello"

实测完整回显：

[INFO] LogFile path: /appcom/Install/LinkisInstall/logs/linkis-cli/linkis-client.hadoop.log.20261011183623754874158
[INFO] User does not provide usr-configuration file. Will use default config
[INFO] user does not specify submit-user, will use current Linux user "hadoop" by default.
[INFO] user does not specify proxy-user, will use current submit-user "hadoop" by default.
[INFO] connecting to linkis gateway:http://127.0.0.1:9001
JobId:13
TaskId:13
ExecId:exec_id018015linkis-cg-entrancelinkis-u22:9104LINKISCLI_hadoop_shell_0
[INFO] Job is successfully submitted!

2026-10-11 18:36:28.036 INFO Program is substituting variables for you
2026-10-11 18:36:28.036 INFO Variables substitution ended successfully
2026-10-11 18:36:28.036 INFO You have submitted a new job, script code (after variable substitution) is
************************************SCRIPT CODE************************************
echo hello
************************************SCRIPT CODE************************************
2026-10-11 18:36:28.036 WARN The code you submit will not be limited by the limit
2026-10-11 18:36:28.036 INFO Job with jobId : 13 and execID : LINKISCLI_hadoop_shell_0 submitted
2026-10-11 18:36:29.036 INFO Your job is accepted,  jobID is LINKISCLI_hadoop_shell_0 and jobReqId is 13 in ServiceInstance(linkis-cg-entrance, linkis-u22:9104, 0).
2026-10-11 18:36:29.036 INFO Your job is being scheduled by orchestrator.
2026-10-11 18:36:29.036 INFO Your job is Running now. Please wait it to complete.
[INFO] Job execute successfully! Will try get execute result
============Result:================
TaskId:13
ExecId: exec_id018015linkis-cg-entrancelinkis-u22:9104LINKISCLI_hadoop_shell_0
User:hadoop
Current job status:SUCCEED
extraMsg:
result:

[INFO] Retrieving result-set, may take time if result-set is large, please do not exit program.
============ RESULT SET 1 ============
hello
############Execute Success!!!########

要点：

JobId/TaskId 由 entrance 分配，是后续查询/取消任务的凭据；
首次提交某类引擎需拉起 EngineConn 进程（实测约 20 秒），之后复用空闲引擎会明显加快；
结果集默认打印到终端，同时落盘到 RESULT_SET_ROOT_PATH（实测为 /tmp/linkis/result/2026-10-11/LINKISCLI/hadoop/13/1_0.dolphin）。

2.3 常用提交参数

参数	说明	示例
`-codeType <type>`	代码类型（shell/python/sql/hive/spark 等）	`-codeType shell`
`-labelMap k=v`	引擎标签，必须含 `engineType=<引擎>-<版本>`	`-labelMap engineType=shell-1`
`-code "<code>"`	直接内联代码	`-code "echo hello"`
`-codePath <path>`	从本地文件读取代码	`-codePath /home/hadoop/demo.sh`
`-submitUser / -proxyUser`	提交用户 / 代理执行用户	缺省取当前 Linux 用户
`-creator <name>`	创建方标识（默认 LINKISCLI）	`-creator jobcenter`
`-outPath <path>`	结果集输出到指定路径而非 stdout	`-outPath file:///tmp/out`
`-confMap k=v`	引擎启动参数（startup）	`-confMap python.python.version=python3`
`-runtimeMap k=v`	运行时参数	`-runtimeMap hive.resultset.use.unique.column.names=true`
`-varMap k=v`	变量替换，代码中用 `${key}` 引用	`-varMap day=20261011`
`-labelMap userCreator=...`	自定义用户-创建方标签	一般无需指定
`--gatewayUrl <url>`	覆盖网关地址	`--gatewayUrl http://gw:9001`
`--authStg token`	token 认证（配合 `--authKey/--authVal`）	脚本化免密调用
`--async`	异步提交，提交后即退出	`--async true`
`--mode ujes/once`	ujes 常规模式 / once 一次性引擎模式	默认 ujes

2.4 脚本化免密提交（token 认证）

客户端默认读 conf/linkis-cli/linkis-cli.properties 中的 token（Validation-Code），无需密码即可提交；也可命令行显式传入：

sh $LINKIS_HOME/bin/linkis-cli \
  --gatewayUrl http://127.0.0.1:9001 \
  --authStg token --authKey Validation-Code \
  --authVal LINKIS-37a25a19da6646c7a6d6a980bd5a46e4 \
  -codeType shell -labelMap engineType=shell-1 -code "echo hello"

三、任务管理子命令

3.1 查询任务状态（--status）

sh $LINKIS_HOME/bin/linkis-cli --status 13

实测回显：

[INFO] user does not specify submit-user, will use current Linux user "hadoop" by default.
{
  "jobId": "13",
  "taskID": "13",
  "simpleExecId": "LINKISCLI_hadoop_shell_0",
  "execId": "exec_id018015linkis-cg-entrancelinkis-u22:9104LINKISCLI_hadoop_shell_0",
  "umUser": "hadoop",
  "logPath": "file:///tmp/linkis/hadoop/log/LINKISCLI/2026-10-11/13.log",
  "status": "SUCCEED",
  "engineType": "shell",
  "runType": "shell",
  "costTime": 21000,
  "createdTime": "Oct 11, 2026 6:36:28 PM",
  "updatedTime": "Oct 11, 2026 6:36:49 PM",
  "engineStartTime": "Oct 11, 2026 6:36:49 PM",
  "errCode": 0,
  "errMsg": "",
  "executeApplicationName": "shell",
  "requestApplicationName": "LINKISCLI",
  "progress": 1.0
}
############Execute Success!!!########

logPath 指向服务端任务日志（publicservice 文件系统服务维护），costTime 单位毫秒。

3.2 获取任务结果（--result）

sh $LINKIS_HOME/bin/linkis-cli --result 13

实测回显：

[INFO] Job execute successfully! Will try get execute result
============Result:================
TaskId:13
ExecId: exec_id018015linkis-cg-entrancelinkis-u22:9104LINKISCLI_hadoop_shell_0
User:hadoop
Current job status:SUCCEED
extraMsg:
result:

[INFO] Retrieving result-set, may take time if result-set is large, please do not exit program.
============ RESULT SET 1 ============
hello
############Execute Success!!!########

3.3 查看任务日志（--log）与取消任务（--kill）

sh $LINKIS_HOME/bin/linkis-cli --log 13      # 拉取服务端任务日志
sh $LINKIS_HOME/bin/linkis-cli --kill 14     # 取消运行中的任务

参数书写注意：任务管理类子命令是双横线（--status/--log/--result/--kill），提交类参数是单横线（-codeType/-code/...）。误写为 -status 13 会报参数校验错误：

[ERROR] Failed to build CliCtx
org.apache.linkis.cli.application.exception.CommandException: CMD0011,Validation failed: Illegal argument: [-status, 13]

3.4 REST API 对照

等价的 REST 调用（token 为 wds.linkis.bml.auth.token.value）：

TOKEN=$(grep "wds.linkis.bml.auth.token.value" $LINKIS_HOME/conf/linkis.properties | cut -d= -f2)
# 登录
curl -s -X POST -H "Content-Type: application/json" \
  -d '{"userName":"hadoop","password":"q1w2e3r4"}' \
  http://127.0.0.1:9001/api/rest_j/v1/user/login
# 任务详情
curl -s -H "Token-Code: $TOKEN" -H "Token-User: hadoop" \
  http://127.0.0.1:9001/api/rest_j/v1/jobhistory/13/get

四、服务启停脚本

4.1 一键启动 linkis-start-all.sh

sh $LINKIS_HOME/sbin/linkis-start-all.sh

按 eureka → gateway → publicservice → manager → entrance → ecm 顺序拉起，每个服务的启动输出形如：

Start to check whether the mg-eureka is running
server linkis-mg-eureka start succeeded!

全部成功后输出：

Apache Linkis started successfully

一键停止：

sh $LINKIS_HOME/sbin/linkis-stop-all.sh

输出按服务逐个打印 Begin to stop <服务名> 与 server <服务名> is not running，结尾为：

stop-all shell script executed completely

4.2 单服务管理 linkis-daemon.sh

sh $LINKIS_HOME/sbin/linkis-daemon.sh {start|stop|restart|status} <服务名>

服务名取值：mg-eureka、mg-gateway、ps-publicservice、cg-linkismanager、cg-entrance、cg-engineconnmanager、cg-engineconn（引擎进程）/linkis-et-monitor（监控）。

status 实测回显（运行中）：

22717
server cg-linkismanager is running.

重启示例（引擎相关排障常用）：

sh $LINKIS_HOME/sbin/linkis-daemon.sh restart cg-engineconnmanager

pid 文件位于 $LINKIS_HOME/pid/（命名如 linkis_cg-linkismanager.pid）。进程被 kill -9 后会遗留僵尸 pid 文件导致 is already running 误判，先 rm -f $LINKIS_HOME/pid/*.pid 再操作。

4.3 启动顺序建议

资源紧张或排障时建议按依赖逐个启动：mg-eureka（等 1 分钟）→ mg-gateway → ps-publicservice → cg-linkismanager（等待其完成引擎插件 BML 上传，观察日志 Upload ... success）→ cg-entrance → cg-engineconnmanager。manager 启动时 gateway 未就绪会因 BML 上传失败退出，单独 restart manager 即可。

五、日志排查

5.1 日志目录结构

$LINKIS_HOME/logs/ 实测文件清单：

linkis-mg-eureka.log / .out / -gc.log
linkis-mg-gateway.log / .out / -gc.log
linkis-ps-publicservice.log / .out / -gc.log
linkis-cg-linkismanager.log / .out / -gc.log
linkis-cg-entrance.log / .out / -gc.log
linkis-cg-engineconnmanager.log / .out / -gc.log
linkis-cli/                     # linkis-cli 客户端日志（按用户+时间戳命名）

*.log：应用日志（log4j2，含 INFO/WARN/ERROR 分级）；
*.out：进程标准输出（Spring 启动画幅、JVM 致命错误）；
-gc.log：GC 日志。

引擎（EngineConn）日志不在 logs/ 目录，而在 ENGINECONN_ROOT_PATH（实测 /appcom/tmp/<用户>/<日期>/<引擎类型>/<ticketId>/logs/），含 stdout/stderr/gc/yarnApp 四个文件，任务失败时 CLI 报错信息中会直接给出该路径。

5.2 常用排查命令

# 全局搜错误
grep ERROR $LINKIS_HOME/logs/linkis-cg-linkismanager.log | tail
# 任务级追踪（带 JobId 过滤）
grep "JobId-13" $LINKIS_HOME/logs/linkis-cg-entrance.log
# 查看网关请求路由失败
grep -E "11011|10905" $LINKIS_HOME/logs/linkis-mg-gateway.log | tail
# 引擎启动失败现场
tail -50 /appcom/tmp/hadoop/20261011/shell/<ticketId>/logs/stdout

5.3 实测常见错误码速查

错误码	含义	实测根因
11011	There are no services available in the registry	目标服务崩溃/未注册，重启对应服务
10905	URL ... request failed	上游服务不可达（多为 publicservice 未启动或超时）
12003 / 21304	Task is Failed	引擎侧失败，按报错内层 errCode 继续排查
30002	Failed to initialize engine	引擎拉起失败：JAVA_HOME 缺失、sudo 无免密、目录属主错误
6005 / 60050	BML 上传失败	`bml.local.prefix` 双 `file://` 前缀或目录权限
CMD0011	Validation failed: Illegal argument	CLI 参数拼写错误（如单横线写成 `-status`）

六、辅助脚本

6.1 clear-server.sh

按服务名强杀残留进程并清理 pid 文件，用于 daemon 状态错乱后的现场清理：

sh $LINKIS_HOME/sbin/clear-server.sh

6.2 kill-ec-process-by-port.sh

引擎进程通过随机端口注册，卡死引擎可按端口强杀：

sh $LINKIS_HOME/sbin/kill-ec-process-by-port.sh 44155

6.3 kill-yarn-jobs.sh / graceful-upgrade.sh

kill-yarn-jobs.sh：接入 Hadoop 集群后按用户清理 YARN 应用；
graceful-upgrade.sh：版本升级时滚动重启服务的辅助脚本。

七、常见问题（FAQ）

7.1 `No JDK 8 found. linkis-client requires Java 1.8`

非登录 shell 下 JAVA_HOME 未加载。在 .bash_profile 中固化，或提交前 source /etc/profile。

7.2 提交报 `engineType` 标签相关错误

-codeType 只声明代码类型，引擎定位还需 -labelMap engineType=<引擎>-<版本>（如 shell-1、python-python2）。缺省标签时无法匹配引擎，任务被拒绝。

7.3 CLI 卡在 `EngineAskAsyncResponse` 不返回

manager 无法创建引擎：查 manager 日志的 create/reuse Engine 报错。实测高频原因：内存不足引发 MySQL 建连超时（Druid GetConnectionTimeoutException）、/tmp/linkis 或引擎插件目录属主不是部署用户、MySQL 授权缺失（skip_name_resolve 场景需 'root'@'127.0.0.1'）。

7.4 任务状态长期 Running 但引擎已退出

进程残留或 entrance 与引擎失联，先用 --status <id> 看 progress，再从 logPath 指向的服务端日志定位；必要时 --kill <id> 后重新提交。

7.5 结果集文件是什么格式

.dolphin 为 Linkis 结果集序列化格式（首行为表头元信息，后续按行存数据），可直接 cat 查看小结果集，或用 --outPath 重导出为指定路径。

Apache Linkis 常用 CLI 命令与工具详解

Apache Linkis 常用 CLI 命令与工具详解

一、命令工具总览

1.1 bin 目录（任务提交客户端）

1.2 sbin 目录（服务管理）

1.3 运行前环境要求

二、linkis-cli 提交任务

2.1 查看帮助与版本

2.2 提交 shell 任务

2.3 常用提交参数

2.4 脚本化免密提交（token 认证）

三、任务管理子命令

3.1 查询任务状态（--status）

3.2 获取任务结果（--result）

3.3 查看任务日志（--log）与取消任务（--kill）

3.4 REST API 对照

四、服务启停脚本

4.1 一键启动 linkis-start-all.sh

4.2 单服务管理 linkis-daemon.sh

4.3 启动顺序建议

五、日志排查

5.1 日志目录结构

5.2 常用排查命令

5.3 实测常见错误码速查

六、辅助脚本

6.1 clear-server.sh

6.2 kill-ec-process-by-port.sh

6.3 kill-yarn-jobs.sh / graceful-upgrade.sh

七、常见问题（FAQ）

7.1 No JDK 8 found. linkis-client requires Java 1.8

7.2 提交报 engineType 标签相关错误

7.3 CLI 卡在 EngineAskAsyncResponse 不返回

7.4 任务状态长期 Running 但引擎已退出

7.5 结果集文件是什么格式

7.1 `No JDK 8 found. linkis-client requires Java 1.8`

7.2 提交报 `engineType` 标签相关错误

7.3 CLI 卡在 `EngineAskAsyncResponse` 不返回