Ubuntu 22.04 安装 Apache Texera 指南

在 Ubuntu 22.04 上从零安装 Apache Texera 1.2.0-incubating，覆盖源码构建全链路（JDK 17、Node 24、sbt、PostgreSQL、jOOQ、前后端编译打包）与官方发行包校验两种方案，命令与回显均实测通过

Apache TexeraApache Texera2026/10/15

Ubuntu 22.04 安装 Apache Texera 指南

目标：在 Ubuntu 22.04 上从零搭建 Apache Texera 1.2.0-incubating 的运行环境，走通「源码构建 → 数据库初始化 → stage 打包 → 服务启动 → API 验证」全链路，并给出官方发行包部署方案。本文全部命令与回显均已在 Ubuntu 22.04.5 LTS 实测通过。

Texera 是 Apache 孵化器中的可协作数据分析平台：前端（Angular 21）负责工作流编辑与可视化，后端由多个 Scala 服务组成，执行核心是 amber 引擎。官方安装文档仅提供编排模板与 Kubernetes 两种方式；对需要理解内部结构或无法使用编排环境的读者，源码构建是唯一完整路径——本文以源码构建为方案 A（推荐），官方 src 发行包为方案 B，两者均实测。

一、环境信息

本节固定可复现的基线环境，后续命令均在此环境执行：

  • 操作系统：Ubuntu 22.04.5 LTS
  • 架构：x86_64
  • JDK：OpenJDK 17.0.20.1（apt 包 openjdk-17-jdk）
  • Node.js：v24.10.0（官方 tarball，前端要求 node>=24）
  • 构建工具：sbt 1.12.9（sbt-launch 方式）
  • 数据库：PostgreSQL 14（apt 包 postgresql）
  • 组件版本：Apache Texera 1.2.0-incubating
  • 实测目录：/work/texera-ub（源码树）、/opt/texera-pkg（发行包）

系统与关键组件确认（实时回显）：

cat /etc/os-release | head -2

PRETTY_NAME="Ubuntu 22.04.5 LTS"
NAME="Ubuntu"

uname -m

x86_64

💡 说明：Texera 不是单一 jar 而是一个多服务工程，安装的判定标准是「数据库就绪 + 后端服务启动 + 元数据接口可用」三件事同时成立，而不是某个包解压完成。

二、前置条件

  1. 具有 root 或 sudo 权限的 Ubuntu 22.04 系统。
  2. 可访问 Ubuntu 软件源（apt 安装 JDK/PostgreSQL）。
  3. 可访问 GitHub（源码克隆）与 Apache 下载站 downloads.apache.org（发行包）。
  4. 磁盘空间建议 6 GB 以上：实测源码树加依赖缓存约 3.1 GB（源码树 2.4 GB + coursier 缓存 674 MB），前端 node_modules 另占约 840 MB。
  5. 内存建议 8 GB：sbt 编译实测堆峰值较高（本文用 -Xmx4g），前端构建脚本自带 8 GB 旧生代上限。

网络连通性确认（实时回显）：

curl -sI --max-time 20 https://downloads.apache.org/incubator/texera/ | head -2

HTTP/1.1 200 OK
Date: Thu, 15 Oct 2026 13:12:40 GMT

curl -sI --max-time 20 https://nodejs.org/dist/v24.10.0/ | head -1

HTTP/2 200

三、版本选型说明

Texera 目前处于 Apache 孵化阶段，版本以 x.y.z-incubating 命名。实测 git ls-remote --tags 的最新 12 个 tag（按版本排序）：

v1.1.0-incubating-rc3
v1.1.0-incubating-rc4
v1.1.0-incubating-rc5
v1.1.0-incubating-rc6
v1.1.0-incubating-rc7
v1.1.0-incubating-rc8
v1.2.0-incubating
v1.2.0-incubating-rc1
v1.2.0-incubating-rc2
v1.2.0-incubating-rc3
v1.2.0-incubating-rc4
v1.2.1-incubating-rc1
类别tag 形态是否可用
候选版本*-rcN供投票评审，不建议生产使用
正式版本v1.2.0-incubating、v1.1.0-incubating官方发布并同步到下载站
历史版本0.1.0、1.0.0项目进入 Apache 前的旧谱系

