fix: avoid Docker Hub timeout in Gitea builds

2026-07-28 09:37:32 +08:00
parent f711e77849
commit 7a36169f5d
4 changed files with 21 additions and 2 deletions
@@ -1535,3 +1535,19 @@
 - 相关记录：BUG-082
 - 复发自：BUG-082
 - 修复版本：待提交（本地可测）
+
+## BUG-084 | Gitea Runner 构建镜像访问 Docker Hub 超时
+
+- 状态：resolved
+- 首次发现：2026-07-28
+- 最近更新：2026-07-28
+- 影响面：Gitea staging 镜像构建与发布
+- 用户现象：镜像构建在解析 `python:3.12-slim` 基础镜像时访问 `registry-1.docker.io` 超时，退出码为 1；代码检出、镜像仓库登录均已成功。
+- 触发条件：xiaoxin Runner 构建 `deploy/railway-api.Dockerfile` 或 `deploy/railway-web.Dockerfile`，且到 Docker Hub 的 HTTPS 连接不可用或不稳定。
+- 根因：Railway API/Web Dockerfile 直接依赖 Docker Hub 官方 registry；本次失败发生在 Dockerfile 第 1 行的基础镜像 metadata 拉取阶段，不是应用代码、依赖安装或 ACR 登录失败。
+- 修复：将 API 的 Python 基础镜像和 Web 的 Node 基础镜像切换为可从当前网络稳定访问的阿里云公共镜像同步地址；增加 Dockerfile 契约断言，防止后续恢复为 Docker Hub 直连。
+- 验证：`tests/test_railway_deployment.py` 的静态契约已更新；当前本机 pytest 7.4.4 低于项目要求的 pytest 8.0，测试执行被项目配置门禁阻断，未伪报通过。
+- 防复发：镜像构建前必须验证基础镜像 registry 可达；统一基础镜像来源，不要在受限 Runner 上直接依赖 Docker Hub；若镜像同步源发生变更，应先更新契约和执行实际构建验证。
+- 相关记录：BUG-082、BUG-083
+- 复发自：无
+- 修复版本：待提交（本地可测）