CI/CD 流水线

1. 页面概览

1.1 是什么

「CI/CD 流水线」页（对应前端源码 action/web/src/views/apollo/PipelinesPage.vue，页面标题「Apollo CI/CD 流水线」）是 LightApollo 的 GitOps 交付流水线管理台（对齐 TAD-03）。它把「定义一次流水线」到「观察一次运行逐步走完」的管理闭环收敛到一张表上：一条流水线定义本身不是可执行脚本，而是一个指针——它指向 Git 仓库（git_repo_id）内某个相对路径的流水线文件（pipeline_file_path，如 .apollo/pipeline.yaml），页面只维护「哪条仓库里的哪个文件、配了哪些 Triggers、当前是启用还是停用」；真正被读取执行的是仓库文件里声明的 stage / step（shell 命令或 lightapollo_deploy 部署触发）。这种「定义即代码」的形态让流水线的版本化、评审、回滚都跟随 Git 仓库走，页面本身不承载流水线内容。

在整个 Apollo 产品流程中，本页处于「Git 仓库与同步目标 → 流水线定义 → 运行 → 阶段 → 步骤 → 日志」的下钻链路中段：Git 仓库在「Git 仓库」页登记（本页下拉复用它），lightapollo_deploy 步骤最终落到 GitOps 同步目标触发一次部署（与「部署与漂移」页共享同一套 SyncEngine）；本页负责让用户发起执行（手动 run / external-trigger）并观察执行过程（运行历史、运行详情、逐步骤日志）。输入是用户在弹窗里填的定义字段或触发参数；输出是一条运行记录及其 stage/step/日志明细，可逐层穿透到「一次 shell 命令的退出码与输出」。

典型使用链路（演示视角的完整闭环）：① 先在「Git 仓库」页登记一个仓库并在其工作目录写好流水线文件（含 stage/step，deploy 步骤要声明 sync_target_id）；② 本页「新建流水线」填名称 + 仓库 + 文件路径 + Triggers（可选 JSON），列表出现一条 enabled（绿）定义；③ 点「运行」手动触发，若后端 worker 已启动则运行异步进入队列，展开该行「运行历史」能看到新运行（trigger=manual，pending→running）；④ 若步骤是 shell 命令，worker 逐 stage、逐 step 串行执行并把退出码与日志落库；若含 lightapollo_deploy 步骤，则转调 GitOps 部署触发；⑤ 点该运行行「详情」，弹窗展示运行概要（状态/触发类型/耗时/Commit/分支），运行中每 3 秒轮询自动刷新；⑥ 点步骤「日志」查看该步完整输出；⑦ 结束后可对进行中运行「取消」（杀进程树）或对定义「停用」（拒绝再次触发）；对不再需要的定义「删除」。

1.2 核心价值/能力表

1.3 一句话总结

本页把「Git 仓库里的流水线文件」变成一条可触发、可启停、可逐层下钻到退出码与日志的交付执行入口，定义与执行分离、观察与取消齐备。

2. 访问入口

2.1 路由与菜单

相邻页（侧边栏顺序）：制品管理 artifacts.md（前）、监控 monitoring.md（后）、Git 仓库 git-repos.md（下拉数据源）、部署与漂移 deployments.md（lightapollo_deploy 步骤的落点）。

2.2 认证与权限

• 路由 requiresAuth: true：未登录访问被前端路由守卫拦到 /apollo/login（登录态为独立 apollo_token，向后兼容回退读取旧 aip_token）。
• 后端各端点走 protected 组鉴权并按权限点细粒度控制：定义与运行的读接口（列表/详情/运行历史/运行详情/日志）要求 PermPipelineRead；写接口（创建/更新/删除）要求 PermPipelineWrite；执行接口（enable/disable/run/external-trigger/cancel）要求 PermPipelineExecute。Git 仓库下拉走 PermGitRepoRead。
• 前端 401 由 apolloClient 响应拦截器清除 token 并跳转登录页；403 统一 alert('无权限执行该操作')，页面 catch 再兜底弹错误条。