官方下载站 https://downloads.apache.org/incubator/texera/ 当前提供 1.1.0-incubating 与 1.2.0-incubating 两个正式版目录；1.2.1 仅有 rc1、尚无正式版。本文实际采用 v1.2.0-incubating（commit c3aa6e4ba36bdd0cdc9f76bd7896c024dda392b3），理由：它是官方下载站的最新正式版，且本文方案 A/B 均针对该版本实测。

四、方案 A：源码构建安装（在线，推荐）

4.1 方案说明

链路为：安装 JDK 17 与 PostgreSQL → 安装 Node 24 与 sbt → 克隆源码并检出 v1.2.0-incubating → 初始化数据库并生成 jOOQ 代码 → 后端编译、前端构建 → stage 打包 → 启动验证。优点是全链路可控、便于阅读源码与二次开发；缺点是首次构建需下载约 1 GB 依赖。

4.2 安装 JDK 17

apt-get update -qq && DEBIAN_FRONTEND=noninteractive apt-get install -y openjdk-17-jdk

# 输出节选（实测）
Unpacking openjdk-17-jdk:amd64 (17.0.20.1+1-1~22.04) ...

确认版本：

java -version

openjdk version "17.0.20.1" 2026-08-18
OpenJDK Runtime Environment (build 17.0.20.1+1-1-22.04-Ubuntu)
OpenJDK 64-Bit Server VM (build 17.0.20.1+1-1-22.04-Ubuntu, mixed mode, sharing)

验证点：版本输出 17.0.x 即可。Texera 1.2.0 的 Scala 2.13 工具链按 JDK 17 验证，勿使用 JDK 11。

4.3 安装 Node.js 24

前端要求 node>=24（frontend/package.json 的 engines 字段），apt 源没有 24 版本，用官方 tarball：

curl -sL -o /tmp/node24.tar.xz https://nodejs.org/dist/v24.10.0/node-v24.10.0-linux-x64.tar.xz
mkdir -p /opt/node24
tar xJf /tmp/node24.tar.xz -C /opt/node24 --strip-components=1
export PATH=/opt/node24/bin:$PATH
node -v

v24.10.0

建议把 export PATH=/opt/node24/bin:$PATH 写入 /root/.bashrc，否则新终端会找不到 node。

4.4 安装 sbt

sbt 通过 sbt-launch 运行。下载 1.12.9 的启动 jar 并建立包装脚本（固定堆内存，避免默认堆过小导致编译失败）：

curl -sL -o /usr/local/bin/sbt-launch.jar \
  https://repo1.maven.org/maven2/org/scala-sbt/sbt-launch/1.12.9/sbt-launch-1.12.9.jar
cat > /usr/local/bin/sbt <<'EOF'
#!/bin/bash
exec java -Xmx4g -jar /usr/local/bin/sbt-launch.jar "$@"
EOF
chmod +x /usr/local/bin/sbt

实测环境走代理下载依赖，包装脚本中实际还带了 -Dhttp.proxyHost=192.168.1.62 -Dhttp.proxyPort=7897 -Dhttps.proxyHost=192.168.1.62 -Dhttps.proxyPort=7897 三个 JVM 代理参数；直连网络的环境按上面写法即可，需代理的环境自行补上。

💡 技术拓展：多模块 Scala 工程的构建工具目前主要是 sbt 与 Maven——Texera 全仓采用 sbt（根 build.sbt 声明 12 个子模块与 1 个根工程），Maven 无法直接替代；若团队统一使用 Maven，建议仅将 sbt 局限在本工程内使用，不要混装全局配置。

4.5 安装并初始化 PostgreSQL

DEBIAN_FRONTEND=noninteractive apt-get install -y postgresql
pg_ctlcluster 14 main start
echo $?

0

su postgres -c "psql -c \"ALTER USER postgres PASSWORD 'postgres';\""

ALTER ROLE

⚠️ 注意：apt 安装 PostgreSQL 时若不加 DEBIAN_FRONTEND=noninteractive，tzdata 配置脚本会等待交互输入导致安装卡住；若已卡住，先 dpkg --configure -a 修复再重装。

4.6 克隆源码并初始化数据库

