flowerui 0.1.0__py3-none-any.whl

flowerui/__init__.py

@@ -0,0 +1,3 @@
+"""FlowerUI —— 可嵌入现有 Celery 项目的 Web 监控面板。"""
+
+__version__ = "0.1.0"

flowerui/__main__.py

@@ -0,0 +1,5 @@
+"""``python -m flowerui`` 入口。"""
+from .cli import main
+
+if __name__ == "__main__":
+    main()

flowerui/api/routers/auth.py

@@ -0,0 +1,48 @@
+"""认证接口。"""
+from __future__ import annotations
+
+from fastapi import APIRouter, HTTPException, status
+from pydantic import BaseModel
+
+from ...core.config import settings
+from ...core.security import create_access_token, verify_basic_credentials
+
+router = APIRouter(prefix="/api/auth", tags=["auth"])
+
+
+class LoginRequest(BaseModel):
+    username: str
+    password: str
+
+
+class LoginResponse(BaseModel):
+    access_token: str
+    token_type: str = "bearer"
+    username: str
+
+
+@router.get("/config")
+async def auth_config():
+    """前端据此决定是否展示登录页。"""
+    return {
+        "auth_enabled": settings.auth_enabled,
+        "basic_auth": bool(settings.basic_auth),
+        "oauth2": bool(settings.oauth2_key and settings.auth),
+        "oauth2_redirect_uri": settings.oauth2_redirect_uri,
+        "auth_provider": settings.auth_provider,
+    }
+
+
+@router.post("/login", response_model=LoginResponse)
+async def login(payload: LoginRequest):
+    if not settings.auth_enabled:
+        return LoginResponse(
+            access_token=create_access_token("anonymous"), username="anonymous"
+        )
+    if not verify_basic_credentials(payload.username, payload.password):
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED, detail="用户名或密码错误"
+        )
+    return LoginResponse(
+        access_token=create_access_token(payload.username), username=payload.username
+    )

flowerui/api/routers/broker.py

@@ -0,0 +1,33 @@
+"""Broker 队列视图（对应 flower 的 /broker 页面）。"""
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from fastapi import APIRouter, Depends, HTTPException
+
+from ...core.celery_app import broker_uri, transport_driver
+from ...core.security import get_current_user
+from ...services.manager import ControlError, manager
+
+router = APIRouter(prefix="/api", tags=["broker"], dependencies=[Depends(get_current_user)])
+
+
+@router.get("/broker")
+async def broker_overview() -> Dict[str, Any]:
+    try:
+        queues = await manager.broker_queues()
+    except ControlError as exc:
+        raise HTTPException(exc.status_code, exc.message) from exc
+
+    return {
+        "broker_url": broker_uri(),
+        "transport": transport_driver(),
+        "mock_mode": manager.mock_mode,
+        "queues": queues,
+        "totals": {
+            "queues": len(queues),
+            "messages": sum(q.get("messages") or 0 for q in queues),
+            "consumers": sum(q.get("consumers") or 0 for q in queues),
+            "unacked": sum(q.get("messages_unacknowledged") or 0 for q in queues),
+        },
+    }

flowerui/api/routers/config.py

