xiaoxia/xiaoxia-saas
1
0
Fork 0
Code Issues 20 Pull Requests 1 Actions 1 Packages Projects Releases 7 Wiki Activity

CI 稳定性治理专项 - 彻底解决 Docker 构建不稳定问题 #1421

New Issue
Closed
opened 2026-08-18 14:42:09 +08:00 by xiaoxia · 0 comments
xiaoxia commented 2026-08-18 14:42:09 +08:00
Owner
Copy Link
Copy Source

CI 稳定性治理专项 - 彻底解决 Docker 构建不稳定问题

问题背景

当前 CI 流水线存在系统性不稳定问题，主要表现为：

  1. Docker 网络池耗尽：高频构建时临时网络累积，超过默认池上限（~31个）导致新构建卡住
  2. API Image 构建超时：Build Staging API Image 经常运行 25+ 分钟甚至无限挂起
  3. Runner 瞬态故障：大量 jobs 的 steps 全部 cancelled，Runner 进程卡死

根因分析

根因 1：Docker 网络池管理不足

  • Docker buildx 每次构建创建临时网络
  • 原有清理策略：每 6 小时一次 docker network prune
  • CI 高峰期（多个 PR 同时提交）网络累积速度 > 清理速度

根因 2：API Image 构建效率低

  • 依赖重复：同时安装 psycopg2-binary==2.9.9 和 psycopg[binary]==3.2.2
  • apt-get 频繁执行：每次构建都要安装 gcc libpq-dev libpq5 ffmpeg
  • 缓存失效：requirements.txt 频繁变更导致 pip install 层重建
  • 网络问题：阿里云 PyPI 镜像不稳定，部分包下载慢

根因 3：Runner 资源与健康检查不足

  • Runner 机器资源竞争（CPU/内存/磁盘）
  • 缺乏 Runner 进程健康检查，卡死后无法自动恢复
  • 缺乏构建超时重试机制

解决方案

阶段一：紧急修复（已完成）

  • PR #1420：Docker buildx build 加 25 分钟超时防止无限挂起
  • 部署 Docker 网络清理脚本（每 1 小时）
  • 部署 buildx 清理脚本（每 30 分钟）

阶段二：API Image 构建优化（本周完成）

任务 2.1：删除重复依赖

  • 删除 psycopg2-binary==2.9.9，保留 psycopg[binary]==3.2.2
  • 验证代码中 psycopg2 的导入，迁移到 psycopg3
  • 预计减少 2-3 分钟构建时间

任务 2.2：预构建基础镜像

创建 xiaoxia-saas-api-base 基础镜像，包含：