git clone https://github.com/apache/texera.git texera-ub
cd texera-ub && git checkout v1.2.0-incubating
git describe --tags

v1.2.0-incubating

执行官方 DDL（28 张业务表 + Iceberg 结果目录库）：

su postgres -c "psql -v ON_ERROR_STOP=0 -f sql/texera_ddl.sql"
echo $?
su postgres -c "psql -f sql/iceberg_postgres_catalog.sql"
echo $?

0
0

DDL 日志中会出现 2 条与 pgroonga 扩展相关的 ERROR，28 张表正常建成（详见第九章 9.1）。

4.7 jOOQ 代码生成与后端编译

sbt "DAO/jooqGenerate"

[info] Generating JOOQ classes...
[info] JOOQ code generation completed successfully
[success] Total time: 3 s

sbt compile

[info] compiling 258 Scala sources and 50 Java sources to /work/texera-ub/common/workflow-operator/target/scala-2.13/classes ...
[info] done compiling
[success] Total time: 72 s (0:01:12.0), completed Oct 15, 2026, 12:57:28 PM

验证点：两个命令均为 [success]。若 DAO/jooqGenerate 日志出现 Connection to localhost:5432 refused，说明数据库未就绪；若跳过本步直接编译，会报 27 个 object jooq is not a member of package org.apache.texera.dao 错误。

4.8 前端构建

export PATH=/opt/node24/bin:$PATH
corepack enable && corepack prepare yarn@4.14.1 --activate
cd frontend
yarn install

➤ YN0013: │ 1565 packages were added to the project (+ 839.42 MiB).
➤ YN0000: └ Completed in 2m 19s

yarn run build

build-version: 1.2.0-incubating.261015390

Initial chunk files           | Names                                                    |  Raw size | Estimated transfer size
main.4c0dbd0f67bc5759.js      | main                                                     |  13.19 MB |                 2.79 MB
styles.0d6ec57d5eb92aca.css   | styles                                                   | 678.37 kB |                89.85 kB
...
                              | Initial total                                            |  13.95 MB |                 2.90 MB

产物为 frontend/dist/（实测 39 MB，入口 index.html 18420 字节）。

4.9 stage 打包

cd /work/texera-ub && sbt "WorkflowExecutionService/stage"

[success] Total time: 53 s, completed Oct 15, 2026, 12:58:29 PM

产物位于 amber/target/universal/stage/，bin/ 下有 4 个 Linux 启动脚本（另有 .bat 为 Windows 用）：

amber
computing-unit-master
computing-unit-worker
texera-web-application

4.10 启动与最小验证

cd /work/texera-ub/amber
target/universal/stage/bin/texera-web-application -J-Xmx512m

启动日志关键行（实测节选）：

texera-hikari - Start completed.
Starting TexeraWebApplication
Started application@6fefc5ea{HTTP/1.1,[http/1.1]}{0.0.0.0:8080}
Started admin@6159fb3c{HTTP/1.1,[http/1.1]}{0.0.0.0:8081}
Started @5540ms

另开终端验证（实测回显）：

curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8080/api/resources/operator-metadata

200

curl -s -X POST -H "Content-Type: application/json" \
  -d '{"username":"ub_admin","password":"q1w2e3r4"}' \
  http://localhost:8080/api/auth/register

{"accessToken":"eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ1Yl9hZG1pbiIsInVzZXJJZCI6MiwiZ29vZ2xlSWQiOm51bGwsImVtYWlsIjoidWJfYWRtaW4iLCJyb2xlIjoiUkVTVFJJQ1RFRCIsImdvb2dsZUF2YXRhciI6bnVsbCwiZXhwIjoxNzkyNjc1NzYzfQ.PWj-AIdWqCxHivCoQFJ5Sut4R6-TXzrLWaKM1VzU9Rc"}

验证点：元数据接口 200、注册接口返回 accessToken 即安装成功。完整单机执行还需再启 computing-unit-master（先）与 computing-unit-worker（后）。

五、方案 B：官方发行包部署

5.1 方案说明

Apache 官方为 1.2.0-incubating 发布了源码包 apache-texera-1.2.0-incubating-src.tar.gz（约 25.5 MB）及配套 .sha512、.asc 校验件。发行包内容与 GitHub 源码树一致但没有 .git 目录，适合无法克隆 Git 仓库的网络环境；下载后仍需按 4.5-4.10 完成数据库与编译步骤。