2.3 端口与 API 前缀

• Apollo 后端端口 18082；Vite 把 /apollo-api 代理到 18082。
• 客户端 baseURL /apollo-api/v1，请求自动附带 Authorization: Bearer <apollo_token>；响应统一 envelope {code,message,data,request_id}，拦截器在 code===0 时把 response.data 解包为业务数据，页面 const { data } = await apiClient.get(...) 直接拿业务数据。项目 id 目前用常量 PROJECT_ID = 1（default 项目），所有定义类路径都以 /projects/1 前缀拼装。

3. 界面布局

┌─────────────────────────────────────────────────────────────┐
│ Apollo CI/CD 流水线                              [新建流水线]  │
│ [顶部说明 alert-info（定义指针 + 可运行/外部触发/启停 说明）]      │
│ [操作结果提示条（v-if alert.message，可「关闭」）]              │
├─────────────────────────────────────────────────────────────┤
│ ┌ 流水线定义列表（loading / 空态 / 表格 三态卡片）────────────┐ │
│ │ ▸运行历史 | ID | 名称 | Git 仓库 | 流水线文件 | Triggers |  │ │
│ │            状态 | 创建时间 | 操作                          │ │
│ │ 操作列：启用/停用 | 运行 | 外部触发 | 编辑 | 删除            │ │
│ └─────────────────────────────────────────────────────────┘ │
├─────────────────────────────────────────────────────────────┤
│ ┌ 运行历史子区（流水线行展开后显示，按行 v-for）───────────────┐ │
│ │ [刷新] 运行历史（N）— 流水线 {name}                        │ │
│ │ 运行号 | 触发类型 | 状态 | 耗时 | Commit | 分支 | 开始时间 |  │ │
│ │          操作（详情 / 取消）                              │ │
│ └─────────────────────────────────────────────────────────┘ │
├─────────────────────────────────────────────────────────────┤
│ ┌ 新建/编辑流水线弹窗（modal）───────────────────────────────┐ │
│ │ 名称（name）* | Git 仓库（git_repo_id）* |                  │ │
│ │ 流水线文件路径（pipeline_file_path）* | Triggers（JSON可选）│ │
│ │ [取消] [创建/保存]                                        │ │
│ └─────────────────────────────────────────────────────────┘ │
│ ┌ 外部触发弹窗（modal）─────────────────────────────────────┐ │
│ │ Commit SHA（git_commit_sha）| 分支（git_branch）           │ │
│ │ [取消] [触发]                                            │ │
│ └─────────────────────────────────────────────────────────┘ │
│ ┌ 运行详情弹窗（modal-lg）──────────────────────────────────┐ │
│ │ 运行概要（状态/触发/耗时/Commit/分支/开始时间）             │ │
│ │ （running 时）「运行中」徽标 + 每 3 秒自动刷新…             │ │
│ │ Stages（N）表：顺序 | Stage 名称 | 状态                    │ │
│ │ Steps（N）表：Step 名称 | 类型 | 状态 | 退出码 | 操作(日志) │ │
│ └─────────────────────────────────────────────────────────┘ │
│ ┌ 日志弹窗（modal-lg）──────────────────────────────────────┐ │
│ │ 深色 code block（logModal.content / 「（无日志内容）」）    │ │
│ └─────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘

各板块职责：

4. 交互元素

4.1 页头、顶部说明与操作结果提示条

提示条形态：<div class="alert" :class="alert.type">，类型有 alert-info（默认）、alert-success、alert-error。页面所有成功反馈用 success、失败用 error。每条关键路径文案在 4.2~4.11 逐条列出（按钮文字、提示文案与源码逐字一致）。

4.2 流水线定义列表卡片

