From 3c95ae0000d08da59e7a7b07c024f1f4643ca861 Mon Sep 17 00:00:00 2001
From: bujie9527 <bujie9527@users.noreply.github.com>
Date: Thu, 5 Feb 2026 22:42:05 +0800
Subject: [PATCH] Add Docker mirror configuration and build scripts

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 DOCKER_MIRROR_CONFIG.md        | 119 +++++++++++++++++++++++++++++++++
 QUICK_BUILD.md                 | 112 +++++++++++++++++++++++++++++++
 deploy/docker/admin.Dockerfile |   7 +-
 scripts/build-with-mirror.ps1  |  99 +++++++++++++++++++++++++++
 4 files changed, 335 insertions(+), 2 deletions(-)
 create mode 100644 DOCKER_MIRROR_CONFIG.md
 create mode 100644 QUICK_BUILD.md
 create mode 100644 scripts/build-with-mirror.ps1

diff --git a/DOCKER_MIRROR_CONFIG.md b/DOCKER_MIRROR_CONFIG.md
new file mode 100644
index 0000000..71e915b
--- /dev/null
+++ b/DOCKER_MIRROR_CONFIG.md
@@ -0,0 +1,119 @@
+# Docker 镜像加速配置（Windows Docker Desktop）
+
+## 快速配置步骤
+
+### 1. 打开 Docker Desktop 设置
+
+1. 右键点击系统托盘中的 **Docker Desktop** 图标
+2. 选择 **Settings**（设置）
+
+### 2. 配置镜像加速
+
+1. 在左侧菜单选择 **Docker Engine**
+2. 在 JSON 配置中添加 `registry-mirrors`：
+
+```json
+{
+  "builder": {
+    "gc": {
+      "defaultKeepStorage": "20GB",
+      "enabled": true
+    }
+  },
+  "experimental": false,
+  "registry-mirrors": [
+    "https://docker.mirrors.ustc.edu.cn",
+    "https://hub-mirror.c.163.com",
+    "https://mirror.baidubce.com"
+  ]
+}
+```
+
+3. 点击 **Apply & Restart**
+4. 等待 Docker 重启完成（通常需要 10-30 秒）
+
+### 3. 验证配置
+
+重启后，在终端运行：
+
+```powershell
+docker info | Select-String -Pattern "Registry Mirrors"
+```
+
+应该能看到配置的镜像源。
+
+### 4. 重新构建
+
+配置完成后，重新运行构建命令：
+
+```powershell
+docker build -f deploy/docker/backend.Dockerfile -t registry.667788.cool/wecom-ai/wecom-ai-backend:latest .
+```
+
+## 镜像源列表
+
+### 推荐镜像源（按优先级）
+
+1. **USTC 镜像**：`https://docker.mirrors.ustc.edu.cn`
+   - 中科大镜像，速度较快
+   
+2. **网易镜像**：`https://hub-mirror.c.163.com`
+   - 网易提供，稳定可靠
+
+3. **百度镜像**：`https://mirror.baidubce.com`
+   - 百度云提供
+
+4. **阿里云镜像**（需要账号）：
+   - 访问：https://cr.console.aliyun.com/cn-hangzhou/instances/mirrors
+   - 获取专属加速地址
+
+## 如果配置后仍然失败
+
+### 方案 A：使用构建参数
+
+```powershell
+# Backend
+docker build --build-arg PYTHON_IMAGE=docker.mirrors.ustc.edu.cn/library/python:3.12-slim -f deploy/docker/backend.Dockerfile -t registry.667788.cool/wecom-ai/wecom-ai-backend:latest .
+
+# Admin
+docker build --build-arg NODE_IMAGE=docker.mirrors.ustc.edu.cn/library/node:20-alpine -f deploy/docker/admin.Dockerfile -t registry.667788.cool/wecom-ai/wecom-ai-admin:latest .
+```
+
+### 方案 B：手动拉取基础镜像
+
+```powershell
+# 拉取基础镜像
+docker pull docker.mirrors.ustc.edu.cn/library/python:3.12-slim
+docker pull docker.mirrors.ustc.edu.cn/library/node:20-alpine
+
+# 打标签
+docker tag docker.mirrors.ustc.edu.cn/library/python:3.12-slim python:3.12-slim
+docker tag docker.mirrors.ustc.edu.cn/library/node:20-alpine node:20-alpine
+
+# 然后正常构建
+docker build -f deploy/docker/backend.Dockerfile -t registry.667788.cool/wecom-ai/wecom-ai-backend:latest .
+```
+
+## 验证配置是否生效
+
+```powershell
+# 查看 Docker 信息
+docker info
+
+# 查看镜像加速配置
+docker info | Select-String "Registry Mirrors" -Context 0,5
+```
+
+## 完成后的操作
+
+配置完成后，可以正常构建和推送：
+
+```powershell
+# 构建 Backend
+docker build -f deploy/docker/backend.Dockerfile -t registry.667788.cool/wecom-ai/wecom-ai-backend:latest .
+docker push registry.667788.cool/wecom-ai/wecom-ai-backend:latest
+
+# 构建 Admin
+docker build -f deploy/docker/admin.Dockerfile -t registry.667788.cool/wecom-ai/wecom-ai-admin:latest .
+docker push registry.667788.cool/wecom-ai/wecom-ai-admin:latest
+```
diff --git a/QUICK_BUILD.md b/QUICK_BUILD.md
new file mode 100644
index 0000000..d490fe1
--- /dev/null
+++ b/QUICK_BUILD.md
@@ -0,0 +1,112 @@
+# 快速构建并推送到 registry.667788.cool
+
+## 问题：无法连接 Docker Hub
+
+如果遇到 `failed to fetch oauth token` 错误，需要配置 Docker 镜像加速。
+
+## 解决方案
+
+### 方案一：配置 Docker Desktop 镜像加速（推荐）
+
+1. **打开 Docker Desktop**
+2. **Settings** → **Docker Engine**
+3. **添加镜像加速配置**：
+   ```json
+   {
+     "registry-mirrors": [
+       "https://docker.mirrors.ustc.edu.cn",
+       "https://hub-mirror.c.163.com",
+       "https://mirror.baidubce.com"
+     ]
+   }
+   ```
+4. **点击 Apply & Restart**
+5. **等待 Docker 重启完成**
+
+### 方案二：使用构建参数指定镜像源
+
+如果无法配置 Docker Desktop，可以使用构建参数：
+
+#### 构建 Backend 镜像
+
+```powershell
+# 使用 USTC 镜像源
+docker build --build-arg PYTHON_IMAGE=docker.mirrors.ustc.edu.cn/library/python:3.12-slim -f deploy/docker/backend.Dockerfile -t registry.667788.cool/wecom-ai/wecom-ai-backend:latest .
+
+# 推送
+docker push registry.667788.cool/wecom-ai/wecom-ai-backend:latest
+```
+
+#### 构建 Admin 镜像
+
+```powershell
+# 使用 USTC 镜像源
+docker build --build-arg NODE_IMAGE=docker.mirrors.ustc.edu.cn/library/node:20-alpine -f deploy/docker/admin.Dockerfile -t registry.667788.cool/wecom-ai/wecom-ai-admin:latest .
+
+# 推送
+docker push registry.667788.cool/wecom-ai/wecom-ai-admin:latest
+```
+
+## 完整构建流程
+
+### 1. 配置镜像加速（方案一）
+
+按照上面的方案一配置 Docker Desktop。
+
+### 2. 构建并推送镜像
+
+```powershell
+# Backend
+docker build -f deploy/docker/backend.Dockerfile -t registry.667788.cool/wecom-ai/wecom-ai-backend:latest .
+docker push registry.667788.cool/wecom-ai/wecom-ai-backend:latest
+
+# Admin
+docker build -f deploy/docker/admin.Dockerfile -t registry.667788.cool/wecom-ai/wecom-ai-admin:latest .
+docker push registry.667788.cool/wecom-ai/wecom-ai-admin:latest
+```
+
+### 3. 验证
+
+```powershell
+# 查看本地镜像
+docker images | grep registry.667788.cool
+
+# 应该看到：
+# registry.667788.cool/wecom-ai/wecom-ai-backend   latest   ...
+# registry.667788.cool/wecom-ai/wecom-ai-admin     latest   ...
+```
+
+## 如果 Registry 需要认证
+
+```powershell
+# 登录 Registry
+docker login registry.667788.cool
+# 输入用户名和密码
+```
+
+## 故障排查
+
+### 问题：仍然无法拉取基础镜像
+
+**解决方案**：
+1. 尝试其他镜像源：
+   - `hub-mirror.c.163.com/library/python:3.12-slim`
+   - `mirror.baidubce.com/library/python:3.12-slim`
+2. 使用代理
+3. 手动拉取基础镜像：
+   ```powershell
+   docker pull docker.mirrors.ustc.edu.cn/library/python:3.12-slim
+   docker tag docker.mirrors.ustc.edu.cn/library/python:3.12-slim python:3.12-slim
+   ```
+
+### 问题：推送失败
+
+**检查项**：
+1. Registry 是否需要登录
+2. 网络连接是否正常
+3. 镜像名称格式是否正确
+
+## 参考文档
+
+- [Docker 镜像加速配置](./docs/docker-mirror.md)
+- [Registry 配置指南](./REGISTRY_667788_SETUP.md)
diff --git a/deploy/docker/admin.Dockerfile b/deploy/docker/admin.Dockerfile
index 28971b7..5b4c03d 100644
--- a/deploy/docker/admin.Dockerfile
+++ b/deploy/docker/admin.Dockerfile
@@ -1,6 +1,8 @@
 # 生产环境 Admin Dockerfile（最小构建）
 # 用途：构建优化的 Next.js 生产镜像