5.2 下载与完整性校验

mkdir -p /opt/texera-pkg && cd /opt/texera-pkg
P=https://downloads.apache.org/incubator/texera/1.2.0-incubating
curl -sL -O $P/apache-texera-1.2.0-incubating-src.tar.gz
curl -sL -O $P/apache-texera-1.2.0-incubating-src.tar.gz.sha512
curl -sL -O $P/apache-texera-1.2.0-incubating-src.tar.gz.asc
curl -sL -O https://downloads.apache.org/incubator/texera/KEYS

先做 SHA-512 校验（实测回显）：

sha512sum -c apache-texera-1.2.0-incubating-src.tar.gz.sha512

apache-texera-1.2.0-incubating-src.tar.gz: OK

再导入官方 KEYS 并验签（实测回显）：

gpg --import KEYS

gpg:               imported: 3
gpg:         new signatures: 1

gpg --verify apache-texera-1.2.0-incubating-src.tar.gz.asc apache-texera-1.2.0-incubating-src.tar.gz

gpg:                using RSA key 36B1DAC3286B3199B4CEFC2BB49658187ADCD1BD
gpg: Good signature from "Xuan Gu (CODE SIGNING KEY) <xuangu@apache.org>" [unknown]
Primary key fingerprint: FF17 8695 C2B3 8EC0 BB8F  4C49 33CC 8C5B 60E4 6FA4

Good signature 即验签通过；[unknown] 与 not certified 警告是因为导入的公钥未经本地信任链签署，属正常现象，核对主钥指纹与官方 KEYS 中登记一致即可。

5.3 解压与后续步骤

tar xzf apache-texera-1.2.0-incubating-src.tar.gz
cd apache-texera-1.2.0-incubating-src

# 解压后顶层内容（实测前 8 项）
AGENTS.md
CLAUDE.md
CONTRIBUTING.md
DISCLAIMER
LICENSE
NOTICE
README.md

随后按 4.5 节初始化数据库，并以该目录为源码树执行 4.7-4.10 的编译、打包与启动（命令完全一致）。

六、方案对比

维度方案 A：源码构建（Git）方案 B：官方发行包
版本准确性tag 检出，含完整 git 历史与发布评审内容逐字节一致（sha512 + gpg 双校验）
网络要求需访问 GitHub只需访问 downloads.apache.org
体积克隆约 600 MB 级仓库25.5 MB 压缩包
后续编译需要（4.7-4.9）同样需要
适用场景开发调试、阅读源码、二次开发网络受限环境、合规审计要求可追溯签名

两个方案最终都落到同一套编译与启动流程，运行期行为一致；生产部署的长期升级建议固定在正式 tag 或发行包上。

七、基础配置

7.1 服务端口

后端端口定义在 amber/src/main/resources/web-config.yml：8080 为应用端口（REST API 与页面），8081 为管理端口（健康检查）。修改后需重新 stage 打包。

7.2 数据库与存储

common/config/src/main/resources/storage.conf 是存储配置中枢：

  • 主库：jdbc:postgresql://localhost:5432/texera_db?currentSchema=texera_db,public（默认账号 postgres/postgres，与 4.5 设置一致）；
  • 工作流结果：Iceberg catalog 默认 postgres 类型，指向 localhost:5432/texera_iceberg_catalog；
  • 数据集：LakeFS 默认 http://localhost:8000/api/v1，S3 协议对象存储默认 http://localhost:9000。

7.3 环境变量覆盖

storage.conf 每一项均带 ${?STORAGE_...} 回退声明，例如 type = ${?STORAGE_ICEBERG_CATALOG_TYPE}。不改文件、仅注入 STORAGE_ 前缀环境变量即可覆盖任意配置，这是多环境部署的推荐方式。

7.4 日志位置

web-config.yml 同时定义请求日志 logs/access.log（按天滚动保留 7 份）与应用日志 logs/amber-server.log，均相对服务启动目录生成。

八、验证清单