加载三态：loading 时显示「加载中...」；pipelines.length===0 时显示 暂无流水线定义，点击"新建流水线"添加（项目 #{{ PROJECT_ID }}）。；有数据渲染表格。列头依次为 （展开按钮）/ ID / 名称 / Git 仓库 / 流水线文件 / Triggers / 状态 / 创建时间 / 操作。单元格渲染细节：名称加粗；Git 仓库列 repoLabel(field(p,'git_repo_id'))——先去 repos 里按 id 找名称显示 {r.name}（#{r.id}），找不到则显示 #<id>，空则 -；流水线文件列等宽字体并超长省略；Triggers 列取 triggers（别名 trigger_config），JSON.stringify 后超 40 字符截断加 …；创建时间 formatTime 去掉 T 截取前 19 位，空则 -。

4.3 「新建流水线」/「编辑流水线」弹窗与保存

「新建流水线」打开 create 模式，标题 新建流水线（项目 #{{ PROJECT_ID }}）；行内「编辑」打开 edit 模式，标题 编辑流水线 #{{pipe.id}}（项目 #{{ PROJECT_ID }}）。两模式共用一套表单与保存逻辑。

保存流程（提交按钮文案 create 模式「创建」/ edit 模式「保存」，busy==='savePipe' 时显示「保存中...」并禁用；旁边「取消」纯关闭弹窗不清表单，右上「关闭」同）：

① 空校验（源码文案 名称（name）、Git 仓库（git_repo_id）与流水线文件路径必填）；② Triggers JSON 校验，非法提示 Triggers 不是合法 JSON，请检查格式（error）不发请求；③ busy='savePipe' → buildPayload() 组装 → create 调 POST /projects/1/pipelines，edit 调 PUT /pipelines/{pipe.id}；④ 成功 create 提示 流水线创建成功${newId?（id=${newId}）:''}（success，newId 取 data.id || data.pipeline.id，create 响应为创建的完整定义对象故必有 id），edit 提示 流水线 #${id} 更新成功（success）；随后关闭弹窗并 fetchPipelines() 刷新列表；⑤ 失败提示 保存流水线失败：<后端 message>（error）。

后端语义：create 时 (project_id, name) 复合唯一冲突返回 409 DUPLICATE_ENTRY（文案 流水线定义 (project_id=1, name=xxx) 已存在）；pipeline_file_path 为空时后端兜底默认 .lightapollo.yml；状态默认 enabled。update 为指针字段全量更新（前端 PUT 时把 name/git_repo_id/pipeline_file_path/triggers 全量带上）。

4.4 「启用」/「停用」按钮

操作列第一个按钮按当前状态显示反向动作：pipeEnabled(p) 为真显示「停用」、否则显示「启用」。

4.5 「运行」（手动触发）

行内「运行」按钮直接触发（无二次确认、无中间弹窗），busy='run-{id}'。

手动 run 的后端行为：定义不存在 → 404；定义 disabled → 400；定义 enabled → 建 run（run_number=max+1、status=pending、trigger_type=manual、triggered_by=当前用户名缺省 manual/system、started_at=now）→ 读取并解析仓库内流水线文件：文件缺失/解析失败则运行直接置 failed 并返回错误；解析成功则提交 worker 队列（worker 池已启动时异步）或同步 executeRun（未启动时，便于单机/自测）。

4.6 「外部触发」弹窗

行内「外部触发」打开弹窗，标题 外部触发：{{pipe.name}}（#{{pipe.id}}）。这是为「外部系统/GitOps 同步引擎代发」设计的入口——只执行流水线里的 lightapollo_deploy 步骤，跳过 build/test。

后端 external-trigger 行为（ExternalTrigger，同步执行于请求内、不经 worker 队列）：定义 disabled → 400 流水线 "%s" 已禁用，拒绝外部触发；enabled → 建 run（run_number=max+1、trigger_type=external、status=running、started_at=now）→ 解析流水线文件（失败则 run 置 failed 返回错误）→ 逐 stage 先建一条 skipped 的 stage_run，仅对其中的 lightapollo_deploy 步骤建 running 的 step_run 并调用 runDeployStep（经 DeployTrigger.TriggerDeploy(sync_target_id, triggered_by) 触发 GitOps 部署）：任一 deploy 步骤失败 → 该 stage 与 run 置 failed；全部成功 → stage 置 success、run 置 success。返回的 run 对象此时已是终态（success/failed）。

