BLSFlow docs

Appearance

项目概览 ​

1. 项目目标 ​

blsflow 旨在为 CPU 矿机场景提供统一设备管理、收益驱动调度托管与维修记录留痕能力。

2. 当前阶段 ​

当前处于：需求边界已收敛，系统骨架与服务边界已完成第一版设计，并已完成 Agent 与设备控制服务之间的第一阶段 WebSocket 通信闭环、正式注册 token 主链路接入、核心设备数据表落库补齐、Control 异常后的 Agent 自动重连验收闭环、Agent 身份自动生成和离线状态回收修复、命令执行可靠性的第一阶段补齐、命令超时与重试策略的第一阶段收敛，以及 SEL/硬件监控诊断数据的周期上报与异步主动触发链路；同时已新增控制台前端工程与 PHP 账号服务工程，完成 email 注册、开发态邮箱验证与登录的最小闭环，并已补齐控制台侧设备注册 token 的创建、查看、作废与删除最小闭环、设备管理列表最小入口，以及 PHP 账号业务逻辑向 services/api 的迁移（账号库使用 MySQL）；控制台 Shell 作业详情现已支持目标结果筛选，并可按筛选结果定向重新执行。

3. 当前总体状态 ​

已完成 ​

  • 一期业务边界第一轮收敛
  • 核心用户与角色边界确认
  • 平台核心能力边界确认
  • Agent 基础职责边界确认
  • 调度模式与冻结语义确认
  • 收益、功耗、电价的核心口径确认
  • 系统一级模块骨架确认
  • 服务边界与状态归属确认
  • 文档驱动 AI 协作目录初始化
  • Agent 第一阶段 Go 工程骨架初始化
  • Agent 与设备控制服务第一阶段 WebSocket 通信闭环实现
  • Agent 服务端最小 MySQL 落库链路实现
  • Agent 设备归属与注册映射第一阶段收敛
  • 正式设备注册 token 最小闭环实现
  • 设备与 Agent 管理模块当前阶段验收闭环补齐
  • Agent 定时上报 machines、machine_hardwares、metric_powers、metric_systems 对应数据；上线硬件快照已从 CPU、内存、磁盘扩展到电源、PCIe 卡、网卡
  • Agent 定时上报 SEL 与 BMC 硬件监控诊断数据，设备控制服务支持 HTTP 异步主动触发并保存最新快照
  • Control 重启后的 Agent 自动重连主链路实现
  • Agent 启动时自动生成稳定 agent_id 与 hostname
  • Agent 断连后的数据库离线状态回收补齐
  • 命令执行链路的第一阶段可靠性补齐
  • Agent 重连后的未完成命令重投与重复结果幂等回写
  • 命令超时后的自动重试与 timeout 终态收敛
  • 设备控制服务命令重试次数与超时扫描频率配置化
  • 控制台统一正式入口、PHP API 后端形态与 email 账号最小闭环的产品约束收敛
  • 控制台前端最小工程初始化
  • PHP 账号服务最小工程初始化
  • email 注册、开发态邮箱验证与登录闭环实现
  • 控制台设备注册 token 创建、查看、作废、删除最小闭环实现
  • 控制台设备管理列表最小入口实现
  • PHP 账号服务 Microframe API 风格代码结构重构完成
  • 控制台账号业务逻辑迁入 services/api 并切换为 MySQL 账号库连接
  • 控制台会话后壳层已按 UI/账号基础信息/code.html 切换为浅色侧栏/顶栏框架（路由前缀 /console）；账号基础信息、订阅与席位、安全设置已按 UI/ 设计迁移；席位绑定/释放拆至 /console/billing/seat-activation；注册、登录、重置密码、邮箱验证使用白色科技风 AuthLayout
  • 控制台设备列表页集群筛选与集群管理（PHP API：/api/clusters、机器按集群筛选与 PUT /api/machines/{id}/cluster；关联表落在设备库 clusters / machine_cluster_rels）
  • 控制台设备列表页设备标签（PHP API：/api/tags、机器按标签筛选与 PUT /api/machines/{id}/tags / POST /api/machines/batch-tags；关联表落在设备库 tags / machine_tag_rels）
  • 控制台设备批量设置集群、单台只读详情页（GET /api/machines/{id} 聚合硬件、指标采样与可切换时间范围的算力图表）、Shell 作业入口
  • 控制台设备列表最近 1 小时算力趋势图：设备列表中用 sparkline 替换“设备编码”列，无数据为空
  • 控制台设备列表性能优化：首批最多加载 500 条设备，滚动到底部后继续分页续载，降低上千设备时的首屏卡顿
  • 控制台远程 Shell 真实下发最小闭环：创建作业（POST /api/shell-jobs）、作业详情（GET /api/shell-jobs/{id}）、单机执行记录（GET /api/machines/{id}/shell-jobs）；设备控制服务投递 run_shell 命令并回写 stdout/stderr/exit_code（截断），Agent 执行 bash -lc（超时/输出限流）
  • 控制台任务管理入口与 Shell 作业列表页：左侧新增“任务管理”，展示当前账号下 Shell 作业分页列表（GET /api/shell-jobs），并可跳转到作业详情页查看目标执行结果
  • 控制台 Shell 作业支持“重新执行”：复用原作业脚本与目标设备创建新作业（POST /api/shell-jobs/{id}/rerun），用于一键重试
  • 控制台 Shell 作业详情页支持目标结果筛选（全部 / 成功 / 失败），并让“重新执行”只作用于当前筛选范围内的设备；其中失败口径包含 failed 与 timeout
  • 手动切币与算力上报最小闭环（Switch Shell）：控制台按用户项目配置生成完整切币脚本并通过 run_shell 下发；脚本以 systemd 守护矿工进程并每 5 秒采样标准化算力 POST 到 Agent 本地 /api/v1/miner-stats；Agent 通过 WebSocket 转发到设备控制服务并写入 metric_miners
  • Agent 更新升级最小闭环：新增 upgrade_agent 结构化命令，Agent 可在本机完成下载、哈希校验、备份/替换二进制，并请求 systemd 重启自身；版本来源已抽到共享 build info，便于后续发布构建覆盖
  • Go 智能调度核心服务（apps/go-services/scheduler）：T0034 / T0044–T0065 已完成 dry-run 全链路、周期 tick、收益失败冻结、USDT/CNY 净收益、switch/stop/power_off execute、shell job 状态日志与基准采样切币编排；T0067/T0068 已完成控制台智能调度门户（策略管理 + 时间窗/资格/基准配置）；T0075 已将分时电价迁至集群 1:1 绑定（/console/clusters 创建/编辑配置）；生产前须 shadow dry-run 并停用 PHP tick 并行真实执行

