Xiaoxia AI
229 lines
6.8 KiB
Markdown
229 lines
6.8 KiB
Markdown
# 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 稳定性修复专项应该作为下一轮最优先启动的独立专项。**
|
||
|
||
不是因为它最有趣，
|
||
而是因为它最影响整个项目后续的推进质量和交付效率。
|
||
|
||
---
|
||
|
||
**建议人**：小虾 🦐
|