4.7 「删除」

4.8 运行历史子区（行展开）

每行展开后渲染 .runs-block 子区，头部 运行历史（{{runsMap[p.id]?runsMap[p.id].length:0}}）— 流水线 {{p.name}} + 右侧「刷新」按钮（loadRuns(p.id, true) 强制清缓存重拉）。三态：runsLoading[p.id] 显示「加载中...」；空显示 暂无运行记录，点击"运行"或"外部触发"发起一次运行。；有数据显示表格。运行表列头 运行号 / 触发类型 / 状态 / 耗时 / Commit / 分支 / 开始时间 / 操作。

运行状态徽标（RUN_STATUS_META class 映射，未知灰）：running/pending/queued 蓝（status-registering）；succeeded/success/completed 绿（status-online）；failed/error 红（status-revoked）；canceled/cancelled 灰（status-offline）。后端实际产出的 run 状态为 pending/running/success/failed/cancelled（另有常量 skipped 供未来扩展），页面映射表冗余覆盖了 succeeded/completed/canceled/error/queued 等别名以便兼容。

4.9 「详情」与运行详情弹窗

点击「详情」openRunDetail(run)：先 stopPoll() 清理旧定时器，置弹窗 loading，调 GET /pipeline-runs/:id，parseRunDetail 解析后填入弹窗；若运行 isRunActive 则 setInterval(refreshRunDetail, 3000) 启动 3 秒轮询。弹窗标题 运行详情：'#' + run_number。

弹窗内容自上而下：

• 运行概要（.run-summary 网格六项）：状态（徽标）/ 触发类型 / 耗时 / Commit / 分支 / 开始时间，取值与运行历史行一致。
• 轮询提示：runModal.pollTimer 非空时显示 <span class="status-badge status-registering">运行中</span> 每 3 秒自动刷新…。
• Stages（N）：stages.length===0 时显示 暂无 Stage 信息。；否则表格列 顺序（order，别名 stage_order/index）/ Stage 名称 / 状态。
• Steps（N）：steps.length===0 时显示 暂无 Step 信息。；否则表格列 Step 名称 / 类型（step_type/type）/ 状态 / 退出码（exit_code，空显示 -）/ 操作（日志按钮）。

parseRunDetail 的宽松解析链：run 本体取 data.run || data.pipeline_run || data；stages 取 data.stages（别名 stage_runs）、steps 取 data.steps（别名 step_runs）；两者都空时再从 run 本体里找；steps 仍空但 stage 内含 steps 时扁平展开补齐（for s of stages: push(...s.steps)）。也就是说前端有能力消费嵌套 stage/step 的响应——但当前后端 GET /pipeline-runs/:id 只返回 run 本体（无嵌套，且 GetStageRuns/GetStepRuns 未注册 HTTP 路由），所以弹窗 Stages/Steps 恒为 0、日志按钮不可达（见 8 章）。

4.10 「日志」按钮与日志弹窗

Step 行内「日志」viewStepLog(step)：runId 取 runModal.run.id，stepId 取 step.id || step.step_name || step.name；调 GET /pipeline-runs/:id/logs/:step_id（stepId encodeURIComponent 编码）。成功弹窗标题 步骤日志：{step_name||stepId}，正文深色 code block 展示全文；内容为空显示 （无日志内容）。

parseLog 兼容形态：原始字符串直接返回；否则取 content || log || logs || text，都不是则 JSON.stringify 兜底。失败提示 加载日志失败：<message>，内容置空。

4.11 「取消」运行