按顺序逐项打钩，全部通过即安装完成：

  1. pg_ctlcluster 14 main status 输出 online（PostgreSQL 就绪）。
  2. sbt "DAO/jooqGenerate" 日志含 JOOQ code generation completed successfully。
  3. sbt compile 与 sbt "WorkflowExecutionService/stage" 均 [success]。
  4. yarn run build 产出 frontend/dist/index.html（实测 18420 字节）。
  5. texera-web-application -J-Xmx512m 日志出现 Started @xxxxms。
  6. curl http://localhost:8080/api/resources/operator-metadata 返回 200 与 163 个算子。
  7. 注册接口返回 accessToken，curl http://localhost:8081/healthcheck 返回 {"deadlocks":{"healthy":true}}。
  8. （完整单机执行）computing-unit-master 先启动、computing-unit-worker 后启动。

九、常见问题（FAQ）

9.1 DDL 报 pgroonga 相关 ERROR

实测 DDL 日志含 2 条 ERROR，源自 CREATE EXTENSION IF NOT EXISTS pgroonga 与插件注册函数——Ubuntu 源默认没有 pgroonga 包。28 张业务表不受影响，仅中文全文检索增强缺失。需要该能力时先安装 groonga/pgroonga 再重跑 DDL。

9.2 编译报 27 个 jooq 错误

[error] object jooq is not a member of package org.apache.texera.dao
[error] 27 errors found

原因：跳过了 DAO/jooqGenerate 或数据库不可达时生成失败。注意该 sbt 任务失败时退出码仍可能为 0，必须看日志。处理：确认 PostgreSQL 运行且 DDL 已执行，重跑 sbt "DAO/jooqGenerate"。

9.3 GET / 返回 404 但 API 正常

stage 独立启动时，静态资源目录按启动位置相对推导（../../frontend/dist），不指向真实构建产物，页面 404 而 /api/* 一切正常。解决：保持源码树目录布局运行，或由反向代理托管 frontend/dist。

9.4 启动日志中的 jgit 堆栈

RepositoryNotFoundException: repository not found: .../amber 来自算子版本号读取（尝试定位 git 仓库），被捕获后服务照常启动，可忽略；在仓库根目录启动可消除。

9.5 sbt 编译内存不足

默认堆下编译易被 OOM 终止，实测采用 4.4 节的 -Xms512m -Xmx4g 包装脚本可稳定完成编译与 stage；内存不足 8 GB 的机器建议关闭前端构建并行执行。

9.6 apt 安装 PostgreSQL 卡住

tzdata 交互等待所致，按 4.5 节加 DEBIAN_FRONTEND=noninteractive，中断后用 dpkg --configure -a 修复。

十、卸载与清理

# 停服务
pkill -f texera-web-application
pg_ctlcluster 14 main stop
# 删除数据库（如不再需要）
su postgres -c "psql -c 'DROP DATABASE IF EXISTS texera_db;'"
su postgres -c "psql -c 'DROP DATABASE IF EXISTS texera_iceberg_catalog;'"
# 删除源码与依赖缓存
rm -rf /work/texera-ub /root/.cache/coursier /root/.sbt /opt/texera-pkg
# 卸载系统包（可选）
DEBIAN_FRONTEND=noninteractive apt-get purge -y openjdk-17-jdk postgresql
apt-get autoremove -y

以上命令是本文各安装步骤的逆操作（停止服务 → 删库 → 删文件 → 卸载系统包）。rm -rf 的四个路径即本文创建的全部落盘内容（源码树 2.4 GB、coursier 缓存 674 MB、sbt 目录 74 MB、发行包 25.5 MB）。执行后系统回到安装前状态。

十一、参考链接

  • Apache Texera 官网：https://texera.apache.org/
  • 源码仓库：https://github.com/apache/texera
  • 官方发行包目录：https://downloads.apache.org/incubator/texera/1.2.0-incubating/
  • 官方 KEYS：https://downloads.apache.org/incubator/texera/KEYS
  • 官方安装文档：仓库内 docs/getting-started/install-texera.md
  • 开发者指南：仓库内 docs/contribution-guidelines/guide-for-developers.md
  • Node.js 下载：https://nodejs.org/dist/v24.10.0/
  • sbt-launch（Maven 坐标）：org.scala-sbt:sbt-launch:1.12.9
  • Apache 软件基金会孵化器声明：https://incubator.apache.org/