aiagents-stock/docs/DOCKER_CN_BUILD_GUIDE.md

# Docker 国内源构建指南

## 📋 概述

`Dockerfile国内源版` 是专为中国大陆用户优化的Docker构建文件，所有依赖都从国内镜像源下载，大幅提升构建速度。

## 🚀 快速构建

```bash
# Windows PowerShell
docker build -f "Dockerfile国内源版" -t agentsstock1:latest .

# Linux/macOS
docker build -f Dockerfile国内源版 -t agentsstock1:latest .
```

## 🌐 国内镜像源配置

### 1. 基础镜像
- **源**: 华为云Docker镜像仓库
- **地址**: `swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/python:3.12-slim`
- **优势**: 华为云CDN加速，下载速度快

### 2. Debian系统包
- **源**: 阿里云Debian镜像
- **地址**: `mirrors.aliyun.com/debian/`
- **包含**: 
  - `bookworm main` - 主仓库
  - `bookworm-updates` - 更新仓库
  - `bookworm-security` - 安全更新
- **优势**: 国内访问速度快，稳定可靠

### 3. Node.js
- **源**: 淘宝npm镜像（二进制包）
- **地址**: `registry.npmmirror.com/-/binary/node/`
- **版本**: Node.js 18.20.4 LTS（长期支持版）
- **安装方式**: 直接下载预编译二进制包
- **优势**: 
  - 淘宝CDN加速，速度极快
  - 无需配置apt源，更稳定可靠
  - 支持多架构（x64/arm64）
  - 固定版本，可预测性强

### 4. npm包管理器
- **源**: 淘宝npm镜像（npmmirror）
- **地址**: `registry.npmmirror.com`
- **优势**: 
  - 同步频率高（10分钟）
  - CDN加速
  - 完整同步官方npm仓库

### 5. Python pip包
- **源**: 清华大学PyPI镜像
- **地址**: `pypi.tuna.tsinghua.edu.cn/simple/`
- **优势**: 
  - 教育网镜像，速度快
  - 每5分钟同步一次官方PyPI
  - 稳定可靠

## ⚡ 性能对比

| 项目 | 官方源 | 国内源 | 提升 |
|------|--------|--------|------|
| 基础镜像下载 | ~5-10分钟 | ~30-60秒 | **10倍** |
| Debian包安装 | ~3-5分钟 | ~30-60秒 | **5倍** |
| Node.js安装 | ~2-5分钟 | ~30秒 | **6倍** |
| Python依赖 | ~10-15分钟 | ~2-3分钟 | **5倍** |
| **总构建时间** | **20-35分钟** | **4-6分钟** | **🚀 6倍+** |

## 🔧 技术细节

### Node.js安装流程

采用**二进制包直接安装**方案，避免apt源配置问题：

```dockerfile
# 1. 设置版本和检测系统架构
NODE_VERSION=18.20.4
ARCH=$(dpkg --print-architecture)
if [ "$ARCH" = "amd64" ]; then NODE_ARCH="x64"; 
elif [ "$ARCH" = "arm64" ]; then NODE_ARCH="arm64"; fi

# 2. 从淘宝npm镜像下载Node.js二进制包（速度快）
curl -fsSL https://registry.npmmirror.com/-/binary/node/v${NODE_VERSION}/node-v${NODE_VERSION}-linux-${NODE_ARCH}.tar.gz \
    -o /tmp/node.tar.gz

# 3. 解压到系统目录
tar -xzf /tmp/node.tar.gz -C /usr/local --strip-components=1

# 4. 清理临时文件
rm /tmp/node.tar.gz

# 5. 创建软链接（兼容性）
ln -s /usr/local/bin/node /usr/local/bin/nodejs
```

**优势说明**：
- ✅ 无需配置apt源，避免GPG密钥和源地址变更问题
- ✅ 直接从淘宝CDN下载，速度快且稳定
- ✅ 支持x64和arm64架构
- ✅ 版本固定（18.20.4 LTS），确保构建可重现

### 为什么选择这些镜像源？

1. **华为云Docker镜像**: 
   - 国内最大的云服务商之一
   - 全国多地CDN节点
   - 企业级稳定性

2. **阿里云Debian源**: 
   - 阿里巴巴维护，可靠性高
   - 同步频率高
   - 访问速度快

3. **清华大学镜像站**: 
   - 教育网核心节点
   - 同步及时（5-10分钟）
   - 学术机构，长期稳定

4. **淘宝npm镜像**: 
   - 阿里巴巴开源团队维护
   - npm官方推荐的中国镜像
   - 同步最快（10分钟）

## 🐛 常见问题

### 1. GPG密钥下载失败
```
curl -fsSL https://mirrors.tuna.tsinghua.edu.cn/nodesource/gpgkey/nodesource-repo.gpg.key | gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg
```
**解决**: 检查网络连接，或暂时关闭防火墙/代理

