Apache Linkis 配置参数详解

本文基于 Apache Linkis 1.8.0 实测环境（Ubuntu 22.04 / JDK 8 / MySQL 8，部署目录 /appcom/Install/LinkisInstall），系统梳理 Linkis 的配置文件体系与核心参数。文中示例值均为实测环境真实值，生产环境请按集群规模调整。

一、配置文件体系总览

1.1 三层配置结构

Linkis 配置分为三层，生效顺序为：安装脚本渲染 → 服务配置文件 → 运行时管理台修改。

层次	位置	说明
部署层	安装包 `deploy-config/db.sh`、`deploy-config/linkis-env.sh`	安装前编写，install.sh 读取后渲染生成运行时配置
运行层	`$LINKIS_HOME/conf/*.properties`	各服务启动时读取，修改后需重启对应服务
管理层	Linkis 管理台 / `linkis_cg_manager_*` 表	引擎启动参数、队列资源等运行时下发

1.2 conf 目录文件清单

/appcom/Install/LinkisInstall/conf/ 实测文件清单：

application-engineconn.yml
application-eureka.yml
application-linkis.yml
db.sh
linkis-cg-engineconnmanager.properties
linkis-cg-entrance.properties
linkis-cg-linkismanager.properties
linkis-cli/                 # linkis-cli 客户端配置目录
linkis-env.sh
linkis-et-monitor-file.properties
linkis-et-monitor.properties
linkis-mg-gateway.properties
linkis-ps-publicservice.properties
linkis.properties           # 全服务共享的核心配置
log4j2-console.xml
log4j2.xml

命名规律：linkis-mg-* 为微服务治理层（eureka/gateway），linkis-cg-* 为计算治理层（manager/entrance/engineconnmanager），linkis-ps-* 为公共服务层。linkis.properties 由所有服务共同加载，服务级 *.properties 覆盖同名键。

二、linkis-env.sh 部署参数详解

该文件位于 conf/linkis-env.sh（由 deploy-config/linkis-env.sh 渲染而来），既是部署脚本输入，也被 sbin/ 下启动脚本 source。

2.1 部署用户与目录

deployUser=hadoop
deployPwd=q1w2e3r4
LINKIS_HOME=/appcom/Install/LinkisInstall
LINKIS_VERSION=1.8.0
LINKIS_PUBLIC_MODULE=lib/linkis-commons/public-module
LINKIS_EXTENDED_LIB=/appcom/common/linkisExtendedLib

deployUser：部署与运行用户，引擎进程以任务提交用户运行时由该用户通过 sudo 切换，因此该用户必须配置免密 sudo。
deployPwd：install.sh 用其初始化 Linkis 管理员账号密码。管理员用户名固定为 hadoop（由 linkis.properties 的 wds.linkis.governance.station.admin 决定，修改该属性可变更管理员用户名）。
LINKIS_EXTENDED_LIB：扩展库目录。该目录会被追加到所有服务的 classpath，是放置 MySQL JDBC 驱动等第三方 jar 的推荐位置（网关的 classpath 不含 public-module，必须依赖此目录加载驱动）。

2.2 JVM 内存参数

export SERVER_HEAP_SIZE="192M"       # 各服务默认堆大小
EUREKA_HEAP_SIZE="128M"              # 覆盖 eureka 堆
# GATEWAY_HEAP_SIZE / ENTRANCE_HEAP_SIZE / PUBLICSERVICE_HEAP_SIZE /
# ENGINECONNMANAGER_HEAP_SIZE / MANAGER_HEAP_SIZE / MONITOR_HEAP_SIZE

各服务启动脚本（sbin/ext/linkis-common-start）的取值逻辑：优先读服务专属 *_HEAP_SIZE，未设置则回落到 SERVER_HEAP_SIZE。服务级变量只在对应 ext 脚本中生效。

实测建议：4 GB 内存的低配环境用 192M/128M 组合并在启动参数追加 -XX:MaxMetaspaceSize=128m -XX:MaxDirectMemorySize=64m -Xss512k；生产环境建议 SERVER_HEAP_SIZE=1G 起步，manager 与 publicservice 可单独放大。

2.3 注册中心与服务端口

DISCOVERY=EUREKA               # 注册中心类型：EUREKA 或 NACOS
EUREKA_PORT=20303
export EUREKA_PREFER_IP=false  # true 时以 IP 注册，false 以主机名注册
NACOS_SERVER_ADDR=127.0.0.1:8848

GATEWAY_PORT=9001
MANAGER_PORT=9101
ENGINECONNMANAGER_PORT=9102
ENTRANCE_PORT=9104
PUBLICSERVICE_PORT=9105

端口值会被渲染进 application-*.yml 与 linkis.properties。修改端口后需同步检查防火墙与 wds.linkis.gateway.url。