后端取消语义：仅 pending/running 可取消（pending 排队中的运行尚无进程，直接置 cancelled）；running（worker 正在执行某 step）时先落库 cancelled，再经 runner 的 ProcessTracker.KillRun 终止该 run 所有活跃 step 子进程（进程树）——先置 cancelled 再杀进程，worker 在每步执行前检查 cancelled，避免取消后新起进程；kill 失败仅记日志降级（不影响取消语义）；已终态运行取消是幂等 no-op。executor 侧 finishRun 守卫 cancelled 终态不被后续 success/failed 覆盖。

5. 后端关联

5.1 API 客户端

action/web/src/api/apolloClient.js：axios 实例 baseURL /apollo-api/v1、timeout 30000ms、请求拦截器对所有请求附加 Authorization: Bearer <token>（token 取 apollo_token，无则回退 aip_token）。响应拦截器：HTTP 2xx 且 code===0 时把 response.data 替换为业务数据（页面 const { data } = ... 直接得到业务对象/数组）；HTTP 2xx 但 code!==0 拒绝；4xx/5xx 提取 body.message || body.error 并把 message 别名写入 error.response.data.error 后 reject——401 清 token 并跳 /apollo/login（登录页自身 401 不跳，避免死循环），403 alert('无权限执行该操作')。页面各 catch 统一用 errMsg(err)（err.response.data.message || err.response.data.error || err.message || '未知错误'）展示后端错误。

5.2 端点表

端点注册于 action/products/apollo/server/server.go protected 组（流水线定义/运行 878-891 行），全部为权限点映射路由；页面只使用上述带「页面触发点」的行。

5.3 响应结构示例

统一 envelope 成功形态（拦截器已解包，业务代码只见 data）：

{ "code": 0, "message": "ok", "data": { "id": 3 }, "request_id": "req_b63f..." }

字段说明：code 0 恒为成功；message 固定 ok；data 业务数据；request_id 全链路追踪 ID（req_+unix 毫秒+4 位 hex，也写响应头 X-Request-ID）。创建类接口 HTTP 201，其余 200。定义列表 data 直接是数组（ok(c, list)）；页面 toList 仍兼容 {items,...} 双形态以防其它页/未来分页变化。

流水线定义对象（GET /projects/:id/pipelines 列表项与 create/update 响应，即 pipeline.PipelineDefinition）：

{
  "id": 3,
  "project_id": 1,
  "name": "deploy-to-prod",
  "git_repo_id": 2,
  "pipeline_file_path": ".apollo/pipeline.yaml",
  "triggers": [
    { "type": "git_push", "branch": "main" },
    { "type": "schedule", "cron": "0 2 * * *" }
  ],
  "status": "enabled",
  "created_by": "admin",
  "created_at": "2026-09-07T09:00:00+08:00",
  "updated_at": "2026-09-07T09:00:01+08:00"
}

字段含义：id 主键；project_id 所属项目（页面固定 1）；name 定义名（项目内唯一）；git_repo_id 关联 Git 仓库；pipeline_file_path 仓库内流水线文件相对路径（后端缺省 .lightapollo.yml）；triggers 触发配置 JSON（git_push/schedule/manual/external，页面仅记录展示不执行判定）；status enabled/disabled；created_by 创建用户名；created_at/updated_at 时间戳。页面行内 Git 仓库列按 git_repo_id 去 repos 下拉数据里查名称（查不到显示 #id）。

Git 仓库对象（GET /projects/:id/git-repos 列表项，即 gitops.GitRepository，仅作为本页下拉数据源）：

{
  "id": 2,
  "project_id": 1,
  "name": "apollo-demo-repo",
  "url": "D:/work/apollo-demo-repo",
  "auth_type": "none",
  "default_branch": "main",
  "sync_interval_seconds": 0,
  "status": "active",
  "last_sync_at": null,
  "created_at": "2026-09-07T08:00:00+08:00"
}

运行对象（POST /pipelines/:id/run、POST /pipelines/:id/external-trigger、GET /pipelines/:id/runs 列表项、GET /pipeline-runs/:id 本体，即 pipeline.PipelineRun）：