### 2. pip安装超时
```dockerfile
RUN pip install --no-cache-dir --default-timeout=1000 -r requirements.txt
```
**说明**: 已设置超时时间为1000秒，应该足够

### 3. Node.js版本问题
当前配置安装Node.js 18.20.4 LTS，如需其他版本：
```dockerfile
# 修改 NODE_VERSION 变量
NODE_VERSION=20.11.1  # 改为20.x LTS
NODE_VERSION=16.20.2  # 改为16.x LTS

# 可用版本查询：https://registry.npmmirror.com/-/binary/node/
```

### 4. 构建缓存问题
如需强制重新构建（不使用缓存）：
```bash
docker build --no-cache -f "Dockerfile国内源版" -t agentsstock1:latest .
```

## 📊 构建日志示例

```
[ 1/10] FROM swr.cn-north-4.myhuaweicloud.com/...  ✅ 1.2s
[ 2/10] RUN echo "deb https://mirrors.aliyun.com...  ✅ 0.3s
[ 3/10] WORKDIR /app                                ✅ 0.0s
[ 4/10] RUN apt-get update && apt-get install...   ✅ 45.2s
[ 5/10] RUN mkdir -p /etc/apt/keyrings &&...       ✅ 28.5s
[ 6/10] RUN node --version && npm --version        ✅ 0.4s
[ 7/10] RUN npm config set registry...             ✅ 0.2s
[ 8/10] COPY requirements.txt .                     ✅ 0.1s
[ 9/10] RUN pip config set && pip install...       ✅ 156.3s
[10/10] COPY . .                                    ✅ 2.1s

✅ 总计: 约 4-5 分钟
```

## 🔄 更新镜像源

如果某个镜像源不可用，可以切换备选源：

### Debian源备选
```dockerfile
# 清华源
deb https://mirrors.tuna.tsinghua.edu.cn/debian/ bookworm main
# 中科大源
deb https://mirrors.ustc.edu.cn/debian/ bookworm main
# 华为源
deb https://repo.huaweicloud.com/debian/ bookworm main
```

### npm源备选
```dockerfile
# 淘宝（推荐）
npm config set registry https://registry.npmmirror.com/
# 腾讯云
npm config set registry https://mirrors.cloud.tencent.com/npm/
# 华为云
npm config set registry https://mirrors.huaweicloud.com/repository/npm/
```

### pip源备选
```dockerfile
# 清华（推荐）
https://pypi.tuna.tsinghua.edu.cn/simple/
# 阿里云
https://mirrors.aliyun.com/pypi/simple/
# 中科大
https://pypi.mirrors.ustc.edu.cn/simple/
# 豆瓣
https://pypi.douban.com/simple/
```

## 📝 完整构建流程

```bash
# 1. 确保在项目根目录
cd /path/to/agentsstock1

# 2. 创建 .env 文件
cp .env.example .env
# 编辑 .env，填入 DEEPSEEK_API_KEY

# 3. 构建镜像（国内源版）
docker build -f "Dockerfile国内源版" -t agentsstock1:latest .

# 4. 运行容器
docker run -d -p 8503:8501 -v $(pwd)/.env:/app/.env --name agentsstock1 agentsstock1:latest

# 5. 查看日志
docker logs -f agentsstock1

# 6. 访问应用
# 打开浏览器: http://localhost:8503
```

## 🎯 推荐配置

### 开发环境
```bash
docker build -f "Dockerfile国内源版" -t agentsstock1:dev .
docker run -d -p 8503:8501 \
  -v $(pwd)/.env:/app/.env \
  -v $(pwd):/app \
  --name agentsstock1-dev \
  agentsstock1:dev
```

### 生产环境
```bash
docker build -f "Dockerfile国内源版" -t agentsstock1:prod .
docker run -d -p 8503:8501 \
  -v $(pwd)/.env:/app/.env \
  -v $(pwd)/data:/app/data \
  --restart unless-stopped \
  --name agentsstock1-prod \
  agentsstock1:prod
```

## ✅ 验证构建结果

```bash
# 检查Node.js版本
docker run --rm agentsstock1:latest node --version
# 预期输出: v18.20.x

# 检查npm版本
docker run --rm agentsstock1:latest npm --version
# 预期输出: 10.x.x

# 检查Python版本
docker run --rm agentsstock1:latest python --version
# 预期输出: Python 3.12.x

# 检查已安装的Python包
docker run --rm agentsstock1:latest pip list
```

## 📚 参考资源

- [清华大学开源软件镜像站](https://mirrors.tuna.tsinghua.edu.cn/)
- [阿里巴巴开源镜像站](https://developer.aliyun.com/mirror/)
- [淘宝npm镜像](https://npmmirror.com/)
- [华为云镜像站](https://mirrors.huaweicloud.com/)

---

**享受高速Docker构建体验！** 🚀