-FROM node:20-alpine AS builder
+# 支持通过构建参数指定基础镜像
+ARG NODE_IMAGE=node:20-alpine
+FROM ${NODE_IMAGE} AS builder
 
 WORKDIR /app
 
@@ -22,7 +24,8 @@ ENV NEXT_TELEMETRY_DISABLED=1
 RUN npm run build
 
 # 生产镜像
-FROM node:20-alpine
+ARG NODE_IMAGE=node:20-alpine
+FROM ${NODE_IMAGE}
 
 WORKDIR /app
 
diff --git a/scripts/build-with-mirror.ps1 b/scripts/build-with-mirror.ps1
new file mode 100644
index 0000000..ad0cca6
--- /dev/null
+++ b/scripts/build-with-mirror.ps1
@@ -0,0 +1,99 @@
+# 使用镜像源构建并推送镜像
+# 用途：解决无法连接 Docker Hub 的问题
+
+param(
+    [string]$RegistryUrl = "registry.667788.cool",
+    [string]$Namespace = "wecom-ai",
+    [string]$Tag = "latest"
+)
+
+Write-Host "=== 使用镜像源构建并推送镜像 ===" -ForegroundColor Cyan
+Write-Host ""
+
+# 镜像源配置（按优先级）
+$mirrors = @(
+    "docker.mirrors.ustc.edu.cn/library",
+    "hub-mirror.c.163.com",
+    "mirror.baidubce.com"
+)
+
+$pythonImage = "python:3.12-slim"
+$nodeImage = "node:20-alpine"
+
+Write-Host "尝试使用镜像源构建..." -ForegroundColor Yellow
+Write-Host ""
+
+# 尝试使用第一个镜像源
+$mirrorBase = $mirrors[0]
+$pythonMirror = "${mirrorBase}/${pythonImage}"
+$nodeMirror = "${mirrorBase}/${nodeImage}"
+
+Write-Host "使用镜像源: $mirrorBase" -ForegroundColor Cyan
+Write-Host ""
+
+# 构建 Backend 镜像
+Write-Host "=== 构建 Backend 镜像 ===" -ForegroundColor Cyan
+$backendImage = "${RegistryUrl}/${Namespace}/wecom-ai-backend:${Tag}"
+Write-Host "镜像: $backendImage" -ForegroundColor Gray
+Write-Host "基础镜像: $pythonMirror" -ForegroundColor Gray
+Write-Host ""
+
+Write-Host "构建中..." -ForegroundColor Yellow
+docker build --build-arg PYTHON_IMAGE=$pythonMirror -f deploy/docker/backend.Dockerfile -t $backendImage .
+if ($LASTEXITCODE -ne 0) {
+    Write-Host "✗ Backend 构建失败" -ForegroundColor Red
+    Write-Host ""
+    Write-Host "请尝试以下解决方案:" -ForegroundColor Yellow
+    Write-Host "1. 配置 Docker Desktop 镜像加速（推荐）" -ForegroundColor Gray
+    Write-Host "   Docker Desktop → Settings → Docker Engine" -ForegroundColor Gray
+    Write-Host "   添加: `"registry-mirrors\": [\"https://docker.mirrors.ustc.edu.cn\"]`" -ForegroundColor Gray
+    Write-Host ""
+    Write-Host "2. 使用代理" -ForegroundColor Gray
+    Write-Host ""
+    Write-Host "3. 手动拉取基础镜像后再构建" -ForegroundColor Gray
+    Write-Host "   docker pull $pythonMirror" -ForegroundColor Gray
+    exit 1
+}
+Write-Host "✓ Backend 构建成功" -ForegroundColor Green
+
+Write-Host "推送中..." -ForegroundColor Yellow
+docker push $backendImage
+if ($LASTEXITCODE -ne 0) {
+    Write-Host "✗ Backend 推送失败" -ForegroundColor Red
+    Write-Host "提示: 请检查 Registry 是否需要登录" -ForegroundColor Yellow
+    Write-Host "  docker login $RegistryUrl" -ForegroundColor Gray
+    exit 1
+}
+Write-Host "✓ Backend 推送成功" -ForegroundColor Green
+Write-Host ""
+
+# 构建 Admin 镜像
+Write-Host "=== 构建 Admin 镜像 ===" -ForegroundColor Cyan
+$adminImage = "${RegistryUrl}/${Namespace}/wecom-ai-admin:${Tag}"
+Write-Host "镜像: $adminImage" -ForegroundColor Gray
+Write-Host "基础镜像: $nodeMirror" -ForegroundColor Gray
+Write-Host ""
+
+Write-Host "构建中..." -ForegroundColor Yellow
+docker build --build-arg NODE_IMAGE=$nodeMirror -f deploy/docker/admin.Dockerfile -t $adminImage .
+if ($LASTEXITCODE -ne 0) {
+    Write-Host "✗ Admin 构建失败" -ForegroundColor Red
+    exit 1
+}
+Write-Host "✓ Admin 构建成功" -ForegroundColor Green
+
+Write-Host "推送中..." -ForegroundColor Yellow
+docker push $adminImage
+if ($LASTEXITCODE -ne 0) {
+    Write-Host "✗ Admin 推送失败" -ForegroundColor Red
+    exit 1
+}
+Write-Host "✓ Admin 推送成功" -ForegroundColor Green
+Write-Host ""
+
+Write-Host "=== 完成 ===" -ForegroundColor Green
+Write-Host ""
+Write-Host "镜像已推送到:" -ForegroundColor Cyan
+Write-Host "  - $backendImage" -ForegroundColor Gray
+Write-Host "  - $adminImage" -ForegroundColor Gray
+Write-Host ""