{
  "id": 12,
  "definition_id": 3,
  "run_number": 5,
  "trigger_type": "manual",
  "git_commit_sha": "",
  "git_branch": "",
  "status": "success",
  "duration_ms": 3840,
  "triggered_by": "admin",
  "started_at": "2026-09-07T10:00:00+08:00",
  "finished_at": "2026-09-07T10:00:04+08:00",
  "artifacts": [
    { "step_id": 88, "step_name": "build", "path": "dist/app.zip", "size_bytes": 2048, "sha256": "a1b2..." }
  ],
  "created_at": "2026-09-07T10:00:00+08:00"
}

字段含义：id 运行记录主键（页面详情/取消/日志的路径参数，也是成功提示里的「id=...」）；definition_id 所属定义；run_number 同一定义内自增运行号（max+1，页面展示为「运行号 #N」）；trigger_type manual/external/git_push/schedule；git_commit_sha/git_branch 触发 commit 上下文（当前仅 manual/external 有值域，external-trigger 因 handler 未解析 body 恒为空，见 8 章）；status pending/running/success/failed/cancelled（另常量 skipped）；duration_ms 执行耗时（finishRun 由 started→finished 计算）；triggered_by 触发人；started_at/finished_at；artifacts 产物清单 JSON（阶段 E 批4a，run 成功时按步骤产物声明收集；manual 全流程 run 有值，external-trigger 无 shell 步骤恒空）；created_at 创建时间。运行状态枚举与前端映射对照：后端 success（页面 RUN_STATUS_META 绿覆盖 success/succeeded/completed）、failed 红、cancelled 灰、running/pending 蓝。

enable / disable / cancel / delete / 日志 的轻量响应（源码逐字一致）：

{ "id": 3, "status": "enabled" }

{ "id": 12, "status": "cancelled" }

{ "deleted": 3 }

{ "run_id": 12, "step_id": 88, "log": "+ echo 'deploy artifact'\n...\n" }

错误形态（统一 envelope，HTTP 4xx/5xx）：

{ "code": 40002, "message": "流水线 \"deploy-to-prod\" 已禁用，拒绝启动", "request_id": "req_..." }

{ "code": 40901, "message": "流水线定义 (project_id=1, name=deploy-to-prod) 已存在", "request_id": "req_..." }

错误码速查（api.go statusToCode/codeForError）：40001 参数 / 40002 校验 / 40101 认证 / 40301 权限 / 40401 不存在 / 40901 冲突 / 42201 语义 / 42901 限流 / 50001 其余。HTTP 状态码由 ierr 承载，业务码与 HTTP 码不一定同号。

5.4 关键机制

运行号与定义生命周期。定义表 (project_id, name) 复合唯一（冲突 409）；运行号 RunNumber 在同一定义内由 max+1 自增（并发下由表索引与单写服务保证不重号）。CreateDefinition 缺省 pipeline_file_path=.lightapollo.yml、status=enabled；DisableDefinition 只翻状态位，停用后 StartRun/ExternalTrigger 双双 400 拒绝。UpdateDefinition 为指针字段全量更新（前端 PUT 全量带 body）。DeleteDefinition 只删定义行，不级联删除 run/stage/step（代码注释明确「关联运行的级联清理由调用方按需处理，简化不删」）——所以删除后历史运行记录仍在库中，只是不再挂在任何定义下。

WorkerPool 与执行队列。流水线服务内置内存 WorkerPool：channel 队列（容量 100）+ 固定 worker（默认 3，NewPipelineService 时注入，server 启动调 StartWorker）。started 标志决定触发路径：worker 已启动 → s.queue <- run.ID 异步执行；未启动 → 请求内同步 executeRun（便于单机/自测，external-trigger 则无论是否启动都同步执行于请求内）。executeRun：run 置 running → 逐 stage 串行（顺序 pf.Stages 数组序）→ 每 stage 内步骤串行 → 任一 shell/deploy 步骤失败 → 该 stage 失败、后续 stage 全 skipped → run 失败；全部成功 → saveRunArtifacts（按步骤产物声明收集登记，见下）→ run 置 success。运行取消的竞态守卫在 isRunCancelled：worker 每步执行前检查，已 cancelled 则本 stage 剩余步骤标记 skipped、不新起进程，finishRun 以 cancelled 为终态不被 success/failed 覆盖。

