This is an automated email from the ASF dual-hosted git repository.
dybyte pushed a commit to branch dev
in repository https://gitbox.apache.org/repos/asf/seatunnel.git
The following commit(s) were added to refs/heads/dev by this push:
new c983db51b0 [Docs] Clarify Zeta REST API and Web UI docs (#11578)
c983db51b0 is described below
commit c983db51b0744e9007d556958c7abc4f3f42e617
Author: David Zollo <[email protected]>
AuthorDate: Thu Jul 30 01:16:14 2026 +0800
[Docs] Clarify Zeta REST API and Web UI docs (#11578)
Co-authored-by: danielnadean
<[email protected]>
---
docs/en/engines/zeta/about.md | 2 +-
docs/en/engines/zeta/busyness-and-backpressure.md | 2 +-
docs/en/engines/zeta/rest-api-and-web-ui.md | 81 ++++++++++++----------
docs/en/engines/zeta/web-ui.md | 58 +++++++++++++---
docs/en/getting-started/overview.md | 2 +-
docs/sidebars.js | 21 ++++--
docs/zh/architecture/cdc-pipeline-architecture.md | 2 +-
.../plugin-discovery-and-class-loading.md | 2 +-
docs/zh/engines/zeta/rest-api-and-web-ui.md | 75 +++++++++++---------
docs/zh/engines/zeta/web-ui.md | 55 ++++++++++++---
10 files changed, 200 insertions(+), 100 deletions(-)
diff --git a/docs/en/engines/zeta/about.md b/docs/en/engines/zeta/about.md
index cfd19a4272..586b6cdc5c 100644
--- a/docs/en/engines/zeta/about.md
+++ b/docs/en/engines/zeta/about.md
@@ -62,7 +62,7 @@ If you are starting from zero, read these pages in order:
2. [Download & Install](download-seatunnel.md)
3. [Quick Start With SeaTunnel
Engine](../../getting-started/locally/quick-start-seatunnel-engine.md)
4. [Job Configuration Guide](../../getting-started/job-configuration-guide.md)
-5. [REST API And Web UI](rest-api-and-web-ui.md)
+5. [REST API and Web UI](rest-api-and-web-ui.md)
If you want to understand the internals after your first successful run,
continue with:
diff --git a/docs/en/engines/zeta/busyness-and-backpressure.md
b/docs/en/engines/zeta/busyness-and-backpressure.md
index c1ca0ee978..0bc503ed0f 100644
--- a/docs/en/engines/zeta/busyness-and-backpressure.md
+++ b/docs/en/engines/zeta/busyness-and-backpressure.md
@@ -220,7 +220,7 @@ curl
"http://<master-host>:8080/metrics/realtime/jobs/<jobId>/vertices?windowMs=
## Related Documentation
-- [REST API And Web UI](./rest-api-and-web-ui.md)
+- [REST API and Web UI](./rest-api-and-web-ui.md)
- [Web UI](./web-ui.md)
- [RESTful API V2](./rest-api-v2.md)
- [Monitoring Metrics](./telemetry.md)
diff --git a/docs/en/engines/zeta/rest-api-and-web-ui.md
b/docs/en/engines/zeta/rest-api-and-web-ui.md
index 740f77df0e..eee5397909 100644
--- a/docs/en/engines/zeta/rest-api-and-web-ui.md
+++ b/docs/en/engines/zeta/rest-api-and-web-ui.md
@@ -2,37 +2,31 @@
sidebar_position: 1
---
-# REST API And Web UI
+# REST API and Web UI
-SeaTunnel Engine exposes two operational interfaces on top of the same HTTP
service:
+SeaTunnel Engine provides REST API and Web UI as the primary interfaces for
remote operations and visual monitoring. This page explains how the two
interfaces relate, how to enable the shared HTTP service, and where to find
detailed reference pages.
-- a **REST API** for programmatic integration, automation, and inspection
-- a **Web UI** for visual monitoring of jobs, workers, and master status
+## Which Page Should I Read?
-This page is the entry point for operators. Use it to understand when to
enable HTTP access, how the REST API and Web UI relate to each other, and where
to find the detailed references.
+| Need | Go to |
+|------|-------|
+| Enable the HTTP service, choose a port, or use `context-path` | This page,
then [RESTful API V2](./rest-api-v2.md) |
+| Build automation, scripts, an operations portal, or a platform integration |
[RESTful API V2](./rest-api-v2.md) |
+| Submit, stop, cancel, savepoint, or restore jobs through HTTP | [Job
Lifecycle API](./rest-api-job-lifecycle.md) |
+| Visually inspect cluster health, jobs, DAG metrics, and logs | [Web
UI](./web-ui.md) |
+| Configure HTTPS or HTTP Basic authentication | [Security](./security.md) |
+| Maintain an old Hazelcast REST client | [RESTful API V1](./rest-api-v1.md) |
-## When To Use This Page
+## How REST API and Web UI Fit Together
-Read this page if you need to:
+REST API and Web UI are not separate services. Both depend on the same
SeaTunnel Engine HTTP capability:
-- monitor running and finished jobs without using the CLI
-- integrate SeaTunnel Engine with an external platform or internal tooling
-- expose connector metadata to a UI or automation workflow
-- secure operational endpoints with basic authentication or HTTPS
+- **REST API** is the complete HTTP interface for automation and integration.
It covers metadata discovery, job submission, job status, job lifecycle
operations, logs, checkpoints, worker information, and realtime metrics.
+- **Web UI** is the built-in visual console. It is optimized for human
inspection of overview data, running and finished jobs, job details, DAG
metrics, logs, worker status, and master status.
-## How The Two Interfaces Fit Together
+Use the Web UI when you need a quick operational view. Use REST API or the
command line when you need lifecycle control such as job submission, stop,
cancel, savepoint, restore, or batch automation.
-The REST API and Web UI are not separate products. They are two interfaces
built on the same HTTP capability of SeaTunnel Engine:
-
-- the REST API is designed for scripts, automation, and system integration
-- the Web UI is designed for visual inspection and day-to-day operations
-
-In practice, many production environments use both:
-
-- external systems call REST endpoints
-- operators troubleshoot and observe jobs through the Web UI
-
-## Enable HTTP Access
+## Enable the HTTP Service
Before using either interface, enable the HTTP service in `seatunnel.yaml`:
@@ -42,11 +36,9 @@ seatunnel:
http:
enable-http: true
port: 8080
- enable-dynamic-port: true
- port-range: 100
```
-Optional settings you may care about early:
+Optional settings commonly used in production:
- `context-path`: prefix all HTTP endpoints under a custom path
- `enable-dynamic-port`: scan for an available port when the configured one is
occupied
@@ -55,7 +47,7 @@ Optional settings you may care about early:
For the full REST parameter details, see [RESTful API V2](./rest-api-v2.md).
For HTTPS and authentication, see [Security](./security.md).
-## Access The Web UI
+## Access the Web UI
Once HTTP is enabled, open:
@@ -63,15 +55,25 @@ Once HTTP is enabled, open:
http://<host>:<port>/#/overview
```
-The Web UI helps you inspect:
+If `context-path` is configured, put the UI route under that prefix:
-- cluster overview
-- running jobs
-- finished jobs
-- worker health and resource usage
-- master status
+```text
+http://<host>:<port>/<context-path>/#/overview
+```
-See the detailed walkthrough in [Web UI](./web-ui.md).
+## Current Web UI Capabilities
+
+The current Web UI is an inspection console. It provides:
+
+| Area | What you can do |
+|------|-----------------|
+| Overview | View project version, cluster slots, worker count, and job counts
|
+| Jobs | Browse running and finished jobs with pagination and open a job
detail page |
+| Job Detail | Inspect job configuration, DAG, source and sink metrics, job
logs, and realtime observability data when enabled |
+| Workers | View worker-node system monitoring information |
+| Master | View master-node system monitoring information |
+
+See the screen-level walkthrough in [Web UI](./web-ui.md).
## Common REST API Scenarios
@@ -85,6 +87,7 @@ The REST API is commonly used for:
The most commonly referenced pages are:
- [RESTful API V2](./rest-api-v2.md)
+- [Job Lifecycle API](./rest-api-job-lifecycle.md)
- [RESTful API V1](./rest-api-v1.md)
If you are building new integrations, prefer **V2** unless you have to
maintain compatibility with an older client.
@@ -101,17 +104,23 @@ If you are building new integrations, prefer **V2**
unless you have to maintain
- query overview and running jobs endpoints
- confirm that the service is reachable from your operational environment
-### 3. Open the Web UI
+### 3. Open Web UI
- use the UI to verify cluster health and inspect job details
-### 4. Lock down production access
+### 4. Use REST API for operational control
+
+- submit, stop, cancel, savepoint, and restore jobs through the lifecycle API
when automation is required
+- use the Web UI as the visual inspection layer during or after those
operations
+
+### 5. Lock down production access
- enable HTTPS and authentication when exposing the endpoints beyond a trusted
internal network
## Related Pages
- [RESTful API V2](./rest-api-v2.md)
+- [Job Lifecycle API](./rest-api-job-lifecycle.md)
- [RESTful API V1](./rest-api-v1.md)
- [Security](./security.md)
- [Web UI](./web-ui.md)
diff --git a/docs/en/engines/zeta/web-ui.md b/docs/en/engines/zeta/web-ui.md
index 877149be86..9ade5ea1f5 100644
--- a/docs/en/engines/zeta/web-ui.md
+++ b/docs/en/engines/zeta/web-ui.md
@@ -2,38 +2,70 @@
## Start Here
-Use [REST API And Web UI](./rest-api-and-web-ui.md) as the main operations
entry point. That page explains when to enable the HTTP service, which REST API
pages to read next, and how Web UI fits into day-to-day operations.
+Use [REST API and Web UI](./rest-api-and-web-ui.md) as the main operations
entry point. That page explains when to enable the HTTP service, which REST API
pages to read next, and how Web UI fits into day-to-day operations.
-This page focuses only on the Web UI screens themselves.
+This page focuses on the Web UI screens themselves and the current capability
boundary of the built-in console.
## Access
-Before accessing the web ui we need to enable the http rest api. first you
need to configure it in the `seatunnel.yaml` configuration file
+Before accessing Web UI, enable the SeaTunnel Engine HTTP service in
`seatunnel.yaml`:
-```
+```yaml
seatunnel:
engine:
http:
enable-http: true
port: 8080
+```
+Then visit:
+
+```text
+http://<host>:8080/#/overview
```
-Then visit `http://ip:8080/#/overview`
+If `context-path` is configured, include it before the hash route:
+
+```text
+http://<host>:8080/<context-path>/#/overview
+```
## Overview
-The Web UI of Apache SeaTunnel offers a user-friendly interface for monitoring
and managing SeaTunnel jobs. Through the Web UI, users can view real-time
information on currently running jobs, finished jobs, and the status of worker
and master nodes within the cluster. The main functional modules include Jobs,
Workers, and Master, each providing detailed status information and operational
options to help users efficiently manage and optimize their data processing
workflows.
+The Web UI of Apache SeaTunnel is a visual inspection console for SeaTunnel
Engine. It helps operators view cluster overview data, running and finished
jobs, job detail pages, logs, realtime DAG metrics, and the status of worker
and master nodes.
+
+## Capability Summary
+
+| UI area | Current capability |
+|---------|--------------------|
+| Overview | View cluster version, slot usage, worker count, and job counts |
+| Jobs | View running and finished jobs, paginate job lists, and open job
details |
+| Job Detail | View DAG, job metrics, exception text, job configuration, logs,
and realtime observability data |
+| Workers | View worker-node system monitoring information |
+| Master | View master-node system monitoring information |
+
## Jobs
### Running Jobs
-The "Running Jobs" section lists all SeaTunnel jobs that are currently in
execution. Users can view basic information for each job, including Job ID,
submission time, status, execution time, and more. By clicking on a specific
job, users can access detailed information such as task distribution, resource
utilization, and log outputs, allowing for real-time monitoring of job progress
and timely handling of potential issues.
+The "Running Jobs" section lists SeaTunnel jobs that are currently in
execution. Users can view job ID, job name, creation time, status, and open a
detail page for a specific job.
+
+The list refreshes periodically and supports pagination.
+
+### Job Detail
+
+The Job Detail page contains four main tabs:
+
+- **Overview**: shows the job DAG, source and sink throughput metrics,
flush-signal metrics, and realtime vertex or edge metrics when observability is
enabled.
+- **Exception**: shows the job error message when the job has failed or
reported an exception.
+- **Configuration**: shows the runtime job configuration exposed by the engine.
+- **Log**: shows job log files returned by the engine log API.
+
#### Realtime Observability
On the Job Detail page, the DAG view can display realtime metrics for the
recent window (3 minutes by default, up to 10 minutes):
@@ -46,25 +78,29 @@ This capability requires the job to enable
`env.engine.observability` or configu
### Finished Jobs
-The "Finished Jobs" section displays all SeaTunnel jobs that have either
successfully completed or failed. This section provides execution results,
completion times, durations, and failure reasons (if any) for each job. Users
can review past job records through this module to analyze job performance,
troubleshoot issues, or rerun specific jobs as needed.
+The "Finished Jobs" section displays jobs that have reached a terminal state,
such as finished, failed, cancelled, or savepoint done. Users can review
historical records and open the detail page to inspect configuration, exception
text, metrics retained by the engine, and logs.
+
## Workers
### Workers Information
-The "Workers" section displays detailed information about all worker nodes in
the cluster, including each worker's address, running status, CPU and memory
usage, number of tasks being executed, and more. Through this module, users can
monitor the health of each worker node, promptly identify and address resource
bottlenecks or node failures, ensuring the stable operation of the SeaTunnel
cluster.
+The "Workers" section displays system monitoring information for worker nodes.
Use it to inspect worker address, resource status, and runtime health signals
exposed by the engine.
+
## Master
### Master Information
-The "Master" section provides the status and configuration information of the
master node in the SeaTunnel cluster. Users can view the master's address,
running status, job scheduling responsibilities, and overall resource
allocation within the cluster. This module helps users gain a comprehensive
understanding of the cluster's core management components, facilitating cluster
configuration optimization and troubleshooting.
+The "Master" section displays system monitoring information for master nodes.
Use it to inspect the current master-side runtime state and resource signals
exposed by the engine.
+
## Next Steps
-- [REST API And Web UI](./rest-api-and-web-ui.md)
+- [REST API and Web UI](./rest-api-and-web-ui.md)
- [REST API V2](./rest-api-v2.md)
+- [Job Lifecycle API](./rest-api-job-lifecycle.md)
- [Security](./security.md)
diff --git a/docs/en/getting-started/overview.md
b/docs/en/getting-started/overview.md
index ba242ea2af..ceced1703b 100644
--- a/docs/en/getting-started/overview.md
+++ b/docs/en/getting-started/overview.md
@@ -80,5 +80,5 @@ Use these pages next:
- [Job Configuration Guide](./job-configuration-guide.md)
- [Scenario Recipes](./recipes/overview.md)
- [SeaTunnel Engine(Zeta) Deployment](../engines/zeta/deployment.md)
-- [REST API And Web UI](../engines/zeta/rest-api-and-web-ui.md)
+- [REST API and Web UI](../engines/zeta/rest-api-and-web-ui.md)
- [Submitting Jobs to a Remote Zeta
Cluster](../getting-started/submit-job-to-remote-zeta-cluster.md)
diff --git a/docs/sidebars.js b/docs/sidebars.js
index 1a51cd53c8..e28811444f 100644
--- a/docs/sidebars.js
+++ b/docs/sidebars.js
@@ -243,7 +243,6 @@ const sidebars = {
"engines/zeta/separated-cluster-deployment"
]
},
- "engines/zeta/rest-api-and-web-ui",
"getting-started/submit-job-to-remote-zeta-cluster",
"engines/zeta/checkpoint-storage",
"engines/zeta/state-storage-and-recovery",
@@ -253,11 +252,22 @@ const sidebars = {
"engines/zeta/resource-isolation",
{
"type": "category",
- "label": "REST API",
+ "label": "REST API and Web UI",
+ "link": {
+ "type": "doc",
+ "id": "engines/zeta/rest-api-and-web-ui"
+ },
"items": [
- "engines/zeta/rest-api-v1",
- "engines/zeta/rest-api-v2",
- "engines/zeta/rest-api-job-lifecycle",
+ {
+ "type": "category",
+ "label": "REST API",
+ "items": [
+ "engines/zeta/rest-api-v2",
+ "engines/zeta/rest-api-job-lifecycle",
+ "engines/zeta/rest-api-v1"
+ ]
+ },
+ "engines/zeta/web-ui",
"engines/zeta/security",
"engines/zeta/python-sdk"
]
@@ -266,7 +276,6 @@ const sidebars = {
"engines/zeta/logging",
"engines/zeta/telemetry",
"engines/zeta/busyness-and-backpressure",
- "engines/zeta/web-ui",
"engines/zeta/slot-allocation-strategy",
"engines/zeta/tuning-guide"
]
diff --git a/docs/zh/architecture/cdc-pipeline-architecture.md
b/docs/zh/architecture/cdc-pipeline-architecture.md
index c26a4fd46b..9415665e8f 100644
--- a/docs/zh/architecture/cdc-pipeline-architecture.md
+++ b/docs/zh/architecture/cdc-pipeline-architecture.md
@@ -217,7 +217,7 @@ CDC Pipeline 比 append-only batch 作业更敏感，常见运维关注点包括
相关文档：
-- [REST API and Web UI](../engines/zeta/rest-api-and-web-ui.md)
+- [REST API 与 Web UI](../engines/zeta/rest-api-and-web-ui.md)
- [插件发现与类加载](./plugin-discovery-and-class-loading.md)
- [Connector 依赖隔离加载机制](../connectors/connector-isolated-dependency.md)
diff --git a/docs/zh/architecture/plugin-discovery-and-class-loading.md
b/docs/zh/architecture/plugin-discovery-and-class-loading.md
index 4991cdf19c..28c182848d 100644
--- a/docs/zh/architecture/plugin-discovery-and-class-loading.md
+++ b/docs/zh/architecture/plugin-discovery-and-class-loading.md
@@ -146,7 +146,7 @@ SEATUNNEL_HOME/
相关文档：
- [配置与 Option 系统](./configuration-and-option-system.md)
-- [REST API and Web UI](../engines/zeta/rest-api-and-web-ui.md)
+- [REST API 与 Web UI](../engines/zeta/rest-api-and-web-ui.md)
## 常见失败模式
diff --git a/docs/zh/engines/zeta/rest-api-and-web-ui.md
b/docs/zh/engines/zeta/rest-api-and-web-ui.md
index b270fe2e2e..92130aeedf 100644
--- a/docs/zh/engines/zeta/rest-api-and-web-ui.md
+++ b/docs/zh/engines/zeta/rest-api-and-web-ui.md
@@ -4,35 +4,29 @@ sidebar_position: 1
# REST API 与 Web UI
-SeaTunnel Engine 在同一套 HTTP 服务之上提供了两类运维入口：
+SeaTunnel Engine 通过 REST API 和 Web UI 提供远程运维与可视化观测入口。本页说明两者的关系、如何开启共用的 HTTP
服务，以及下一步应该阅读哪些参考文档。
-- 面向程序调用、自动化和平台集成的 **REST API**
-- 面向人工排障与可视化观测的 **Web UI**
+## 应该先看哪一页
-这页是运维侧的统一入口。它的目标是帮助你先理解什么时候需要开启 HTTP 能力、REST API 和 Web UI
的关系是什么，以及接下来该去看哪一页详细文档。
-
-## 什么时候先看这页
-
-如果你有以下需求，建议先从本页开始：
-
-- 不依赖 CLI 查看运行中或已完成的作业
-- 把 SeaTunnel Engine 接入外部平台或内部运维系统
-- 为动态表单或自动化流程暴露连接器元数据
-- 用基础认证或 HTTPS 保护运维接口
+| 需求 | 阅读入口 |
+|------|----------|
+| 开启 HTTP 服务、选择端口或配置 `context-path` | 本页，然后阅读 [RESTful API
V2](./rest-api-v2.md) |
+| 构建自动化脚本、运维平台或系统集成 | [RESTful API V2](./rest-api-v2.md) |
+| 通过 HTTP 提交、停止、取消、savepoint 或恢复作业 | [作业生命周期 API](./rest-api-job-lifecycle.md)
|
+| 可视化查看集群健康、作业、DAG 指标和日志 | [Web UI](./web-ui.md) |
+| 配置 HTTPS 或 HTTP Basic 认证 | [安全配置](./security.md) |
+| 维护旧版 Hazelcast REST 客户端 | [RESTful API V1](./rest-api-v1.md) |
## REST API 与 Web UI 的关系
-REST API 和 Web UI 不是两套独立系统，而是构建在同一个 HTTP 能力之上的两种访问方式：
+REST API 和 Web UI 不是两套独立服务。它们都依赖 SeaTunnel Engine 的同一套 HTTP 能力：
-- REST API 面向脚本、自动化和系统集成
-- Web UI 面向人工巡检、排障和日常运维
+- **REST API** 是完整的 HTTP
接口，面向自动化和平台集成，覆盖元数据发现、作业提交、作业状态、生命周期操作、日志、checkpoint、worker 信息和实时指标。
+- **Web UI** 是内置可视化控制台，面向人工巡检，适合查看 overview、运行中和已完成作业、作业详情、DAG 指标、日志、worker
状态和 master 状态。
-在实际生产环境中，这两者通常会同时使用：
+需要快速查看运行态时使用 Web UI；需要提交、停止、取消、savepoint、恢复或批量自动化时，使用 REST API 或命令行。
-- 外部系统调用 REST 接口
-- 运维人员通过 Web UI 查看任务和集群状态
-
-## 开启 HTTP 能力
+## 开启 HTTP 服务
在使用这两类入口之前，需要先在 `seatunnel.yaml` 中开启 HTTP 服务：
@@ -42,11 +36,9 @@ seatunnel:
http:
enable-http: true
port: 8080
- enable-dynamic-port: true
- port-range: 100
```
-通常还需要尽早关注这些配置项：
+生产环境常用的可选配置包括：
- `context-path`：给所有 HTTP 接口加统一前缀
- `enable-dynamic-port`：当指定端口被占用时自动探测可用端口
@@ -55,7 +47,7 @@ seatunnel:
完整的 REST 参数说明请查看 [RESTful API V2](./rest-api-v2.md)。如果需要 HTTPS 和认证配置，请继续查看
[安全配置](./security.md)。
-## 如何访问 Web UI
+## 访问 Web UI
HTTP 开启后，可以通过下面的地址访问：
@@ -63,15 +55,25 @@ HTTP 开启后，可以通过下面的地址访问：
http://<host>:<port>/#/overview
```
-Web UI 适合查看：
+如果配置了 `context-path`，需要把 UI 路由放到该前缀下面：
-- 集群总览
-- 运行中的作业
-- 已完成的作业
-- Worker 健康状态与资源使用
-- Master 状态
+```text
+http://<host>:<port>/<context-path>/#/overview
+```
-详细界面说明请查看 [Web UI](./web-ui.md)。
+## 当前 Web UI 能力
+
+当前 Web UI 是一个可视化巡检控制台，支持：
+
+| 区域 | 可以做什么 |
+|------|------------|
+| Overview | 查看项目版本、集群 slot、worker 数量和作业数量 |
+| Jobs | 分页浏览运行中和已完成作业，并进入作业详情页 |
+| Job Detail | 查看作业配置、DAG、source 和 sink 指标、作业日志，以及开启后的实时可观测指标 |
+| Workers | 查看 worker 节点系统监控信息 |
+| Master | 查看 master 节点系统监控信息 |
+
+界面级说明请继续查看 [Web UI](./web-ui.md)。
## REST API 的典型用途
@@ -85,6 +87,7 @@ REST API 常见的使用方式包括：
最常用的参考文档是：
- [RESTful API V2](./rest-api-v2.md)
+- [作业生命周期 API](./rest-api-job-lifecycle.md)
- [RESTful API V1](./rest-api-v1.md)
如果是新接入系统，建议优先使用 **V2**；只有在兼容旧客户端时再考虑 V1。
@@ -105,13 +108,19 @@ REST API 常见的使用方式包括：
- 用 UI 验证集群健康情况和作业细节
-### 4. 生产环境补齐安全配置
+### 4. 需要操作控制时使用 REST API
+
+- 需要提交、停止、取消、savepoint 和恢复作业时，通过生命周期 API 完成
+- Web UI 作为这些操作前后的可视化巡检入口
+
+### 5. 生产环境补齐安全配置
- 如果接口会暴露给更广的内网或外部系统，建议开启 HTTPS 与认证
## 继续阅读
- [RESTful API V2](./rest-api-v2.md)
+- [作业生命周期 API](./rest-api-job-lifecycle.md)
- [RESTful API V1](./rest-api-v1.md)
- [安全配置](./security.md)
- [Web UI](./web-ui.md)
diff --git a/docs/zh/engines/zeta/web-ui.md b/docs/zh/engines/zeta/web-ui.md
index 7fe9896ed6..88c8bc58bb 100644
--- a/docs/zh/engines/zeta/web-ui.md
+++ b/docs/zh/engines/zeta/web-ui.md
@@ -4,13 +4,13 @@
建议把 [REST API 与 Web UI](./rest-api-and-web-ui.md) 作为运维入口页先读完。那一页会先解释什么时候启用
HTTP 服务、接下来该看哪些 REST API 页面，以及 Web UI 在日常运维里的位置。
-本页只聚焦 Web UI 各个界面本身。
+本页聚焦 Web UI 各个界面本身，以及当前内置控制台的能力边界。
## 访问
-在访问 web ui 之前我们需要开启 http rest api。首先需要在`seatunnel.yaml`配置文件中配置
+访问 Web UI 前，需要先在 `seatunnel.yaml` 中开启 SeaTunnel Engine HTTP 服务：
-```
+```yaml
seatunnel:
engine:
http:
@@ -18,21 +18,54 @@ seatunnel:
port: 8080
```
-然后访问 `http://ip:8080/#/overview`
+然后访问：
+
+```text
+http://<host>:8080/#/overview
+```
+
+如果配置了 `context-path`，需要把它放在 hash 路由之前：
+
+```text
+http://<host>:8080/<context-path>/#/overview
+```
## 概述
-Apache SeaTunnel 的 Web UI 提供了一个友好的用户界面，用于监控和管理 SeaTunnel 作业。通过 Web
UI，用户可以实时查看当前运行的作业、已完成的作业，以及集群中工作节点和管理节点的状态。主要功能模块包括 Jobs、Workers 和
Master，每个模块都提供了详细的状态信息和操作选项，帮助用户高效地管理和优化其数据处理流程。
+Apache SeaTunnel 的 Web UI 是 SeaTunnel Engine
的可视化巡检控制台。它可以帮助运维人员查看集群概览、运行中和已完成作业、作业详情页、日志、实时 DAG 指标，以及 worker 和 master 节点状态。
+
+## 能力总览
+
+| UI 区域 | 当前能力 |
+|---------|----------|
+| Overview | 查看集群版本、slot 使用、worker 数量和作业数量 |
+| Jobs | 查看运行中和已完成作业、分页浏览作业列表、进入作业详情 |
+| Job Detail | 查看 DAG、作业指标、异常文本、作业配置、日志，以及开启后的实时可观测指标 |
+| Workers | 查看 worker 节点系统监控信息 |
+| Master | 查看 master 节点系统监控信息 |
+
## 作业
### 运行中的作业
-“运行中的作业”模块列出了当前正在执行的所有 SeaTunnel 作业。用户可以查看每个作业的基本信息，包括作业
ID、提交时间、状态、执行时间等。点击具体作业可以查看更多详细信息，如任务分布、资源使用情况和日志输出，便于用户实时监控作业进度并及时处理潜在问题。
+“运行中的作业”模块列出当前正在执行的 SeaTunnel 作业。用户可以查看作业 ID、作业名称、创建时间、状态，并进入具体作业的详情页。
+
+列表会周期性刷新，并支持分页。
+
+### 作业详情
+
+作业详情页包含四个主要 tab：
+
+- **Overview**：展示作业 DAG、source 和 sink 吞吐指标、flush signal 指标，以及开启可观测性后的 vertex 或
edge 实时指标。
+- **Exception**：当作业失败或上报异常时，展示异常文本。
+- **Configuration**：展示引擎暴露的运行时作业配置。
+- **Log**：展示引擎日志 API 返回的作业日志文件。
+
#### 实时可观测性（Realtime Observability）
在 Job Detail 页面中，DAG 图支持展示“最近 N 分钟”的实时指标（默认 3 分钟，最大 10 分钟）：
@@ -46,25 +79,29 @@ Apache SeaTunnel 的 Web UI 提供了一个友好的用户界面，用于监控
### 已完成的作业
-“已完成的作业”模块展示了所有已成功完成或失败的 SeaTunnel
作业。此部分提供了每个作业的执行结果、完成时间、耗时以及失败原因（如果有）。用户可以通过此模块回顾过去的作业记录，分析作业性能，进行故障排查或重复执行某些特定作业。
+“已完成的作业”模块展示已进入终态的作业，例如 finished、failed、cancelled 或 savepoint
done。用户可以回看历史记录，并进入详情页查看配置、异常文本、引擎保留的指标和日志。
+
## 工作节点
### 工作节点信息
-“工作节点”模块展示了集群中所有工作节点的详细信息，包括每个工作节点的地址、运行状态、CPU
和内存使用情况、正在执行的任务数量等。通过该模块，用户可以监控各个工作节点的健康状况，及时发现和处理资源瓶颈或节点故障，确保 SeaTunnel
集群的稳定运行。
+“工作节点”模块展示 worker 节点的系统监控信息。可以用它查看 worker 地址、资源状态和引擎暴露的运行时健康信号。
+
## 管理节点
### 管理节点信息
-“管理节点”模块提供了 SeaTunnel 集群中主节点的状态和配置信息。用户可以查看 Master
节点的地址、运行状态、负责的作业调度情况以及整体集群的资源分配情况。该模块帮助用户全面了解集群的核心管理部分，便于进行集群配置优化和故障排查。
+“管理节点”模块展示 master 节点的系统监控信息。可以用它查看当前 master 侧运行状态和引擎暴露的资源信号。
+
## 下一步
- [REST API 与 Web UI](./rest-api-and-web-ui.md)
- [REST API V2](./rest-api-v2.md)
+- [作业生命周期 API](./rest-api-job-lifecycle.md)
- [安全](./security.md)
