AIclinicalresearch/docs/05-部署文档/0126部署/05-前端服务部署方案.md

# 🎨 前端Nginx服务部署方案

> **文档版本**：v1.0  
> **创建日期**：2026-01-26  
> **适用范围**：frontend-v2 前端服务  
> **变更类型**：代码更新 + 镜像重建

---

## 📋 一、变更概述

### 1.1 变更内容

| 变更项 | 描述 | 优先级 |
|--------|------|--------|
| **IIT Manager Agent前端** | AI对话、REDCap数据展示 | 🟡 中 |
| **ASL文献筛选UI** | 功能完善和优化 | 🟡 中 |
| **DC数据清洗UI** | 功能更新 | 🟡 中 |
| **其他UI优化** | 样式和交互改进 | 🟢 低 |

### 1.2 当前状态

```yaml
服务名称: frontend-nginx-service
当前版本: v1.2
镜像大小: ~50MB
内网地址: http://172.17.173.80:80
技术栈:
  - React: 19
  - TypeScript: 5
  - Vite: 6
  - Ant Design: 5
  - TailwindCSS: 3
```

### 1.3 目标状态

```yaml
目标版本: v1.3
预计镜像大小: ~50MB
主要更新:
  - IIT模块前端页面
  - ASL模块UI优化
  - DC模块功能完善
```

---

## 🚀 二、构建与部署步骤

### Step 1：进入前端目录

```bash
cd D:\MyCursor\AIclinicalresearch\frontend-v2
```

### Step 2：检查代码状态

```bash
# 查看Git状态
git status

# 确保代码最新
git pull origin main
```

### Step 3：本地测试构建（可选）

```bash
# 安装依赖
npm install

# 本地构建测试
npm run build

# 本地预览
npm run preview
```

### Step 4：构建Docker镜像

```powershell
docker build -t ai-clinical_frontend-nginx:v1.3 .

# 预计时间：10分钟（包含React构建）
# 预计大小：约50MB
```

### Step 5：本地验证镜像（可选）

```powershell
# 运行容器测试
docker run --rm -p 80:80 `
  -e BACKEND_SERVICE_HOST=172.17.173.73 `
  -e BACKEND_SERVICE_PORT=3001 `
  ai-clinical_frontend-nginx:v1.3

# 访问 http://localhost 验证
```

### Step 6：登录ACR

```powershell
docker login --username=gofeng117@163.com `
  --password=fengzhibo117 `
  crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com
```

### Step 7：打标签

```powershell
docker tag ai-clinical_frontend-nginx:v1.3 `
  crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/ai-clinical_frontend-nginx:v1.3
```

### Step 8：推送到ACR

```powershell
docker push `
  crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/ai-clinical_frontend-nginx:v1.3

# 预计时间：3分钟（镜像约50MB）
# 成功标志：看到 "digest: sha256:..."
```

### Step 9：SAE部署

1. 登录SAE：https://sae.console.aliyun.com/
2. 进入应用：`frontend-nginx-service`
3. 点击【部署应用】
4. 配置：
   - **镜像地址**：选择 `ai-clinical_frontend-nginx`
   - **镜像版本**：选择 `v1.3`
5. 点击【确认】
6. 等待部署完成（约3-5分钟）

### Step 10：检查环境变量

确保环境变量正确：

```bash
BACKEND_SERVICE_HOST=172.17.173.73  # 后端内网IP
BACKEND_SERVICE_PORT=3001
```

**注意**：如果后端部署后IP变化，需要更新此变量！

### Step 11：验证部署

```bash
# 通过公网访问
curl http://8.140.53.236/

# 或访问域名
curl https://iit.xunzhengyixue.com/

# 检查静态资源加载
# 浏览器访问并打开开发者工具查看Network
```

---

## 📋 三、一键部署脚本

### PowerShell脚本

`frontend-v2/update-and-deploy.ps1`：

```powershell
# 前端Nginx一键更新脚本
# 使用方法: .\update-and-deploy.ps1 v1.3

param(
    [Parameter(Mandatory=$true)]
    [string]$Version
)

$ErrorActionPreference = "Stop"

Write-Host "========================================" -ForegroundColor Green
Write-Host "开始更新前端Nginx到版本: $Version" -ForegroundColor Green
Write-Host "========================================" -ForegroundColor Green

