跳至主要內容

Web 管理界面

HSXISAWD2026/3/20大约 4 分钟功能特性HsxWorkFlowWeb管理

Web 管理界面

HsxWorkFlow 提供了基于 FastAPI + Socket.IO 的 Web 管理界面，支持 RESTful API 和 WebSocket 实时通信。本文档详细介绍 Web 管理界面的使用方法。

概览

启动 Web 服务

基本启动

from hsxworkflow import WorkflowManager, WorkRegisterHandler

wf = WorkRegisterHandler(step_key="demo")

@wf.register_class()
class DemoWorkFlow(StepActionHandler):
    @wf.step(sort=1)
    def hello(self):
        return self.set_success()

manager = WorkflowManager()
manager.register_object(wf)
manager.run_app()  # 访问 http://localhost:5050

自定义配置

manager.run_app(
    host="0.0.0.0",    # 监听地址
    port=8080,         # 监听端口
    debug=True,        # 调试模式
)

访问地址

  • Web 界面: http://localhost:5050
  • API 文档: http://localhost:5050/docs
  • 健康检查: http://localhost:5050/health

REST API

所有接口前缀为 /api，自动生成 OpenAPI 文档。

API 端点

端点方法描述请求体
/api/workflow/listGET获取工作流列表-
/api/workflow/startPOST启动指定工作流{"classId": int}
/api/workflow/stopPOST停止指定工作流{"classId": int}
/api/workflow/{class_id}GET获取工作流详情-
/healthGET健康检查-

获取工作流列表

请求:

curl http://localhost:5050/api/workflow/list

响应:

{
  "code": 200,
  "data": [
    {
      "WorkflowTitle": "演示工作流",
      "WorkflowDesc": "三步走的示例流程",
      "WorkflowClass": "DemoWorkFlow",
      "WorkflowGroup": [
        {
          "WorkflowName": "demo",
          "WorkflowID": 140234567890,
          "WorkflowRunType": "single",
          "WorkflowStatus": "standby",
          "WorkflowCurrentStep": null,
          "WorkflowStartTime": "--",
          "WorkflowRunCount": 0
        }
      ]
    }
  ]
}

启动工作流

请求:

curl -X POST http://localhost:5050/api/workflow/start \
  -H "Content-Type: application/json" \
  -d '{"classId": 140234567890}'

响应:

{
  "message": "Workflow started",
  "code": 10000
}

停止工作流

请求:

curl -X POST http://localhost:5050/api/workflow/stop \
  -H "Content-Type: application/json" \
  -d '{"classId": 140234567890}'

响应:

{
  "message": "Workflow stopped",
  "code": 10000
}

获取工作流详情

请求:

curl http://localhost:5050/api/workflow/140234567890

响应:

{
  "code": 10000,
  "data": {
    "WorkflowTitle": "演示工作流",
    "WorkflowDesc": "三步走的示例流程",
    "WorkflowClass": "DemoWorkFlow",
    "WorkflowGroup": [
      {
        "WorkflowName": "demo",
        "WorkflowID": 140234567890,
        "WorkflowRunType": "single",
        "WorkflowStatus": "running",
        "WorkflowCurrentStep": "process",
        "WorkflowStartTime": "2025-01-31 12:00:00",
        "WorkflowRunCount": 1
      }
    ]
  }
}

健康检查

请求:

curl http://localhost:5050/health

响应:

{
  "status": "healthy",
  "version": "0.2.0",
  "workflow_manager": true
}

WebSocket

基于 Socket.IO 协议，支持房间机制实现精准推送。

连接服务器

import { io } from "socket.io-client";

const socket = io("http://localhost:5050");

客户端 → 服务端

事件数据格式描述
list-获取工作流列表
start{classId: int}启动工作流
stop{classId: int}停止工作流
work_data{classId: int}获取工作流详情
join{classId: int}加入房间（订阅日志）
leave{classId: int}离开房间

服务端 → 客户端

