205 lines
4.4 KiB
Markdown
205 lines
4.4 KiB
Markdown
# 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 |