AIclinicalresearch/docs/05-部署文档/19-日常更新快速操作手册.md

AI临床研究平台 - 日常更新快速操作手册

文档用途：日常功能更新的快速操作指南
目标用户：开发团队、运维人员、AI助手
更新时间：2025-12-25
特点：短小精悍、关键信息密集、可直接复制执行

---

🎯 使用说明

本文档适用于：

• ✅ 日常功能更新（修改代码后更新部署）
• ✅ 快速迭代（每天/每周更新）
• ✅ 团队协作（其他人或AI快速上手）

不适用于：

• ❌ 首次完整部署（请看 17-完整部署实战手册-2025版.md）
• ❌ 环境变量修改（请看本文档第5节）
• ❌ 问题排查（请看 15-Node.js后端-部署成功总结.md）

---

📦 一、前置信息（必读5分钟）

1.1 ACR镜像仓库信息

登录凭证：

Registry: crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com
用户名: gofeng117@163.com
密码: fengzhibo117

镜像地址格式：

# 公网地址（本地推送用）
crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/<仓库名>:<版本号>

# VPC地址（SAE拉取用）
crpi-cd5ij4pjt65mweeo-vpc.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/<仓库名>:<版本号>

3个镜像仓库：

• python-extraction - Python微服务
• backend-service - Node.js后端
• ai-clinical_frontend-nginx - 前端Nginx

---

1.2 SAE应用信息

应用名称	服务	当前版本	内网地址
python-extraction-test	Python微服务	v1.0	172.17.173.66:8000
nodejs-backend-test	Node.js后端	v1.3	172.17.173.73:3001
frontend-nginx-service	前端Nginx	v1.0	172.17.173.72:80

SAE控制台：https://sae.console.aliyun.com/

---

1.3 版本号规范

语义化版本：v主版本.次版本.修订号

v1.0 → 首次部署
v1.1 → 功能更新
v1.2 → 功能更新
v1.3 → 功能更新
v2.0 → 重大更新

建议：每次更新递增次版本号（v1.3 → v1.4）

---

🚀 二、更新Node.js后端（最常用）⭐⭐⭐⭐⭐

步骤1：本地构建（5分钟）

# 进入后端目录
cd D:\MyCursor\AIclinicalresearch\backend

# 编译TypeScript
npm run build

# 验证编译结果
dir dist
# 应该看到：index.js, common/, modules/ 等

# 构建Docker镜像（版本号递增）
docker build -t backend-service:v1.4 .

预计时间：5分钟

---

步骤2：推送镜像到ACR（10分钟）

# 1. 登录ACR（首次需要）
docker login --username=gofeng117@163.com \
  --password=fengzhibo117 \
  crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com

# 2. 打标签
docker tag backend-service:v1.4 \
  crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/backend-service:v1.4

# 3. 推送镜像
docker push \
  crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/backend-service:v1.4

# 等待推送完成（约10分钟，镜像约838MB）
# 看到 "digest: sha256:..." 表示成功

预计时间：10分钟

---

步骤3：在SAE更新应用（3分钟）

方式1：Web控制台（推荐）

1. 登录SAE：https://sae.console.aliyun.com/
2. 进入应用：nodejs-backend-test
3. 点击【部署应用】按钮
4. 配置参数：

   镜像地址: 选择 backend-service
   镜像版本: 选择 v1.4
   

5. 点击【确认】
6. 等待部署完成（约5-8分钟）

方式2：命令行（高级）

# 使用阿里云CLI
aliyun sae DeployApplication \
  --AppId <应用ID> \
  --ImageUrl crpi-cd5ij4pjt65mweeo-vpc.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/backend-service:v1.4

预计时间：3分钟操作 + 5-8分钟等待部署

---

步骤4：验证部署（2分钟）

# 1. 查看应用状态
# SAE控制台 → 实例部署 → 状态应为 "Running"

# 2. 查看日志（确认启动成功）
# SAE控制台 → 日志查询 → 应该看到：
# "🚀 AI临床研究平台 - 后端服务器启动成功！"

# 3. 健康检查
curl http://172.17.173.73:3001/health
# 或通过公网
curl http://8.140.53.236/api/v1/health

# 4. 功能测试
# 访问前端：http://8.140.53.236/
# 测试更新的功能

预计时间：2分钟

---

完整流程时间

步骤	操作	时间
1	本地构建	5分钟
2	推送镜像	10分钟
3	SAE部署	3分钟操作 + 5-8分钟等待
4	验证	2分钟
总计	-	20-25分钟

---

🎨 三、更新前端Nginx（次常用）⭐⭐⭐⭐

步骤1：本地构建（10分钟）

# 进入前端目录
cd D:\MyCursor\AIclinicalresearch\frontend-v2

# 构建Docker镜像（版本号递增）
docker build -t ai-clinical_frontend-nginx:v1.1 .

# 注意：Dockerfile会自动执行 npm run build

预计时间：10分钟（包含React构建）

---

步骤2：推送镜像到ACR（3分钟）

# 1. 打标签
docker tag ai-clinical_frontend-nginx:v1.1 \
  crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/ai-clinical_frontend-nginx:v1.1

