BLSFlow docs

Appearance

设备与 Agent 管理模块 ​

1. 模块目标 ​

管理矿机生命周期内的在线接入、心跳、基础资源状态、远程控制和 Agent 执行通道，是平台连接真实矿机的基础设施层。

2. 模块边界 ​

对外提供 ​

  • 设备注册与接入
  • Agent 通信网关
  • 设备状态管理
  • 远程控制执行
  • 批量操作协调
  • 设备能力基线管理

不负责 ​

  • 调度策略判断
  • 收益计算
  • 门户展示逻辑

3. 核心对象 ​

  • 矿机
  • Agent 连接状态
  • 设备主状态
  • 控制命令
  • 命令执行结果
  • 单机能力基线

4. 核心流程 ​

  1. Agent 接入平台并建立通信通道
  2. 上报在线状态与资源状态
  3. 平台或调度服务下发控制命令
  4. Agent 执行动作并回传结果
  5. 更新设备事实状态和运行上下文

5. 手动切币链路中的职责边界 ​

在手动切币场景中，本模块的职责应收敛为“消费统一配置并执行”，而不是维护配置主事实。

最小链路可理解为：

  1. 控制台发起手动切币操作
  2. 数据与配置服务提供目标币种的可运行配置和适配边界
  3. 设备控制服务读取并消费这些配置
  4. 设备控制服务将配置转换为设备执行动作并下发给 Agent
  5. Agent 执行后回传结果
  6. 设备控制服务更新执行结果和机器运行上下文

这里的关键边界是：

  • 设备控制服务负责“如何执行”
  • 不负责“配置主事实归谁维护”
  • Agent 只负责本机执行，不负责决定目标币种或解析平台级业务规则

6. 对外能力 ​

  • 提供机器在线状态
  • 提供资源状态
  • 提供当前运行币种
  • 提供执行结果与失败原因
  • 提供 BMC 功耗数据或缺失状态

7. 依赖关系 ​

  • 被平台接入与控制台模块调用
  • 依赖币种与挖矿配置模块获取运行参数
  • 依赖调度与执行编排模块接收自动调度命令
  • 向收益数据与监控模块输出机器状态、功耗、运行上下文

8. 约束 ​

  • 负责“能否执行、如何执行、执行结果如何”
  • 设备主状态归本模块/服务持有
  • 不负责判断“为什么要切币”
  • 不负责维护币种、钱包、矿池、启动参数的主配置
  • 不负责在手动切币场景下自行生成另一套长期配置副本

9. 已知问题 ​

  • 当前已形成第一阶段 WebSocket 最小消息闭环、基于注册 token 的正式注册主链路、机器事实/硬件/指标/诊断快照落库、运行时自动生成稳定 agent_id 与 hostname、control 异常后的 Agent 自动重连、数据库离线状态回收，以及命令链路中未完成命令重投、重复结果幂等回写和超时后的自动重试/timeout 收敛；token 由控制台系统或外部预置提供，但完整控制台注册入口、生产级命令执行可靠性、高风险命令的细粒度幂等边界、更细粒度鉴权、心跳超时策略细化和更完整的硬件/功耗采集策略仍未细化
  • 当前尚未细化手动切币场景中配置读取能力的协议层和操作时序定义

10. 最近变更 ​

  • 2026-06-18：根据 T0075，集群创建/编辑 API（POST/PUT /api/clusters）同步维护分时电价；列表/详情回显 tariff_ready 与 tariff.periods；删集群级联删除 cluster_tariffs 与时段
  • 2026-04-03：根据系统骨架与服务边界生成模块文档
  • 2026-04-08：完成 Agent 与设备控制服务的第一阶段 WebSocket 通信闭环实现，当前采用写死鉴权与内存态状态存储
  • 2026-04-08：完成 Agent 服务端最小 MySQL 落库实现，当前采用引导账号归属策略和最小任务映射策略
  • 2026-04-08：完成 Agent 设备归属与注册映射第一阶段收敛，当前采用服务端显式 registration.agents 配置维护归属关系
  • 2026-04-08：完成正式设备注册 token 最小闭环，当前 Agent 首连通过注册 token 识别所属用户，registration.agents 降级为兼容兜底路径
  • 2026-04-08：移除仓库内的内部 token 工具，明确设备控制服务只负责识别 token、校验 token 与完成设备归属
  • 2026-04-09：补齐当前阶段验收闭环，Agent 定时上报机器事实、硬件明细、系统指标与功耗采样，设备控制服务将数据写入 machines、machine_hardwares、metric_powers、metric_systems，并支持 control 异常后的 Agent 自动重连
  • 2026-04-09：修复 Agent 身份与离线状态问题，agent_id 和 hostname 改为运行时自动生成；同机重装后基于稳定机器标识生成相同 agent_id；Agent 断连或心跳超时后，设备控制服务会将 machines.status 回收到 offline
  • 2026-04-09：补齐命令执行可靠性的第一阶段能力，设备控制服务会将命令先落库为 queued/running 状态；Agent 重连后可重新装载未完成命令；Agent 对重复命令直接重发已缓存结果；设备控制服务对重复结果回传按终态幂等处理
  • 2026-04-09：补齐命令超时与重试策略的第一阶段能力，设备控制服务支持按配置扫描超时 running 命令；在允许范围内重置为 queued 重试，超过上限后收敛为 timeout
  • 2026-04-10：补充手动切币链路中的职责边界，明确设备控制服务在该场景中只消费统一配置并执行，Agent 只负责本机执行与结果回传
  • 2026-04-17：控制台已开始消费 metric_miners 进行设备列表/详情算力趋势展示；该变更仅增加门户侧只读查询与展示，不改变 Agent 上报、设备控制服务入库和状态归属
  • 2026-04-14：控制台 PHP API 增加单台设备只读详情与批量改集群写入口（T0025），数据仍来自设备库既有表；远程 Shell 未接入设备控制命令链路
  • 2026-04-20：补齐 Agent 自升级最小闭环，设备控制服务可下发 upgrade_agent 结构化命令；Agent 在本机完成下载、哈希校验、二进制备份/替换并通过 systemd 重启自身；失败语义收敛为“替换前失败不影响旧版本继续运行”，当前仍需在真实 MySQL + systemd 环境补最终联调验证
  • 2026-04-29：控制台 Shell 作业详情页新增“全部 / 成功 / 失败”目标结果筛选；Portal API 的 rerun 入口支持可选 machine_ids，允许在保持原作业脚本与权限校验前提下，仅对原作业目标子集重建新作业；该变更仅增加门户筛选展示与 API 入口校验，不改变设备控制服务对作业事实和目标状态的主归属
  • 2026-05-21：新增机器诊断数据链路，Agent 可按 runtime.diagnostics_interval 周期上报 SEL 与硬件监控快照，设备控制服务提供异步主动触发入口并将最新数据写入 machine_sel_snapshots / machine_hardware_monitor_snapshots
  • 2026-05-28：新增 apps/api/scripts/metric_retention_cleanup.php，可定期清理 metric_miners、metric_powers、metric_systems 中 7 天前的历史采样数据；该变更仅补充运维清理入口，不改变 Agent 上报、设备控制服务入库与指标主事实归属