# 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 稳定性修复专项应该作为下一轮最优先启动的独立专项。**

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

---

**建议人**：小虾 🦐