perf(ci): 流水线提速 - 路径过滤/持久builder缓存/依赖缓存卷/部署job迁移ci-l2 #1536

Merged

auto-approve-bot merged 8 commits from ci/ci-speedup-phase1 into develop 2026-08-29 14:36:05 +08:00

Conversation 5 Commits 8 Files Changed 6

+480 -138

xiaoxia commented 2026-08-29 11:28:39 +08:00

Owner

Copy Link

Copy Source

CI 流水线提速（小改动部署慢优化）

背景

develop 推送小改动：三镜像全量构建 8min、代码质量检查 1013min（每次现装工具）、后端单测 14min（每次现 pip install），staging 端到端 ~10min。实际部署只需 1.5min。

改动内容

1. build-staging 路径过滤（新增 check-push-paths job）

• 纯前端改动（仅 apps/web/）：只构建 Web 镜像
• 纯后端改动（无 apps/web/）：只构建 API/Worker 镜像
• 未重建镜像 → 新增 retag-staging-skipped job：把 registry 上 :develop/:main 分支 tag retag 为新 SHA 并推送
• 构建成功同时推分支 tag 作为 retag 稳定来源；找不到源镜像时 job 明确失败（不会静默部署错版本）
• Watchtower 部署链路完全不变（三个镜像的新 SHA tag 都保证存在）

2. deploy-staging、acr-cleanup 迁移

• runs-on: runtime-builder → ci-l2（只需 SSH + docker login，不再占用构建槽）

3. buildx 持久 builder + 本地层缓存

• 宿主机常驻 ci-builder-persist（docker-container driver, host 网络），层缓存保存在 buildkit 命名卷，跨 job 共享
• job 结束不再 docker buildx prune -af；残留容器由宿主机 ci-docker-cleanup.sh 兜底（已加白名单豁免持久 builder）
• Worker 镜像从 plain docker build 改为同样走持久 builder，接入缓存
• registry cache 保留为冷启动兜底读取

4. 依赖缓存到宿主机命名卷（act-toolcache 模式）

• 12 个 runner config.yaml 增加挂载：ci-pip-cache:/root/.cache/pip、xiaoxia-npm-cache:/root/.npm、act-toolcache:/opt/act-toolcache
• validate-code-quality / unit-tests / frontend-unit-test 等 job 的 pip/npm 安装直接命中缓存，不再每次重装

不改动

• build-production / deploy-production / canary-release / production-e2e 完全未动
• 生产发版链路、分支保护门禁不变

宿主机配套（已完成）

• 新 CI 服务器 172.30.18.199：12 runner 已挂载缓存卷并重启、持久 builder 已创建、清理脚本已豁免

## CI 流水线提速（小改动部署慢优化） ### 背景 develop 推送小改动：三镜像全量构建 ~8min、代码质量检查 10~13min（每次现装工具）、后端单测 14min（每次现 pip install），staging 端到端 ~10min。实际部署只需 1.5min。 ### 改动内容 **1. build-staging 路径过滤（新增 check-push-paths job）** - 纯前端改动（仅 apps/web/）：只构建 Web 镜像 - 纯后端改动（无 apps/web/）：只构建 API/Worker 镜像 - 未重建镜像 → 新增 `retag-staging-skipped` job：把 registry 上 `:develop`/`:main` 分支 tag retag 为新 SHA 并推送 - 构建成功同时推分支 tag 作为 retag 稳定来源；找不到源镜像时 job 明确失败（不会静默部署错版本） - Watchtower 部署链路完全不变（三个镜像的新 SHA tag 都保证存在） **2. deploy-staging、acr-cleanup 迁移** - runs-on: runtime-builder → ci-l2（只需 SSH + docker login，不再占用构建槽） **3. buildx 持久 builder + 本地层缓存** - 宿主机常驻 `ci-builder-persist`（docker-container driver, host 网络），层缓存保存在 buildkit 命名卷，跨 job 共享 - job 结束不再 `docker buildx prune -af`；残留容器由宿主机 ci-docker-cleanup.sh 兜底（已加白名单豁免持久 builder） - Worker 镜像从 plain docker build 改为同样走持久 builder，接入缓存 - registry cache 保留为冷启动兜底读取 **4. 依赖缓存到宿主机命名卷（act-toolcache 模式）** - 12 个 runner config.yaml 增加挂载：`ci-pip-cache:/root/.cache/pip`、`xiaoxia-npm-cache:/root/.npm`、`act-toolcache:/opt/act-toolcache` - validate-code-quality / unit-tests / frontend-unit-test 等 job 的 pip/npm 安装直接命中缓存，不再每次重装 ### 不改动 - build-production / deploy-production / canary-release / production-e2e 完全未动 - 生产发版链路、分支保护门禁不变 ### 宿主机配套（已完成） - 新 CI 服务器 172.30.18.199：12 runner 已挂载缓存卷并重启、持久 builder 已创建、清理脚本已豁免