FROM python:3.12-slim
# 预装 apt 依赖
RUN apt-get update && apt-get install -y \
    gcc libpq-dev libpq5 ffmpeg \
    && rm -rf /var/lib/apt/lists/*
# 预装 pip 依赖
COPY requirements-base.txt requirements.txt /tmp/
RUN pip install --no-cache-dir -r /tmp/requirements-base.txt -r /tmp/requirements.txt

API Dockerfile 改为：

FROM xiaoxia-registry.cn-hangzhou.cr.aliyuncs.com/xiaoxia/saas-api-base:latest
# 只复制应用代码，不重新安装依赖
COPY apps/api/ /app/apps/api/

预计构建时间：25 分钟 → 3-5 分钟

任务 2.3：优化 Docker 缓存策略

  • 使用 --mount=type=cache 缓存 apt 包
  • 使用 --mount=type=cache 缓存 pip 下载（已有）
  • 分离 requirements-base.txt 和 requirements.txt 的 COPY 步骤（已有）

阶段三：Runner 健康检查与扩容（下周完成）

任务 3.1：Runner 进程监控

在构建服务器上部署监控脚本：

#!/bin/bash
# /opt/ci-ops/runner-health-check.sh
RUNNERS=("docker-runner-9" "docker-runner-10" "docker-runner-11" "docker-runner-12")
for runner in "${RUNNERS[@]}"; do
    if ! docker ps | grep -q $runner; then
        echo "[$(date)] Runner $runner is down, restarting..."
        # 重启逻辑
    fi
done

Crontab 每 5 分钟执行一次。

任务 3.2：构建超时自动重试

在 CI workflow 中添加：

- name: Build and push image
  run: |
    for i in 1 2 3; do
      if docker buildx build --timeout 25m ...; then
        break
      fi
      echo "Build failed, retry $i/3..."
      sleep 10
    done
  timeout-minutes: 30

任务 3.3：Runner 扩容

  • 增加 2 个专用 API Image 构建 Runner（4核 8GB）
  • 其他 Runner 只负责轻量级 jobs（lint/test）
  • 通过 labels 分离：ci-heavy vs ci-light

阶段四：长期优化（1 个月内）

任务 4.1：CI 流水线分层

  • 快速通道（<5分钟）：lint + type check + unit tests
  • 构建通道（并行）：API/Web/Worker Image build
  • 部署通道（串行）：staging deploy + E2E tests

任务 4.2：外部构建缓存

  • 使用 ACR 作为 Docker 层缓存
  • 预构建所有基础镜像（python-base, node-base, worker-base）
  • 定期更新基础镜像（每周一次）

验收标准

阶段二验收（本周）

  • API Image 构建时间 < 10 分钟（从 25+ 分钟降低）
  • 无重复依赖（psycopg2-binary 已删除）
  • 基础镜像 xiaoxia-saas-api-base 已构建并推送

阶段三验收（下周）

  • Runner 健康检查脚本部署，卡死后 5 分钟内自动恢复
  • 构建超时自动重试机制生效
  • 新增 2 个高配 Runner 已上线

阶段四验收（1 个月）

  • CI 流水线快速通道 < 5 分钟
  • Docker 构建网络池耗尽事件 = 0
  • Runner 瞬态故障事件 < 2 次/周
  • CI 整体成功率 > 95%

时间线

阶段 任务 负责人 截止日期 状态
一 超时保护 + 网络清理 构建运维 2026-08-18 ✅ 已完成
二 API Image 优化 后端编程 2026-08-22 ⏳ 待开始
三 Runner 健康检查 + 扩容 构建运维 2026-08-29 ⏳ 待开始
四 CI 流水线分层 后端编程 + 构建运维 2026-09-18 ⏳ 待开始

相关 PR

  • PR #1420：docker buildx build 加 25 分钟超时防止无限挂起（已合并）
  • PR #1421：添加 Docker 网络清理脚本（每 1 小时）（已合并）
  • PR #1422：添加 buildx 清理脚本（每 30 分钟）（已合并）

监控指标

部署后需要持续监控：

  1. API Image 构建时间（目标 < 10 分钟）
  2. Docker 网络池使用率（目标 < 50%）
  3. Runner 健康状态（目标 > 95% 在线率）
  4. CI 整体成功率（目标 > 95%）

优先级：P0（阻塞开发效率）
影响范围：所有 PR 合并和部署
预估工作量：40 人时

# CI 稳定性治理专项 - 彻底解决 Docker 构建不稳定问题 ## 问题背景 当前 CI 流水线存在系统性不稳定问题，主要表现为： 1. **Docker 网络池耗尽**：高频构建时临时网络累积，超过默认池上限（~31个）导致新构建卡住 2. **API Image 构建超时**：Build Staging API Image 经常运行 25+ 分钟甚至无限挂起 3. **Runner 瞬态故障**：大量 jobs 的 steps 全部 `cancelled`，Runner 进程卡死 ## 根因分析 ### 根因 1：Docker 网络池管理不足 - Docker buildx 每次构建创建临时网络 - 原有清理策略：每 6 小时一次 `docker network prune` - CI 高峰期（多个 PR 同时提交）网络累积速度 > 清理速度 ### 根因 2：API Image 构建效率低 - **依赖重复**：同时安装 `psycopg2-binary==2.9.9` 和 `psycopg[binary]==3.2.2` - **apt-get 频繁执行**：每次构建都要安装 `gcc libpq-dev libpq5 ffmpeg` - **缓存失效**：`requirements.txt` 频繁变更导致 pip install 层重建 - **网络问题**：阿里云 PyPI 镜像不稳定，部分包下载慢 ### 根因 3：Runner 资源与健康检查不足 - Runner 机器资源竞争（CPU/内存/磁盘） - 缺乏 Runner 进程健康检查，卡死后无法自动恢复 - 缺乏构建超时重试机制 ## 解决方案 ### 阶段一：紧急修复（已完成） - [x] PR #1420：Docker buildx build 加 25 分钟超时防止无限挂起 - [x] 部署 Docker 网络清理脚本（每 1 小时） - [x] 部署 buildx 清理脚本（每 30 分钟） ### 阶段二：API Image 构建优化（本周完成） #### 任务 2.1：删除重复依赖 - 删除 `psycopg2-binary==2.9.9`，保留 `psycopg[binary]==3.2.2` - 验证代码中 psycopg2 的导入，迁移到 psycopg3 - 预计减少 2-3 分钟构建时间 #### 任务 2.2：预构建基础镜像 创建 `xiaoxia-saas-api-base` 基础镜像，包含： ```dockerfile FROM python:3.12-slim # 预装 apt 依赖 RUN apt-get update && apt-get install -y \ gcc libpq-dev libpq5 ffmpeg \ && rm -rf /var/lib/apt/lists/* # 预装 pip 依赖 COPY requirements-base.txt requirements.txt /tmp/ RUN pip install --no-cache-dir -r /tmp/requirements-base.txt -r /tmp/requirements.txt ``` API Dockerfile 改为： ```dockerfile FROM xiaoxia-registry.cn-hangzhou.cr.aliyuncs.com/xiaoxia/saas-api-base:latest # 只复制应用代码，不重新安装依赖 COPY apps/api/ /app/apps/api/ ``` 预计构建时间：25 分钟 → 3-5 分钟 #### 任务 2.3：优化 Docker 缓存策略 - 使用 `--mount=type=cache` 缓存 apt 包 - 使用 `--mount=type=cache` 缓存 pip 下载（已有） - 分离 `requirements-base.txt` 和 `requirements.txt` 的 COPY 步骤（已有） ### 阶段三：Runner 健康检查与扩容（下周完成） #### 任务 3.1：Runner 进程监控 在构建服务器上部署监控脚本： ```bash #!/bin/bash # /opt/ci-ops/runner-health-check.sh RUNNERS=("docker-runner-9" "docker-runner-10" "docker-runner-11" "docker-runner-12") for runner in "${RUNNERS[@]}"; do if ! docker ps | grep -q $runner; then echo "[$(date)] Runner $runner is down, restarting..." # 重启逻辑 fi done ``` Crontab 每 5 分钟执行一次。 #### 任务 3.2：构建超时自动重试 在 CI workflow 中添加： ```yaml - name: Build and push image run: | for i in 1 2 3; do if docker buildx build --timeout 25m ...; then break fi echo "Build failed, retry $i/3..." sleep 10 done timeout-minutes: 30 ``` #### 任务 3.3：Runner 扩容 - 增加 2 个专用 API Image 构建 Runner（4核 8GB） - 其他 Runner 只负责轻量级 jobs（lint/test） - 通过 labels 分离：`ci-heavy` vs `ci-light` ### 阶段四：长期优化（1 个月内） #### 任务 4.1：CI 流水线分层 - **快速通道**（<5分钟）：lint + type check + unit tests - **构建通道**（并行）：API/Web/Worker Image build - **部署通道**（串行）：staging deploy + E2E tests #### 任务 4.2：外部构建缓存 - 使用 ACR 作为 Docker 层缓存 - 预构建所有基础镜像（python-base, node-base, worker-base） - 定期更新基础镜像（每周一次） ## 验收标准 ### 阶段二验收（本周） - [ ] API Image 构建时间 < 10 分钟（从 25+ 分钟降低） - [ ] 无重复依赖（psycopg2-binary 已删除） - [ ] 基础镜像 `xiaoxia-saas-api-base` 已构建并推送 ### 阶段三验收（下周） - [ ] Runner 健康检查脚本部署，卡死后 5 分钟内自动恢复 - [ ] 构建超时自动重试机制生效 - [ ] 新增 2 个高配 Runner 已上线 ### 阶段四验收（1 个月） - [ ] CI 流水线快速通道 < 5 分钟 - [ ] Docker 构建网络池耗尽事件 = 0 - [ ] Runner 瞬态故障事件 < 2 次/周 - [ ] CI 整体成功率 > 95% ## 时间线 | 阶段 | 任务 | 负责人 | 截止日期 | 状态 | |------|------|--------|----------|------| | 一 | 超时保护 + 网络清理 | 构建运维 | 2026-08-18 | ✅ 已完成 | | 二 | API Image 优化 | 后端编程 | 2026-08-22 | ⏳ 待开始 | | 三 | Runner 健康检查 + 扩容 | 构建运维 | 2026-08-29 | ⏳ 待开始 | | 四 | CI 流水线分层 | 后端编程 + 构建运维 | 2026-09-18 | ⏳ 待开始 | ## 相关 PR - PR #1420：docker buildx build 加 25 分钟超时防止无限挂起（已合并） - PR #1421：添加 Docker 网络清理脚本（每 1 小时）（已合并） - PR #1422：添加 buildx 清理脚本（每 30 分钟）（已合并） ## 监控指标 部署后需要持续监控： 1. API Image 构建时间（目标 < 10 分钟） 2. Docker 网络池使用率（目标 < 50%） 3. Runner 健康状态（目标 > 95% 在线率） 4. CI 整体成功率（目标 > 95%） --- **优先级**：P0（阻塞开发效率） **影响范围**：所有 PR 合并和部署 **预估工作量**：40 人时
xiaoxia added the P3 label 2026-08-18 14:42:09 +08:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
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 P3
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
auto-approve-bot xiaoxia
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: xiaoxia/xiaoxia-saas#1421
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?