2.4 存储路径参数

WORKSPACE_USER_ROOT_PATH=file:///tmp/linkis/   # 用户工作空间根目录
RESULT_SET_ROOT_PATH=file:///tmp/linkis        # 结果集根目录
HDFS_USER_ROOT_PATH=file:///tmp/linkis         # HDFS 模式下的用户根目录
ENGINECONN_ROOT_PATH=/appcom/tmp               # 引擎工作目录（日志/临时文件）

本地模式三个路径都用 file:// 协议指向本地目录；接入 HDFS 时改为 hdfs:/// 前缀。目录必须归属部署用户，否则 BML 上传/结果集写出失败。

2.5 Hadoop 生态开关

export ENABLE_HDFS=false
export ENABLE_HIVE=false
export ENABLE_SPARK=false

HADOOP_HOME=${HADOOP_HOME:-"/appcom/Install/hadoop"}
HADOOP_CONF_DIR=${HADOOP_CONF_DIR:-"/appcom/config/hadoop-config"}
HADOOP_KERBEROS_ENABLE=false
HADOOP_KEYTAB_PATH="/appcom/keytab/"
HADOOP_VERSION="3.3.4"
HIVE_HOME=/appcom/Install/hive
SPARK_HOME=/appcom/Install/spark
YARN_RESTFUL_URL="http://127.0.0.1:8088"

ENABLE_* 为 false 时安装脚本跳过对应组件校验，Linkis 以纯本地形态运行 Shell/Python 引擎。接入真实集群时置 true 并填写各组件路径；Kerberos 环境还需 keytab。

2.6 数据库连接参数

dbType=mysql

db.sh 中配套的 MYSQL_HOST/MYSQL_PORT/MYSQL_DB/MYSQL_USER/MYSQL_PASSWORD 渲染进 linkis.properties 的 mybatis 数据源；dbType 决定 install.sh 使用 linkis_ddl.sql 还是 PostgreSQL DDL。

三、linkis.properties 核心参数详解

所有服务共享，路径 conf/linkis.properties。以下为实测环境生效值与解析。

3.1 服务基础

wds.linkis.server.version=v1
wds.linkis.home=/appcom/Install/LinkisInstall
linkis.discovery.prefer-ip-address=false
linkis.discovery.server-address=http://linkis-u22:20303/eureka/
wds.linkis.gateway.url=http://linkis-u22:9001

linkis.discovery.server-address：Eureka 地址，各服务据此注册与发现；
wds.linkis.gateway.url：网关地址，引擎与客户端回连入口，必须保证全节点可达。

3.2 数据源与 MySQL 安全