xiaoxia added 1 commit 2026-08-29 11:28:40 +08:00

perf(ci): 流水线提速 - 路径过滤/持久builder缓存/依赖缓存卷/部署job迁移ci-l2 ... a64037881a

1. build-staging 路径过滤：纯前端改动只构建Web，纯后端只构建API/Worker；
   未重建镜像通过 retag-staging-skipped job 将分支tag retag为新SHA推送，Watchtower链路不变
2. deploy-staging、acr-cleanup runs-on 从 runtime-builder 改为 ci-l2，释放构建槽
3. buildx 改为宿主机持久 builder(ci-builder-persist)+buildkit命名卷缓存，
   job结束不再prune，Worker镜像同样接入buildx缓存
4. validate/unit-test/frontend-test 的 pip/npm 依赖通过宿主机命名卷持久化缓存
   （runner config 挂载 ci-pip-cache/xiaoxia-npm-cache/act-toolcache）
5. 不影响生产构建/发版/canary 相关 job

gitea-actions bot commented 2026-08-29 11:40:28 +08:00

Copy Link

Copy Source

🚀 预览环境已部署

项目	详情
PR号	#1536
预览链接	https://pr-1536.preview.xiaoxiajianji.com
API环境	staging

💡 预览环境使用 staging API 数据，请勿在预览环境中操作重要数据。

🔄 每次提交新代码后预览环境会自动更新。

🗑️ PR 关闭或合并后，预览环境会自动清理。

🚀 **预览环境已部署** | 项目 | 详情 | |------|------| | PR号 | #1536 | | 预览链接 | [https://pr-1536.preview.xiaoxiajianji.com](https://pr-1536.preview.xiaoxiajianji.com) | | API环境 | staging | > 💡 预览环境使用 staging API 数据，请勿在预览环境中操作重要数据。 > > 🔄 每次提交新代码后预览环境会自动更新。 > > 🗑️ PR 关闭或合并后，预览环境会自动清理。

xiaoxia added 1 commit 2026-08-29 12:43:38 +08:00

perf(ci): validate/unit-tests/frontend-unit-test 三个 job 增加 actions/cache@v4 依赖缓存 ... a441b760d4

act_runner v0.2.13 不支持 runner config 自定义 volume 挂载（container.volumes 不在 schema，
container.options -v 实测不生效），改用 Gitea Actions 标准 actions/cache@v4：
- validate-code-quality / unit-tests: 缓存 /root/.cache/pip，key 按 requirements*.txt hash
- frontend-unit-test: 缓存 /root/.npm，key 按 apps/web/package-lock.json hash
runner 已启用内置 cache server。

auto-approve-bot approved these changes 2026-08-29 12:55:32 +08:00

auto-approve-bot left a comment

Collaborator

Copy Link

Copy Source

CI全绿，自动审批通过。

CI全绿，自动审批通过。

auto-approve-bot approved these changes 2026-08-29 12:55:32 +08:00

auto-approve-bot left a comment

Collaborator

Copy Link

Copy Source

CI全绿，自动审批通过。

CI全绿，自动审批通过。

xiaoxia added 1 commit 2026-08-29 13:03:52 +08:00

fix(ci): 强制启用 pip 缓存目录（镜像 PIP_NO_CACHE_DIR=0 被当作真值禁用缓存） ... 88cd5db299

ci-base 镜像 ENV PIP_NO_CACHE_DIR=0 中字符串 "0" 被 pip 解析为真值，
导致 /root/.cache/pip 从不写入，actions/cache 报 Path Validation Error。
在 validate-code-quality / unit-tests 两个 pip job 的 env 中显式覆盖：
PIP_CACHE_DIR=/root/.cache/pip + PIP_NO_CACHE_DIR=''。

xiaoxia added 1 commit 2026-08-29 13:25:30 +08:00

perf(ci): Worker PR 构建也接入持久 builder（移除普通 docker build 捷径） ... 3a41c9b598

原 Worker PR 构建走 plain docker build，无 buildx 层缓存；
现与 API/Web 统一走 docker_build_only.sh (ci-builder-persist)。

auto-approve-bot commented 2026-08-29 13:31:14 +08:00

Collaborator

Copy Link