事件数据格式描述
connect_res{data: [id1, id2]}连接成功，返回所有工作流 ID
work_flow_list{WorkflowID, WorkflowStatus, ...}状态更新推送
work_flow_step_log{WorkflowID, WorkflowLog, WorkflowLogType}步骤日志推送
work_flow_step_infoStepResult dict步骤信息推送
work_flow_count{WorkflowID, WorkflowRunCount}运行次数更新

完整示例

import { io } from "socket.io-client";

const socket = io("http://localhost:5050");

// 连接成功
socket.on("connect_res", (data) => {
  console.log("可用工作流:", data.data);
});

// 获取列表
socket.emit("list");
socket.on("list_res", (data) => {
  console.log("工作流列表:", data);
});

// 加入房间订阅日志
socket.emit("join", { classId: 140234567890 });

// 监听日志
socket.on("work_flow_step_log", (data) => {
  console.log(`[${data.WorkflowLogType}] ${data.WorkflowLog}`);
});

// 监听状态变化
socket.on("work_flow_list", (data) => {
  console.log("状态更新:", data);
});

// 监听步骤信息
socket.on("work_flow_step_info", (data) => {
  console.log("步骤结果:", data);
});

// 启动工作流
socket.emit("start", { classId: 140234567890 });

// 停止工作流
socket.emit("stop", { classId: 140234567890 });

// 离开房间
socket.emit("leave", { classId: 140234567890 });

房间机制

房间机制允许客户端订阅特定工作流的日志和状态更新。

// 加入房间
socket.emit("join", { classId: 140234567890 });

// 离开房间
socket.emit("leave", { classId: 140234567890 });

加入房间后，只会接收该工作流的相关消息。

OpenAPI 文档

FastAPI 自动生成交互式 API 文档，访问 http://localhost:5050/docs。

功能

  • 查看 API 端点
  • 查看请求/响应模型
  • 在线测试 API
  • 下载 OpenAPI 规范

使用

  1. 访问 http://localhost:5050/docs
  2. 展开对应的 API 端点
  3. 点击 "Try it out"
  4. 填写请求参数
  5. 点击 "Execute" 执行请求

配置

Web 服务配置

在 .env 文件中配置：

# Web 服务配置
WEB_HOST=0.0.0.0
WEB_PORT=5050
WEB_DEBUG=false
WEB_DOCS_ENABLED=true
WEB_CORS_ORIGINS=["*"]

代码中访问配置

from hsxworkflow import config

print(config.web.host)    # 0.0.0.0
print(config.web.port)    # 5050
print(config.web.debug)   # False

最佳实践

1. 错误处理

// 连接错误处理
socket.on("connect_error", (error) => {
  console.error("连接错误:", error);
});

// 断开连接处理
socket.on("disconnect", (reason) => {
  console.log("断开连接:", reason);
});

// 事件错误处理
socket.on("error", (error) => {
  console.error("事件错误:", error);
});

2. 重连机制

const socket = io("http://localhost:5050", {
  reconnection: true, // 启用重连
  reconnectionAttempts: 5, // 最大重连次数
  reconnectionDelay: 1000, // 重连延迟（毫秒）
});

3. 房间管理

// 离开页面时离开房间
window.addEventListener("beforeunload", () => {
  socket.emit("leave", { classId: currentWorkflowId });
});

// 切换工作流时先离开旧房间
function switchWorkflow(newClassId) {
  socket.emit("leave", { classId: currentWorkflowId });
  socket.emit("join", { classId: newClassId });
  currentWorkflowId = newClassId;
}

4. 日志过滤

// 根据日志级别过滤
socket.on("work_flow_step_log", (data) => {
  const logType = data.WorkflowLogType;

  if (logType === "ERROR" || logType === "CRITICAL") {
    console.error(`[${logType}] ${data.WorkflowLog}`);
  } else if (logType === "WARNING") {
    console.warn(`[${logType}] ${data.WorkflowLog}`);
  } else {
    console.log(`[${logType}] ${data.WorkflowLog}`);
  }
});

下一步

现在你已经了解了 Web 管理界面的使用方法，可以继续学习：

Default footer
Copyright © 2026 HSXISAWD