架构示例 · 侧载接入 · v1.0 · 2026-11-14

示例工程架构 · 侧载接入

平台内建的角色只有两个:调度机(控制面)和开发机(执行面)。开发人员、测试人员、售后人员、CI 任务、脚本和外部系统都不是容器、也不注册为实例——各自持有一枚侧载令牌(sdl_…),调用路径为设备 → 控制面 → 该主机的根调度机 → 开发机。设备既不知道调度机地址,也不持有实例凭据。主机侧只保留通用能力——工作区、Agent 运行时、控制台命令和资源准入——不展示具体项目操作。

English
接入侧:一台设备 + 一枚侧载令牌 —— 无容器、不注册实例 开发人员 sdl_… · tasks:write · console:run 测试人员 sdl_… · tasks:write · tasks:read CI / 其他系统 sdl_… · 按需调用 API 售后 / 客户 sdl_… · tasks:read/write HTTPS · Authorization: Bearer sdl_… 任务调度机(控制面) 内建 · 唯一状态权威 · 令牌到此为止 侧载入口(PCS) 校验 Bearer sdl_ · scope 解析该主机的根调度机 任务 API POST /api/v1/tasks 状态 + 幂等键 状态机 QUEUED → ASSIGNED → RUNNING trace_id 全链路 队列与派发 Pull + 心跳 · 能力匹配 租约 · 超时 · 重试 文件通道 附件进 · 产物出 SHA-256 · 逐字节一致 PostgreSQL · 审计 任务状态的唯一来源 令牌创建 / 删除留痕 任务派发 · 心跳(Pull) 执行面 · 内建开发机 每台主机暴露相同的通用能力 —— 不展示具体项目操作。 开发机 01 host-runtime · 工作区 · 独立任务工作区 · Agent Profile / Shell · 控制台命令(按 scope) 内建 · 通用主机 开发机 02 host-runtime · 工作区 · 独立任务工作区 · Agent Profile / Shell · 控制台命令(按 scope) 内建 · 通用主机 开发机 03 host-runtime · 工作区 · 独立任务工作区 · Agent Profile / Shell · 控制台命令(按 scope) 内建 · 通用主机 横向扩容 · ×N 增加开发机 · 同一任务 / 租约路径 · 同一准入规则 · 同一产物通道 唯一的内建执行角色 文件通道 · 附件与产物 · 开发机把结果写在自己的工作区 · 调度机将其收集进产物通道 · 客户端凭 tasks:read 下载 · 不直连主机 · 校验 SHA-256 · 逐字节返回 附件反向流动:先上传到任务,再由开发机读取。 侧载系统 · 非内建 同一任务 API · 同一 scope · 同一审计 —— 无容器、无心跳、不占租约 CI / 构建任务 sdl_… · tasks:write · 提交 / 取消任务 · 读取构建机与队列 · 收集产物 测试自动化 sdl_… · tasks:write · 提交测试任务 · 轮询状态 · 下载产物 内部门户 / 工单 sdl_… · tasks:read/write · 创建任务 · 展示队列状态 · 关联产物 脚本 / CLI sdl_… · 按需授权 · 一次性任务 · 自动化 · 同一 HTTPS 路径 边界:无容器 · 无实例记录 · 无心跳 · 无租约 · 令牌以哈希保存 · 未知 scope 被拒绝 侧载客户端视角 一枚令牌,一台主机 HTTPS · 在控制面校验 scope · POST /api/v1/tasks · GET /api/v1/tasks/:id · POST .../attachments · GET .../artifacts 始终不知道调度机地址 客户 / 第三方 curl · 脚本 · 按需令牌 同一条侧载路径 主机网络策略 · 仅出站 开发机 · 不开放入站 访问依赖 · 不持有实例凭据 宿主机资源与保护 先准入再启动 · 资源状态独立于任务状态 · 单台宿主机 Host Resource Monitor 内建 · 短周期采样 · CPU / 内存 / 磁盘 / I/O · 容器健康 · PID 资源准入控制器 宿主 / 控制面 / 存储 / 余量 · 原子判定:预算 + 并发 · 不足 → QUEUED,不起容器 保护看门狗 host-watchdog.service · 独立进程 · 心跳丢失 → PROTECTING · 关闭准入 · 告警 claim 前资源准入 过载分级 独立于任务状态 NORMAL 正常调度 WARNING 降并发 · 轻量优先 THROTTLED 暂停高资源任务 PROTECTING 关闭准入 · 保护 PG RECOVERING 观察后渐进恢复 支撑面(内网) 仅调度机 / 开发机接入 · 侧载客户端不接入 · 全部内网 产物存储 报告 / 附件 · SHA-256 PostgreSQL 任务状态权威 · 审计 Redis 队列提示 · 可重建 LLM 网关 模型映射 · 配额 Secret Store 引用 · 不存明文 监控 指标 · 日志 · 看板
图例 侧载接入(设备 → 控制面) 任务派发 / 心跳(Pull) 文件通道(附件 / 产物) 主机网络策略(仅出站) 资源准入 / 看门狗 侧载边界(非内建)
① 持有侧载令牌→ ② 提交任务→ ③ 校验 scope→ ④ 调度机排队 / 派发→ ⑤ 开发机执行→ ⑥ 文件通道收集→ ⑦ 客户端下载产物

只有两个内建角色

平台只有调度机和至少一台开发机。开发人员、测试人员、售后人员、CI 任务、脚本和外部系统都通过侧载令牌进入,因此不需要为它们新增角色、容器或派发规则。

固定的调用链

设备只调用控制面;控制面校验令牌、解析主机及其根调度机,再转发请求。设备看不到调度机地址,也不持有实例凭据——与后台管理端走的是同一条路径。

侧载不是 Agent

它没有容器、不注册、不发心跳、不占租约。由于复用常规的任务 / 租约 / fencing 路径,它无法绕过调度、准入和审计。

主机保持通用并可横向扩容

每台开发机暴露相同的通用能力:独立工作区、绑定的 Agent Profile 或 Shell、scope 内的控制台命令,以及启动前的资源准入。扩容意味着增加主机,而不是定义新角色或项目专属操作。

权限天生最小

scope 是封闭集合:tasks:read、tasks:write、builders:read、queue:read、console:run。其中 console:run 需在 tasks:write 之上单独授予;未知 scope 会被拒绝而不是忽略。

文件双向流动

输入以附件上传,落到 <workspace>/attachments/。输出通过调度机的产物通道收集:任意格式,校验 SHA-256,逐字节返回,而不是塞进标准输出。