# 日常更新操作手册

> 版本: v2.4（0305 二次热修后更新）  
> 更新日期: 2026-03-05  
> 适用: 日常代码更新、功能迭代、配置变更

---

## 0. 部署前检查

```
□ 打开 03-待部署变更清单.md，确认本次要部署哪些变更
□ 打开 00-阿里云SAE最新真实状态记录.md，确认当前版本号
□ 确认新版本号（当前版本 +1）
□ 如有数据库变更，先执行数据库迁移
```

---

## 1. ACR 登录（首次 / 过期后）

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

---

## 2. Node.js 后端更新（~25 分钟）

**当前版本**: v2.8 → 下个版本: v2.9

### 2.1 构建

```powershell
cd D:\MyCursor\AIclinicalresearch\backend

# TypeScript 编译（有类型错误时用 --noCheck）
npm run build
# 或: npx tsc --noCheck

# 构建 Docker 镜像
docker build -t backend-service:v2.9 .
```

> **0227 经验**: `tsc` 不会拷贝 `.json` 配置文件，Dockerfile 中已有 `COPY src/modules/ssa/config/*.json` 等补丁步骤。如新模块有 JSON 配置文件需要确认 Dockerfile 覆盖到。

### 2.2 推送

```powershell
docker tag backend-service:v2.9 crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/backend-service:v2.9

docker push crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/backend-service:v2.9
```

推送约 10 分钟（~840MB），看到 `digest: sha256:...` 表示成功。

### 2.3 SAE 部署

1. SAE 控制台 → `nodejs-backend-test` → 部署应用
2. 选择镜像 `backend-service:v2.9`（与上方构建版本一致）
3. 确认部署，等待 5-8 分钟

### 2.4 验证

```
□ SAE 实例状态为 Running
□ 日志中出现启动成功信息
□ 健康检查: curl http://<新IP>:3001/health
□ 前端功能测试
```

> **重要**: 部署后 IP 会变更！需同步更新 `frontend-nginx-service` 的 `BACKEND_SERVICE_HOST` 环境变量。

---

## 3. 前端 Nginx 更新（~15 分钟）

**当前版本**: v2.5 → 下个版本: v2.6

### 3.1 构建

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

docker build -t ai-clinical_frontend-nginx:v2.6 .
```

构建约 5 分钟（含 React 编译）。

### 3.2 推送

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

docker push crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/ai-clinical_frontend-nginx:v2.6
```

推送约 2 分钟（~50MB）。

### 3.3 SAE 部署

1. SAE 控制台 → `frontend-nginx-service` → 部署应用
2. 选择镜像版本 `v2.6`（与上方构建版本一致）
3. **检查环境变量**: `BACKEND_SERVICE_HOST` 指向最新后端 IP

### 3.4 验证

```
□ 访问 https://iit.xunzhengyixue.com/ 页面正常
□ 登录功能正常（排除 504 超时）
□ 测试核心功能
```

---

## 4. Python 微服务更新（~30 分钟）

**当前版本**: v1.2 → 下个版本: v1.3

### 4.1 构建

```powershell
cd D:\MyCursor\AIclinicalresearch\extraction_service

docker build -t python-extraction:v1.3 .
```

构建约 15 分钟（镜像 ~1.1GB）。

### 4.2 推送

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

docker push crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/python-extraction:v1.3
```

### 4.3 SAE 部署

1. SAE 控制台 → `python-extraction-test` → 部署应用
2. 选择新版本

### 4.4 验证

```
□ 健康检查: curl http://<新IP>:8000/api/health
□ 如 IP 变更，更新后端的 EXTRACTION_SERVICE_URL
```

---

## 5. R 统计引擎更新（~40 分钟）

**当前版本**: v1.0.1 → 下个版本: v1.0.2

### 5.1 构建

```powershell
cd D:\MyCursor\AIclinicalresearch\r-statistics-service

docker build -t ssa-r-statistics:v1.0.2 .
```

构建约 20 分钟（镜像 ~1.8GB，R 包编译耗时）。

### 5.2 推送

```powershell
docker tag ssa-r-statistics:v1.0.2 crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/ssa-r-statistics:v1.0.2

docker push crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/ssa-r-statistics:v1.0.2
```

### 5.3 SAE 部署

1. SAE 控制台 → `r-statistics-test` → 部署应用
2. 选择新版本

### 5.4 验证

```
□ 健康检查: curl http://<新IP>:8080/health
□ 如 IP 变更，更新后端的 R_STATISTICS_SERVICE_URL
```

---

## 6. 数据库迁移

### 6.1 标准迁移（Prisma migration 文件）

```powershell
# 通过后端 SAE Webshell 执行（推荐）
npx prisma migrate deploy

# 或手动执行 SQL
# 将 migration.sql 内容粘贴到 Webshell psql 中
```

### 6.2 手动 SQL 补丁

```powershell
# 在 SAE nodejs-backend-test 的 Webshell 中
node -e "
const { execSync } = require('child_process');
execSync('PGPASSWORD=Xibahe@fengzhibo117 psql -h pgm-2zex1m2y3r23hdn5so.pg.rds.aliyuncs.com -U airesearch -d ai_clinical_research_test -c \"你的SQL\"', {stdio:'inherit'});
"
```

### 6.3 标记手动迁移

```powershell
npx prisma migrate resolve --applied <migration_name>
```

---

## 7. 环境变量修改（5 分钟）

**核心规则: 只改环境变量时用「重启应用」，不要「部署应用」！**

| 操作 | 用途 | IP 是否变 |
|------|------|----------|
| 重启应用 | 改配置/环境变量 | 不变 |
| 部署应用 | 更新镜像版本 | 会变 |

步骤: SAE 控制台 → 应用 → 应用配置 → 环境变量 → 编辑 → 保存 → **重启应用**

---

## 8. 部署后收尾

```
□ 更新 00-阿里云SAE最新真实状态记录.md（新IP/版本）
□ 清零 03-待部署变更清单.md（已部署项移到历史区域）
□ 如果是大版本部署，创建 MMDD部署/ 文件夹记录过程
□ 如有服务 IP 变更，检查相互依赖的环境变量是否已更新
□ CLB 负载均衡器无需手动更新（阿里云自动处理）
```

---

## 9. 常见问题速查

| 现象 | 原因 | 解决 |
|------|------|------|
| 前端 504 Gateway Timeout | 后端 IP 变更但前端环境变量未更新 | 更新 `BACKEND_SERVICE_HOST` 并重启 |
| `column does not exist` | 数据库迁移遗漏 | 检查 `03-待部署变更清单.md` 中是否有未执行的 DB 变更 |
| `ENOENT .json` 文件 | tsc 不拷贝非 .ts 文件 | 在 Dockerfile 中添加 `COPY` 指令 |
| 健康检查失败 404 | 健康检查路径配置错误 | 确认 HTTP 路径为 `/health` |
| 镜像推送超时 | 网络问题 | 重试，或换网络环境 |
| `prisma db push` 遗留 drift | 开发时绕过了迁移系统 | 创建 patch migration + `resolve --applied` |

---

## 10. 部署顺序参考

如果多个服务同时更新：

```
1. 数据库迁移（先行，确保表结构就绪）
2. R 统计引擎（独立服务，不影响其他）
3. Python 微服务（独立服务）
4. Node.js 后端（依赖上游服务 IP，需更新环境变量）
5. 前端 Nginx（最后部署，需要最新的后端 IP）
```