两类步骤执行器。① shell：Runner.RunStep 执行命令并把输出写日志文件，落库 exit_code + log_path；支持 Artifacts 产物声明，完成后 collectStepArtifacts 把产物文件信息（step_id/step_name/path/size_bytes/sha256）收集进 manifest，run 成功时统一存 run.Artifacts JSON。② lightapollo_deploy：runDeployStep 取步骤的 sync_target_id（缺失 → lightapollo_deploy 步骤 %q 缺少 sync_target_id 内部错误），转调注入的 DeployTrigger.TriggerDeploy(sync_target_id, triggered_by)——server 层把它接到 gitops.SyncEngine，即与「部署与漂移」页同源的 GitOps 部署触发链路（pipeline 包通过接口注入避免与 gitops 循环依赖）。此步骤无日志文件（LogPath 空），点「日志」返回空。

external-trigger 的「直达 deploy」语义。与手动 run 不同，ExternalTrigger 不读取也无视 shell/build/test：只为每个 stage 建一条 skipped stage_run 占位，仅对 stage 内 lightapollo_deploy 类型步骤建 running step_run 并立即执行，命中失败即 stage/run 置 failed。因此 external-trigger 返回的 run 已是终态，历史上该 run 的 Stage 表会是「全 skipped + 一个实际执行过的 stage」的形态（能否看到取决于 8 章所述 stage/step 下钻缺陷是否修复）。

取消即杀进程树（阶段 E 批4a）。CancelRun 先对 pending/running 落库 cancelled 终态，再通过 runner.(ProcessTracker).KillRun(runID) 终止该 run 全部活跃 step 子进程（含子进程树），避免孤儿进程继续写日志/改产物；pending 排队中尚无进程 → KillRun 幂等返回 nil；已终态取消 no-op。kill 失败仅 logger.Warn 降级，取消语义不受影响。

日志与产物读取。GetStepLog 校验 step 属于该 run（step.RunID != runID → 404），LogPath 为空返回空串，否则 os.ReadFile 全文返回（LogOffset 字段预留增量拉取扩展，当前简化返回全文）。GetRunArtifacts（页面未使用）返回 run.Artifacts 内 []ArtifactEntry（无产物空数组）；产物引用解析 resolveArtifactRefs 支持 run 内 @step_name/path 引用替换（阶段 E 批4a）。

6. 权限与安全

• 认证分层：页面整体 requiresAuth；读（pipeline:read）vs 写（pipeline:write）vs 执行（pipeline:execute，enable/disable/run/external-trigger/cancel）三点分离，细粒度控制谁能看、谁能改、谁能触发。
• 写操作防护：删除定义、取消运行均有浏览器原生 confirm 二次确认；外部触发虽无确认但前端提示文案写明 commit/branch 上下文。
• 定义启停即熔断：disable 后后端拒绝一切触发（400），可作为「暂停该流水线」的运维熔断手段；enable 恢复。
• 执行隔离：shell 步骤在 worker 进程中执行命令、日志落文件；取消走进程树 kill，防止取消后孤儿进程继续执行；产物收集做了 pathWithin(base, abs) 路径越界防护（产物目录外文件不入清单）。
• 审计留痕：创建/更新/删除（PIPELINE_CREATE/UPDATE/DELETE）、手动运行（PIPELINE_RUN）、外部触发（PIPELINE_EXTERNAL_TRIGGER）均写审计日志（audit：动作/对象 id/结果 + 上下文），可在审计日志页追溯。注意取消与启停当前不写专项审计。
• 错误透出：前端把 4xx/5xx 后端 message 直接透出提示条，可能暴露内部校验细节；403 由拦截器统一 alert。

