Apache Texera 1.2.0-incubating 快速入门与集成示例

在 Ubuntu 22.04 上实测 Apache Texera 1.2.0-incubating 的完整闭环：源码构建、PostgreSQL 初始化、jOOQ 代码生成、前后端构建、stage 打包、服务启动与核心 API 验证，并给出示例工作流集成要点

Apache TexeraApache Texera2026/10/15

Apache Texera 1.2.0-incubating 快速入门与集成示例

目标：从零完成一次 Texera 源码构建、数据库初始化、前后端编译打包、服务启动到 API 验证的完整闭环，并用官方示例工作流讲清集成要点。已在 Ubuntu 22.04.5 LTS（x86_64）+ OpenJDK 17.0.20.1 + sbt 1.12.9 + PostgreSQL 14 环境实测通过，文中全部命令与回显均来自真实执行。

一、环境信息

  • 操作系统：Ubuntu 22.04.5 LTS（PRETTY_NAME="Ubuntu 22.04.5 LTS"）
  • 架构：x86_64
  • JDK：OpenJDK 17.0.20.1（apt 包 openjdk-17-jdk）
  • 构建工具：sbt 1.12.9（sbt-launch 方式安装，Scala 2.13.18 编译）
  • Node.js：v24.10.0（官方 tarball 安装，前端要求 node>=24）
  • 包管理器：yarn 4.14.1（corepack 激活，对应 frontend/package.json 的 packageManager 声明）
  • 数据库：PostgreSQL 14（apt 包 postgresql）
  • 组件版本：Texera v1.2.0-incubating（commit c3aa6e4ba36bdd0cdc9f76bd7896c024dda392b3）
  • 实测工作目录：/work/texera-ub（源码树）

系统确认（实时回显）：

cat /etc/os-release | head -2

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

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)

二、获取源码与前置依赖

2.1 获取指定版本源码

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

2.2 前置依赖就位确认

JDK 17 由 apt 提供（apt-get install -y openjdk-17-jdk）；Node 24 从官方 tarball 解压到 /opt/node24：

export PATH=/opt/node24/bin:$PATH
node -v

v24.10.0

sbt 采用 sbt-launch 运行（/usr/local/bin/sbt-launch.jar 下载 1.12.9 版后，用包装脚本固定 JVM 内存）：

ls -la /usr/local/bin/sbt-launch.jar

-rw-r--r-- 1 root root 3823001 Oct 15 12:39 /usr/local/bin/sbt-launch.jar

💡 技术拓展：同类数据科学平台的本地起步通常二选一——JupyterHub 以 pip/hub 镜像起步、Apache Zeppelin 以 bin 包起步，而 Texera 官方推荐形态是源码构建或编排模板部署；本文以源码构建为主线，能完整走通「编译→初始化→启动」每一步，便于理解各组件耦合关系。

三、初始化 PostgreSQL 与数据库 DDL

3.1 安装并启动 PostgreSQL 14

DEBIAN_FRONTEND=noninteractive apt-get install -y postgresql

Setting up postgresql (14+238) ...

Ubuntu 22.04 的 apt 源提供 PostgreSQL 14。以集群方式启动（实测回显）：

pg_ctlcluster 14 main start
echo $?

0

设置超级用户口令（后续配置文件默认口令即 postgres）：

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

ALTER ROLE

3.2 执行官方 DDL

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

实测退出码为 0，日志中 CREATE TABLE 共 28 条（用户、工作流、项目、执行、配额等表），并伴随 2 条与 pgroonga 扩展相关的 ERROR（详见第九章 9.1，不影响建表）。再初始化 Iceberg 结果目录：

su postgres -c "psql -f sql/iceberg_postgres_catalog.sql"
echo $?

0

3.3 验证数据库就绪

su postgres -c "psql -c '\dt texera_db.*' | head -8"

联库信息在 common/config/src/main/resources/storage.conf 第 138 行：

url = "jdbc:postgresql://localhost:5432/texera_db?currentSchema=texera_db,public"

四、jOOQ 代码生成与后端编译

4.1 生成 jOOQ 代码（编译的前置步骤）

sbt "DAO/jooqGenerate"

[info] Generating JOOQ classes...
[info] JOOQ code generation completed successfully
[success] Total time: 3 s, completed Oct 15, 2026, 12:56:07 PM

⚠️ 注意：这一步必须在 3.2 的 DDL 之后执行——它连接 texera_db 反向生成代码；同时不能只看 sbt 退出码，数据库不可达时该任务会打 [warn] JOOQ code generation failed: Connection to localhost:5432 refused 但退出码仍为 0。缺了这一步直接编译，实测会集中报 27 个 object jooq is not a member of package org.apache.texera.dao 错误。

4.2 后端全量编译

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

编译期若日志出现 [warn] protoc or protoc-gen-python_betterproto not found on PATH; skipping Python proto generation.，属正常告警，不影响 Java/Scala 编译与服务启动。

五、前端依赖安装与构建

5.1 激活 yarn 4.14.1

frontend/package.json 声明 packageManager: yarn@4.14.1 与 engines.node >= 24.0.0，用 corepack 对齐版本（Node 24 tarball 解压后先 corepack enable，如无 corepack 可 npm i -g corepack）：

corepack enable && corepack prepare yarn@4.14.1 --activate

5.2 安装依赖