@@ -0,0 +1,98 @@
+"""配置查看与修改接口。
+
+- ``GET  /api/config``        分组返回全部配置项（敏感值脱敏）
+- ``PUT  /api/config``        批量修改，落盘后立即生效
+- ``POST /api/config/reload`` 不重启进程，重新应用最新配置来源并分级报告
+- ``POST /api/config/reset``  恢复到进程启动时的取值
+- ``GET  /api/config/ui``     免鉴权，供前端启动时读取界面默认值
+"""
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, List, Optional
+
+from fastapi import APIRouter, Depends, HTTPException, status
+from pydantic import BaseModel, Field
+
+from ...core.security import get_current_user
+from ...services import runtime_config
+
+logger = logging.getLogger("flowerui.config_api")
+router = APIRouter(prefix="/api/config", tags=["config"])
+
+
+class UpdateRequest(BaseModel):
+    changes: Dict[str, Any] = Field(default_factory=dict)
+
+
+class ResetRequest(BaseModel):
+    keys: Optional[List[str]] = None
+
+
+@router.get("/ui")
+async def get_ui_defaults():
+    """界面默认值。刻意不鉴权：登录页本身也需要按服务端默认主题渲染。"""
+    return runtime_config.ui_defaults()
+
+
+@router.get("")
+async def get_config(_user: str = Depends(get_current_user)):
+    return runtime_config.describe()
+
+
+@router.put("")
+async def update_config(payload: UpdateRequest, _user: str = Depends(get_current_user)):
+    try:
+        applied = runtime_config.update(payload.changes)
+    except runtime_config.ConfigError as exc:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(exc)) from exc
+    return {
+        "ok": True,
+        "applied": applied,
+        "message": f"已更新 {len(applied)} 项配置",
+        "config": runtime_config.describe(),
+    }
+
+
+@router.post("/reload")
+async def reload_config(_user: str = Depends(get_current_user)):
+    """不重启进程，重新读取并应用最新配置（app.conf / 环境变量 / CLI / TOML）。
+
+    适用于手工改了配置文件或注入了新环境变量、又不想重启服务的场景。
+    响应按「已热生效 / 需重启 / 仅下次启动」分级列出本次变更，前端据此提示。
+    """
+    try:
+        result = runtime_config.hot_reload()
+    except Exception as exc:  # noqa: BLE001 - 失败要给出可诊断的回包
+        logger.exception("配置热应用失败")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="配置热应用失败: %s" % exc,
+        ) from exc
+
+    parts = []
+    if result["applied"]:
+        parts.append("已即时生效 %d 项" % len(result["applied"]))
+    if result["requires_restart"]:
+        parts.append("需重启服务才能生效: %s" % "、".join(result["requires_restart"]))
+    if result["next_start_only"]:
+        parts.append("仅下次启动生效: %s" % "、".join(result["next_start_only"]))
+    result["message"] = "；".join(parts) if parts else "配置无变化，无需重启"
+    return result
+
+
+@router.post("/reset")
+async def reset_config(payload: ResetRequest, _user: str = Depends(get_current_user)):
+    restored = runtime_config.reset(payload.keys)
+    return {
+        "ok": True,
+        "restored": restored,
+        "message": f"已恢复 {len(restored)} 项配置的启动值" if restored else "当前没有被修改过的配置项",
+        "config": runtime_config.describe(),
+    }
+
+
+@router.post("/materialize")
+async def materialize_config(_user: str = Depends(get_current_user)):
+    """生成一份完整带中文注释的默认配置模板（保留手工键）。"""
+    return runtime_config.materialize()

flowerui/api/routers/control.py

