feat: add scheduler and flower monitoring with worker registry

2026-05-01 20:59:12 +08:00
parent 6dc386e752
commit 0019aa0fba
31 changed files with 2341 additions and 583 deletions
@@ -598,3 +598,152 @@
 - 风险与影响：
  - 影响范围仅前端全局 404 页面。
  - 文案当前为英文（对齐原闪现页面），若后续需要中英双语可再单独调整。
+
+## Work Log - 迁移 Celery 与任务/Worker 双监控页面到 fquiz（2026-05-01）
+
+- 背景：
+  - 需求要求将 `modo-next` 的 Celery 调度与两类监控页（任务监控、Worker 监控）迁移到当前 `fquiz`。
+  - 仓库已有 Celery 与 `/admin/task-monitor`，缺口是“独立 Worker 监控页 + 对应 API/菜单入口”。
+
+- 本次改动（最小闭环）：
+  - 后端新增 Worker 监控模型与接口：
+    - `api/app/schemas/worker_monitor.py`
+      - 新增 `WorkerMonitorOverviewResponse`、`WorkerMonitorTaskOverviewResponse` 及相关 item/summary 模型。
+    - `api/app/services/worker_monitor_service.py`
+      - 基于 Celery inspect 提供 Worker 概览（状态/队列/并发/处理量）。
+      - 提供单 Worker 任务快照（active/reserved/scheduled）与 recent 历史任务聚合。
+      - 复用现有 `task_monitor_service` 的通用解析工具，保持行为一致性。
+    - `api/app/api/v1/worker_monitor.py`
+      - 新增路由：
+        - `GET /api/v1/admin/workers/overview`
+        - `GET /api/v1/admin/workers/tasks?worker=...&recent_limit=...`
+      - 权限统一 `celery.read` / `celery.manage`。
+    - `api/app/api/router.py`
+      - 挂载 `worker_monitor` 路由。
+
+  - 前端新增独立 Worker 监控页：
+    - `web/src/app/admin/workers/page.tsx`
+      - 新增 Worker 列表页：支持名称/队列/在线状态筛选、自动刷新、手动刷新。
+      - 新增 Worker 任务抽屉：查看 active/reserved/scheduled/recent 四类任务明细（含 args/kwargs/error）。
+      - 数据源对齐新后端 API。
+
+  - 菜单与权限入口联动：
+    - `api/app/services/seed_service.py`
+      - 新增菜单 `admin.workers`（`/admin/workers`）。
+      - admin 默认菜单绑定加入 `admin.workers`。
+      - 调整后续菜单 `sort_order`，避免排序冲突。
+    - `api/app/services/legacy_authz_service.py`
+      - 增加 `admin.workers -> celery.read/celery.manage` 权限映射。
+      - synthetic legacy menu rows 增加 `admin.workers`。
+      - 同步顺序号，保持 legacy 菜单序一致。
+    - `api/app/services/legacy_admin_rbac_service.py`
+      - `PROTECTED_MENU_CODES` 加入 `admin.workers`，避免误删。
+    - `api/app/services/admin_service.py`
+      - 菜单删除保护集合加入 `admin.workers`。
+    - `web/src/app/admin/menus/page.tsx`
+      - 前端受保护菜单集合加入 `admin.workers`。
+    - `web/src/app/admin/page.tsx`
+      - 后台首页新增“Worker监控”卡片入口。
+
+- 验证：
+  - 后端语法检查：
+    - `python3 -m py_compile api/app/schemas/worker_monitor.py api/app/services/worker_monitor_service.py api/app/api/v1/worker_monitor.py api/app/api/router.py api/app/services/seed_service.py api/app/services/legacy_authz_service.py api/app/services/admin_service.py` -> 通过。
+  - 前端构建：
+    - `rm -f web/.next/lock && npm run build:web` -> 通过。
+    - 构建产物路由包含：`/admin/workers`、`/admin/task-monitor`。
+
+- 风险与影响：
+  - 影响范围：Celery 监控模块（新增 Worker 监控维度），权限仍复用 `celery.read/manage`。
+  - `recent_tasks` 依赖 Celery Redis result backend 中任务元数据是否含 `worker/hostname` 字段；若上游未写入，recent 列表会偏少，但不影响 active/reserved/scheduled 实时快照。
+
+## Work Log - 新增 Scheduler + Flower + Worker 自动注册并切换监控数据源（2026-05-01）
+
+- 背景：
+  - 新需求要求当前 `fquiz` 引入独立 `scheduler` 服务、`flower` 监控服务，监控页面改走 Flower，并提供 worker 自动注册机制。
+
+- 本次改动（最小闭环）：
+
+  - 后端新增 `scheduler` 调度 API：
+    - `api/app/schemas/scheduler.py`
+      - 定义任务入队/撤销请求响应模型。
+    - `api/app/services/scheduler_service.py`
+      - 封装 `celery_app.send_task` 与 `celery_app.control.revoke`。
+    - `api/app/api/v1/scheduler.py`
+      - 提供：
+        - `GET /api/v1/scheduler/healthz`
+        - `POST /api/v1/scheduler/v1/tasks/enqueue`
+        - `POST /api/v1/scheduler/v1/tasks/revoke`
+      - 支持 `x-scheduler-token`（环境变量配置后生效）。
+    - `api/app/scheduler_main.py`
+      - 独立 scheduler 进程入口（只挂 scheduler 路由）。
+    - `api/app/api/router.py`
+      - 主 API 路由挂载 scheduler 与 flower monitor 路由。
+
+  - 后端新增 Flower 监控代理层（页面不直连 Flower）：
+    - `api/app/schemas/flower_monitor.py`
+      - 定义 worker 概览与任务快照模型。
+    - `api/app/services/flower_monitor_service.py`
+      - 代理调用 Flower API：
+        - `/api/workers?refresh=...`
+        - `/api/workers?status=true`
+        - `/api/tasks?limit=...&workername=...`
+      - 统一解析 worker/task 字段、状态、时间戳。
+    - `api/app/api/v1/flower_monitor.py`
+      - 提供：
+        - `GET /api/v1/admin/flower/workers`
+        - `GET /api/v1/admin/flower/worker-tasks`
+      - 权限：`celery.read`/`celery.manage`。
+
+  - Worker 自动注册机制：
+    - `api/app/models/worker_registry.py`
+      - 新增 `worker_registry` 表模型。
+    - `api/app/services/worker_registry_service.py`
+      - worker 注册、离线标记、离线扫描。
+    - `api/app/core/worker_signals.py`
+      - 绑定 Celery 信号：`worker_ready` / `heartbeat_sent` / `worker_shutdown`。
+    - `api/app/tasks/worker_registry_tasks.py`
+      - 定时离线扫描任务。
+    - `api/app/core/celery_app.py`
+      - include 新任务模块，beat schedule 增加 `sweep_worker_registry_offline`。
+      - 引入 worker signal 注册。
+    - `api/app/core/database.py` + `api/app/models/__init__.py`
+      - 把 `worker_registry` 纳入 ORM 初始化与建表。
+
+  - 监控页面切 Flower：
+    - `web/src/app/admin/workers/page.tsx`
+      - 改为请求 `/api/v1/admin/flower/workers` 与 `/api/v1/admin/flower/worker-tasks`。
+      - 展示 Flower 维度字段（在线状态、并发、registered、processed、心跳、任务来源等）。
+    - `web/src/app/admin/task-monitor/page.tsx`
+      - 重构为 Flower 聚合视图：批量拉取每个 worker 任务快照并汇总状态分布/任务表。
+    - `api/app/services/task_monitor_service.py`
+      - 从原 inspect+redis 直读切换为基于 Flower 代理服务聚合，保持原接口契约。
+
+  - 调度链路接入 scheduler（可选）：
+    - `api/app/services/elevation_service.py`
+      - `create_apply_job` 增加 `dispatch_mode`，支持 `scheduler_api`。
+      - `api/app/api/v1/elevation.py` 新增 `dispatchMode` 查询参数透传。
+      - 默认仍为 `celery_direct`，不破坏现有行为。
+
+  - 运行环境与编排配置：
+    - `docker-compose.yml`
+      - 新增 `scheduler` 服务（19100）。
+      - 新增 `flower` 服务（5555，basic auth）。
+      - `celery-worker` 增加 `CELERY_WORKER_QUEUES` 配置。
+      - API/worker/beat 注入 `SCHEDULER_*`、`FLOWER_*`、`WORKER_REGISTRY_TTL_SECONDS`。
+    - `.env.example`
+      - 新增 `SCHEDULER_API_BASE_URL`、`SCHEDULER_API_TOKEN`、`SCHEDULER_DEFAULT_QUEUE`。
+      - 新增 `FLOWER_API_BASE_URL`、`FLOWER_API_TIMEOUT_SECONDS`、`FLOWER_BASIC_AUTH`、`FLOWER_PORT`。
+      - 新增 `WORKER_REGISTRY_TTL_SECONDS`、`CELERY_WORKER_QUEUES`、`SCHEDULER_PORT`。
+
+- 验证：
+  - 后端语法校验通过：
+    - `python3 -m py_compile ...`（覆盖 scheduler/flower/worker_registry/celery/task-monitor 相关文件）
+  - 前端构建通过：
+    - `npm run build:web` -> 通过，页面路由包含 `/admin/workers`、`/admin/task-monitor`。
+  - Compose 渲染校验通过：
+    - `docker compose config` 渲染包含 `scheduler`、`flower` 服务以及关键 env/command 字段。
+
+- 风险与影响：
+  - Flower 代理链路新增了对 `FLOWER_BASIC_AUTH`、`FLOWER_API_BASE_URL` 的配置依赖，配置不一致会导致监控页 502。
+  - `task-monitor` 改为按 worker 聚合调用，worker 数量多时会增加 API 聚合开销。
+  - `dispatchMode=scheduler_api` 需确保 `scheduler` 服务可达；默认 `celery_direct` 兼容旧行为。