Copy Source

【阻塞级判定】

• 是否存在阻塞级问题：是
• 阻塞级问题数量：2 个

📊 审查概览

• 整体评价：需修改
• 建议级问题数量：2 个

🔴 阻塞级问题（必须修复）

1. [scripts/ci/ensure_persistent_builder.sh: 15-21] 竞态条件导致并发构建失败

   • 问题类型：逻辑bug
   • 问题描述：脚本使用 if ! inspect ... then create ... fi 的模式来确保 builder 存在。在 CI 并发场景下（如 build-staging 的 matrix 任务并行启动），如果多个任务同时检测到 builder 不存在，都会尝试执行 create。第二个任务会因 "builder already exists" 报错并退出（set -eu），导致 CI 流程不稳定。
   • 修改建议：在 docker buildx create 命令后追加 || true，或者捕获特定错误码，确保创建失败时脚本不退出，因为此时 builder 实际上已经存在了。

2. [scripts/ci/docker_build_push.sh: 90-94] 并发任务间的资源冲突风险

   • 问题类型：逻辑bug / 数据损坏风险
   • 问题描述：当检测到缓存损坏时，脚本会执行 docker buildx rm 删除 builder 并重建。由于 ci-builder-persist 是跨 Job 共享的持久资源，如果 Job A（如构建 API）正在执行，Job B（如构建 Web）因缓存损坏触发删除操作，会导致 Job A 的构建进程突然崩溃（连接断开或 builder 消失），造成无辜的构建任务失败。
   • 修改建议：在并发构建场景下，不应轻易删除共享的持久 builder。建议改为：1) 仅记录错误并让当前任务失败；2) 或者使用文件锁（flock）串行化重建逻辑；3) 或者将重建逻辑移到独立的串行步骤中，而非在构建脚本内部动态处理。

💡 改进建议（不阻塞合并）

1. [scripts/ci/docker_build_only.sh: 22-35] 缺少缓存损坏的容错机制

   • 具体内容：docker_build_push.sh 中已经增加了检测缓存损坏并重建 builder 的逻辑，但 docker_build_only.sh（用于 PR 验证）中未包含此逻辑。如果持久 builder 缓存损坏，PR 检查会直接失败，需要手动重试。建议同步添加类似的容错逻辑，或至少在注释中说明差异原因。

2. [scripts/ci/retag_skipped_image.sh: 30-36] 镜像拉取缺少重试机制

   • 具体内容：在循环中尝试 docker pull 拉取候选镜像时，如果网络抖动导致失败，会直接跳过该候选源。如果所有候选源都因此失败，任务会报错。建议对 docker pull 命令增加简单的重试逻辑（如重试 2 次），以提高 CI 的鲁棒性。

✅ 良好实践

• 引入持久化 builder (ci-builder-persist) 并利用宿主机卷缓存，能有效减少重复下载依赖，显著提升构建速度。
• check-push-paths 逻辑设计严密，在无法判断变更时默认全量构建，符合 "安全兜底" 的最佳实践。
• retag-staging-skipped 机制巧妙地解决了部分构建场景下的 Watchtower 触发问题，保证了部署的一致性。

---

_{🤖 由 AI 代码审查机器人自动生成 | 2026-08-29 05:31:13 | 模型:}

