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 当前状态

服务名称: 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 目标状态

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

---

🚀 二、构建与部署步骤

Step 1：进入前端目录

cd D:\MyCursor\AIclinicalresearch\frontend-v2

Step 2：检查代码状态

# 查看Git状态
git status

# 确保代码最新
git pull origin main

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

# 安装依赖
npm install

# 本地构建测试
npm run build

# 本地预览
npm run preview

Step 4：构建Docker镜像

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

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

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

# 运行容器测试
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

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

Step 7：打标签

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

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：检查环境变量

确保环境变量正确：

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

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

Step 11：验证部署

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

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

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

---

📋 三、一键部署脚本

PowerShell脚本

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

# 前端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. 检查方法：

   # 检查是否有CRLF
   (Get-Content docker-entrypoint.sh -Raw) -match "`r`n"
   # 如果返回True，需要转换
   

3. 转换方法：

   (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
维护人员：开发团队