xiaoxia/xiaoxia-saas
1
0
Fork 0
Code Issues 8 Pull Requests 1 Actions Packages Projects Releases 7 Wiki Activity
Files
main
xiaoxia-saas/docs/CI-CD-稳定性修复专项规划-草案.md
T

6.8 KiB
Raw Permalink Blame History

CI/CD 稳定性修复专项规划（草案）

文档状态：草案
创建时间：2026-06-19
适用范围：小虾 SaaS 仓库 CI/CD 专项治理
专项性质：独立专项，不得混入 Phase 7 业务收尾提交

一、专项背景

在 feature/phase7-asset-generation-alignment 分支推进 Phase 7 业务收尾过程中，提交 e5d5ae4 对应的 ci-cd.yml #239 最终失败。

已确认：

  • 失败点位于 Code Quality Check
  • 当前判断更偏向 CI/CD 环境 / 开发依赖工具链可执行性异常
  • 暂未定性为本轮 Phase 7 业务代码主链缺陷

根据当前已确认的流程约束：

  • 本轮业务收尾只记录问题
  • 不得边做边改 CI/CD
  • CI/CD 修复必须进入下一次单独规划、单独执行的专项

本文件即用于承接该专项。

二、专项目标

把当前 CI/CD 从“曾经可跑通，但不稳定”收敛为：

  1. Code Quality Check 稳定可执行
  2. Run Tests 稳定可执行
  3. Build Summary 触发逻辑符合预期
  4. .gitea / .github workflow 不再漂移
  5. feature 分支提交结果可被稳定信任
  6. CI 真正成为交付门禁，而不是偶尔成功的脚本

三、专项边界

只做这些

  • CI workflow 执行链路检查
  • 开发依赖安装链路检查
  • 容器 / venv / 工具调用方式一致性检查
  • .gitea 与 .github workflow 同步关系核查
  • 质量检查工具（如 black / isort / flake8 / mypy / bandit）可执行性验证
  • 与 CI/CD 直接相关的文档修订

不做这些

  • 不处理 Phase 7 新业务功能
  • 不处理生成链深化
  • 不处理前端新页面开发
  • 不顺手清理无关历史代码债
  • 不把 README、测试、架构等非 CI 主问题混成一个大杂烩专项

四、当前已知问题

问题 0：runner 基础设施缺少正式纳管

当前已确认：

  • workflow 可以触发
  • run 可以入队
  • job 可长期停留在 Waiting to run
  • 文档里虽然声明 act_runner 已注册并持续运行，但当前机器上缺少清晰可验证的 runner 安装位置、配置文件、日志路径和健康检查方式
  • 进一步交叉核对后，现有仓库内多处路径约定实际指向 xiaoxia-server:/var/lib/xiaoxia-ci，这意味着 CI 基础设施的真实宿主很可能是服务器侧，而不是当前本机

这说明当前问题不仅是 workflow 稳定性问题，更是 CI 执行基础设施没有正式闭环、且宿主边界未被文档明确说明的问题。

问题 1：最新提交 #239 在质量检查阶段失败

  • 提交：e5d5ae4
  • run：ci-cd.yml #239
  • 结果：failure
  • 失败阶段：Code Quality Check

问题 2：CI 工具链可执行性存在疑点

当前症状表明：

  • requirements-dev.txt 虽已建立
  • 但质量工具链在 CI 环境中未必稳定成为可执行命令
  • “本地通过”与“CI 稳定通过”之间仍存在断层

问题 3：CI 真源与镜像副本虽已统一，但仍需持续核查

根据环境收敛规则：

  • .gitea/workflows/ci-cd.yml 是真源
  • .github/workflows/ci-cd.yml 是镜像/兼容副本

专项中必须再次验证两者当前是否完全一致，避免后续再次漂移。

五、专项执行原则

  1. 文档先行

    • 先明确问题清单、修复方案、验证口径，再动配置。

  2. 最小必要改动

    • 只改和 CI/CD 稳定性直接相关的内容。

  3. 不混业务提交

    • 所有 CI 专项修复在独立分支完成。

  4. 先复现再修

    • 先找出稳定复现条件，禁止凭猜测叠补丁。

  5. 一次只修一个链路问题

    • 避免把依赖、容器、workflow、文档同时大改导致新漂移。

  6. 修复后必须验证

    • 不能只看本地命令通过，必须看 feature 分支 CI 结果。

六、建议执行步骤

Step 1：问题复盘

输出一份问题复盘清单，至少回答：

  • #239 失败时实际执行到了哪一步？
  • 哪个命令或哪个工具最先不可用？
  • 本地与 CI 的差异点有哪些？
  • 是安装问题、PATH 问题、容器问题，还是 workflow 写法问题？

Step 2：环境链路核查

逐项核查：

  • requirements-dev.txt
  • .gitea/workflows/ci-cd.yml
  • .github/workflows/ci-cd.yml
  • container: catthehacker/ubuntu:act-latest
  • python3 -m venv .venv
  • python -m pip install --index-url https://pypi.org/simple -r requirements-dev.txt
  • 质量工具调用方式

Step 3：形成修复方案

修复方案必须明确：

  • 改哪些文件
  • 为什么改
  • 改完如何验证
  • 是否会影响现有分支保护与门禁规则

Step 4：在独立分支执行修复

建议分支命名：

  • bugfix/ci-quality-check-stability
  • 或 refactor/ci-toolchain-alignment

Step 4.5：runner 基础设施正式纳管

在继续追单次 workflow 结果之前，必须先完成：

  • 固定 runner 安装目录
  • 固定 runner 配置文件路径
  • 固定 runner 日志目录
  • 固定 runner 启停脚本
  • 固定 runner 健康检查脚本
  • 文档与现实一致性校验

参考文档：

  • docs/RUNNER-INFRASTRUCTURE.md
  • scripts/ci/check-runner.ps1
  • scripts/ci/install-runner.ps1
  • scripts/ci/start-runner.ps1
  • scripts/ci/stop-runner.ps1

Step 5：专项验证

至少验证：

  • Code Quality Check
  • Run Tests
  • Build Summary
  • .gitea / .github 一致性
  • feature 分支提交完整 run 结果

Step 6：文档回写

专项结束后必须更新：

  • PHASE7-PROGRESS.md（只记录状态变化）
  • 专项文档本身
  • 如有必要，再更新环境收敛方案文档

七、验收标准

本专项完成的标准不是“我觉得差不多行了”，而是以下条件成立：

  • Code Quality Check 稳定通过
  • Run Tests 稳定通过
  • Build Summary 按规则正常执行
  • .gitea / .github workflow 保持一致
  • feature 分支同类提交不再复现“本地过、CI 挂”
  • 本专项过程和结果已文档化

八、风险提醒

风险 1：顺手扩大范围

最容易犯的错误是：修 CI 时顺手改业务代码、测试、文档、依赖策略，最后变成一锅粥。

风险 2：局部成功误判为稳定成功

一次通过不代表已经稳定；必须至少经过一轮 feature 分支真实验证。

风险 3：修完未回写文档

如果修完不更新文档，就会再次回到“规则和现实分离”的老问题。

九、建议优先级

优先级：P0

原因：

  • 它是当前最明确的交付阻塞点
  • 它会放大所有后续专项的执行成本
  • 它直接影响质量门禁是否真实有效

十、专项结论

当前建议非常明确：

CI/CD 稳定性修复专项应该作为下一轮最优先启动的独立专项。

不是因为它最有趣， 而是因为它最影响整个项目后续的推进质量和交付效率。

建议人：小虾 🦐

Reference in New Issue View Git Blame Copy Permalink