# 管理后台使用说明：数据流功能

URL: https://docs.ones.cn/deploy/configure/ones-admin/ones-admin-dataflow-usage

本文面向实施维护人员，说明如何在 ONES 管理后台查看数据流状态、定位链路问题，并按需使用重建功能。

管理后台打开方式请参考： [打开管理后台](https://docs.ones.cn/deploy/configure/ones-admin/open-ones-admin/) 。

## 1. 功能说明

`数据流` 页面用于查看业务数据从上游数据库、消息链路到下游服务的处理状态。

当前页面主要关注：

- `Index` ：搜索索引链路。
- `Report` ：报表数据链路。
- `Audit log` ：审计日志链路。
页面可以帮助实施维护人员判断：

- 数据流是否正常。
- 哪条链路需要关注。
- 问题更可能出现在上游、消费服务还是下游写入。
- 是否需要执行数据流重建。
注意：

- 数据流页面用于观察和辅助排查，不会自动修复问题。
- `Rebuild` 会消耗系统资源，生产环境应在业务低峰或维护窗口操作。
- 如果上游 MySQL、Kafka Connect 或监控采集本身异常，应先处理上游问题，再考虑重建。

## 2. 使用前准备

使用数据流功能前，需要确认 MySQL 状态服务已打开。

在 `config/private.yaml` 中配置：

```yaml
mysqlStatusServerEnable: 'true'
```

配置后执行：

```bash
./ones-ai-k8s.sh
make setup-ones
```

验证方式：

```bash
kubectl -n ones get deploy mysql-status-server-deployment
kubectl -n ones get endpoints mysql-status-server-service
kubectl -n ones-installer exec deploy/installer-api -- curl http://mysql-status-server-service.ones/status
```

正常情况下：

- `mysql-status-server-deployment` 为 `1/1` 。
- `mysql-status-server-service` 有 endpoints。
- `/status` 返回 `healthy: true` 。
如果没有打开 `mysqlStatusServerEnable` ，数据流页面可能显示 `Observation failed` ，因为管理后台无法确认 MySQL 上游状态。

## 3. 登录和入口

浏览器访问：

```text
http://<管理后台访问地址>/ones-admin/
```

登录成功后，左侧菜单点击 `数据流` 。

如果需要使用英文界面查看或截图，可以访问：

```text
http://<管理后台访问地址>/ones-admin/?locale=en-US#/dataflows
```

页面示例：

![Data flows list](https://docs.ones.cn/assets/images/dataflow-list-en-1c48c677cd3e5c7adee042d956568e91.png)

示例中 `Report` 为 `Normal` 。如果 `Index` 显示 `Rebuilding` ，通常表示后台重建任务仍在推进观察版本，不等同于链路异常。 `Audit log` 显示 `Not enabled` 时，说明操作日志业务未启用或组织级状态未打开。

## 4. 查看数据流列表

进入 `数据流` 页面后，先看列表。

重点查看：

- `Data flow` ：数据流名称，例如 Index、Report、Audit log。
- `Current status` ：当前状态。
- `Downstream diagnosis` ：页面给出的诊断结论。
- `Recent signal` ：最近观察到的信号或异常原因。
- `Action` ：查看详情或执行重建。
常见状态说明：

- `Normal` ：当前观察结果正常。
- `Delay` ：存在延迟，需要关注消费积压或写入速度。
- `Error` ：链路存在明确异常，需要排查。
- `Observation failed` ：管理后台没有拿到完整观察数据，通常要先检查监控采集、MySQL 或 Kafka Connect。
- `Not enabled` ：该功能未启用，例如现场没有开启审计日志。
建议处理顺序：

1. 先看是否有 `Error` 或 `Observation failed` 。
2. 再看是否有 `Delay` 。
3. 对异常链路点击 `View details` 查看详情。
4. 不要直接把重建当作第一步，先确认上游服务和监控采集是否正常。

## 5. 查看详情定位问题

在列表中点击对应数据流的 `View details` 。

详情页会展示：

- 当前诊断结论。
- 推荐处理动作。
- 数据路径中的关键节点。
- 每个节点的状态和指标。
- 延迟趋势。
- 历史重建任务。
Report 健康详情示例：

![Report detail](https://docs.ones.cn/assets/images/dataflow-report-detail-en-213c7c0b42476a0dbe27a4acbc50d992.png)

排查时建议按页面顺序看：

1. 先看顶部诊断结论，例如 `Upstream error` 。
2. 再看 `Current recommendation` ，按推荐动作检查对应服务。
3. 在 `Data path` 中逐个查看 MySQL、Kafka Connect、消费服务等节点。
4. 如果某个节点显示异常，优先排查该节点。
5. 如果页面显示 `Observation failed` ，优先确认 `mysqlStatusServerEnable` 已打开，并检查 MySQL 状态服务和监控数据是否正常。

## 6. 查看延迟趋势和历史任务

在详情页继续向下查看 `Lag trend` 和 `Historical tasks` 。

![Report metrics and history](https://docs.ones.cn/assets/images/dataflow-report-diagnostics-en-213c7c0b42476a0dbe27a4acbc50d992.png)

`Lag trend` 用于观察消费积压趋势：

- 当前值持续升高：说明下游消费可能跟不上。
- 当前值逐步下降：说明积压正在恢复。
- 曲线没有数据：可能是该指标未采集到，或当前链路没有对应指标。
`Historical tasks` 用于查看历史重建记录：

- `Start time` ：任务开始时间。
- `Result` ：执行结果。
- `Triggered by` ：触发人。
- `Rebuild scope` ：本次重建范围。
- `Total duration` ：总耗时。
- `Action` ：查看任务详情。
如果历史任务为空，说明当前环境还没有执行过该数据流的重建任务。

## 7. 使用重建功能

在数据流列表中，如果某条数据流支持重建，页面会显示 `Rebuild` 。

点击 `Rebuild` 后，会打开重建抽屉：

![Rebuild drawer](https://docs.ones.cn/assets/images/dataflow-report-rebuild-drawer-en-caaf0bb600639b86a044e7391ba87c17.png)

操作步骤：

1. 确认要重建的数据流是否正确。
2. 选择本次需要重建的表或表分组。
3. 确认业务低峰或维护窗口。
4. 点击 `Confirm start` 开始重建。
5. 返回详情页，在历史任务或当前任务中查看进度。
注意：

- 不要在业务高峰期随意重建。
- 不要短时间内重复触发同一条数据流的重建。
- 如果上游服务仍然异常，重建可能无法解决问题。
- 如果不确定要选哪些表，建议先联系产品支持或研发确认范围。
- 执行重建前，建议记录当前异常现象、数据流状态和操作时间，便于后续追踪。

### 7.1 实际执行示例：Index 重建

本次在当前测试环境实际执行了一次 `Index` 数据流重建，验证流程如下。

执行范围：

- 数据流： `Index`
- 选择表： `project.team`
- 必选表： `project.resource`
- 任务 ID： `rb_index_1782198274310225509`
- 接口结果： `status = success`
- 页面结果： `Result = Done`
- 开始时间： `2026-06-23 15:04:34`
选择范围时，页面会显示已选分组和已选表数量。本次示例中只选择 `project.team` ，同时保留 `Others` 中不可取消的 `project.resource` 。

![Rebuild selected tables](https://docs.ones.cn/assets/images/dataflow-rebuild-selected-en-45283d1d276f4e36eb1b6c0b1b89cff3.png)

点击 `Confirm start` 后，页面会进入重建任务页。实施维护人员重点看：

- `Task ID` ：确认当前查看的是刚触发的任务。
- `Rebuild scope` ：确认重建范围是否正确。
- `Target version` / `Current observed version` ：观察版本推进。
- `Table-level progress` ：观察表级进度。
![Rebuild running](https://docs.ones.cn/assets/images/dataflow-rebuild-running-en-5a2dcee52d48b02d8feadf80e5b5e321.png)

任务完成后，返回数据流详情页，滚动到 `Historical tasks` 。当 `Result` 显示 `Done` ，且 `Rebuild scope` 是本次选择的表，说明任务已经完成。

![Rebuild done in history](https://docs.ones.cn/assets/images/dataflow-rebuild-history-done-en-a7714e720854a3ee1af49fd06910e8db.png)

注意：

- `Others` 分组如果显示为不可取消，说明它是必选表，执行时必须保留。
- 重建过程中不要重复点击 `Start rebuild` ，同一条数据流同一时间只允许一个重建任务。
- 页面短时间内可能仍显示运行时观测信息，最终是否完成以历史任务 `Result = Done` 或任务接口 `status = success` 为准。
- 如果结果为 `Failed` ，点击 `View details` 查看失败信息和日志，再结合相关服务日志继续排查。

## 8. 异常处理建议

数据流异常不要直接重建，先按页面诊断定位异常位置。

建议处理顺序：

1. 先看列表页状态： `Observation failed` 、 `Error` 、 `Delay` 、 `Not enabled` 、 `Rebuilding` 。
2. 点击 `View details` ，查看顶部诊断和 `Current recommendation` 。
3. 在 `Data path` 中找到异常节点，例如 MySQL、Kafka Connect、下游消费服务或写入侧。
4. 先恢复异常节点，再观察数据流状态是否恢复。
5. 只有在上游和下游服务都正常，但数据仍需要补齐时，再考虑执行 `Rebuild` 。
常见处理方式：

- `Observation failed` ：优先确认 `mysqlStatusServerEnable: 'true'` 已生效， `mysql-status-server-service` 有 endpoints，并且 installer-api 容器内可以访问 `/status` 。然后检查 Kafka Connect、监控采集和 installer-api 日志。
- `Error` ：进入详情页看异常节点。如果 MySQL 或 Kafka Connect 异常，先恢复共同来源链路；如果下游消费服务异常，检查对应 deployment、pod 日志和消费组状态。
- `Delay` ：重点看消费积压是否持续升高。持续升高时检查消费者实例、资源压力、Kafka lag 和写入目标服务。
- `Rebuilding` ：表示有重建任务正在执行或观察版本还在推进。不要重复触发重建，进入 `View rebuild` 查看当前任务。
- `Audit log` 为 `Not enabled` ：如果现场不需要操作日志，这是正常状态；如果需要操作日志，进入 `ONES 系统` - `配置中心` ，搜索并开启 `enableAuditLog` ，再确认组织级操作日志状态已打开。开启后检查 `binlog-event-sync` 、 `audit-log-sync` 和 ClickHouse 中 `audit_log` 相关表是否正常。
排查时建议记录：

- 数据流名称。
- 当前状态和诊断文案。
- 异常节点。
- 最近观察时间。
- 是否刚执行过重建。
- 相关服务日志或监控截图。

## 9. 常见问题

### 页面显示 Observation failed

常见原因：

- `mysqlStatusServerEnable` 没有打开，导致管理后台无法访问 `mysql-status-server-service` 。
- MySQL 监控数据没有采集到。
- Kafka Connect 状态无法确认。
- 下游消费服务指标无法查询。
- installer-api 或监控查询链路异常。
建议先确认 `mysqlStatusServerEnable: 'true'` 已配置并执行过 `make setup-ones` ，再检查监控功能和对应服务状态，最后判断是否需要重建。

### Audit log 显示 Not enabled

通常表示当前环境没有开启操作日志/审计日志功能，或组织级操作日志状态未打开。如果现场不使用操作日志，这是正常状态。

如果现场需要使用操作日志：

1. 进入 `ONES 系统` - `配置中心` 。
2. 搜索并开启 `enableAuditLog` 。
3. 确认组织级操作日志状态已打开。
4. 检查 `binlog-event-sync` 和 `audit-log-sync` 是否正常运行。
5. 回到管理后台数据流页面，确认 `Audit log` 不再是 `Not enabled` 。

### 点击 View details 后仍看不出原因

可以先记录：

- 数据流名称。
- 当前状态。
- 页面顶部诊断结论。
- Data path 中异常的节点。
- 最近观察时间。
然后结合服务日志、监控页面和巡检结果继续排查。

### 重建按钮看不到

可能原因：

- 当前数据流不支持重建。
- 当前账号没有操作权限。
- 数据流处于不允许触发重建的状态。
以页面实际显示为准。

### 重建后数据仍异常

常见原因：

- 上游数据源仍异常。
- 消费服务仍有错误。
- 监控采集仍然失败。
- 重建范围不完整。
建议回到详情页重新查看诊断结论和数据路径，不要连续重复重建。