### 【阻塞级判定】 - 是否存在阻塞级问题：是 - 阻塞级问题数量：2 个 ### 📊 审查概览 - 整体评价：需修改 - 建议级问题数量：2 个 ### 🔴 阻塞级问题（必须修复） 1. **[scripts/ci/ensure_persistent_builder.sh: 15-21] 竞态条件导致并发构建失败** - 问题类型：逻辑bug - 问题描述：脚本使用 `if ! inspect ... then create ... fi` 的模式来确保 builder 存在。在 CI 并发场景下（如 `build-staging` 的 matrix 任务并行启动），如果多个任务同时检测到 builder 不存在，都会尝试执行 `create`。第二个任务会因 "builder already exists" 报错并退出（`set -eu`），导致 CI 流程不稳定。 - 修改建议：在 `docker buildx create` 命令后追加 `|| true`，或者捕获特定错误码，确保创建失败时脚本不退出，因为此时 builder 实际上已经存在了。 2. **[scripts/ci/docker_build_push.sh: 90-94] 并发任务间的资源冲突风险** - 问题类型：逻辑bug / 数据损坏风险 - 问题描述：当检测到缓存损坏时，脚本会执行 `docker buildx rm` 删除 builder 并重建。由于 `ci-builder-persist` 是跨 Job 共享的持久资源，如果 Job A（如构建 API）正在执行，Job B（如构建 Web）因缓存损坏触发删除操作，会导致 Job A 的构建进程突然崩溃（连接断开或 builder 消失），造成无辜的构建任务失败。 - 修改建议：在并发构建场景下，不应轻易删除共享的持久 builder。建议改为：1) 仅记录错误并让当前任务失败；2) 或者使用文件锁（flock）串行化重建逻辑；3) 或者将重建逻辑移到独立的串行步骤中，而非在构建脚本内部动态处理。 ### 💡 改进建议（不阻塞合并） 1. **[scripts/ci/docker_build_only.sh: 22-35] 缺少缓存损坏的容错机制** - 具体内容：`docker_build_push.sh` 中已经增加了检测缓存损坏并重建 builder 的逻辑，但 `docker_build_only.sh`（用于 PR 验证）中未包含此逻辑。如果持久 builder 缓存损坏，PR 检查会直接失败，需要手动重试。建议同步添加类似的容错逻辑，或至少在注释中说明差异原因。 2. **[scripts/ci/retag_skipped_image.sh: 30-36] 镜像拉取缺少重试机制** - 具体内容：在循环中尝试 `docker pull` 拉取候选镜像时，如果网络抖动导致失败，会直接跳过该候选源。如果所有候选源都因此失败，任务会报错。建议对 `docker pull` 命令增加简单的重试逻辑（如重试 2 次），以提高 CI 的鲁棒性。 ### ✅ 良好实践 - 引入持久化 builder (`ci-builder-persist`) 并利用宿主机卷缓存，能有效减少重复下载依赖，显著提升构建速度。 - `check-push-paths` 逻辑设计严密，在无法判断变更时默认全量构建，符合 "安全兜底" 的最佳实践。 - `retag-staging-skipped` 机制巧妙地解决了部分构建场景下的 Watchtower 触发问题，保证了部署的一致性。 --- _{🤖 由 AI 代码审查机器人自动生成 | 2026-08-29 05:31:13 | 模型:} <!-- AI_CODE_REVIEW_AUTO_COMMENT -->

xiaoxia added 1 commit 2026-08-29 14:18:44 +08:00

fix(ci): ensure_persistent_builder 并发安全 - create 失败时若已被并发 job 创建则复用 77d582f13a

xiaoxia added 1 commit 2026-08-29 14:18:44 +08:00

fix(ci): docker_build_push 缓存损坏重建改为 flock 串行 + 健康度复查，避免并发互删 acc21ee22f

xiaoxia added 1 commit 2026-08-29 14:18:47 +08:00

fix(ci): retag_skipped_image 候选源 docker pull 增加 3 次重试，网络抖动容错 b290b15eb3

auto-approve-bot merged commit 5672757e23 into develop 2026-08-29 14:36:05 +08:00

auto-approve-bot deleted branch ci/ci-speedup-phase1 2026-08-29 14:36:05 +08:00

gitea-actions bot commented 2026-08-29 14:38:53 +08:00

Copy Link

Copy Source

🗑️ 预览环境已清理

PR #1536 已关闭或合并，对应的预览环境已被清理。

如有需要，可以重新打开 PR 来重新生成预览环境。

🗑️ **预览环境已清理** PR #1536 已关闭或合并，对应的预览环境已被清理。 > 如有需要，可以重新打开 PR 来重新生成预览环境。

xiaoxia referenced this pull request 2026-08-29 14:51:47 +08:00

fix(ci): push 路径检测改用 compare 响应内每提交 files 聚合 #1539

xiaoxia referenced this issue from a commit 2026-08-31 00:23:28 +08:00

fix(generate): 修复步骤1/2/3缺少下一步按钮 (#1536)

Sign in to join this conversation.

Reviewers

No Reviewers

auto-approve-bot

Labels

Clear labels

P0

阻塞性，必须立即处理

P1

高优先级

P2

中优先级

P3

低优先级/后考虑

architecture

架构设计

backend

后端相关

blocked

阻塞中

bug

Bug修复

ci-bug

CI本身的bug

ci-optimization

CI优化类任务

ci-pipeline

CI流水线/workflow相关

cleanup

代码清理

devops

运维/部署/CI

documentation

文档相关

feature

新功能

frontend

前端相关

question

需要讨论确认

ready

PR CI通过，可合并

refactor

代码重构

No Label

Milestone

No items

No Milestone

Projects

Clear projects

No project

Assignees

Clear assignees

auto-approve-bot xiaoxia

No Assignees

3 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: xiaoxia/xiaoxia-saas#1536