# Docker 本地镜像构建步骤指南

## 概述
本文档详细记录了在本地构建前端应用Docker镜像的完整步骤，包括问题排查和解决方案。

## 环境要求
- Docker Desktop 已安装并运行
- 项目目录：`d:\work\Aiproject\DeotalandAi\apps\frontend`

## 构建步骤

### 1. 初始构建尝试

#### 1.1 执行构建命令
```bash
cd d:\work\Aiproject\DeotalandAi\apps\frontend
docker build -t deotaland-frontend .
```

#### 1.2 遇到的第一个问题
**错误信息：**
```
ERROR: pull access denied, repository does not exist or may require authorization
```

**问题原因：** 原Dockerfile使用了阿里云镜像源 `registry.cn-hangzhou.aliyuncs.com/library/node:18-alpine`，但该镜像源无法访问。

**解决方案：** 修改为使用官方Docker Hub镜像源。

### 2. Dockerfile修改

#### 2.1 修改基础镜像
将：
```dockerfile
FROM registry.cn-hangzhou.aliyuncs.com/library/node:18-alpine
```
修改为：
```dockerfile
FROM node:20-alpine
```

#### 2.2 调整依赖安装策略
将：
```dockerfile
RUN npm ci --only=production
```
修改为：
```dockerfile
RUN npm ci
```

**原因：** 需要安装开发依赖（如vite）来构建项目。

#### 2.3 升级Node.js版本
从Node.js 18升级到20，解决Vite版本兼容性问题：
```dockerfile
FROM node:18-alpine  # 旧版本
FROM node:20-alpine  # 新版本
```

### 3. 最终Dockerfile配置

```dockerfile
# 使用官方Node.js镜像
FROM node:20-alpine

# 设置工作目录
WORKDIR /app

# 复制 package.json 和 package-lock.json
COPY package*.json ./

# 使用国内npm镜像源
RUN npm config set registry https://registry.npmmirror.com/

# 复制项目文件
COPY . .

# 安装所有依赖（包括开发依赖）
RUN npm ci

# 构建生产版本
RUN npm run build

# 安装 serve 来提供静态文件服务
RUN npm install -g serve

# 暴露端口
EXPOSE 3000

# 启动命令
CMD ["serve", "-s", "dist", "-l", "3000"]
```

### 4. 成功构建

#### 4.1 执行构建
```bash
docker build -t deotaland-frontend .
```

#### 4.2 构建输出
```
 => [internal] load build definition from Dockerfile
 => [internal] load .dockerignore
 => [internal] load metadata for docker.io/library/node:20-alpine
 => [1/8] FROM docker.io/library/node:20-alpine
 => [2/8] WORKDIR /app
 => [3/8] COPY package*.json ./
 => [4/8] RUN npm config set registry https://registry.npmmirror.com/
 => [5/8] COPY . .
 => [6/8] RUN npm ci
 => [7/8] RUN npm run build
 => [8/8] RUN npm install -g serve
 => exporting to image
 => => exporting layers
 => => writing image sha256:...
 => => naming to docker.io/library/deotaland-frontend:latest
```

### 5. 运行容器

#### 5.1 启动容器
```bash
docker run -d -p 3001:3000 --name deotaland-frontend-container deotaland-frontend
```

#### 5.2 验证运行状态
```bash
docker ps
```

#### 5.3 查看容器日志
```bash
docker logs deotaland-frontend-container
```

**预期输出：**
```
INFO  Accepting connections at http://localhost:3000
```

### 6. 访问应用

应用运行在：http://localhost:3001

## 常见问题及解决方案

### 6.1 端口冲突
**问题：** 端口3000已被占用
**解决方案：** 使用不同的主机端口映射，如3001:3000

### 6.2 容器名称冲突
**问题：** 容器名称已存在
**解决方案：** 
```bash
docker rm deotaland-frontend-container
```

### 6.3 构建失败
**问题：** vite命令未找到
**解决方案：** 确保安装了所有依赖，不要使用`--only=production`

### 6.4 Node.js版本不兼容
**问题：** Vite需要Node.js 20.19+或22.12+
**解决方案：** 升级到Node.js 20

## 最佳实践

### 7.1 镜像优化建议
- 使用多阶段构建减少镜像大小
- 合理利用缓存层
- 使用`.dockerignore`文件排除不必要的文件

### 7.2 安全建议
- 使用非root用户运行应用
- 定期更新基础镜像
- 扫描镜像漏洞

### 7.3 性能优化
- 使用国内npm镜像源加速构建
- 合理设置工作目录
- 优化文件复制顺序

## 后续步骤

1. 配置CI/CD流水线自动构建
2. 设置镜像仓库推送
3. 配置生产环境部署
4. 设置监控和日志收集

## 相关文件

- `Dockerfile` - Docker镜像构建配置
- `.dockerignore` - Docker构建忽略文件
- `package.json` - 项目依赖配置
- `docker-compose.yml` - Docker Compose配置（如存在）

---

**构建完成时间：** $(date)
**构建状态：** ✅ 成功
**镜像名称：** deotaland-frontend
**容器名称：** deotaland-frontend-container
**访问地址：** http://localhost:3001