7. 常见问题与排错

1. 点「运行」提示 流水线 "x" 已禁用，拒绝启动（40002）：原因是该定义当前为 disabled（可能被「停用」过或初始建为停用），但行内「运行/外部触发」按钮并不按状态隐藏，照样可点。处理：先点「启用」把定义翻回 enabled 再触发；若确认定义状态栏是灰的即可直接判断。

2. 新建保存提示 流水线定义 (project_id=1, name=xxx) 已存在（409）：原因是定义名在项目内唯一，与既有定义重名。处理：改名后重新提交；或先在列表找到同名定义用「编辑」修改而非新建。

3. 运行详情弹窗 Stages/Steps 恒为「暂无 Stage/Step 信息」：原因是后端 GET /pipeline-runs/:id 只返回 run 本体、不返回嵌套 stage/step（GetStageRuns/GetStepRuns 存在但未注册 HTTP 路由），前端 parseRunDetail 即便兼容嵌套形态也无数据可解析（前端缺陷/契约缺口，见 8 章）。处理：运行是否成功以运行历史/详情概要的状态徽标与耗时为准；步骤日志因 Steps 表为空当前无法从本页打开。需由前端/后端配合修复后才有 Stage/Step/日志下钻。

4. 「外部触发」成功后展开行的运行历史没出现新运行：原因是 handleExternalTrigger 在关闭弹窗后读取 extModal.value.pipe?.id——弹窗对象已被重置为 {visible:false}，pipe 为 null，expanded.value[undefined] 恒为 falsy，刷新分支永远不执行（前端逻辑 bug，见 8 章）。处理：在运行历史子区点「刷新」手动重拉；修复前这是稳定复现的行为。

5. 外部触发创建的历史行 Commit/分支列显示 -：原因是外部触发弹窗里填的 commit_sha/branch 前端会放进请求体，但后端 handleExternalTriggerPipeline 不解析 body、ExternalTrigger 创建 run 时也不回填 git_commit_sha/git_branch，两字段恒为空。处理：以「触发类型=external」与状态判断该运行即可；Commit/分支溯源待后端解析 body 后才有值（见 8 章）。

6. 保存时提示 Triggers 不是合法 JSON，请检查格式：原因是 Triggers 文本框内容不是合法 JSON（前端 JSON.parse 抛错，请求未发出）。处理：按 placeholder 填 JSON 数组（如 [{"type":"git_push","branch":"main"}]）或对象；留空则不配置（不传 triggers 字段）。

7. 编辑弹窗里 Git 仓库下拉变成了数字输入框：原因是 GET /projects/1/git-repos 加载失败或仓库列表为空（fetchRepos catch 静默置空数组、不阻断页面）。处理：手动输入仓库 ID（先到「Git 仓库」页确认该 ID 存在）；或修复仓库下拉数据源后重新打开弹窗。新建弹窗此时 git_repo_id 默认值为 null，必须手输。

8. 步骤日志弹窗显示「（无日志内容）」：原因分两类——① 该步骤是 lightapollo_deploy 类型（无日志文件，LogPath 空，后端返回空串）；② shell 步骤确实没输出或日志文件被清。处理：确认步骤类型（Steps 表「类型」列）；对 deploy 步骤日志为空属正常，执行结果看运行/阶段状态；shell 步骤日志为空则检查命令是否真的无 stdout。

9. 取消运行后状态未变 / 取消按钮消失但状态仍 running：原因是后端先落 cancelled 再杀进程树，若 worker 正卡在子进程 I/O，落库已 cancelled 但列表数据可能未刷新。处理：点子区「刷新」强制重拉；若仍 running 且反复取消无果，看后端日志确认 KillRun 是否降级失败（仅 Warn 不阻断取消语义）。

8. 已知缺陷与边界

附录 A：速查——常用字段别名与提示文案清单