进行中 ​

  • 搭建长期使用的文档驱动 AI 协作体系
  • 为后续设计/开发阶段沉淀标准文档模板
  • 逐步从设备与 Agent 管理模块起步进入实现阶段

未开始 ​

4. 当前核心用户 ​

第一阶段高频用户：

  1. 项目负责人
  2. 运维人员

当前暂定只有一个角色，登录后拥有全部权限。

5. 一期范围摘要 ​

5.1 设备范围 ​

  • 仅做 CPU 矿机
  • 设备异构是常态，不假设硬件标准化

5.2 平台能力 ​

一期平台需支持：

  1. email 注册、登录与邮箱验证
  2. 控制台统一入口访问
  3. 机器接入与统一管理
  4. 远程配置
  5. 切换挖矿任务 / 切币
  6. 启停机器
  7. 升级程序
  8. 批量调度
  9. 上报机器 CPU、内存、磁盘状态
  10. 维修日志管理

5.3 Agent 定位 ​

Agent 是平台核心基础设施之一，负责：

  1. 状态上报
  2. 接收控制指令
  3. 执行任务切换
  4. 执行升级、启停等动作

6. 当前业务口径 ​

6.1 币种边界 ​

第一阶段计划接入的币种：

  • xcb
  • qubic
  • 门罗

每个币种至少维护：

  • 币种名
  • 算法
  • 钱包地址
  • 矿池地址
  • 启动参数

6.2 调度模式边界 ​

  • 支持智能调度模式与手动模式
  • 智能调度开启后可在策略组选择两种子模式：保低电费调度（收益+集群分时电价）与 固定时间段调度（时间窗主决策，不看盈亏）
  • 分时电价在集群管理创建/编辑时配置（一集群一套），不在策略页单独绑定
  • 单台机器任意时刻只允许运行一个币种
  • 可将多台机器加入智能调度
  • 未加入智能调度的机器由用户自由操作
  • 智能调度仅能在平台已支持智能调度的币种范围内切换

6.3 调度目标与异常边界 ​

  • 目标：最大化扣除电费后的实时利润
  • 智能调度是自动执行型能力
  • 异常时优先保守
  • 关键依赖异常时默认停止整个调度域
  • 冻结后保持现状不动，并通知用户

6.4 收益口径 ​

实时净利润 = 产量 × 币价 - 机器能耗 × 电价

当前暂不考虑：

  1. 切换成本
  2. 停机损耗

6.5 数据口径 ​

  • 产量优先以矿池接口为准
  • 最小统计粒度暂定为 20 分钟
  • 功耗优先通过 BMC 获取，缺失时允许人工补充
  • 电费由用户手工录入，且存在分时电价