@@ -0,0 +1,96 @@
+"""远程控制接口：worker 生命周期、进程池、队列消费、任务限流与撤销。"""
+from __future__ import annotations
+
+from typing import Optional
+
+from fastapi import APIRouter, Depends, HTTPException, Query
+
+from ...core.security import get_current_user
+from ...services.manager import ControlError, manager
+
+router = APIRouter(prefix="/api", tags=["control"], dependencies=[Depends(get_current_user)])
+
+
+def _wrap(fn):
+    async def runner(*args, **kwargs):
+        try:
+            return {"message": await fn(*args, **kwargs)}
+        except ControlError as exc:
+            raise HTTPException(exc.status_code, exc.message) from exc
+
+    return runner
+
+
+# ----------------------------------------------------------------------
+# Worker 控制
+# ----------------------------------------------------------------------
+@router.post("/worker/shutdown/{workername:path}")
+async def worker_shutdown(workername: str):
+    return await _wrap(manager.worker_shutdown)(workername)
+
+
+@router.post("/worker/pool/restart/{workername:path}")
+async def worker_pool_restart(workername: str):
+    return await _wrap(manager.worker_pool_restart)(workername)
+
+
+@router.post("/worker/pool/grow/{workername:path}")
+async def worker_pool_grow(workername: str, n: int = Query(1, ge=1)):
+    return await _wrap(manager.worker_pool_grow)(workername, n)
+
+
+@router.post("/worker/pool/shrink/{workername:path}")
+async def worker_pool_shrink(workername: str, n: int = Query(1, ge=1)):
+    return await _wrap(manager.worker_pool_shrink)(workername, n)
+
+
+@router.post("/worker/pool/autoscale/{workername:path}")
+async def worker_pool_autoscale(
+    workername: str,
+    min: int = Query(..., ge=1, alias="min"),
+    max: int = Query(..., ge=1, alias="max"),
+):
+    return await _wrap(manager.worker_pool_autoscale)(workername, min, max)
+
+
+@router.post("/worker/queue/add-consumer/{workername:path}")
+async def worker_queue_add_consumer(workername: str, queue: str = Query(...)):
+    return await _wrap(manager.worker_add_consumer)(workername, queue)
+
+
+@router.post("/worker/queue/cancel-consumer/{workername:path}")
+async def worker_queue_cancel_consumer(workername: str, queue: str = Query(...)):
+    return await _wrap(manager.worker_cancel_consumer)(workername, queue)
+
+
+# ----------------------------------------------------------------------
+# 任务控制
+# ----------------------------------------------------------------------
+@router.post("/task/revoke/{taskid}")
+async def task_revoke(
+    taskid: str,
+    terminate: bool = Query(False),
+    signal: str = Query("SIGTERM"),
+):
+    return await _wrap(manager.task_revoke)(taskid, terminate, signal)
+
+
+@router.post("/task/rate-limit/{taskname:path}")
+async def task_rate_limit(
+    taskname: str,
+    workername: str = Query(...),
+    ratelimit: str = Query(...),
+):
+    return await _wrap(manager.task_rate_limit)(taskname, workername, ratelimit)
+
+
+@router.post("/task/timeout/{taskname:path}")
+async def task_timeout(
+    taskname: str,
+    workername: str = Query(...),
+    soft: Optional[float] = Query(None),
+    hard: Optional[float] = Query(None),
+):
+    if soft is None and hard is None:
+        raise HTTPException(400, "soft 与 hard 至少提供一个")
+    return await _wrap(manager.task_time_limit)(taskname, workername, soft, hard)

flowerui/api/routers/dashboard.py

