deotalandAi/apps/frontend/DEPLOYMENT_GUIDE.md

# 🚀 前端 Docker 镜像部署到后端服务器完整指南

## 📋 部署流程概览

```
本地构建 → 导出镜像 → 上传服务器 → 导入镜像 → 启动容器
     ↓           ↓           ↓           ↓           ↓
  前端负责    前端负责    前端/后端   后端负责    后端负责
```

---

## 👥 角色分工

### 🔧 前端开发者职责
- ✅ 构建 Docker 镜像
- ✅ 测试镜像本地运行
- ✅ 导出镜像文件
- ✅ 提供部署文档和配置文件

### 🖥️ 后端运维职责
- ✅ 提供服务器访问权限
- ✅ 接收镜像文件
- ✅ 导入并运行容器
- ✅ 配置域名和 SSL（如需要）

---

## 📝 步骤详解

### 🎯 第一步：后端提供的信息

**后端需要向前端提供：**

```bash
# 1. 服务器连接信息
服务器IP: 192.168.1.100
用户名: deploy
端口: 22

# 2. 部署目录
部署路径: /app/frontend

# 3. 端口信息
应用端口: 3000
域名: your-domain.com
```

### 🏗️ 第二步：前端本地构建镜像

#### 1. 确保代码可正常构建
```bash
# 本地测试构建
npm run build

# 检查构建结果
ls -la dist/
```

#### 2. 构建 Docker 镜像
```bash
# 在项目根目录执行
cd d:\work\Aiproject\DeotalandAi\apps\frontend

# 构建镜像（使用版本号标记）
docker build -t deotaland-frontend:v1.0.0 .

# 验证镜像构建成功
docker images | grep deotaland-frontend
```

#### 3. 本地测试镜像
```bash
# 运行容器测试
docker run -d -p 3001:3000 --name test-frontend deotaland-frontend:v1.0.0

# 检查容器状态
docker ps

# 测试访问（本地浏览器）
# 访问: http://localhost:3001

# 停止测试容器
docker stop test-frontend
docker rm test-frontend
```

### 📦 第三步：导出镜像

#### 1. 保存镜像为文件
```bash
# 导出镜像（文件会很大，这是正常的）
docker save -o deotaland-frontend-v1.0.0.tar deotaland-frontend:v1.0.0

# 检查文件大小
ls -lh deotaland-frontend-v1.0.0.tar
```

#### 2. 压缩镜像文件（推荐）
```bash
# Windows 上压缩
powershell Compress-Archive deotaland-frontend-v1.0.0.tar deotaland-frontend-v1.0.0.tar.zip

# 或者使用 7zip
7z a deotaland-frontend-v1.0.0.tar.gz deotaland-frontend-v1.0.0.tar
```

### 🚀 第四步：上传到服务器

#### 方法 A：使用 SCP（推荐）
```bash
# 直接上传（需要服务器SSH权限）
scp deotaland-frontend-v1.0.0.tar.gz deploy@192.168.1.100:/app/frontend/

# 如果端口不是22
scp -P 2222 deotaland-frontend-v1.0.0.tar.gz deploy@192.168.1.100:/app/frontend/
```

#### 方法 B：使用 FTP/SFTP 工具
- FileZilla
- WinSCP
- MobaXterm

#### 方法 C：通过中间存储
```bash
# 上传到云存储（如阿里云OSS、AWS S3）
# 后端再从云存储下载
```

### 🔧 第五步：后端导入和运行

#### 1. 登录服务器
```bash
# 后端操作
ssh deploy@192.168.1.100

# 进入部署目录
cd /app/frontend
```

#### 2. 解压文件（如果需要）
```bash
# 解压 tar.gz
gunzip deotaland-frontend-v1.0.0.tar.gz

# 或者解压 zip
unzip deotaland-frontend-v1.0.0.tar.zip
```

#### 3. 导入镜像
```bash
# 导入 Docker 镜像
docker load -i deotaland-frontend-v1.0.0.tar

# 验证导入成功
docker images | grep deotaland-frontend
```