cd frontend && yarn install

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

5.3 产物构建

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

实测产物 dist/ 共 39 MB，入口 index.html 18420 字节。构建脚本自带 --max-old-space-size=8192，内存偏小的机器需留意。

六、stage 打包与启动服务

6.1 打包 stage 产物

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

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

产物清单（实测 ls amber/target/universal/stage/bin/）：

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

6.2 启动 Web 服务

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

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

Registering FileAssetBundle with servlet name file-assets for request path /* from file system /work/texera-ub/amber/../../frontend/dist
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

约 5.5 秒完成启动：8080 为 API 端口，8081 为管理端口，同时出现 Started @5540ms 即代表 Jetty 就绪。完整单机执行还需按官方顺序另启 computing-unit-master（先）与 computing-unit-worker（后）。

七、核心 API 验证闭环

7.1 算子元数据

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

200

curl -s http://localhost:8080/api/resources/operator-metadata \
  | python3 -c "import sys,json; d=json.load(sys.stdin); print(len(d['operators']), d['operators'][0]['operatorType'])"

163 TwitterFullArchiveSearch

7.2 注册与登录

curl -s -w "\nHTTP=%{http_code}\n" -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"}
HTTP=200

JWT 载荷中 role 为 RESTRICTED（新用户默认角色）。同一用户重复注册实测返回：

{"code":406,"message":"Username exists already."}

登录接口 POST /api/auth/login（同样的 JSON 体）返回 200 与新签发的 accessToken。

7.3 健康检查与静态边界

curl -s http://localhost:8081/healthcheck

{"deadlocks":{"healthy":true}}

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

404

GET / 返回 404 属预期边界：stage 产物独立启动时，静态目录按启动位置相对推导（../../frontend/dist），不指向真实构建产物；GUI 页面需按仓库目录布局运行或由反向代理托管前端文件。所有 /api/* 接口不受影响。

八、示例工作流与集成要点

8.1 官方示例工作流

仓库内置示例位于 bin/single-node/examples/workflows/，如 [Example] Data Exploration on Movies Dataset.json。实测解析其顶层结构：

top keys: ['operators', 'operatorPositions', 'links', 'commentBoxes', 'settings']

其中一条真实连线展示了 CSV 读取→聚合→饼图的最小拓扑（同一文件节选）：

{"linkID": "3fba9036-949b-41e6-b1ac-809074e95b3d",
 "source": {"operatorID": "Aggregate-operator-41c3fbf6-...", "portID": "output-0"},
 "target": {"operatorID": "PieChart-operator-...", "portID": "input-0"}}

示例数据集在同目录 datasets/ 下，load-examples.sh 可将示例工作流批量导入平台。

8.2 与存储链路的集成要点

工作流结果的落库位置由 storage.conf 决定：元数据走 PostgreSQL texera_db；结果表走 Iceberg（默认 postgres catalog，指向 localhost:5432/texera_iceberg_catalog，即 3.2 初始化的第二个库）；数据集走 LakeFS + S3 协议对象存储（默认 localhost:8000 与 localhost:9000，示例密钥可直接用于本地验证）。所有配置项均可通过 STORAGE_ 前缀环境变量覆盖而无需改文件。

九、注意事项与常见问题

9.1 DDL 中 pgroonga 的 2 条 ERROR

texera_ddl.sql 会执行 CREATE EXTENSION IF NOT EXISTS pgroonga 及插件注册函数，系统未安装 groonga 系包时实测报 2 条 ERROR，但 28 张业务表全部建成（DDL_EXIT=0）。仅全文检索相关增强不可用；如需完整能力，须先安装 groonga/pgroonga 再重跑 DDL。

9.2 缺 jOOQ 生成代码的编译报错形态

实测（省略重复行）：

[error] /work/texera-ub/common/auth/src/main/scala/org/apache/texera/auth/JwtAuth.scala:23:30: object jooq is not a member of package org.apache.texera.dao
[error] import org.apache.texera.dao.jooq.generated.tables.pojos.User
[error] 27 errors found

处理方式：回到 4.1 重跑 DAO/jooqGenerate 后再编译。

9.3 apt 安装 PostgreSQL 卡在 tzdata

交互式安装时 tzdata 会等待时区选择，实测需以 DEBIAN_FRONTEND=noninteractive 前缀执行，或先 dpkg --configure -a 修复中断状态。

9.4 sbt 内存建议

全模块编译与 stage 打包在默认堆下偏紧，实测采用 java -Xms512m -Xmx4g 的 sbt 包装脚本顺利通过；前端构建脚本自带 8GB 旧生代上限，2GB 内存机器不宜尝试。

9.5 stage 启动后的静态 404

见 7.3。判别方法：/api/* 返回 200 而页面 404 即为此边界，并非服务故障。

十、参考链接

  • Apache Texera 官网：https://texera.apache.org/
  • 源码仓库：https://github.com/apache/texera（tag v1.2.0-incubating）
  • 官方发行包目录：https://downloads.apache.org/incubator/texera/1.2.0-incubating/
  • 官方安装文档：仓库内 docs/getting-started/install-texera.md
  • 开发者指南：仓库内 docs/contribution-guidelines/guide-for-developers.md
  • 存储配置：仓库内 common/config/src/main/resources/storage.conf
  • Apache 软件基金会孵化器声明：https://incubator.apache.org/