Apache Linkis Docker Compose 部署指南

本文介绍用 Docker Compose 在单台宿主机上部署 Apache Linkis 1.8.0 单节点环境，包括官方镜像的两种获取方式、compose 编排文件、数据持久化、等价的 docker run 命令与日常运维操作。所用 Dockerfile 与构建脚本内容均取自官方 binary 包 apache-linkis-1.8.0-bin/docker/ 目录。

一、官方镜像选型

1.1 镜像获取的两种方式

方式一：Docker Hub 官方镜像。 Apache 官方在 Docker Hub 的 apache/linkis 仓库发布 Linkis 镜像，可用 docker pull apache/linkis:<tag> 直接获取，具体可用标签以 Docker Hub 页面 hub.docker.com/r/apache/linkis 为准（应与所使用的 Linkis 版本号一致，如 1.8.0）。

方式二：使用官方包内 Dockerfile 自建。 binary 包 docker/ 目录提供了完整构建链：

docker/
├── linkis.Dockerfile                    # 基础镜像（Linkis 程序包 + JDK8 运行环境）
├── linkis-with-mysql-jdbc.Dockerfile    # 在基础镜像上追加 MySQL JDBC 驱动
├── ldh.Dockerfile                       # 集成 LDH（Hadoop 伪分布式）调试镜像
└── scripts/
    ├── make-linkis-image-with-mysql-jdbc.sh   # 一键构建含 JDBC 驱动的镜像
    └── entry-point-ldh.sh

1.2 官方镜像的关键约定

linkis.Dockerfile（内容实测摘录）定义了镜像的目录与运行约定：

ARG IMAGE_BASE=centos:7
ARG JDK_VERSION=1.8.0-openjdk
ARG LINKIS_VERSION=1.8.0
ARG LINKIS_SYSTEM_USER="hadoop"
ARG LINKIS_SYSTEM_UID="9001"
ARG LINKIS_HOME=/opt/linkis
ARG LINKIS_CONF_DIR=/etc/linkis-conf
ARG LINKIS_LOG_DIR=/var/logs/linkis

镜像内 Linkis 部署目录为 /opt/linkis（注意与裸机安装默认的 /appcom/Install/LinkisInstall 不同）；
运行用户为 hadoop（UID 9001），且镜像内已配置 %wheel ALL=(ALL) NOPASSWD: ALL，满足引擎切换执行用户所需的免密 sudo；
ENTRYPOINT ["/bin/bash"]，即容器启动后需自行执行启动脚本；
配置目录 /etc/linkis-conf、日志目录 /var/logs/linkis 是官方预留的挂载点。

linkis-with-mysql-jdbc.Dockerfile 揭示了 JDBC 驱动的正确安放位置——同时放入公共模块与网关两个目录（裸机部署时网关找不到驱动的经典问题，官方镜像同样通过双目录解决）：

ARG LINKIS_HOME=/opt/linkis
ARG MYSQL_JDBC_VERSION=8.0.28

COPY mysql-connector-java-${MYSQL_JDBC_VERSION}.jar ${LINKIS_HOME}/lib/linkis-commons/public-module/
COPY mysql-connector-java-${MYSQL_JDBC_VERSION}.jar ${LINKIS_HOME}/lib/linkis-spring-cloud-services/linkis-mg-gateway/

1.3 自建含 JDBC 驱动的镜像

官方包 docker/scripts/make-linkis-image-with-mysql-jdbc.sh 的一键构建流程（脚本会先从 Maven Central 下载 mysql-connector-java-8.0.28.jar 再构建）：

# 1. 构建基础镜像（在 binary 包解压目录执行，构建上下文为该目录）
docker build -f docker/linkis.Dockerfile -t linkis:dev .

# 2. 构建含 JDBC 驱动的镜像（默认产物名 linkis:with-jdbc）
sh docker/scripts/make-linkis-image-with-mysql-jdbc.sh

