# Fustor Agent 前端控制台用户操作指南

欢迎使用 Fustor Agent 前端控制台！本指南将帮助您了解如何使用这个强大的界面来配置、管理和监控您的数据同步任务。

在开始具体操作前，请务必理解 Fustor Agent 前端设计的两个核心理念，这将帮助您更好地使用本系统。

-----

### ⭐ 核心理念一：配置与实例的分离

Fustor Agent 的界面严格区分了“**静态配置**”和“**运行时实例**”，这是理解所有操作的基础。

  * **导航菜单 (数据源, 接收端, 同步任务)** : 这里是您系统的“**蓝图绘制中心**”。您在这里定义数据从哪里来 (`Source`)、到哪里去 (`Pusher`)、以及如何去 (`Sync`) 。此处的所有操作**不会**直接启动或停止任何数据同步，它只负责管理这些“蓝图”的增、删、改、查、启用和禁用。

  * **仪表盘 (Dashboard)**: 这里是您系统的“**生产车间监控室**”。您在这里查看根据“蓝图”创建出来的、正在运行的机器（即“实例”）的实时状态。您可以在这里对“实例”进行启停、重启等运行时操作，但**不能**在这里修改它们的内在设计（即配置）。

> **一句话总结**: 先去【数据源】、【接收端】、【同步任务】页面设计好蓝图，再去【仪表盘】或【同步任务】页面启动和监控根据蓝图生产的机器。

### ⭐ 核心理念二：“克隆并取代”的核心工作流

为了保证配置变更的安全、可追溯和可回滚，Fustor Agent 中**所有对现有配置的修改**都遵循“**克隆并取代 (Clone & Supersede)**”的模式 。

当您需要修改一个配置时（例如，更改数据库密码），您不应该寻找一个“编辑”按钮然后原地修改，正确的流程如下：

1.  找到您想修改的配置项，点击 `[克隆并编辑]` 按钮 。
2.  向导启动后，系统会要求您输入一个**新的、唯一的ID**。这是**强制性**的，也是最关键的一步 。
3.  在预填了旧配置信息的基础上，进行您需要的修改。
4.  点击 `[保存]`。
5.  系统会自动完成：
      * 创建一个使用新ID的全新配置 。
      * 自动**禁用**旧的配置,而不是删除它 。

这个工作流的好处是，您的每一次变更都作为一个新的配置版本被保留下来。任何时候如果新配置出现问题，您都可以轻松地在配置中心**手动禁用新配置、重新启用旧配置**，然后通过“应用变更”功能让系统回滚到上一个稳定状态，极大地提升了系统的健壮性。

-----

### **主要功能区介绍**

#### **1. 仪表盘 (Dashboard) **

这是您系统的健康状态概览页面。

  * **全局健康摘要** : 页面顶部以卡片形式展示了系统的核心健康指标，包括 **系统状态 (Healthy/Error)**、**运行中管道数量** 和 **错误管道数量** ，让您对全局状况一目了然。
  * **“消息优先”数据管道可视化** : 每一个正在运行的同步任务都会被可视化为一个数据流图。在新架构下，任务总是优先处理实时数据，因此您看到的主要链路总是 `Source` -> `Event Bus` -> `Pusher`。
    * **消息同步 (`MESSAGE_SYNC`)**: 这是任务的**主要运行状态**。可视化图会清晰地展示实时数据流，并实时更新每个环节的状态和关键指标。
    * **并发快照 (`SNAPSHOT_SYNC`)**: 当一个任务正在进行补充性质的快照时，它的状态会**同时显示** `MESSAGE_SYNC` 和 `SNAPSHOT_SYNC`。可视化图的主链路（消息同步）**不会中断**，同时会有一个额外的指示（例如一个徽章或状态标签），表明一个并发的快照任务正在后台运行，直接从 `Source` 向 `Pusher` 回填历史数据。
  * **系统日志快照** : 仪表盘底部会展示最新的系统日志快照，方便您快速了解近期发生的事件 。

#### **2. 配置管理 (数据源, 接收端, 同步任务)**

