diff --git a/docs/ci/ci-failure-diagnosis-20260713.md b/docs/ci/ci-failure-diagnosis-20260713.md new file mode 100644 index 000000000..61723b54b --- /dev/null +++ b/docs/ci/ci-failure-diagnosis-20260713.md @@ -0,0 +1,104 @@ +# CI 大量失败根因排查报告 + +**排查时间：** 2026-07-13 +**排查人：** 构建服务器运维Agent +**范围：** 最近15次 CI run（PR #258~#265 + develop 分支多次 push） + +## 一、整体概况 + +最近 20 次 CI run 中 16 次失败，失败率 **80%**。失败集中在 3 个 Job： + +| Job | 失败率 | 根因类型 | +|-----|--------|----------| +| Validate Code Quality | 100% | black 代码格式检查失败 | +| Unit Tests | 100% | 测试断言未同步国际化改动 | +| Integration Tests | 100% | 密码重置接口变更未同步测试 | +| Frontend Lint | 20% | 各 PR 代码质量问题 | + +**结论：3 个全局性失败点导致所有 PR CI 全红，不是代码本身问题，是基础设施/测试用例滞后。** + +--- + +## 二、详细根因分析 + +### 1. Validate — black 格式检查失败 + +**现象：** +``` +would reformat scripts/check_migration_safety.py +1 file would be reformatted, 369 files would be left unchanged. +Oh no! 💥 💔 💥 +``` + +**根因：** +`scripts/check_migration_safety.py` 文件不符合 black 格式化规范。该文件是最近新增的迁移安全检查脚本，提交前未本地跑 black 格式化。 + +**影响范围：** 所有 PR 及 develop 分支，全量失败。 + +**修复方案：** +```bash +black scripts/check_migration_safety.py +``` + +--- + +### 2. Unit Tests — 1 个用例失败 + +**现象：** +``` +FAILED tests/unit/test_asset_library_delete.py::TestDeleteAssetLibrary::test_delete_library_access_denied + AssertionError: assert 'Access denied' in '无权访问该项目' +``` + +**统计：** 1442 passed, 1 failed + +**根因：** +项目之前做了国际化（i18n）改造，错误信息从英文改成了中文，但对应的单元测试断言仍然检查英文 "Access denied"，导致断言失败。 + +**影响范围：** 所有 PR 及 develop 分支，全量失败。 + +**修复方案：** +修改 `tests/unit/test_asset_library_delete.py` 中的断言，将 `'Access denied'` 改为 `'无权访问该项目'`，或改为断言 HTTP 状态码（403）而不是错误消息文本。 + +--- + +### 3. Integration Tests — 1 个用例失败 + +**现象：** +``` +FAILED tests/integration/test_auth.py::TestPasswordReset::test_request_password_reset_success + assert 404 in (200, 202) +``` + +**统计：** 45 passed, 1 failed, 13 deselected, 2 rerun + +**根因：** +密码重置请求接口（`POST /auth/password-reset/request` 或类似路由）返回 404，说明该接口已被移除、路由变更，或对应的功能模块暂时被注释/下线。 + +**影响范围：** 所有 PR 及 develop 分支，全量失败。 + +**修复方案：** +- 如果接口确实下线了：删除或 skip 这个测试用例 +- 如果是路由改了：更新测试中的 API 路径 +- 如果是功能待开发：标记为 `@pytest.mark.skip` 并加上 TODO + +--- + +## 三、修复优先级 + +| 优先级 | 问题 | 修复难度 | 预估时间 | +|--------|------|----------|----------| +| P0 | black 格式检查失败 | ⭐ | 5分钟 | +| P0 | 单元测试国际化断言失败 | ⭐ | 10分钟 | +| P1 | 集成测试密码重置接口404 | ⭐⭐ | 30分钟（需确认接口状态） | + +**建议：** 先修前两个 P0（能让 2/3 的 job 变绿），再处理密码重置那个。 + +--- + +## 四、Runner 执行情况观察 + +- 当前 9 个 Runner 全部在线（构建服务器 4 个 + 新服务器 5 个） +- 失败的 Job 都是在构建服务器的 Runner 上执行的（xiaoxia-ci-runner-2/3 等） +- 新服务器 5 个 Runner 目前全部空闲（标签修复后首次接任务可能需要时间） +- 并发能力充足，瓶颈在代码/测试本身，不在 Runner 资源 diff --git a/docs/ci/runner-planning.md b/docs/ci/runner-planning.md new file mode 100644 index 000000000..27450fdc0 --- /dev/null +++ b/docs/ci/runner-planning.md @@ -0,0 +1,136 @@ +# 三台服务器 Runner 分工规划 + +**制定日期：** 2026-07-13 +**状态：** 规划中 + +--- + +## 一、现状总览 + +当前共 9 个 Gitea Actions Runner，分布在 3 台服务器上： + +| 服务器 | IP | 配置 | Runner 数量 | 当前状态 | +|--------|-----|------|-------------|----------| +| 构建服务器 | 114.55.236.178 | 4核 / 7.1G RAM / 49G NVMe | 4个（ID: 8, 42, 46, 47） | ✅ 在线 | +| 新CI服务器 | 116.62.226.203 | 8核 / 14G RAM | 5个（ID: 58-62） | ✅ 在线 | +| 业务服务器 | 47.98.113.167 | - | 0个（旧3个已下线） | ⚠️ 待规划 | + +**所有 Runner 共用标签：** `saas`, `runtime-builder`, `host`, `ubuntu-latest` + +--- + +## 二、问题分析 + +### 2.1 标签无区分 +所有 Runner 标签完全一致，CI 任务随机分配到任意 Runner，导致： +- 构建任务（Build）可能跑到配置低的机器上，构建慢 +- 代码检查任务占着构建服务器，影响构建速度 +- 业务服务器跑 CI 影响线上服务稳定性 + +### 2.2 资源浪费 +- 新服务器 8核14G 跑 validate/lint 有点大材小用 +- 构建服务器 4核7G 跑 Docker 构建偏紧张 + +--- + +## 三、规划方案 + +### 3.1 分工原则 + +| 服务器 | 角色 | 主要任务类型 | 标签策略 | +|--------|------|-------------|----------| +| **构建服务器** (114.55.236.178) | 构建专机 | Build Staging / Build Production / Docker 镜像构建 | 保留 `saas` + `host`，新增 `build-only` | +| **新CI服务器** (116.62.226.203) | 代码检查专机 | Validate / Unit Tests / Integration Tests / Frontend Lint | 保留 `saas` + `host`，新增 `ci-check` | +| **业务服务器** (47.98.113.167) | 部署专机 | Deploy Staging / Deploy Production / E2E Tests | 保留 `saas` + `host`，新增 `deploy-only` | + +### 3.2 具体配置 + +#### 构建服务器（4个 Runner） +- **数量：** 3个（从4个缩减，释放资源给构建缓存） +- **标签：** `saas`, `host`, `build-only`, `ubuntu-latest` +- **负责 Job：** + - `build-staging` + - `build-production-runtime-images` + - 其他需要 Docker buildx 的任务 + +#### 新CI服务器（5个 Runner） +- **数量：** 5个（保持不变） +- **标签：** `saas`, `host`, `ci-check`, `ubuntu-latest` +- **负责 Job：** + - `validate` + - `unit-tests` + - `integration-tests` + - `frontend-lint` + - 安全扫描（gitleaks / pip-audit / vulture 等） + +#### 业务服务器（1-2个 Runner） +- **数量：** 1-2个（逐步替换旧的3个） +- **标签：** `saas`, `host`, `deploy-only`, `ubuntu-latest` +- **负责 Job：** + - `deploy-staging` + - `deploy-production` + - `staging-e2e` / `production-e2e` + - `staging-api-tests` + +--- + +## 四、实施步骤 + +### Phase 1: 标签打标（低风险，立即做） +1. 新服务器 5 个 Runner 添加 `ci-check` 标签 +2. 构建服务器保留 3 个 Runner，添加 `build-only` 标签 +3. 业务服务器部署 1 个新 Runner，标签 `deploy-only` + +### Phase 2: Job 路由调整（中风险，逐步来） +1. validate / unit-tests / integration-tests / frontend-lint 改为 `runs-on: ci-check` +2. build-staging / build-production 改为 `runs-on: build-only` +3. deploy-* / e2e 改为 `runs-on: deploy-only` + +### Phase 3: 旧 Runner 下线 +- 业务服务器旧的 3 个 Runner 确认无任务后下线 +- 构建服务器多余的 1 个 Runner 迁移到新服务器 + +--- + +## 五、并发配置优化建议 + +### 5.1 当前并发情况 +- 首发并行 Job：validate + unit-tests + frontend-lint（3个并行） +- integration-tests 依赖 validate（串行，浪费资源） +- 无 concurrency 限制，同一分支多次 push 会重复跑 + +### 5.2 优化建议 + +**1. integration-tests 改为与 unit-tests 并行** +```yaml +# 当前 +integration-tests: + needs: validate # 没必要等validate + +# 优化后 +integration-tests: + needs: [] # 直接和unit-tests并行跑 +``` + +**2. 增加分支级 concurrency，取消重复构建** +```yaml +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true +``` +同一 PR 多次 push 时，取消旧的构建，只跑最新的。 + +**3. Build Staging 移出 PR 门禁** +- 已在阶段二优化中完成（PR #245） +- Build Staging 只在 develop/main 上异步构建 + +--- + +## 六、预期收益 + +| 指标 | 当前 | 优化后 | 提升 | +|------|------|--------|------| +| PR CI 总时长 | ~8-12分钟 | ~4-6分钟 | ⏱️ 缩短 40-50% | +| 构建速度 | 可能抢到慢机器 | 固定高配构建机 | 🚀 更稳定更快 | +| 线上稳定性 | CI和业务抢资源 | 部署独立Runner | 🛡️ 隔离保障 | +| Runner 利用率 | 随机分配 | 按任务类型调度 | 📈 更合理 |