# 2. 推送镜像
docker push \
  crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/ai-clinical_frontend-nginx:v1.1

# 等待推送完成（约3分钟，镜像约50MB）

预计时间：3分钟

---

步骤3：在SAE更新应用（3分钟）

1. 登录SAE：https://sae.console.aliyun.com/
2. 进入应用：frontend-nginx-service
3. 点击【部署应用】
4. 选择镜像版本：v1.1
5. 确认部署

预计时间：3分钟操作 + 3-5分钟等待

---

步骤4：验证部署（1分钟）

# 访问前端
open http://8.140.53.236/

# 或
curl http://8.140.53.236/

完整时间：约15-20分钟

---

🐍 四、更新Python微服务（较少用）⭐⭐⭐

步骤1：本地构建（15分钟）

# 进入Python服务目录
cd D:\MyCursor\AIclinicalresearch\extraction_service

# 构建Docker镜像
docker build -t python-extraction:v1.1 .

预计时间：15分钟（镜像较大）

---

步骤2：推送镜像（10分钟）

# 打标签
docker tag python-extraction:v1.1 \
  crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/python-extraction:v1.1

# 推送
docker push \
  crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/python-extraction:v1.1

预计时间：10分钟（镜像约1.1GB）

---

步骤3：SAE部署（3分钟）

1. 进入应用：python-extraction-test
2. 部署新版本：v1.1

完整时间：约30分钟

---

⚙️ 五、修改环境变量（高频操作）⭐⭐⭐⭐⭐

关键规则

⚠️ 重要：修改环境变量时，使用【重启应用】，不要用【部署应用】！

操作	用途	IP是否变
重启应用 ✅	修改配置	❌ 不会变
部署应用 ❌	更新镜像	✅ 会变更

---

操作步骤（5分钟）

1. 登录SAE：https://sae.console.aliyun.com/
2. 进入对应应用（如 nodejs-backend-test）
3. 点击【应用配置】→【环境变量】
4. 找到要修改的变量，点击【编辑】
5. 修改变量值
6. 点击【保存】
7. 点击【重启应用】（⚠️ 不是"部署应用"！）
8. 等待重启完成（约2-3分钟）

---

常用环境变量速查

Node.js后端关键变量：

# Python服务地址（⚠️ 变量名必须精确！）
EXTRACTION_SERVICE_URL=http://172.17.173.66:8000

# 数据库连接
DATABASE_URL=postgresql://airesearch:Xibahe%40fengzhibo117@pgm-2zex1m2y3r23hdn5.pg.rds.aliyuncs.com:5432/ai_clinical_research

# LLM API密钥
DEEPSEEK_API_KEY=sk-...
DASHSCOPE_API_KEY=sk-...

前端Nginx关键变量：

# 后端服务地址
BACKEND_SERVICE_HOST=172.17.173.73
BACKEND_SERVICE_PORT=3001

完整环境变量清单：

• 查看 11-Node.js后端-SAE部署配置清单.md

---

📋 六、查看日志（日常运维）⭐⭐⭐⭐

SAE控制台查看

1. 登录SAE：https://sae.console.aliyun.com/
2. 进入对应应用
3. 点击【日志查询】
4. 选择时间范围
5. 查看实时日志

---

常用日志关键字

正常启动：

# Node.js后端
"🚀 AI临床研究平台 - 后端服务器启动成功！"
"Server listening at http://172.17.173.73:3001"

# Python服务
"Uvicorn running on http://0.0.0.0:8000"
"Application startup complete"

# 前端Nginx
"Starting Frontend Nginx Service"
"Backend Service: 172.17.173.73:3001"

常见错误：

# 环境变量问题
"EXTRACTION_SERVICE_URL"
"connect ECONNREFUSED"

# 数据库连接问题
"Can't reach database server"
"Connection timeout"

# 镜像问题
"ENOENT: no such file or directory"
"Error: unable to determine transport target"

---

🔄 七、回滚操作（紧急情况）⭐⭐⭐

什么时候需要回滚？

• ❌ 新版本有严重Bug
• ❌ 功能不符合预期
• ❌ 性能下降明显

---

回滚步骤（5分钟）

1. 登录SAE：https://sae.console.aliyun.com/
2. 进入对应应用
3. 点击【部署应用】
4. 选择旧版本号（如 v1.3）
5. 确认部署
6. 等待回滚完成（约5分钟）

---

验证回滚

# 查看日志，确认版本
# 或访问应用，测试功能

---

🎯 八、一键更新脚本（高级）

为Node.js后端创建更新脚本

创建文件：backend/update-and-deploy.ps1

# Node.js后端一键更新脚本
# 使用方法: .\update-and-deploy.ps1 v1.5

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

Write-Host "========================================" -ForegroundColor Green
Write-Host "开始更新Node.js后端到版本: $Version" -ForegroundColor Green
Write-Host "========================================" -ForegroundColor Green

# 1. 编译TypeScript
Write-Host "`n[1/4] 编译TypeScript..." -ForegroundColor Cyan
npm run build
if ($LASTEXITCODE -ne 0) {
    Write-Host "❌ 编译失败！" -ForegroundColor Red
    exit 1
}
Write-Host "✅ 编译成功！" -ForegroundColor Green