# 1. 构建镜像（包含React build）
Write-Host "`n[1/3] 构建Docker镜像（包含React构建）..." -ForegroundColor Cyan
docker build -t ai-clinical_frontend-nginx:$Version .
if ($LASTEXITCODE -ne 0) {
    Write-Host "❌ 构建失败！" -ForegroundColor Red
    exit 1
}
Write-Host "✅ 镜像构建成功！" -ForegroundColor Green

# 2. 打标签
Write-Host "`n[2/3] 打标签..." -ForegroundColor Cyan
$ImageUrl = "crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/ai-clinical_frontend-nginx:$Version"
docker tag ai-clinical_frontend-nginx:$Version $ImageUrl
Write-Host "✅ 标签已打！" -ForegroundColor Green

# 3. 推送到ACR
Write-Host "`n[3/3] 推送到ACR..." -ForegroundColor Cyan
Write-Host "推送地址: $ImageUrl" -ForegroundColor Yellow
docker push $ImageUrl
if ($LASTEXITCODE -ne 0) {
    Write-Host "❌ 推送失败！" -ForegroundColor Red
    exit 1
}

Write-Host "`n========================================" -ForegroundColor Green
Write-Host "✅ 前端镜像已推送成功！" -ForegroundColor Green
Write-Host "========================================" -ForegroundColor Green
Write-Host "`n下一步操作：" -ForegroundColor Yellow
Write-Host "1. 登录SAE控制台: https://sae.console.aliyun.com/" -ForegroundColor Yellow
Write-Host "2. 进入应用: frontend-nginx-service" -ForegroundColor Yellow
Write-Host "3. 检查环境变量（如果后端IP有变化）：" -ForegroundColor Red
Write-Host "   BACKEND_SERVICE_HOST=<后端新IP>" -ForegroundColor Red
Write-Host "4. 点击【部署应用】" -ForegroundColor Yellow
Write-Host "5. 选择镜像版本: $Version" -ForegroundColor Yellow
Write-Host "6. 确认部署" -ForegroundColor Yellow
Write-Host "`n镜像地址（VPC）:" -ForegroundColor Cyan
Write-Host "crpi-cd5ij4pjt65mweeo-vpc.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/ai-clinical_frontend-nginx:$Version" -ForegroundColor Cyan
```

---

## ⚠️ 四、注意事项

### 4.1 Windows换行符问题

之前v1.1部署遇到过CRLF问题，确保：

1. `docker-entrypoint.sh` 使用Unix换行符（LF）
2. 检查方法：
   ```powershell
   # 检查是否有CRLF
   (Get-Content docker-entrypoint.sh -Raw) -match "`r`n"
   # 如果返回True，需要转换
   ```
3. 转换方法：
   ```powershell
   (Get-Content docker-entrypoint.sh -Raw) -replace "`r`n", "`n" | Set-Content -NoNewline docker-entrypoint.sh
   ```

### 4.2 后端IP变更处理

如果后端部署后IP变化：

1. 获取新的后端内网IP
2. 更新前端环境变量：
   ```
   BACKEND_SERVICE_HOST=<新IP>
   ```
3. 使用【重启应用】（不是部署，IP不会变）

### 4.3 缓存问题

前端更新后用户可能看到旧版本：
- 告知用户使用 Ctrl+F5 强制刷新
- 或清除浏览器缓存

---

## 🔄 五、回滚方案

如果v1.3出现问题，回滚到v1.2：

1. 登录SAE控制台
2. 进入应用：`frontend-nginx-service`
3. 点击【部署应用】
4. 选择镜像版本：`v1.2`
5. 确认部署

---

## ✅ 六、验证清单

### 部署前验证

- [ ] 本地 `npm run build` 成功
- [ ] Docker镜像构建成功
- [ ] ACR推送成功

### 部署后验证

- [ ] SAE部署成功
- [ ] 公网可访问
- [ ] 静态资源加载正常
- [ ] API代理正常（前端→后端）
- [ ] IIT模块页面可访问
- [ ] ASL模块功能正常
- [ ] DC模块功能正常

---

## 📊 七、时间估算

| 步骤 | 预计时间 |
|------|---------|
| 构建Docker镜像 | 10分钟 |
| 推送到ACR | 3分钟 |
| SAE部署 | 5分钟 |
| 验证测试 | 5分钟 |
| **总计** | **23分钟** |

---

> **最后更新**：2026-01-26  
> **维护人员**：开发团队