自建镜像的内部部署动作与裸机一致：linkis-package/* 被移动到 /opt/linkis，配置渲染仍依赖 deploy-config/。

二、Docker Compose 编排

2.1 编排设计

单节点最小形态包含两个服务：

服务	镜像	说明
mysql	mysql:8.0	Linkis 元数据库，数据卷持久化
linkis	apache/linkis:1.8.0 或自建 linkis:with-jdbc	6 个 Linkis 服务进程运行于同一容器

2.2 compose.yaml

services:
  mysql:
    image: mysql:8.0
    container_name: linkis-mysql
    environment:
      MYSQL_ROOT_PASSWORD: "q1w2e3r4"
      MYSQL_DATABASE: "linkis"
    command:
      --character-set-server=utf8mb4
      --collation-server=utf8mb4_general_ci
      --default-authentication-plugin=mysql_native_password
    volumes:
      - mysql-data:/var/lib/mysql
      - ./initdb:/docker-entrypoint-initdb.d:ro
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-uroot", "-pq1w2e3r4"]
      interval: 10s
      timeout: 5s
      retries: 10

  linkis:
    image: apache/linkis:1.8.0        # 或自建的 linkis:with-jdbc
    container_name: linkis-server
    hostname: linkis
    depends_on:
      mysql:
        condition: service_healthy
    environment:
      # 镜像内部署目录约定
      LINKIS_HOME: /opt/linkis
      LINKIS_CONF_DIR: /etc/linkis-conf
    entrypoint: ["/bin/bash", "-c", "/opt/linkis/sbin/linkis-start-all.sh && tail -f /dev/null"]
    ports:
      - "9001:9001"    # 网关
      - "20303:20303"  # Eureka 注册中心
      - "9101:9101"    # linkismanager
      - "9102:9102"    # engineconnmanager
      - "9104:9104"    # entrance
      - "9105:9105"    # publicservice
    volumes:
      - linkis-conf:/etc/linkis-conf
      - linkis-logs:/var/logs/linkis
      - linkis-tmp:/tmp/linkis
    mem_limit: 6g

volumes:
  mysql-data:
  linkis-conf:
  linkis-logs:
  linkis-tmp:

2.3 数据库初始化脚本

Linkis 的 DDL/DML 位于 binary 包 linkis-package/db/（镜像内为 /opt/linkis/db/）。将其复制到 ./initdb/ 供 MySQL 容器首次启动时自动导入：

mkdir -p initdb
cp apache-linkis-1.8.0-bin/linkis-package/db/linkis_ddl.sql initdb/01-ddl.sql
cp apache-linkis-1.8.0-bin/linkis-package/db/linkis_dml.sql initdb/02-dml.sql

MySQL 官方镜像按文件名顺序执行 /docker-entrypoint-initdb.d/ 下的 .sql 文件，仅需执行一次。

2.4 渲染 Linkis 配置

Linkis 配置中数据库连接信息来自 deploy-config/db.sh。容器方式无需重跑 install.sh，直接编辑挂载卷中的配置（以挂载到 /etc/linkis-conf 后软链或复制到 /opt/linkis/conf）：

db.sh（数据库指向 compose 服务名 mysql）：

MYSQL_HOST=mysql
MYSQL_PORT=3306
MYSQL_DB=linkis
MYSQL_USER=root
MYSQL_PASSWORD=q1w2e3r4

linkis-env.sh 关键项（与裸机安装一致，JDBC 驱动镜像内已就位）：

deployUser=hadoop
deployPwd=q1w2e3r4
export SERVER_HEAP_SIZE="512M"
export ENABLE_HDFS=false
export ENABLE_HIVE=false
export ENABLE_SPARK=false
RESULT_SET_ROOT_PATH=file:///tmp/linkis
LINKIS_EXTENDED_LIB=/appcom/common/linkisExtendedLib

同时把 conf/linkis.properties 中以下三项改为容器内可达地址：

wds.linkis.server.mybatis.datasource.url=jdbc:mysql://mysql:3306/linkis?characterEncoding=UTF-8
linkis.discovery.server-address=http://linkis:20303/eureka/
wds.linkis.gateway.url=http://linkis:9001

三、启动与验证

3.1 启动

docker compose up -d
docker compose ps

Linkis 容器启动脚本按 eureka → gateway → publicservice → manager → entrance → ecm 顺序拉起，全部就绪约需 2~4 分钟。

3.2 验证网关登录

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

status: 0 即部署成功（响应体与裸机安装一致："message":"login successful(登录成功)！"）。

3.3 提交任务验证

在 Linkis 容器内通过 linkis-cli 提交 shell 任务：

docker compose exec linkis bash -c \
  'sh /opt/linkis/bin/linkis-cli -codeType shell -labelMap engineType=shell-1 -code "echo hello"'

成功时结尾输出 Current job status:SUCCEED 与 RESULT SET 1 中的 hello，与裸机安装的回显一致。

四、等价 docker run 命令

与 2.2 节 compose 等价的单命令启动（先创建网络与卷）：

docker network create linkis-net

docker run -d --name linkis-mysql --network linkis-net \
  -e MYSQL_ROOT_PASSWORD=q1w2e3r4 -e MYSQL_DATABASE=linkis \
  -v linkis-mysql-data:/var/lib/mysql \
  mysql:8.0 \
  --character-set-server=utf8mb4 --default-authentication-plugin=mysql_native_password

docker run -d --name linkis-server --network linkis-net \
  -p 9001:9001 -p 20303:20303 -p 9101:9101 -p 9102:9102 -p 9104:9104 -p 9105:9105 \
  -e LINKIS_HOME=/opt/linkis -e LINKIS_CONF_DIR=/etc/linkis-conf \
  -v linkis-conf:/etc/linkis-conf -v linkis-logs:/var/logs/linkis -v linkis-tmp:/tmp/linkis \
  --memory 6g \
  apache/linkis:1.8.0 \
  /bin/bash -c "/opt/linkis/sbin/linkis-start-all.sh && tail -f /dev/null"

数据库初始化与配置渲染步骤与 2.3/2.4 节相同。

五、日常运维

5.1 启停与状态

docker compose start linkis      # 启动
docker compose stop linkis       # 停止（容器内 Linkis 进程随 entrypoint 退出）
docker compose restart linkis    # 重启
docker compose down              # 停止并删除容器（命名卷保留）
docker compose down -v           # 连同数据卷一起删除（危险，元数据丢失）

容器内亦可直接使用官方脚本精细控制单个服务：

docker compose exec linkis bash -c "sh /opt/linkis/sbin/linkis-daemon.sh status mg-gateway"
docker compose exec linkis bash -c "sh /opt/linkis/sbin/linkis-daemon.sh restart cg-entrance"

5.2 日志排查

docker compose logs -f --tail=200 linkis     # 容器标准输出
docker compose exec linkis bash -c "ls -lt /var/logs/linkis | head"   # 各服务日志目录
docker compose exec linkis bash -c "grep ERROR /var/logs/linkis/linkis-mg-gateway.log | tail"

各服务日志文件命名（linkis-<服务名>.log / .out / -gc.log）与裸机安装一致。

5.3 备份与恢复

# 元数据备份
docker compose exec mysql sh -c 'mysqldump -uroot -p"$MYSQL_ROOT_PASSWORD" linkis' > linkis-meta-$(date +%F).sql

# 恢复
docker compose exec -T mysql sh -c 'mysql -uroot -p"$MYSQL_ROOT_PASSWORD" linkis' < linkis-meta-2026-10-11.sql

结果集与用户工作目录位于 linkis-tmp 卷（/tmp/linkis），可用 docker run --rm -v linkis-tmp:/data -v $PWD:/backup alpine tar czf /backup/linkis-tmp.tgz /data 打包。

5.4 版本升级

mysqldump 备份元数据并停容器；
将 compose 中 image 标签改为新版本（或用新版 binary 包重新 docker build 自建镜像）；
docker compose up -d 后执行新版本包 db/ 下的增量升级 SQL（官方按版本提供）；
核对 linkis.properties、linkis-env.sh 是否有新配置项。

六、常见问题（FAQ）

6.1 网关报 `Cannot load driver class: com.mysql.jdbc.Driver`

镜像内未安装 JDBC 驱动或只放了一个目录。官方做法是同时放入 /opt/linkis/lib/linkis-commons/public-module/ 与 /opt/linkis/lib/linkis-spring-cloud-services/linkis-mg-gateway/，或使用 linkis-with-mysql-jdbc.Dockerfile 构建的 linkis:with-jdbc 镜像。

6.2 Linkis 容器启动后部分服务退出

检查 depends_on 是否使用 condition: service_healthy，MySQL 未就绪时 Linkis 各服务会因数据库连接失败退出；
单机内存不足时 6 个 JVM 同时启动会触发 OOM，可将 mem_limit 提升到 6g 以上，或参照《Ubuntu 22.04 安装 Apache Linkis 指南》9.7 节压缩 JVM 堆与元内存参数。

6.3 容器间无法通过服务名访问

Linkis 默认以主机名注册（linkis.discovery.prefer-ip-address=false），compose 中必须为 linkis 服务设置固定 hostname: linkis，且 linkis.discovery.server-address 指向 http://linkis:20303/eureka/；跨主机部署需保证服务名可解析或改用 IP 注册。

6.4 任务报 `file://file:///tmp/linkis` 双前缀错误

与裸机安装相同，把 linkis.properties 的 wds.linkis.bml.local.prefix 改为 /tmp/linkis（去掉 file:// 前缀）后重启 publicservice 与 manager。

6.5 Web 控制台如何部署

Linkis 前端（Scriptis 管理台）是独立镜像/独立构建产物：官方 linkis.Dockerfile 使用 nginx:1.19.6 作为 linkis-web 阶段，产物目录为 apache-linkis-web-<版本>-dist/dist。可在 compose 中追加一个 nginx 服务，把 dist 挂载为静态站点，并将后端代理地址指向 linkis 服务的 9001 端口。

6.6 数据持久化范围

需要持久化的三块：MySQL 数据卷（元数据）、/etc/linkis-conf（配置）、/tmp/linkis（结果集与工作目录）。日志卷按需保留。docker compose down 不会删除命名卷，down -v 会。

Apache Linkis Docker Compose 部署指南

Apache Linkis Docker Compose 部署指南

一、官方镜像选型

1.1 镜像获取的两种方式

1.2 官方镜像的关键约定

1.3 自建含 JDBC 驱动的镜像

二、Docker Compose 编排

2.1 编排设计

2.2 compose.yaml

2.3 数据库初始化脚本

2.4 渲染 Linkis 配置

三、启动与验证

3.1 启动

3.2 验证网关登录

3.3 提交任务验证

四、等价 docker run 命令

五、日常运维

5.1 启停与状态

5.2 日志排查

5.3 备份与恢复

5.4 版本升级

六、常见问题（FAQ）

6.1 网关报 Cannot load driver class: com.mysql.jdbc.Driver

6.2 Linkis 容器启动后部分服务退出

6.3 容器间无法通过服务名访问

6.4 任务报 file://file:///tmp/linkis 双前缀错误

6.5 Web 控制台如何部署

6.6 数据持久化范围

6.1 网关报 `Cannot load driver class: com.mysql.jdbc.Driver`

6.4 任务报 `file://file:///tmp/linkis` 双前缀错误