# 2. 构建Docker镜像
Write-Host "`n[2/4] 构建Docker镜像..." -ForegroundColor Cyan
docker build -t backend-service:$Version .
if ($LASTEXITCODE -ne 0) {
    Write-Host "❌ 构建失败！" -ForegroundColor Red
    exit 1
}
Write-Host "✅ 镜像构建成功！" -ForegroundColor Green

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

# 4. 推送到ACR
Write-Host "`n[4/4] 推送到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. 进入应用: nodejs-backend-test" -ForegroundColor Yellow
Write-Host "3. 点击【部署应用】" -ForegroundColor Yellow
Write-Host "4. 选择镜像版本: $Version" -ForegroundColor Yellow
Write-Host "5. 确认部署" -ForegroundColor Yellow
Write-Host "`n镜像地址（VPC）:" -ForegroundColor Cyan
Write-Host "crpi-cd5ij4pjt65mweeo-vpc.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/backend-service:$Version" -ForegroundColor Cyan

使用方法：

cd D:\MyCursor\AIclinicalresearch\backend
.\update-and-deploy.ps1 v1.5

---

为前端创建更新脚本

创建文件：frontend-v2/update-and-deploy.ps1

# 前端Nginx一键更新脚本
param(
    [Parameter(Mandatory=$true)]
    [string]$Version
)

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

# 1. 构建镜像
docker build -t ai-clinical_frontend-nginx:$Version .

# 2. 打标签并推送
$ImageUrl = "crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/ai-clinical_frontend-nginx:$Version"
docker tag ai-clinical_frontend-nginx:$Version $ImageUrl
docker push $ImageUrl

Write-Host "✅ 完成！请在SAE控制台部署版本: $Version" -ForegroundColor Green

---

📊 九、常用操作时间估算

操作	操作时间	等待时间	总计
更新Node.js后端	5分钟	15-20分钟	20-25分钟
更新前端Nginx	3分钟	12-18分钟	15-20分钟
更新Python服务	3分钟	25-30分钟	30分钟
修改环境变量	2分钟	2-3分钟	5分钟
查看日志	1分钟	0	1分钟
回滚版本	2分钟	5分钟	7分钟

---

⚠️ 十、关键注意事项

1. 环境变量名必须精确

# ❌ 错误
PYTHON_SERVICE_URL=http://172.17.173.66:8000

# ✅ 正确
EXTRACTION_SERVICE_URL=http://172.17.173.66:8000

教训：环境变量名必须与代码完全一致！

---

2. 重启 vs 部署

修改配置 → 重启应用（IP不变）✅
更新代码 → 部署应用（IP可能变）⚠️

建议：尽量使用服务发现代替硬编码IP

---

3. 使用VPC地址拉取镜像

# SAE部署时选择VPC地址（免流量费）
crpi-xxx-vpc.cn-beijing.personal.cr.aliyuncs.com/...

# 本地推送时使用公网地址
crpi-xxx.cn-beijing.personal.cr.aliyuncs.com/...

---

4. 版本号管理

建议规范：

v1.0 - 首次部署
v1.1 - 小功能更新
v1.2 - 小功能更新
v2.0 - 重大版本升级

记录版本：在 00-部署进度总览.md 中更新版本号

---

🆘 十一、常见问题

Q1：推送镜像失败？

现象：denied: requested access to the resource is denied

解决：

# 重新登录ACR
docker login --username=gofeng117@163.com \
  --password=fengzhibo117 \
  crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com

---

Q2：SAE部署失败？

步骤：

1. 查看实例日志，找到具体错误
2. 参考 15-Node.js后端-部署成功总结.md
3. 检查环境变量配置
4. 验证镜像是否推送成功

---

Q3：功能更新后不生效？

可能原因：

• 浏览器缓存（Ctrl+F5强制刷新）
• SAE部署未完成
• 版本号选择错误

---

Q4：IP地址变更了怎么办？

步骤：

1. 记录新的IP地址
2. 更新依赖该IP的服务的环境变量
3. 重启相关服务
4. 更新文档 00-部署进度总览.md

---

📞 十二、需要帮助？

详细文档参考

• 完整部署：17-完整部署实战手册-2025版.md
• 资源查询：00-部署进度总览.md
• 问题排查：15-Node.js后端-部署成功总结.md
• 文档导航：README.md 或 18-部署文档使用指南.md

---

🎯 总结

日常最常用的3个操作

1. 更新Node.js后端（20-25分钟）
2. 修改环境变量（5分钟）
3. 查看日志（1分钟）

记住3个关键点

1. ✅ 版本号递增：v1.3 → v1.4 → v1.5
2. ✅ 修改配置用重启，更新代码用部署
3. ✅ 使用VPC地址拉取镜像（省钱）

一句话总结

编译 → 构建 → 推送 → 部署 → 验证（20分钟搞定！）

---

最后更新：2025-12-25
维护人员：开发团队
使用反馈：请及时更新本文档

祝您更新顺利！ 🚀