Skip to content

PUB-23-流水线部署流程.md

Latest commit

 

History

History
199 lines (160 loc) · 7.71 KB

PUB-23-流水线部署流程.md

File metadata and controls

199 lines (160 loc) · 7.71 KB
Raw

PUB-23 流水线部署流程

版本：v1.1 | 日期：2026-08-09（v1.0 于 2026-08-06） 对应需求：流水线编译上传后自动部署 v1.1 修订：移除"未配置节点时自动回退全部启用节点"，改为仅部署勾选节点、不回退、未勾选则标记 Failed（克制原则：一条流水线对应一个分支）

功能说明

流水线（AppPipeline）把「代码提交 → 编译 → 上传 → 部署」串成自动流程：

  1. 监听 Git 仓库 webhook 或用户手动触发。
  2. 向编译节点下发 deploy/compile/Build-Upload 命令。
  3. 编译节点拉代码、编译、打包、上传 zip 到 StarServer。
  4. StarServer 收到编译命令回包后，根据流水线设置决定是否自动部署。
  5. 若开启自动部署，向目标节点下发 deploy/install。

涉及实体

实体 说明
AppPipeline 流水线配置：关联应用部署集、编译节点、部署节点、分支、自动部署开关
AppPipelineRun 一次流水线运行记录，含状态、版本、起止时间
AppPipelineStep 单次运行中的步骤（Build / Deploy），记录命令Id与状态
AppBuildNode 编译节点配置
AppDeployNode 部署节点配置
AppDeployVersion 上传生成的应用版本
NodeCommand StarServer 下发给节点的命令
AppDeployHistory 部署历史日志

状态机

Pending -> Building -> UploadSucceeded -> Deploying -> Success
   |         |            |                  |         |
   |         |            |                  |         +-- 全部 Deploy 步骤成功
   |         |            |                  +-- 已下发 deploy/install
   |         |            +-- Build 命令成功（CommandReply）
   |         +-- 已下发 deploy/compile
   +-- 刚创建 run

失败分支：
Building/Deploying -> Failed（命令回包为错误或下发失败）
Building/Deploying -> Cancelled（用户取消）

完整流程

用户/Webhook
    |
    v
PipelineService.Trigger / HandleWebhookAsync
    |
    v
PipelineService.RunAsync
    |
    v
DeployService.Compile 下发 deploy/compile/Build-Upload
    |                              ^
    |                              |
    v                              |
DeployAgent.OnCompile              |
    |                              |
    +-- Git 拉取                   |
    +-- 编译项目                   |
    +-- 打包 zip                   |
    +-- UploadBuildPackageSync     |
        |                          |
        v                          |
    StarServer DeployController.UploadBuildFile
        |                          |
        +-- 保存附件                |
        +-- 创建/更新 AppDeployVersion
        +-- 写历史 "UploadBuildFile"
        |                          |
        v                          |
    StarClient 框架自动回复 CommandReply
        |                          |
        v                          |
NodeService.CommandReply           |
    |                              |
    +-- ProcessPipelineReplyAsync  |
        |                          |
        +-- 找到 Build 步骤        |
        +-- 写历史 "编译完成"      |
        +-- 取最新 AppDeployVersion |
        +-- 使用版本（app.Version） |
        +-- 判断是否 AutoDeploy    |
            |                      |
            +-- 否 -> Success     |
            |                      |
            +-- 是 -> Deploying   |
                |                  |
                v                  |
            DispatchDeployAsync    |
                |                  |
                +-- 仅按勾选的 DeployNodeIds 创建 Deploy 步骤
                +-- 未勾选任何节点则不下发、不回退（避免误部署）
                +-- 下发 deploy/install
                |                  |
                v                  |
            StarAgent 执行安装    |
                |                  |
                v                  |
            CommandReply（Deploy） |
                |                  |
                v                  |
            ProcessPipelineReplyAsync Deploy 分支
                +-- 写历史 "部署成功"
                +-- 全部完成 -> Success

自动部署判定规则

在 NodeService.ProcessPipelineReplyAsync 中：

条件 行为 历史记录
编译失败 run -> Failed，Remark=错误信息 -
编译成功但取不到版本 run -> Failed，Remark=未产出可部署版本 pipeline/autoDeploy 失败
编译成功且 AutoDeploy=false run -> Success，Remark=自动部署未开启 pipeline/autoDeploy 成功
编译成功且 AutoDeploy=true run -> Deploying，调用 DispatchDeployAsync pipeline/autoDeploy 成功
无可用部署节点 run -> Failed，Remark=未找到可部署节点 deploy/install 失败
部分节点下发失败 run -> Failed，Remark=部署命令下发失败 -
全部 Deploy 步骤成功 run -> Success deploy/install/Deploy 成功

部署节点选择规则（克制原则）

设计约束：一条流水线对应一个分支，部署范围必须显式、可控。 仅部署流水线「勾选」的部署节点，不自动回退到全部启用节点，避免误部署到非预期环境。

NodeService.DispatchDeployAsync 按以下规则选择节点：

  1. 仅使用 AppPipeline.DeployNodeIds（逗号分隔的 AppDeployNode.Id，即页面上勾选的节点）。
  2. 若 DeployNodeIds 为空：不下发任何部署命令、不回退，仅记录 pipeline/autoDeploy 失败日志；上层据此将 run 标记为 Failed（Remark=未找到可部署节点），不出现假成功。
  3. 以下节点会被跳过（Skipped）：
    • AppDeployNode 不存在
    • AppDeployNode 未启用
    • AppDeployNode.DeployId 与流水线不匹配
    • 对应 Node 不存在
  4. 命令下发异常会标记为 Failed。

关键代码位置

文件 职责
Stardust.Web/Services/PipelineService.cs 流水线入口：创建 run、下发编译命令
Stardust.Web/Services/DeployService.cs 编译/发布控制封装
Stardust.Server/Services/NodeService.cs 命令回包处理、流水线续跑、自动部署下发
Stardust.Server/Controllers/DeployController.cs UploadBuildFile 接口：接收 zip 并创建版本
DeployAgent/DeployService.cs 编译节点执行：拉代码、编译、打包、上传

日志与排查

关键历史 Action：

Action 含义
deploy/compile/Build-Upload 编译阶段完成
pipeline/version 取到/未取到可部署版本
pipeline/autoDeploy 自动部署判定与下发记录
deploy/install 部署命令下发/完成
deploy/install/Deploy 单个 Deploy 步骤成功

常见问题

上传成功但「没有触发部署」

现象：AppDeployHistory 中看到 UploadBuildFile 和 上传成功，但后续没有 deploy/install 或看到 部署完成 却没有实际安装。

常见原因：

  1. 流水线未开启「自动部署」。检查 AppPipeline.AutoDeploy。
  2. 流水线未勾选「部署节点」。当前版本遵循克制原则：未勾选任何节点则不下发、不回退，run 直接标记 Failed（Remark=未找到可部署节点），不会再出现"上传完成即假成功"的假象。
  3. 配置的部署节点不存在、未启用、或 DeployId 不匹配，导致全部 Skipped（仍会下发 0 个，run 标记 Failed）。
  4. 命令下发异常（如节点不在线），导致 Failed。

排查方法：

查看 AppDeployHistory 中 pipeline/autoDeploy 和 deploy/install 记录； 查看 AppPipelineRun.Remark 和 AppPipelineStep.Message。