@@ -0,0 +1,106 @@
+"""Dashboard 聚合接口：概览卡片、趋势时间线、筛选项、任务分布。"""
+from __future__ import annotations
+
+import collections
+import time
+from typing import Any, Dict, List
+
+from fastapi import APIRouter, Depends, Query
+
+from ...core.config import settings
+from ...core.security import get_current_user
+from ...services.hub import hub
+from ...services.manager import manager
+
+router = APIRouter(prefix="/api", tags=["dashboard"], dependencies=[Depends(get_current_user)])
+
+
+@router.get("/dashboard/summary")
+async def summary() -> Dict[str, Any]:
+    return manager.dashboard_summary()
+
+
+@router.get("/dashboard/snapshot")
+async def snapshot(
+    since: int = Query(0, ge=0, description="事件游标，传上一次返回的 cursor 做增量拉取"),
+    timeline_limit: int = Query(120, ge=1, le=720),
+    events: bool = Query(True, description="是否附带事件流"),
+    event_limit: int = Query(120, ge=1, le=500),
+) -> Dict[str, Any]:
+    """一次请求拿齐 Dashboard 所需的全部实时数据。
+
+    这是「HTTP 轮询」模式的主力接口：语义与 WebSocket 首帧 snapshot 对齐，
+    额外带上事件游标，让轮询也能做到事件不重不漏。
+    """
+    payload: Dict[str, Any] = {
+        "summary": manager.dashboard_summary(),
+        "workers": manager.worker_rows(),
+        "timeline": manager.state.get_timeline(timeline_limit),
+        "server_time": time.time(),
+    }
+    if events:
+        payload.update(hub.recent(since=since, limit=event_limit))
+    else:
+        payload.update({"cursor": hub.cursor, "events": []})
+    return payload
+
+
+@router.get("/dashboard/timeline")
+async def timeline(limit: int = Query(120, ge=1, le=720)) -> Dict[str, Any]:
+    return {"points": manager.state.get_timeline(limit)}
+
+
+@router.get("/dashboard/filters")
+async def filters() -> Dict[str, Any]:
+    """前端下拉框选项：worker / 任务类型 / 状态 / 队列。"""
+    states = sorted(manager.state.totals().keys())
+    return {
+        "workers": sorted(manager.visible_worker_names()),
+        "task_types": manager.state.task_types(),
+        "states": states or [
+            "PENDING", "RECEIVED", "STARTED", "SUCCESS",
+            "FAILURE", "RETRY", "REVOKED",
+        ],
+        "queues": manager.active_queue_names(),
+        "columns": settings.task_columns_list,
+    }
+
+
+@router.get("/dashboard/task-distribution")
+async def task_distribution(top: int = Query(10, ge=1, le=50)) -> Dict[str, Any]:
+    """按任务名统计成功 / 失败 / 平均耗时，用于饼图与柱状图。"""
+    agg: Dict[str, Dict[str, Any]] = collections.defaultdict(
+        lambda: {"total": 0, "succeeded": 0, "failed": 0, "retried": 0,
+                 "revoked": 0, "runtime_sum": 0.0, "runtime_n": 0}
+    )
+    for task in list(manager.state.tasks.values()):
+        name = task.name or "unknown"
+        item = agg[name]
+        item["total"] += 1
+        if task.state == "SUCCESS":
+            item["succeeded"] += 1
+        elif task.state == "FAILURE":
+            item["failed"] += 1
+        elif task.state == "RETRY":
+            item["retried"] += 1
+        elif task.state == "REVOKED":
+            item["revoked"] += 1
+        runtime = getattr(task, "runtime", None)
+        if runtime:
+            item["runtime_sum"] += runtime
+            item["runtime_n"] += 1
+
+    rows: List[Dict[str, Any]] = []
+    for name, item in agg.items():
+        rows.append({
+            "name": name,
+            "total": item["total"],
+            "succeeded": item["succeeded"],
+            "failed": item["failed"],
+            "retried": item["retried"],
+            "revoked": item["revoked"],
+            "avg_runtime": round(item["runtime_sum"] / item["runtime_n"], 4)
+            if item["runtime_n"] else None,
+        })
+    rows.sort(key=lambda r: r["total"], reverse=True)
+    return {"data": rows[:top]}

flowerui/api/routers/monitor.py