这些页面是管理系统静态配置的**唯一**入口。

  * **数据源 (Sources)**: 管理所有数据源的连接信息。

      * **Schema缓存提示**: 如果一个已启用的数据源缺少字段描述缓存，系统会显示一个 \<i class="ti ti-alert-triangle text-warning"\>\</i\> 警告图标，提示您需要编辑该配置并执行“校验并发现” 。
      * **清理无用配置**: 提供一个 `[清理无用配置]` 按钮，可以一键删除所有已禁用且未被任何同步任务使用的配置 。

  * **接收端 (Pushers)** : 管理所有数据接收方的连接信息。同样提供 `[清理无用配置]` 功能 。

  * **同步任务 (Sync Tasks)**: 定义数据从哪个 `Source` 流向哪个 `Pusher`，以及字段如何映射。

      * **全新的表格视图**: 任务列表现在以信息更密集的表格形式展现，包含**状态**、ID、数据流向、已推送/缓冲区大小等关键信息。任务状态现在更具体，主要状态总是 `MESSAGE_SYNC`，并可能伴随一个并发的 `SNAPSHOT_SYNC` 状态。
      * **启/禁用切换**: 您可以直接在列表中通过 `[Enable]` / `[Disable]` 按钮切换配置的启用状态，而无需进入编辑模式 。

  * **\<i class="ti ti-palette"\>\</i\> 颜色编码的操作按钮**:

      * 为了提高操作的清晰度和安全性，整个UI的操作按钮都进行了颜色编码 。
      * \<span style="color: green;"\>**绿色**\</span\> 代表 **启动/启用** 等安全操作。
      * \<span style="color: blue;"\>**蓝色**\</span\> 代表 **重启**。
      * \<span style="color: orange;"\>**橙色**\</span\> 代表 **停止/禁用** 等需要注意的操作。
      * \<span style="color: red;"\>**红色**\</span\> 代表 **删除** 等危险操作 。

#### **3. 日志中心 (Logs)** 一个完整的日志查询页面，您可以通过**级别**和**组件名称**进行精确的筛选和查询 。日志查看器支持向上滚动**自动加载**更早的历史日志，方便您追溯问题 。

-----

### **核心操作流程**

#### **如何添加一个全新的数据源/接收端？**

Fustor Agent 引入了全新的分步向导来引导您完成配置。

1.  导航到 **[数据源]** 或 **[接收端]** 页面，点击 `[+ 添加...]` 按钮 。
2.  **第一步：环境与连接** * 输入一个唯一的**配置ID** 。
      * 选择**驱动 (Driver)** 类型（如 `mysql`）。
      * 填写连接地址(URI/Endpoint)和用于**安装校验的管理员凭证**（此凭证不会被保存）。
      * 点击 `[校验并发现]` 按钮 。系统会以清单的形式，实时反馈连接测试、参数检查、字段发现等每一步的结果 。
      * 只有所有步骤都成功后，才能进入下一步 。
3.  **第二步：配置与校验** * 为 Fustor Agent 创建一个权限受限的、用于日常拉取数据的**代理用户凭证**（此凭证将被保存）。
      * 配置其他高级参数（可选）。
      * 点击 `[校验用户]` 按钮，系统会验证代理用户的有效性 。
      * 所有校验通过后，点击 `[保存配置]` 。

#### **如何添加一个全新的同步任务？**

1.  导航到 **[同步任务]** 页面，点击 `[+ 新建同步任务]` 按钮 。
2.  **第一步：选择源与目标** * 为新任务指定一个唯一的**任务ID** 。
      * 从下拉列表中选择一个已配置的**数据源 (Source)** 和**接收端 (Pusher)** 。
      * 点击 `[加载可用字段]` ，系统会自动获取源和目标的字段信息并展示 。
3.  **第二步：字段映射** * **智能映射**：系统会自动尝试映射名称相似的字段 。
      * **手动映射**：您可以通过拖拽或下拉选择的方式，手动调整或完成剩余字段的映射 。
      * 对于 `object` 类型的字段，未被直接映射的源字段会自动归集到该集合中 。
      * 所有标记为 \<span class="text-danger"\>\*\</span\> 的必填字段都必须完成映射才能保存 。
4.  点击 `[保存配置]` 完成创建 。

#### **如何应用配置变更？**

1.  当您通过“克隆并取代”的方式修改了一个正在被运行任务所使用的配置后，旧的配置会被自动禁用。所有正在使用旧配置的运行中任务，其状态会自动变为 **`RUNNING_CONF_OUTDATE`**。
2.  此时，页面顶部会出现一个**黄色的全局告警横幅** 。
3.  它会提示您“检测到配置变更，部分任务需要重启以应用新配置” 。
4.  在您完成所有配置修改后，点击此横幅上的 `[立即应用所有变更]` 按钮 。
5.  Fustor Agent 会自动**优雅地重启所有状态为 `RUNNING_CONF_OUTDATE` 的同步任务**，而无需中断整个服务 。