6.6 维修边界 ​

一期只做维修记录，不做备件库存与生命周期管理。 维修日志字段当前确认：

  1. 记录时间
  2. 处理人
  3. 故障描述
  4. 处理结果

7. 模块状态 ​

模块状态说明
平台接入与控制台模块开发中已明确统一正式入口边界，并完成控制台前端、账号入口、设备注册 token、设备列表与详情、远程 Shell 作业、挖矿/币种配置等；T0067/T0068 已接入 /console/smart-schedule 智能调度（策略、启停/解冻、dry-run/execute、日志 SSE、调度资格、时间窗、基准只读）；T0075 分时电价改在集群管理创建/编辑；T0071 已补齐席位状态查看与指定机器换绑，绑定/释放入口现位于 /console/billing/seat-activation；会话前账号入口已升级为白色科技风，控制台会话后壳层、账号基础信息、订阅与席位、安全设置已开始按 UI/ 浅色设计迁移；手动切币读取链路边界已由 T0015 收敛
设备与 Agent 管理模块开发中已完成 WebSocket 最小通信闭环、正式注册 token 识别、machines / machine_hardwares / metric_powers / metric_systems 基础落库、SEL 与硬件监控最新快照落库、control 异常后的 Agent 自动重连、运行时自动生成稳定 agent_id 与 hostname、Agent 断连后的数据库离线状态回收、命令链路中未完成命令重投、重复结果幂等回写和最小状态流转补齐，以及命令超时后的自动重试与 timeout 收敛；Agent 上线硬件快照已覆盖 CPU、内存、磁盘、电源、PCIe 卡、网卡；并已接入远程 Shell 作业真实投递与执行回写（run_shell）、Agent 自升级最小闭环（upgrade_agent）、设备注册自动占席/无席只读与控制作业席位门禁；生产级鉴权与更完整的高风险命令/指标可靠性策略仍待继续补齐
挖矿配置与币种配置模块开发中T0012–T0016 文档边界已闭合；T0027 三表 CRUD 已落地；资格主事实见 smart_schedule_resource_eligibilities
收益数据与监控模块开发中Go scheduler 通过外部 /v1/estimate + BLSFLOW_SCHEDULER_USDT_TO_CNY_RATE 形成 CNY 净收益；基准回填仍待设备指标能力
调度与执行编排模块开发中T0034 已完成 Go scheduler 周期 tick 与 execute 编排；T0071 已让 dry-run/execute 对未占有效席位机器输出 skip/no_active_seat 并避免生成真实动作；详见 apps/go-services/scheduler/README.md
维修记录模块已定义已收敛为最小可用留痕体系

8. 当前已知约束 ​

  1. 第一阶段是内部生产系统，不是面向市场的完整通用 SaaS
  2. 设备异构是常态，不是特例
  3. Agent 是平台核心基础设施
  4. 调度是自动执行型，而不是建议型
  5. 手动模式与智能模式会并存
  6. 当前收益模型允许先近似，不要求一开始绝对精准
  7. 默认不进入实现层，除非有任务文档显式授权
  8. 设备注册 token 由控制台系统或外部预置提供，设备控制服务不负责生成 token
  9. 用户所有正式业务操作应通过控制台完成
  10. 除 Agent 外，其它后端能力统一以 PHP API 提供
  11. 账号体系使用 email 注册登录，并需要邮箱验证闭环
  12. 当前邮箱验证仍为开发态本地文件邮箱方案，未接入真实邮件供应商

9. 当前痛点优先级 ​

  1. 设备太多难管理
  2. 人工切币太累
  3. 收益不透明

10. 下一阶段可选方向 ​

  1. 继续推进 PHP API 形态的数据与配置服务最小实现
  2. 继续接入控制台的配置管理与手动切币入口
  3. 继续细化高风险命令的幂等保护与去重边界
  4. 继续细化心跳超时策略、指标口径与异常处理闭环
  5. 继续补齐设备详情、控制动作与更完整的设备管理视图

11. 文档索引 ​

  • 全局规则：../AGENTS.md
  • 架构设计：./架构设计.md
  • 文档优先级：./standards/文档优先级.md
  • 开发规范：./standards/开发规范.md
  • 验收门禁：./standards/验收门禁.md
  • 反例清单：./standards/反例清单.md
  • 任务模板：./standards/任务模板.md
  • 模块文档：./modules/
  • 决策记录：./decisions/
  • 任务目录：../tasks/

12. 更新规则 ​

每次完成新任务后，如影响项目事实状态，需要同步更新：

  • 当前总体状态
  • 模块状态
  • 当前约束或新增约束
  • 下一阶段重点
  • 相关模块文档与决策记录