@@ -0,0 +1,59 @@
+"""运维接口：Prometheus 指标与健康检查（对齐 flower /metrics、/healthcheck）。"""
+from __future__ import annotations
+
+import time
+from typing import Any, Dict
+
+from fastapi import APIRouter, Response
+from prometheus_client import CONTENT_TYPE_LATEST, generate_latest
+
+from ...core.celery_app import broker_uri, mask_url_password, transport_driver
+from ...services.manager import manager
+
+# 这两个端点不做鉴权，方便被 Prometheus / K8s 探针直接抓取
+router = APIRouter(tags=["monitor"])
+
+
+@router.get("/metrics")
+async def metrics() -> Response:
+    return Response(generate_latest(), media_type=CONTENT_TYPE_LATEST)
+
+
+@router.get("/healthcheck")
+async def healthcheck() -> Dict[str, str]:
+    return {"status": "OK"}
+
+
+@router.get("/api/system")
+async def system_info() -> Dict[str, Any]:
+    """系统信息面板：运行模式、broker、容量配置。"""
+    import platform
+    import sys
+
+    import celery
+
+    from ...core.config import settings
+
+    return {
+        "mock_mode": manager.mock_mode,
+        "broker_url": broker_uri(),
+        "transport": transport_driver(),
+        # 未配置 result backend 时 /api/task/apply 与 /api/task/result 无法取回结果，
+        # 这里显式暴露，避免用户对着 503 猜原因。
+        # 与 broker_url 一样必须脱敏：结果后端连接串常带密码，直接回显会泄露。
+        "result_backend": (
+            mask_url_password(settings.result_backend)
+            if settings.result_backend else None
+        ),
+        "result_backend_configured": manager.backend_configured(),
+        "events_connected": bool(manager.events and manager.events.connected),
+        "uptime": int(time.time() - manager.started_at),
+        "python_version": sys.version.split()[0],
+        "celery_version": celery.__version__,
+        "platform": platform.platform(),
+        # 只统计当前 broker_url 中的 worker；事件广播会混入其它 broker/db 的
+        # 心跳，foreign_workers_hidden 记录被隔离的数量，便于排障。
+        "workers_in_memory": manager.configured_worker_count(),
+        "foreign_workers_hidden": manager.foreign_worker_count(),
+        "tasks_in_memory": len(manager.state.tasks),
+    }

flowerui/api/routers/system.py

@@ -0,0 +1,55 @@
+"""系统级操作：重启后端进程等。"""
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel
+
+from ...core.security import get_current_user
+from ...services import restart as restart_service
+
+router = APIRouter(tags=["system"])
+
+
+class RestartResponse(BaseModel):
+    ok: bool = True
+    message: str = "后端正在重启，请稍候刷新页面"
+    mode: str = restart_service.MODE_RELAUNCH
+    container: bool = False
+    detail: str = ""
+
+
+@router.post("/api/system/restart", response_model=RestartResponse)
+async def restart_system(_user: str = Depends(get_current_user)) -> RestartResponse:
+    """重启后端 API 进程，使需要重启才生效的配置（监听端口、CORS、持久化、
+    认证、演示模式、事件采集等）真正落地。
+
+    策略由 ``restart_mode`` 决定，并在响应的 ``mode`` 字段回传：
+
+    - ``python-relaunch``（非容器默认）：用 ``sys.executable -m flowerui.relaunch``
+      拉起继任者进程（不经过任何 shell / shell 脚本），当前进程优雅退出，
+      继任者重新级联解析配置后接管服务；
+    - ``exit``（容器 / 编排器托管时默认）：**不创建子进程**，因为容器主进程
+      退出即容器终止，子进程会被一并杀掉。只让当前进程优雅退出，交由外部
+      重启策略（Docker / k8s / systemd / supervisord）重新拉起；
+    - ``disabled``：直接返回 409，不执行任何重启动作。
+
+    Celery worker 属于独立进程，其相关配置需另行重启 worker。
+    """
+    plan = restart_service.plan_restart()
+    if plan["mode"] == restart_service.MODE_DISABLED:
+        raise HTTPException(
+            status_code=409,
+            detail="界面重启已禁用（restart_mode=disabled）：请通过容器编排器或进程管理器重启服务。",
+        )
+
+    restart_service.restart_later(plan=plan)
+    if plan["mode"] == restart_service.MODE_EXIT:
+        message = "后端进程即将优雅退出，将由容器 / 进程管理器重新拉起，请稍候刷新页面"
+    else:
+        message = "后端正在重启，请稍候刷新页面"
+    return RestartResponse(
+        message=message,
+        mode=str(plan["mode"]),
+        container=bool(plan["container"]),
+        detail=str(plan["reason"]),
+    )