#### 4. 准备部署文件
```bash
# 创建部署目录
mkdir -p /app/frontend/configs

# 上传 docker-compose 文件（前端提供）
# 保存为 docker-compose.yml
```

### 🎯 第六步：启动应用

#### 1. 使用 docker-compose 启动
```bash
# 在包含 docker-compose.yml 的目录下执行
cd /app/frontend

# 启动服务
docker-compose -f docker-compose.prod.yml up -d

# 检查状态
docker-compose ps

# 查看日志
docker-compose logs -f
```

#### 2. 验证部署成功
```bash
# 检查容器运行状态
docker ps

# 测试本地访问
curl http://localhost:3000

# 检查端口监听
netstat -tlnp | grep 3000
```

---

## 📁 需要提供的文件清单

### 📋 前端需要提供给后端的文件：

1. **镜像文件**（必需）
   ```
   deotaland-frontend-v1.0.0.tar
   ```

2. **docker-compose 配置文件**（必需）
   ```
   docker-compose.prod.yml
   ```

3. **部署文档**（推荐）
   ```
   DEPLOYMENT_GUIDE.md (本文档)
   ```

4. **版本信息**（推荐）
   ```
   version.txt - 包含版本号和构建时间
   ```

---

## 🔧 常用命令速查

### 前端构建命令
```bash
# 构建镜像
docker build -t deotaland-frontend:v1.0.0 .

# 导出镜像
docker save -o deotaland-frontend-v1.0.0.tar deotaland-frontend:v1.0.0

# 压缩文件
gzip deotaland-frontend-v1.0.0.tar
```

### 后端部署命令
```bash
# 导入镜像
docker load -i deotaland-frontend-v1.0.0.tar

# 启动服务
docker-compose -f docker-compose.prod.yml up -d

# 查看状态
docker-compose ps

# 查看日志
docker-compose logs -f

# 停止服务
docker-compose down

# 重启服务
docker-compose restart
```

---

## 🚨 常见问题解决

### 问题 1：镜像文件太大
**解决方案：**
- 使用 `.dockerignore` 文件排除不需要的文件
- 使用多阶段构建优化镜像大小
- 考虑使用镜像仓库代替文件传输

### 问题 2：上传速度慢
**解决方案：**
- 使用压缩工具（gzip/7zip）
- 分批上传或使用云存储中转
- 优化网络环境

### 问题 3：容器启动失败
**排查步骤：**
```bash
# 1. 查看容器状态
docker ps -a

# 2. 查看错误日志
docker logs <container-id>

# 3. 检查端口占用
netstat -tlnp | grep 3000

# 4. 检查资源使用
docker stats
```

### 问题 4：服务无法访问
**排查步骤：**
```bash
# 1. 检查容器是否运行
docker ps

# 2. 测试容器内服务
docker exec <container-id> curl http://localhost:3000

# 3. 检查防火墙设置
sudo ufw status  # Ubuntu
sudo firewall-cmd --list-all  # CentOS

# 4. 检查云服务器安全组设置
```

---

## 📊 性能优化建议

### 镜像优化
- 使用 Alpine Linux 基础镜像
- 实施多阶段构建
- 清理构建缓存

### 部署优化
- 使用镜像仓库（Docker Registry）
- 实施蓝绿部署
- 配置健康检查

### 监控建议
- 设置容器资源限制
- 配置日志收集
- 实施监控告警

---

## 🎯 下一步建议

1. **建立 CI/CD 流程**：自动化构建和部署
2. **使用镜像仓库**：替代文件传输
3. **配置域名和 SSL**：提供 HTTPS 访问
4. **设置监控告警**：及时发现问题
5. **实施自动扩容**：应对流量高峰

---

## 📞 支持联系方式

- **前端开发支持**：前端团队
- **后端运维支持**：运维团队
- **紧急问题**：电话/微信 XXX-XXXX-XXXX

---

**最后更新时间**：2025年1月21日  
**文档版本**：v1.0  
**适用范围**：前端 Docker 镜像部署到后端服务器