# 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-16 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 云枢(CloudPivot) > 更新于 2026-11-13。本文件是项目上下文与交接的统一入口;开发操作约定见 [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 块荔枝派的集群方案仍是历史参考。 ## 当前进展 **两步数据协同复核结论**:2026-11-12 两轮复核确认的 4 项结算/恢复反例与追加的客户端 `PUT` 在途杀停/恢复落盘失败反例(共 5 项独立探针、59 项检查)已全部修复并纳入常驻回归;修复与验收记录见[实施路线 §6.7](docs/implementation-roadmap.md#67-两步式数据协同恢复与事务边界加固2026-11-12-复核闭环)。 | 能力 | 状态与证据 | |---|---| | 工程基础 | C++17/CMake,交付 `yunshu-server`、`yunshu-cli`、`yunshu-runner`、`yunshu-k3s-data-wrapper` 四个可执行程序及按职责拆分的内部库目标 | | 任务接入 | container/vm 字段校验、`extensions.k3s` 生产安全白名单(`imagePullPolicy`、`imagePullSecrets`、`nodeSelector`)、9 个任务端点(及 5 个云资源/指标只读端点)与 8 个 CLI 任务子命令、事件分页保留;VM 默认 Pending,完整连接并显式开启供给后可准备/关联 Server,已接独立 Runner 事件反馈,真实 VM 尚未验收 | | 持久化 | Task/Event/Attempt、事务与幂等;首次启动缺失 `dataDir` 时自动以 `0700` 权限初始化;迁移 `0001`~`0019` 内嵌编译并做篡改校验(`0008` 冻结资源事实,`0009`~`0014` 保存 Runner 身份/心跳/回执/终态/停止截止/日志快照,`0015`~`0019` 保存无密钥数据执行计划、输入输出记录与单次身份绑定);主任务仓储 `ITaskRepository`、Runner 仓储 `IRunnerRepository` 与数据协同仓储 `IDataExecutionRepository` 三端口职责隔离;旧任务原文/哈希保留 | | 云执行 | 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 恢复联调已接通,默认不执行 | | 资源与监控 | 6.2 只读资源接口与 6.3 节点指标接口已本地完成:连接健康、节点容量/配额、规格/镜像及快照分页;k3s 节点 CPU/内存实际使用量指标(`GET /api/v1/clouds/{cloudId}/metrics`)及时效评估;OpenStack 遥测未定明确 unsupported;已整体回归。真实云/指标待环境验收 | | 存储与短期授权 | 已完成 `objectStorage.profiles` 准入、私有凭据文件 `0600` 校验、Query SigV4 短期预签名(输入 `GET` 与输出 `If-None-Match: *` 条件 `PUT`)及无 `secretKey` 流式 S3 客户端;50 项 TLS 契约与 RustFS HTTPS S3 真实互通已本地验证,目标环境存储待验 | | 数据计划与结果 | 已完成 `storageProfile` 云绑定准入、无密钥冻结执行计划、产物登记与 `GET .../result` / `yunshu-cli task result`(完整展示 64 位 SHA-256、字节大小与最终对象 URI)闭环 | | 数据控制 | 已由原 D1~D5 七步平行状态机重构收敛为**两步式数据协同**(`POST .../session` 获取冻结计划与批量短期预签名授权 + `POST .../complete` 服务端 S3 `HEAD` 核验与完成提交),通过独立端口 `IDataExecutionRepository` 与主任务仓储 `ITaskRepository` 分离,双云共享 `DataStagingClient`,在执行端私有暂存区持久保存必要的上传意图和待提交回执;**OpenStack VM + 本机真实 k3s v1.36.5(含 `wrapperInitImage` 零业务镜像侵入原厂 `busybox:1.37.0`)双端联合验收、失败分类与全链路脱敏验收均已通过**;k3s 与 OpenStack 数据任务提交生产默认均关闭 | | 任务查询闭环 | 6.4 已本地完成:`GET /api/v1/tasks/{taskId}/attempts` 与 `GET /api/v1/tasks/{taskId}/result`(支持可选 attemptId);`yunshu-cli task attempts` 与 `yunshu-cli task result`(支持 --attempt-id、--json、格式化表格);只读事务保证原子快照,退出码 0 准确保留,无数据任务 `outputs.status="unsupported"`,数据任务返回 `available`/`pending`/`unavailable` 及产物清单,全响应(含错误)返回 `Cache-Control: no-store` | | 验证增强与可靠性 | 6.5 本地审查通过:三轮压力记录已核对,应用 ENOSPC 已复测;原生 Runner/TLS 丢回执流程已实际接入备份/独立恢复并验证去重、预算/日志保留及一次执行。模拟云不代替真实 OpenStack 验收 | | 安全与部署 | 已实现业务 Bearer/角色及独立 Runner/k3s Attempt 凭据鉴权,不能交叉使用。Runner 与数据控制接口显式开启时要求回环监听,外部经 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 已核对并构建 | | 测试与退出 | 全量 51 项 CTest(44 项普通用户态 + 7 项 root 降权/真实 k3s 零侵入数据/`ENOSPC` 专项,另在 root 下复核 `unit.data_control` 真实 `65534` 降权)全部通过,离线包无外网 `chroot` 11 项隔离检查全部通过。普通用户在验证准入和引导后按设计跳过降权执行 | | 离线部署 | 已提供 third_party 离线 SDK、来源/版本/校验及许可;CMake 从 SDK 构建,部署包(`out/cloud-pivot-linux-x86_64.tar.gz`,以随包生成的 `out/cloud-pivot-linux-x86_64.tar.gz.sha256` 为准)完整交付 `yunshu-server`、`yunshu-cli`、`yunshu-runner`、`yunshu-k3s-data-wrapper` 四个二进制、34 个运行库、配置模板、备份恢复工具、VM 镜像加固模板与 k3s 零侵入初始化镜像构建脚本;相对 RUNPATH、迁移 0001 跨平台等价校验接管及无外网的最小系统 chroot 启动验证通过,当前仅验证 Ubuntu 22.04 x86_64 | **阶段 3/4 已验收;5.2~5.6 本地闭环完成,6.1~6.5 与数据扩展 D1~D4.3 本地闭环完成。D5 本地双端联合验收与离线交付通过。** 真实 OpenStack 认证/供给、镜像预装、cloud-init 启动和网络隔离仍待环境验收,阶段 5 尚未整体完成。默认 VM Pending,仅供给模式 ACTIVE 保持 Starting;只有显式开启 runner.executionEnabled 且 Runner 使用 --execute 时才按分配启动一次业务。网络重连和 systemd 通信服务重启不重跑;原监督器保留预算并处理 stop;控制器等待 Runner 结果,固定窗口到期后才由云端停止。保留策略下的取消/超时需确认实例关机。Runner 在终态事件提交前尝试回传固定日志快照(每路最多 256 KiB,首次入库起保留 24 小时),最多尝试三次且重启不重置;失败不伪造确认或阻碍终态。非空外部引用优先,无引用且未上传时 unavailable。既有业务端点、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 排队,承载公开 API 与 Runner 请求)与数据协同内部回调池 `kCallbackWorker`(4 线程 / 32 排队,承载 `/api/v1/data/*`),队列满返回 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) 供两个后端共同遵循。无数据 VM 示例见 [08-vm-pending.json](examples/tasks/08-vm-pending.json),S3 文件任务示例见 [k3s](examples/tasks/03-data-processing.json) 与 [OpenStack](examples/tasks/09-vm-data-processing.json)。显式启用数据执行后,执行端下载只读输入、上传独立产物,云枢登记并查询产物清单。 ## 剩余工作与依赖 阶段编号为 1~7,初始化另计阶段 0。阶段 6 的数据扩展 D1~D5 已完成本地联调。首期范围是 S3 兼容对象存储、只读输入与独立输出。目录递归、共享挂载和原位写回属于后续范围。目标环境的存储产品、权限和典型文件规模仍需确认。 | 阶段及状态 | 现在可以推进 | 依赖真实 OpenStack | 依赖真实 RISC-V | |---|---|---|---| | 1 工程基础:本机基线完成 | 维护构建、打包和部署材料,随新增功能做必要增量验证;无须重新建框架 | 目标云环境部署核验随阶段 5 | 目标 SDK/ABI/加载器及离线包在阶段 7 核验 | | 2 任务接入:完成 | 维护 TaskSpec、REST、CLI 兼容性 | 无独立待办 | 服务接入能力随阶段 7 实测 | | 3 执行与恢复:公共机制已有本地基线 | 维护上传预写对账恢复及事务截止时间/候选版本守卫 | 云端真实断连、实例故障与资源对账随阶段 5 验收 | 服务重启、资源占用和部署可靠性随阶段 7 实测 | | 4 k3s:任务执行与本地数据闭环完成 | 使用实际测试集群验证 Metrics API,归阶段 6 | 无依赖 | 板卡上的管理后端访问远端 k3s,归阶段 7 | | 5 OpenStack:适配器/Runner 本地联调完成 | 准备任务镜像、Runner/工作账号/CA、安装包和 HTTPS 入口方案;复用模板在普通 Linux VM 验证预装/自启。环境清单和验收任务先准备 | 真实 Keystone/目录/权限/配额,Glance 镜像、Nova/cloud-init/网络,程序执行/结果回传,停止/清理及实例故障恢复 | 管理后端在板卡访问远端 OpenStack 的验收归阶段 7 | | 6 管理与验证:两步协议及恢复加固本地完成 | 核验真实 k3s 指标、权限及样本时效,确认目标存储产品、权限和典型文件规模 | 验证 VM 实际数据与产物、资源目录及配额。OpenStack CPU/内存遥测须确认采集源与权限,目前返回 `unsupported` | 在目标板卡验证管理负载、备份恢复与离线交付 | | 7 RISC-V:未完成 | 现在可盘点依赖、选板卡/系统;目标明确后可在 x86 主机做交叉构建探针、制备对应 SDK/包 | 板卡上的最终 OpenStack 联合验收需真云;Mock/k3s 初验可先做 | ISA/ABI/系统与工具链冻结依赖目标确定;安装启动、依赖/网络/重启/性能与离线部署最终需真实板卡 | OpenStack 镜像预装可在普通 Linux VM 中先验证。RISC-V 可先选板卡、系统和工具链,明确 ABI 后做交叉构建并制备离线包。真实 k3s 指标验证需要目标集群提供 Metrics API 与对应权限。 通用资源写接口、Web、HA、自动择云、跨组织多租户及多阶段工作流不因本次整理自动纳入首期;独立资源管理继续按已确认只读范围,不为填满底层 API 清单新增功能。 ## 下一步 两步数据协议、执行恢复预写对账与终态事务边界已在本地闭环并纳入常驻回归,原有模块划分与协议边界继续沿用。后续推进以下环境准备与验收: 1. **独立于云环境的准备与核验**。核验真实 k3s 集群 Metrics API、权限与样本时效;确认目标 S3 兼容对象存储权限边界与典型文件规模;按需在普通 Linux VM 中先行验证加固镜像预装与 `yunshu-runner` 自启模板。 2. **真实 OpenStack 环境联调与验收**。OpenStack 环境就绪后验证 Keystone 认证与服务目录、Glance 镜像、Nova 供给与 `cloud-init`(`config_drive`)引导、Runner 跨机 HTTPS 通信、跨云数据任务及异常恢复与资源清理;同时落实 OpenStack 实际指标采集源。 3. **阶段 7 RISC-V 板卡移植与实机验收**。确定目标 RISC-V 板卡型号、发行版与 ISA/ABI,构建 `linux-riscv64` 离线依赖 SDK 与部署包,由板卡实机运行 `yunshu-server` 连接远端 k3s 与 OpenStack 双云集群,完成生命周期、数据协同、故障恢复与资源占用验收。 详细验收与已知问题只在 [实施路线](docs/implementation-roadmap.md) 维护。沿用同事现有工程和有效验证证据,按本次改动及环境变化补充检查,不重复搭建框架。 待落实:团队负责人及排期、OpenStack 测试环境、板卡与系统、后续资源写动作、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` 及其校验文件 `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-12,两步数据协议两轮审查缺陷闭环与常驻回归) | |---|---| | 完成内容 | 在保留两步数据协议(`/session` + `/complete`)、现有分层与迁移 `0001`~`0019` 的前提下,闭环修复两轮代码审查确认的 5 项并发/在途恢复/落盘错误与事务边界问题:① 云观测后刷新数据状态并在结算事务内增加预期候选摘要守卫(含空候选守卫与竞争重裁决);② `DataStagingClient` 在远端 `PUT` 前先于私有暂存区原子预写 `0600` 的 `output_recovery_state.json`(记录 `may_have_written` 上传意图、已完成状态与待提交完成请求),本地暂存/读取/落盘失败明确报错中止且不先写远端,`PUT` 在途被 `SIGKILL` 或 `/complete` 瞬断重启后先对账再续报,同时严格保留对预置外来冲突对象(含同大小同摘要)与退出后篡改/不安全文件的拒绝规则;③ 支持持久完成请求幂等重放及已鉴权空请求体 `/session` 只读完成收据快照(零 S3 授权签发、拒绝二次启动业务);④ 在 `CommitExecution` 与数据结算事务 `BEGIN IMMEDIATE` 内按事务时钟复核总 `deadline`,越界重裁决为 `Failed/timeout`(详见实施路线 §6.7) | | 常驻测试 | `tests/unit/data_control_test.cpp` 覆盖全部 5 套审查反例回归套件(共 8 套、341 项断言,含实际子进程 `PUT` 在途 `SIGKILL` 恢复、落盘失败零远端 `PUT` 与预置同哈希外来冲突拦截);`tests/integration/openstack_data_execution_e2e.py` 第 `6c-ter` 节覆盖真实 `yunshu-runner` 进程杀停重启与 `/complete` 丢回执双路径(`replay` / `readonly_session`)恢复及脱敏验收 | | 实际验证 | WSL `~/.cache/build/cloud-pivot` 增量构建零警告通过;全部 19 项 `unit.*` CTest 通过(`unit.data_control` 在普通用户态与 `root` 真实 `65534` 降权态均通过);审查方 `review_extended.cpp` 全部 5 项独立探针(59 项检查)0 失败通过;受影响集成测试(含 `root` 实跑 `integration.openstack_data_execution`、`integration.runner_network`、`integration.runner_outbox` 及非 `root` 的 `integration.s3_transport` 等)全部通过。未替代真实 OpenStack/RISC-V 环境验收 | | 交付范围 | 产品代码、常驻单元/集成测试与文档(`README.md`、`docs/implementation-roadmap.md`、`docs/api-design.md`、`docs/execution-contract.md`)已同步更新 | | Codex 实际复核 | 本轮代码复核未发现新增阻断项;WSL 必要目标增量编译通过,`unit.data_control`、`unit.s3_client`、`integration.s3_transport` 3 项全部通过(15.18s);保持原探针源码不变,重新编译并链接最新库,5 项独立探针/59 项检查全部通过,在途杀停结果为 `progressFile=1 result=available puts=2`。本轮未重复全量/root 集成测试 | | 下一步 | 推进真实 k3s Metrics/目标存储规模确认、OpenStack 环境联调验收与阶段 7 RISC-V 移植实测 | 交接优先通过 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、测试报告和“已定稿”文字均不能代替当前明确的需求及实际验证。