# CloudPivot **Repository Path**: AC-DISL/cloud-pivot ## Basic Information - **Project Name**: CloudPivot - **Description**: CloudPivot - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-10-15 - **Last Updated**: 2026-11-02 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 云枢（CloudPivot） > 更新于 2026-11-02。本文件是项目上下文与交接的统一入口；开发操作约定见 [AGENTS.md](AGENTS.md)，详细材料见 [文档索引](docs/README.md)。 云枢使用 C++17，在 k3s/Kubernetes 和 OpenStack API 之上提供统一的任务调度、资源管理与资源监控服务。业务系统只调用云枢 REST API；用户提交单个批任务，指定一个具体云连接，随后查询状态、日志和结果，或发起取消。 项目借鉴 Sky Computing 的统一使用思路，以及 Primus 的组件解耦、状态管理和执行反馈。Primus 是设计参考，不是产品依赖。架构与规范用于团队协作，固定职责和公共行为，模块内部的文件、类与函数按实际需要设计。 ## 目标流程 ```text 业务系统 / yunshu-cli / 可选 Web │ HTTPS REST + JSON ▼ 云枢服务端 鉴权校验 → 持久化 → 后台控制与对账 │ 按指定 cloud_id 派发 ┌─────┴──────┐ ▼ ▼ k3s 适配器 OpenStack 适配器 │ │ Job → Pod Server → Runner → 业务程序 │ │ └── 状态、日志、结果反馈 ──→ 云枢 ``` 独立资源查询/操作和指标查询与任务控制并列，由相应端口接入平台。Runner 是虚机内独立的 C++ 进程，负责启动和跟踪程序，主动通过 HTTPS 反馈；虚机 ACTIVE 或 Runner 心跳均不等于业务成功。 ## 已确认范围 | 事项 | 基线 | |---|---| | 语言与部署 | C++17；管理后端面向 RISC-V Linux，板卡、发行版、ISA/ABI 待定；先连接其他云节点 | | 产品形态 | 单活动实例的独立 REST 后端、CLI、独立 Runner；已有本地执行、HTTPS 观测及显式网络执行，本地联调通过，Web/SDK 后续按需确认 | | 任务调度 | 单个批任务显式指定 cloud_id，在一个 k3s 或 OpenStack 接入范围运行；节点调度交给底层云 | | 执行方式 | k3s Job；OpenStack Server + 预置 C++ Runner，cloud-init 配合服务启动 | | 管理能力 | 任务、独立资源管理、资源指标；具体资源种类和写动作在对应阶段前明确 | | 数据边界 | 镜像、网络和存储预置；任务引用数据或卷，管理后端不承担大文件中转 | | 可靠性 | SQLite 单实例可重启恢复；默认不重跑业务；显式重跑产生新 Attempt，旧执行不确定时先核验 | | 使用与权限 | 同一组织内部业务系统，区分管理、提交和只读权限；Runner 反馈单独鉴权 | | 验证目标 | ≤5 个云连接、100 个在管任务；实际并行受云资源限制，性能须实测 | | 高可用 | 后续迁移 PostgreSQL，并补充租约、并发控制、接管与恢复验证 | 首期不做自动跨云择优或换云、跨云联合执行、分布式训练、多阶段工作流、常驻服务、镜像制作平台或大文件中转平台。管理后端、云节点、任务镜像和 Runner 的 CPU 架构分别验证；3～4 块荔枝派的集群方案仍是历史参考。 ## 当前进展 | 能力 | 状态与证据 | |---|---| | 工程基础 | 阶段 3 代码基线 909fa02；C++17/CMake，已有 yunshu-server、yunshu-cli、yunshu-runner 和独立模块目标 | | 任务接入 | container/vm 字段校验、7 个任务端点及 CLI、事件分页保留；VM 默认 Pending，完整连接并显式开启供给后可准备/关联 Server，已接独立 Runner 事件反馈，真实 VM 尚未验收 | | 持久化 | Task/Event/Attempt、事务与幂等；0008 冻结资源事实，0009 保存 Runner 身份，0010 保存心跳观测，0011 保存有序回执，0012 扩展终态材料与日志引用，0013 保存 Runner 停止等待截止。创建意图、凭据关联及发现的 UUID 先保存，再执行后续副作用；旧任务原文/哈希保留 | | 云执行 | Mock 生命周期和 k3s 真实 Job 闭环保留；Mock 不运行程序。OpenStack 已有 VM 供给及最小停止/回收，本地 HTTPS 联调通过，真实云未验收；显式网络 Runner 已将真实本地进程事实反馈到任务，实际 VM 环境待验收 | | OpenStack 认证 | 5.2 首个工作包已完成本地实现：连接配置、独立凭据文件、Keystone 项目认证、令牌缓存和服务目录选择；单次 --check-openstack 诊断及本机 HTTPS 联调通过，尚未连接真实云 | | k3s 环境 | 4.1 已核验本机 WSL 单节点 k3s v1.36.5+k3s1 / containerd 2.3.4，节点 Ready，API 为 https://127.0.0.1:6443；专用 cloudpivot-dev Namespace/受限账号、CA/临时令牌、固定摘要镜像，以及原生 Job 的退出码 0/7、日志和清理通过验证。4.2 已由云枢 CLI 提交真实 Job，UID 关联、字面参数和服务重启不重复创建验证通过 | | 云连接与执行模型 | 显式 cloudId 和固定平台绑定；Mock 与 OpenStack 供给开关默认关闭。k3s 完整配置启用 Job；OpenStack 仅配置不派发，开启后 ACTIVE 保持 Starting，不自动选云或重跑 | | 执行契约 | 5.4 已接身份/分配、HTTPS 心跳、五类事件、终态/日志引用及原文发件箱；显式执行开关与 --execute 串联原本地监督，Nova 引导材料、网络 systemd、Runner 优先停止及 5.6 恢复联调已接通，默认不执行 | | 资源与监控 | 独立资源管理和指标接口尚未实现；健康检查不是云资源监控 | | 安全与部署 | 已实现业务 Bearer/角色及独立 Runner 凭据鉴权，不能交叉使用。Runner 接口显式开启时要求业务鉴权、OpenStack 供给与回环监听，外部经 HTTPS；本机 TLS 入口测试通过，生产入口、虚机下发与 RISC-V 待验收 | | 本地验证 | WSL2 Ubuntu 22.04.5 x86_64，GCC 11.4、CMake 3.22.1、Python 3.10；固定 Drogon v1.9.14 及 trantor commit 已核对并构建 | | 测试与退出 | 上轮全量 33 个目标：普通用户 29 通过、4 root 项跳过；本轮相关回归 5 通过、4 root 项跳过（97.46 秒），扩展原生执行/停止/恢复/联合 root 专项另通过。覆盖 VM 异常/消失、监督丢失、模拟旧 boot、动作丢响应及两端重启；其他专项和离线包沿用有效证据，真实云与性能待验收 | | 离线部署 | 已提供 third_party 离线 SDK、来源/版本/校验及许可；CMake 从 SDK 构建，部署包携带 34 个直接及间接运行库；相对 RUNPATH、迁移目录及无外网的最小系统启动验证通过，当前仅验证 Ubuntu 22.04 x86_64 | **阶段 3/4 已验收；5.2、5.3 本地完成；5.4～5.6 的本地执行、停止与故障恢复联调已完成，下一步 6.1 资源/指标范围确认。** 真实 OpenStack 认证/供给、镜像预装、cloud-init 启动和网络隔离仍待环境验收，阶段 5 尚未整体完成。默认 VM Pending，仅供给模式 ACTIVE 保持 Starting；只有显式开启 runner.executionEnabled 且 Runner 使用 --execute 时才按分配启动一次业务。网络重连和 systemd 通信服务重启不重跑；原监督器保留预算并处理 stop；控制器等待 Runner 结果，固定窗口到期后才由云端停止。保留策略下的取消/超时需确认实例关机。日志只支持结果引用，当前未自动上传本地正文；终态 references=[] 表示没有已登记的外部日志。既有业务端点、TaskSpec 原文/哈希及默认不重跑规则保持。 云连接通过 cloudConnections 登记 id/backend；可选 k3s 段配置 HTTPS endpoint、namespace、caFile/tokenFile 后启用真实 Job 提交，仅登记仍不派发。配置和当前阶段限制见 [k3s 任务提交](docs/development.md#k3s-任务提交)。任务固定提交时的连接/平台，配置删除或改动不改变已有绑定和幂等重放。使用方式见 [指定云连接](docs/development.md#指定云连接)，新增示例见 [04-explicit-cloud.json](examples/tasks/04-explicit-cloud.json)。 OpenStack 配置与凭据见 [认证检查](docs/development.md#openstack-认证检查)，供给开关及无云环境测试见 [虚机供给](docs/development.md#openstack-虚机供给)。--check-openstack 只验证认证/目录，不监听或建库。默认启动不访问云；显式开启 openstackProvisioningEnabled 后才核验资源和供给 VM。云凭据与业务 Bearer、后续 Runner 身份分开。 模拟验证使用 [Mock 配置](configs/cloudpivot.mock.json) 和 [任务示例](examples/tasks/05-mock-lifecycle.json)，操作见 [模拟执行](docs/development.md#模拟执行)。后台按持久待办有界扫描，通过独立模拟资源记录核验状态；进行中的尝试重启后沿用原身份和计时，策略重跑才建立新尝试。HTTP 使用 2 个工作线程、最多 32 个排队请求，队列满返回 503；healthz 直接响应，不等待数据库锁。 [重试示例](examples/tasks/06-mock-retry.json) 通过已有 retryLimit 显式授权失败重跑；每次结束先保存结果和退避，再建立新编号/ID。退避为 1、2、4、8、16、30 秒并封顶，重启不重新计时。取消、总超时、观测不确定和结果重传不触发业务重跑；旧尝试清理独立推进，历史结果不会被新尝试覆盖。 [事件分页](docs/development.md#事件分页) 使用 `task events --after-seq 0 --limit 50`，分页响应含 nextAfterSeq，不带参数仍全量返回。增量读取保存最后已处理的 seq，空页不重置位置；游标不依赖内存，服务重启后可继续读取。 基础鉴权见 [使用说明](docs/development.md#基础鉴权) 和 [权限契约](docs/api-design.md#16-认证)：令牌验证后取得稳定 subject/role，换令牌不改变任务归属或幂等作用域；submittedBy 不作为身份。组织任务可共享读取，submitter 仅取消本人任务，admin 可取消旧任务。旧幂等键继续占用，认证请求命中时返回 409，避免启用鉴权后误重跑。此令牌用于访问云枢，与底层云连接凭据分别配置。 保留现有 `include/cloudpivot/`、命名风格和十一态；恢复、重跑、Runner 等行为按已确认范围统一。取舍见 [ADR-0006](docs/decisions/0006-project-consolidation.md)，当前运行契约见 [任务模型](docs/task-model.md) 和 [REST API](docs/api-design.md)。 [执行与 Runner 契约](docs/execution-contract.md) 供真实适配器共同遵循：容器镜像和虚机镜像分别表达；每 Attempt 凭据及服务端分配 GET 已实现，事件去重/原子确认、迟到隔离、持久发件箱和显式网络执行已实现。VM 示例为 [08-vm-pending.json](examples/tasks/08-vm-pending.json)；独立 Runner 本地示例为 [local-assignment.json](examples/runner/local-assignment.json)，真实服务分配由网络入口取得，本地示例仅供独立练习。结果清单及后续扩展随真实消费者补齐。 ## 下一步 1. **当前下一步为 6.1 资源与指标范围确认**：确定首批资源种类、查询/写动作、权限、指标来源和采样要求，再实现接口。沿用现有模块职责，不将底层 API 清单全部纳入首期。 2. **真实云验收继续待环境**：提供 OpenStack 测试项目、受限凭据、CA、镜像/规格/网络和配额，落实 Runner 的 HTTPS 通路；按依赖补真实认证、供给、镜像启动、停止及恢复。5.2～5.6 本地通过不等于真实云已验收，见 [准备清单](docs/development.md#vm-接入与-openstack-准备)。 3. 阶段 6 后续：资源 API、资源指标、数据/结果引用，以及压力和备份验证。 4. 阶段 7：实际 RISC-V 板卡验证，板卡确定后可提前做依赖构建探针。 详细验收与已知问题只在 [实施路线](docs/implementation-roadmap.md) 维护。沿用同事现有工程和有效验证证据，按本次改动及环境变化补充检查，不重复搭建框架。 待落实：团队负责人及排期、OpenStack 测试环境、板卡与系统、资源动作清单、指标来源与采样频率、数据任务的预置存储访问方式、HTTPS 入口及部署凭据发放。首期采用本地 Bearer，统一身份平台按将来的接入需求扩展；不自动给旧任务分配云或认领主体。 当前已有本机 WSL 开发环境及已核验的 k3s 测试集群；OpenStack 测试环境仍待准备。k3s 访问文件保存在 WSL 的 `~/.local/share/cloud-pivot/k3s-lab/`，准备与续期见 [操作说明](docs/development.md#k3s-环境)。本机 `local-path` StorageClass 已存在，本步无外部卷任务，尚未验证卷读写。[离线部署包](out/cloud-pivot-linux-x86_64.tar.gz)及其 [SHA256](out/cloud-pivot-linux-x86_64.tar.gz.sha256) 由打包脚本生成，out/ 不入库。已验证基线为 Ubuntu 22.04.5 x86_64、glibc 2.35；目标系统提供加载器、glibc、正常挂载的 /proc、DNS 配置与可信 CA。其他系统及 RISC-V 需分别构建和验证，操作见 [开发说明](docs/development.md#离线交付)，依赖规则见 [third_party](third_party/README.md#离线交付约定)。 ## 接力记录 本节只保留最近一次交接，完成任务后覆盖更新；详细改动由 Git 历史或工作区差异承载。接手流程见 [AGENTS.md](AGENTS.md#接力开发)。 | 项目 | 本次交接（2026-11-02） | |---|---| | 工作内容 | 完成 5.6 本地故障恢复联调，补 VM 异常/消失、监督器丢失、旧 boot 标识模拟，以及停止/删除已生效后丢响应和服务端 SIGKILL。已有机制满足本次已验证契约，本轮仅增加测试和说明，未改产品运行逻辑 | | 代码定位 | [恢复场景](tests/integration/runner_recovery_e2e.py) 复用现有 HTTPS/Nova/SQLite 设施，由 [原生执行专项](tests/integration/runner_execution_e2e.py) 调用。目标仍为 33 个，仅将该专项超时改为 210 秒；不增加生产故障接口、配置、状态机或依赖 | | 验证范围 | 构建通过、无编译告警；相关 CTest 9 个目标中 5 通过、4 root 项跳过（97.46 秒），扩展原生 root 专项另通过，包含原有最短 60 秒预算、systemd、停止和联合场景。上轮全量 29 项普通测试、其他 root 专项及离线包证据沿用，产品二进制/运行包未变，本轮未重打包 | | 恢复结果 | VM ERROR/非预期 SHUTOFF/消失为 Unknown，允许重试也不自动重建不确定执行；真实监督器 SIGKILL 不伪造退出。模拟旧 boot 保持分配/预算且不重新启动。os-stop 已生效后重启查询原 UUID 的 SHUTOFF，截止不重置、不重复发已生效动作；DELETE 已生效后重启确认不存在，原成功/Attempt/退出码及一次业务执行保持 | | 实际命令与证据 | WSL cmake --build "$build_dir" -j2；ctest --test-dir "$build_dir" -R 'runner|openstack_recovery' --output-on-failure；root python3 "$repo/tests/integration/runner_execution_e2e.py" "$build_dir/bin"。build_dir=~/.cache/cloud-pivot/offline-validated-build；日志 ~/.cache/cloud-pivot/stage5-recovery-{build,regression,native-tests}.log；源码仍为 D: 的 /mnt/d 映射 | | 版本与数据 | 阶段 5 的代码、迁移、测试与说明本次统一纳入 Git，版本以当前提交及 Git 历史为准；接力时获取完整提交。schema 13、既有迁移、REST/TaskSpec/Runner 协议及依赖版本均保持。新迁移及 Runner 服务模板固定 LF，避免跨平台检出改变迁移校验字节。数据库、两端私有材料及全部执行记录继续保留 | | 真实欠项 | VM 状态/电源由测试 Nova 模拟，跨 boot 只修改临时标识记录，实际宿主/VM 没有重启；真实认证、镜像/cloud-init、VM 重启、电源/宿主隔离及 HTTPS 入口仍待环境，不能将阶段 5 整体标成已验收。原生仍不自动上传日志 | | 下一步 | 唯一下一步为 6.1 资源/指标范围确认；确定首批动作及权限后实现资源 API。真实 OpenStack 欠项按环境补验，后续阶段 6 其余四步及阶段 7 四步继续沿路线推进 | 交接优先通过 Git 获取同一仓库版本，third_party/prebuilt 的离线归档已随阶段 3 代码提交；如另有未提交修改或新增文件，需一并说明和传递。部署时另传 out/ 中的程序包及校验文件。 ## 工程导航 ```text apps/ 程序入口 include/cloudpivot/ 公共声明：api、domain、ports、application、公共组件 src/ 领域/应用实现、服务端装配、CLI、基础设施 migrations/ 数据库迁移 configs/ 示例配置 deploy/runner/ Runner 手动部署模板 examples/tasks/ 当前 TaskSpec 示例 tests/ 单元与集成测试 cmake/、scripts/ 构建辅助与开发工具 third_party/ 固定版本依赖及来源说明 docs/ 专项设计、开发说明、决策与参考资料 ``` 代码与手动操作从 [上手练习](docs/hands-on.md) 开始，配有四个可提交的练习 JSON。构建、运行和自动化测试命令见 [开发与验证](docs/development.md)；目录职责和协作边界见 [目录与依赖](docs/directory-structure.md)。底层接口仅维护 [API 清单](docs/reference/cloud-api-list.md)，调用演示见 [API 示例](docs/reference/cloud-api-examples.md)，它们不定义云枢自己的 REST 接口。 工作区 `../learning/` 保留教学资料和 Primus 源码，不属于产品构建依赖。该目录不随单独克隆本仓库出现时，可按 [来源与版本记录](docs/references.md) 查找参考版本，不影响产品编译。 ## 术语 | 术语 | 含义 | |---|---| | Task / TaskSpec | 用户任务及要求；一次提交可能有多次明确允许的执行尝试 | | Attempt | 一次业务执行；请求重试、继续观测和结果重传不产生新的业务执行 | | CloudConnection / cloud_id | 一个已注册的集群或 OpenStack 接入范围；与 k3s/openstack 平台类型不同 | | Principal / subject | 认证得到的可信调用主体；subject 是稳定身份，不等同于令牌或任务文档中的 submittedBy | | Role | reader/submitter/admin 三类组织内权限；与主体身份分别表达，换令牌或改角色不改变任务归属 | | 执行配置 / ExecutionProfile | 本次执行实际使用的镜像、运行环境及云端参数；可直接保存生效配置，名称不表示需要独立版本管理平台 | | ExecutionRef | 某次尝试对应的 Job 或 Server 标识 | | ResourceRef | 含云连接、种类、作用域及归属的资源引用，区分创建与借用 | | Operation | 外部动作的意图与结果记录，按需要用字段或记录表达；任务相关动作先实现，独立资源请求随对应功能增加 | | Runner | 虚机内启动、跟踪和反馈业务程序的独立执行器 | | Runner 事件 / 心跳 | 事件是有序、可去重并需持久确认的执行事实；心跳是在线和进程观测，不能代替最终结果 | | 持久确认 / ackedSeq | 已原子接收的连续 Runner 事件序号；不是公开 TaskEvent.seq，也不表示资源已清理 | | 对账 | 比较持久化意图与云端事实，核验不确定结果并推进流程 | | 取消 / 清理 | 取消负责停止执行；清理按归属回收资源，二者分别跟踪 | 需求或进展变化后更新本文件对应条目和日期，不追加聊天记录。历史草案、PDF、测试报告和“已定稿”文字均不能代替当前明确的需求及实际验证。