wds.linkis.server.mybatis.datasource.url=jdbc:mysql://127.0.0.1:3306/linkis?characterEncoding=UTF-8
wds.linkis.server.mybatis.datasource.username=root
wds.linkis.server.mybatis.datasource.password=q1w2e3r4
wds.linkis.server.mybatis.datasource.driver-class-name=com.mysql.jdbc.Driver
wds.linkis.server.mybatis.mapperLocations=classpath*:mapper/common/*.xml,classpath*:mapper/mysql/*.xml
wds.linkis.mysql.is.encrypt=false
linkis.mysql.strong.security.enable=false
linkis.mysql.force.params=allowLoadLocalInfile=false&autoDeserialize=false&allowLocalInfile=false&allowUrlInLocalInfile=false

wds.linkis.mysql.is.encrypt=true 时密码需为加密串（管理台提供加密工具），明文部署保持 false；
linkis.mysql.force.params 是强制附加到所有 JDBC URL 的安全参数，防止本地文件读取与反序列化攻击，生产环境保持默认。

3.3 文件系统与 BML 存储

wds.linkis.filesystem.root.path=file:///tmp/linkis/
wds.linkis.filesystem.hdfs.root.path=file:///tmp/linkis
wds.linkis.bml.is.hdfs=false
wds.linkis.bml.local.prefix=/tmp/linkis

wds.linkis.bml.local.prefix：BML 物料本地存储前缀。实测注意：默认值 file:///tmp/linkis 会导致引擎插件上传时拼出 file://file:///tmp/linkis 双协议而失败，必须改为不带 file:// 的纯路径；
引擎插件（engineconn plugin conf.zip 等）经 BML 上传共享，该路径损坏会导致 manager 无法启动引擎。

3.4 管理员与权限

wds.linkis.governance.station.admin=hadoop
wds.linkis.jobhistory.admin=hadoop

管理员用户名可改为其他 Linux 用户（该用户需在部署服务器上存在），修改后重启 publicservice/entrance。

3.5 网关 token

wds.linkis.bml.auth.token.key=Validation-Code
wds.linkis.bml.auth.token.value=LINKIS-37a25a19da6646c7a6d6a980bd5a46e4

token 同步写入数据库表 linkis_mg_gateway_auth_token，用于服务间与脚本化调用（REST 头 Token-Code/Token-User，linkis-cli 客户端配置亦引用）。生产环境应更换为随机长串并同步更新两侧。

3.6 引擎 JVM 内存

wds.linkis.engineconn.java.driver.memory=256m

默认 1g。该值决定每个 EngineConn（引擎进程）的 -Xmx。单机多任务场景按 引擎数 × 该值 估算内存占用，低配环境建议 256m（实测值）。

3.7 Spring 框架参数

spring.spring.cloud.config.enabled=false
spring.spring.main.allow-circular-references=true
spring.spring.mvc.pathmatch.matching-strategy=ant_path_matcher
spring.spring.cloud.loadbalancer.cache.enabled=false

框架兼容性开关，保持默认即可，不建议修改。

四、服务级配置文件详解

4.1 linkis-mg-gateway.properties

wds.linkis.gateway.admin.user=hadoop
wds.linkis.gateway.conf.url.pass.auth=/actuator/health
wds.linkis.session.timeout=3600000

网关级免认证路径、会话超时（毫秒）。登录接口返回的 sessionTimeOut:3600000 即来源于此。

4.2 linkis-cg-entrance / linkis-cg-linkismanager / linkis-cg-engineconnmanager

三者的 properties 主要为日志路径与 RPC 参数，个别常用项：

# linkis-cg-entrance.properties
wds.linkis.entrance.max.ask.executor.time=6h        # 单任务最长等待时间
# linkis-cg-engineconnmanager.properties
wds.linkis.ecm.worker.num=3                          # ECM 工作线程数

4.3 linkis-cli 客户端配置

conf/linkis-cli/linkis-cli.properties 实测生效项：

wds.linkis.client.common.gatewayUrl=http://127.0.0.1:9001
wds.linkis.client.common.authStrategy=token
wds.linkis.client.common.tokenKey=Validation-Code
wds.linkis.client.common.tokenValue=LINKIS-37a25a19da6646c7a6d6a980bd5a46e4
wds.linkis.client.noncustomizable.enable.user.specification=true
wds.linkis.client.noncustomizable.enable.proxy.user=true

authStrategy 支持 token（免密，用 tokenKey/tokenValue）与 username（用户名密码）两种认证方式；gatewayUrl 可被命令行 --gatewayUrl 覆盖。

五、引擎配置详解

5.1 引擎插件目录结构

lib/linkis-engineconn-plugins/
├── shell/dist/1/{lib,conf,plugin}
├── python/dist/1/{lib,conf,plugin}
└── ...（spark/hive/jdbc 等）

dist/<版本> 中的数字即引擎版本号，对应标签 engineType=shell-1（引擎类型-版本）。

5.2 引擎启动参数

引擎进程的 JVM 参数由 manager 侧构建，可配置项包括：

参数	默认值	说明
`wds.linkis.engineconn.java.driver.memory`	1g	引擎进程 -Xmx，实测环境改 256m
`wds.linkis.rm.client.memory.max`	20G	RM 视角单用户内存上限
`wds.linkis.rm.instance`	10	单用户最大引擎实例数

任务提交时可通过 linkis-cli 的 -confMap 下发启动参数（写入引擎 linkis-engineconn.properties），通过 -runtimeMap 下发运行时参数。

5.3 引擎标签

引擎由标签组合定位，提交任务至少需要：

codeType=shell          # 执行代码类型
engineType=shell-1      # 引擎类型-版本（缺省时任务被拒绝）
userCreator=hadoop-LINKISCLI   # 提交用户-创建方（自动生成）

标签持久化于 linkis_cg_manager_label 表，管理台可在"引擎管理"中查看。

六、生产环境参数模板

6.1 linkis-env.sh 生产模板（节选）

deployUser=hadoop
deployPwd=<强密码>
LINKIS_HOME=/appcom/Install/LinkisInstall
LINKIS_EXTENDED_LIB=/appcom/common/linkisExtendedLib

export SERVER_HEAP_SIZE="1G"
# GATEWAY_HEAP_SIZE="1G"; MANAGER_HEAP_SIZE="2G"; PUBLICSERVICE_HEAP_SIZE="2G"

DISCOVERY=EUREKA
EUREKA_PORT=20303
export EUREKA_PREFER_IP=true          # 多主机部署建议 IP 注册，避免主机名解析问题

GATEWAY_PORT=9001
MANAGER_PORT=9101
ENGINECONNMANAGER_PORT=9102
ENTRANCE_PORT=9104
PUBLICSERVICE_PORT=9105

RESULT_SET_ROOT_PATH=hdfs:///tmp/linkis
HDFS_USER_ROOT_PATH=hdfs:///tmp/linkis
export ENABLE_HDFS=true
export ENABLE_HIVE=false
export ENABLE_SPARK=false
HADOOP_CONF_DIR=/etc/hadoop/conf

6.2 linkis.properties 生产增补（节选）

wds.linkis.server.mybatis.datasource.url=jdbc:mysql://mysql-vip:3306/linkis?characterEncoding=UTF-8&useSSL=false&rewriteBatchedStatements=true
wds.linkis.server.mybatis.datasource.password=<加密后的密码串>
wds.linkis.mysql.is.encrypt=true
wds.linkis.bml.local.prefix=/data/linkis/bml
wds.linkis.filesystem.root.path=hdfs:///tmp/linkis/
wds.linkis.gateway.url=http://<网关VIP>:9001
wds.linkis.engineconn.java.driver.memory=1g

七、常见问题（FAQ）

7.1 修改配置后不生效

分清层次：linkis-env.sh 中的堆/端口参数在进程启动时读取，修改后必须重启对应服务；linkis.properties 同样需重启加载；引擎参数随每次任务创建引擎时下发，改完即生效。管理台修改的运行时配置存于数据库，优先级高于 conf 文件。

7.2 参数 `wds.linkis.bml.local.prefix` 报 `file://file://` 双前缀

该参数只需纯路径（如 /tmp/linkis），代码会自行补 file:// 协议头，默认模板中的 file:///tmp/linkis 是官方模板笔误，详见安装指南 9.4 节。

7.3 忘记 Linkis 管理员密码

管理员密码存于数据库 linkis_user 表（密码列加密存储）。最简方式是用部署密码重跑 install.sh 选择 2 重建表（会清空任务历史），或使用官方提供的密码重置入口重新生成。

7.4 如何为单个服务单独调堆

在 linkis-env.sh 设置服务专属变量（优先级高于 SERVER_HEAP_SIZE）：GATEWAY_HEAP_SIZE、MANAGER_HEAP_SIZE、ENTRANCE_HEAP_SIZE、PUBLICSERVICE_HEAP_SIZE、ENGINECONNMANAGER_HEAP_SIZE、EUREKA_HEAP_SIZE、MONITOR_HEAP_SIZE。

7.5 低内存环境（4 GB）推荐参数组合

实测验证：SERVER_HEAP_SIZE=192M、EUREKA_HEAP_SIZE=128M、启动参数追加 -XX:MaxMetaspaceSize=128m -XX:MaxDirectMemorySize=64m -Xss512k、引擎内存 wds.linkis.engineconn.java.driver.memory=256m；MySQL 侧 performance_schema=OFF、innodb_buffer_pool_size=64M、mysqlx=OFF（配置须写入 [mysqld] 段）。该组合下 6 个服务 + MySQL + 1 个 shell 引擎可稳定共存。

7.6 MySQL 启用 skip_name_resolve 后连接被拒

报 Host '127.0.0.1' is not allowed to connect：localhost 授权不再匹配 IP 来源，补 'root'@'127.0.0.1' 授权即可，详见安装指南 9.6 节。

Apache Linkis 配置参数详解

Apache Linkis 配置参数详解

一、配置文件体系总览

1.1 三层配置结构

1.2 conf 目录文件清单

二、linkis-env.sh 部署参数详解

2.1 部署用户与目录

2.2 JVM 内存参数

2.3 注册中心与服务端口

2.4 存储路径参数

2.5 Hadoop 生态开关

2.6 数据库连接参数

三、linkis.properties 核心参数详解

3.1 服务基础

3.2 数据源与 MySQL 安全

3.3 文件系统与 BML 存储

3.4 管理员与权限

3.5 网关 token

3.6 引擎 JVM 内存

3.7 Spring 框架参数

四、服务级配置文件详解

4.1 linkis-mg-gateway.properties

4.2 linkis-cg-entrance / linkis-cg-linkismanager / linkis-cg-engineconnmanager

4.3 linkis-cli 客户端配置

五、引擎配置详解

5.1 引擎插件目录结构

5.2 引擎启动参数

5.3 引擎标签

六、生产环境参数模板

6.1 linkis-env.sh 生产模板（节选）

6.2 linkis.properties 生产增补（节选）

七、常见问题（FAQ）

7.1 修改配置后不生效

7.2 参数 wds.linkis.bml.local.prefix 报 file://file:// 双前缀

7.3 忘记 Linkis 管理员密码

7.4 如何为单个服务单独调堆

7.5 低内存环境（4 GB）推荐参数组合

7.6 MySQL 启用 skip_name_resolve 后连接被拒

7.2 参数 `wds.linkis.bml.local.prefix` 报 `file://file://` 双前缀