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

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

---

## 🎯 使用说明

**本文档适用于**：
- ✅ 日常功能更新（修改代码后更新部署）
- ✅ 快速迭代（每天/每周更新）
- ✅ 团队协作（其他人或AI快速上手）

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

---

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

### 1.1 ACR镜像仓库信息

**登录凭证**：
```bash
Registry: crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com
用户名: gofeng117@163.com
密码: fengzhibo117
```

**镜像地址格式**：
```bash
# 公网地址（本地推送用）
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主版本.次版本.修订号`

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

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

---

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

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

```bash
# 进入后端目录
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分钟）

```bash
# 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. 配置参数：
   ```yaml
   镜像地址: 选择 backend-service
   镜像版本: 选择 v1.4
   ```
5. 点击【确认】
6. 等待部署完成（约5-8分钟）

**方式2：命令行（高级）**

```bash
# 使用阿里云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分钟）

```bash
# 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分钟）

```bash
# 进入前端目录
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分钟）

```bash
# 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分钟）

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

# 或
curl http://8.140.53.236/
```

**完整时间**：约15-20分钟

---

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

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

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

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

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

---

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

```bash
# 打标签
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后端关键变量**：
```bash
# 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关键变量**：
```bash
# 后端服务地址
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. 查看实时日志

---

### 常用日志关键字

**正常启动**：
```bash
# 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"
```

**常见错误**：
```bash
# 环境变量问题
"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分钟）

---

### 验证回滚

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

---

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

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

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

```powershell
# 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
```

**使用方法**：
```powershell
cd D:\MyCursor\AIclinicalresearch\backend
.\update-and-deploy.ps1 v1.5
```

---

### 为前端创建更新脚本

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

```powershell
# 前端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. 环境变量名必须精确

```bash
# ❌ 错误
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地址拉取镜像

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

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

---

### 4. 版本号管理

**建议规范**：
```bash
v1.0 - 首次部署
v1.1 - 小功能更新
v1.2 - 小功能更新
v2.0 - 重大版本升级
```

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

---

## 🆘 十一、常见问题

### Q1：推送镜像失败？

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

**解决**：
```bash
# 重新登录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  
> **维护人员**：开发团队  
> **使用反馈**：请及时更新本文档

**祝您更新顺利！** 🚀