DCTS/docs/dynamic_cpu_slots_design.md

动态调整计算节点 CPU 核数（并发槽位）设计方案

状态：已实现（effective_max_slots + 心跳响应下发配额 + /api/admin/nodes/:node_id/quota + 节点详情管理弹窗）。下文为设计原文，保留作实现参照；实际实现以 crates/node/src/worker.rs、 crates/server/src/api/admin.rs、dashboard/src/components/nodesTable.js 为准。

1. 需求背景

目前 DCTS 的计算节点 (Worker) 在启动时通过本地配置确定最大计算槽位 (max_slots)，并在心跳和注册时上报给服务端。如果在不重启 Worker 进程的情况下，因为设备资源被其他用户借用等原因，需要临时减少该节点分发的任务数（即缩减 CPU 核数/并发槽位）。

2. 现有架构分析

• Pull 模式：任务的领用是由 Worker 主动发起 POST /api/task/claim 的。Worker 内部根据自身的 max_slots 控制并发领用的数量。
• 状态同步：Worker 定期发送 POST /api/node/heartbeat 汇报当前的 active_slots（正在运行的任务数）和资源负载。

因为是 Pull 模式，如果在服务端强行拒绝 claim（例如当节点的活跃任务超过管理员设定的配额时返回空），会导致 Worker 不断进行无效的轮询（Busy Loop），浪费网络和日志资源。因此，最优解是让 Worker 能够感知到服务端下发的配额上限，并动态调整其本地的并发控制器。

3. 设计方案：基于心跳响应的配额下发机制 (Heartbeat-based Quota Sync)

3.1 数据库与服务端改造

1. DB 结构更新： 在服务端的 nodes 表中新增一个可空字段 admin_max_slots (INTEGER, Nullable)，用于保存管理员强制指定的并发上限。
2. 新增管理 API：
   • 接口：POST /api/admin/nodes/:node_id/quota
   • 权限：Admin 角色
   • 请求体：{"admin_max_slots": 4}（传 null 表示解除限制，恢复节点的物理槽位上限）
3. 心跳响应扩展： 修改 POST /api/node/heartbeat 的响应结构，将 admin_max_slots 的值透传给 Worker：

   {
     "status": "ok",
     "admin_max_slots": 4  // 如果无限制，则为 null
   }
   

   注意：还需在 crates/common/src/models.rs 中为 NodeInfo 增加 pub admin_max_slots: Option<i32> 字段，确保 /api/admin/nodes 返回配额数据供 Dashboard 渲染。

3.2 Worker 节点改造

1. 解析心跳响应： 目前 Worker 的心跳线程（crates/node/src/worker.rs）忽略了响应体。需要在 crates/common/src/models.rs 中定义 NodeHeartbeatResponse 结构体，并在 Worker 中反序列化，提取 admin_max_slots。
2. 状态共享： Worker 并非使用 Semaphore 控制并发，而是依赖 Arc<AtomicI32> (active_slots) 计数。我们需要在 NodeWorker 的状态中新增一个 effective_max_slots: Arc<AtomicUsize>，以便心跳线程和领用线程共享配额信息。
3. 动态调整并发控制逻辑：
   • 心跳线程在收到心跳响应后，计算生效配额并更新：

     let target_slots = match admin_max_slots {
         Some(admin_limit) => std::cmp::min(admin_limit as usize, physical_max_slots),
         None => physical_max_slots
     };
     self.effective_max_slots.store(target_slots, Ordering::Release);
     

   • 任务领用（Claim）主循环的条件相应修改为：

     let active = self.active_slots.load(Ordering::Acquire);
     if (active as usize) < self.effective_max_slots.load(Ordering::Acquire) {
         // ... 领用任务 ...
     } else {
         tokio::time::sleep(Duration::from_secs(2)).await;
     }
     

   • 平滑降级：如果缩减时当前正在运行的槽位大于 target_slots，上述 if 判断会直接失败，Worker 自然进入 sleep 分支待命。无需强行中断物理计算任务，等现有任务结束后，数量便会自动回落到新配额以下，实现安全平滑降级（即便配额设为 0，也会安全地暂停接收新任务）。

3.3 前端控制台 (Dashboard) 改造

1. 保持表格原状： 外部节点列表的大表维持原状（“CPU 槽位”列仍然显示 占用 / 最大，不作修改，保持界面整洁）。
2. 重构操作列交互（收敛至统一弹窗）：
   • 将“管理操作”列中原有的“启用/停用”、“重发 Token”等多个离散按钮，统一替换为一个三个点 (More Options) 的 SVG 图标按钮。
   • 点击该按钮后，利用系统中现有的弹窗样式 (如 .modal-card) 弹出一个节点详情与管理 Modal。
3. 节点详情管理弹窗内容：
   • 基础信息展示：显示节点的详细状态、心跳时间、资源使用率等。
     • 槽位占用情况展示：如果没有配额限制，显示格式为 16/16（占用/最大）；如果有配额限制，显示格式为 12/12/16（占用/配额/最大），其中“最大”代表节点 .env 中 DCTS_MAX_SLOTS 设置的运行使用上限。
   • 修改配额 (CPU 核数)：提供表单供输入新的配额数字，调用 /api/admin/nodes/:node_id/quota 保存；或提供“清除配额”恢复运行使用的最大核数上限。
   • 节点调度控制：提供“暂停(停用)/启动(启用)节点”的操作按钮。
   • 安全管理：提供“重新颁发 Token”的操作按钮。

4. 方案优势

1. 平滑降级：不中断正在运行的 TLUSTY 任务，实现优雅缩容。
2. 网络高效：利用现有的高频心跳链路顺带下发配置，不增加额外的 RPC 接口，且避免了服务端阻断 claim 带来的无效轮询。
3. 职责清晰：Server 依然是状态中心，Worker 仍旧掌控并发调度，逻辑解耦。