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

# ⚙️ Node.js后端服务部署方案

> **文档版本**：v1.0  
> **创建日期**：2026-01-26  
> **适用范围**：backend Node.js服务  
> **变更类型**：代码更新 + Schema同步 + 环境变量更新

---

## 📋 一、变更概述

### 1.1 变更内容

| 变更项 | 描述 | 优先级 |
|--------|------|--------|
| **IIT Manager Agent模块** | 完整AI对话、REDCap集成、企业微信推送 | 🔴 高 |
| **ASL文献筛选模块** | 功能完善和Bug修复 | 🟡 中 |
| **DC数据清洗模块** | 功能更新 | 🟡 中 |
| **Prisma Schema更新** | 添加iit_schema | 🔴 高 |
| **OSS环境变量** | 新增OSS_BUCKET_STATIC等 | 🔴 高 |

### 1.2 当前状态

```yaml
服务名称: nodejs-backend-test
当前版本: v1.3
镜像大小: 838MB
内网地址: http://172.17.173.73:3001
技术栈:
  - Node.js: 22.x
  - Prisma: 6.17.0
  - Fastify: 4.x
  - pg-boss: Postgres队列
```

### 1.3 目标状态

```yaml
目标版本: v1.4
预计镜像大小: ~850MB
主要更新:
  - IIT模块完整功能
  - Prisma Schema包含iit_schema
  - OSS环境变量更新
```

---

## 🔧 二、Prisma Schema更新

### 2.1 修改datasource配置

编辑 `backend/prisma/schema.prisma`：

```prisma
datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
  schemas  = ["platform_schema", "aia_schema", "pkb_schema", "asl_schema", "common_schema", "dc_schema", "rvw_schema", "admin_schema", "ssa_schema", "st_schema", "iit_schema", "public"]
}
```

**注意**：添加了 `iit_schema` 到schemas数组。

### 2.2 验证IIT模块表已存在

当前IIT模块的表是通过原生SQL创建的，需要确认表结构：

```sql
-- 检查iit_schema的表
SELECT table_name FROM information_schema.tables 
WHERE table_schema = 'iit_schema';

-- 预期结果：
-- projects
-- pending_actions
-- task_runs
-- user_mappings
-- audit_logs
```

### 2.3 执行Prisma操作

```bash
cd backend

# 1. 生成Prisma Client（必须）
npx prisma generate

# 2. 验证Schema（可选，查看差异）
npx prisma db pull --schema=./prisma/schema.prisma

# 3. 推送Schema变更（谨慎，可能有破坏性变更）
# npx prisma db push

# 4. 验证
npx prisma studio
```

---

## ⚙️ 三、环境变量更新

### 3.1 需要更新的环境变量

| 变量名 | 当前值 | 新值 | 说明 |
|--------|--------|------|------|
| `OSS_BUCKET` | ai-clinical-research | ai-clinical-data | 数据Bucket |
| `OSS_BUCKET_STATIC` | （新增） | ai-clinical-static | 静态资源Bucket |
| `OSS_INTERNAL` | （新增） | true | 使用内网Endpoint |

### 3.2 完整环境变量清单（SAE生产）

```bash
# 基础配置
NODE_ENV=production
PORT=3001

# 数据库
DATABASE_URL=postgresql://airesearch:Xibahe%40fengzhibo117@pgm-2zex1m2y3r23hdn5.pg.rds.aliyuncs.com:5432/ai_clinical_research?connection_limit=18&pool_timeout=10

# Python微服务地址
EXTRACTION_SERVICE_URL=http://172.17.173.66:8000

# OSS配置（更新）
STORAGE_TYPE=oss
OSS_REGION=oss-cn-beijing
OSS_BUCKET=ai-clinical-data
OSS_BUCKET_STATIC=ai-clinical-static
OSS_ACCESS_KEY_ID=LTAI5tB2Dt3NdvBL3G7nYGv7
OSS_ACCESS_KEY_SECRET=1iSN9k39RkApP93QjUhC1DcPIeMG4V
OSS_INTERNAL=true

# JWT密钥
JWT_SECRET=8a3f9e7c2d1b5a4e6f8c9d0a3b5e7f1c2a4b6c8d0e2f4a6b8c0d2e4f6a8b0c2d4
JWT_EXPIRES_IN=7d

# LLM API Keys
DEEPSEEK_API_KEY=sk-7f8cc37a79fa4799860b38fc7ba2e150
DASHSCOPE_API_KEY=sk-75b4ff29a14a49e79667a331034f3298

# CloseAI配置
CLOSEAI_API_KEY=sk-cu0iepbXYGGx2jc7BqP6ogtSWmP6fk918qV3RUdtGC3Ed1po
CLOSEAI_OPENAI_BASE_URL=https://api.openai-proxy.org/v1
CLOSEAI_CLAUDE_BASE_URL=https://api.openai-proxy.org/anthropic

# Dify配置
DIFY_API_URL=http://localhost/v1
DIFY_API_KEY=dataset-mfvdiKvQ213NvxWm7RoYMN3c

# Postgres-Only架构
QUEUE_TYPE=pgboss
CACHE_TYPE=postgres

# 企业微信配置
WECHAT_CORP_ID=ww6ab493470ab4f377
WECHAT_AGENT_ID=1000002
WECHAT_CORP_SECRET=AZIVxMtoLb0rEszXS81e4dBRl-I9kgTjygIS0cFfENU
WECHAT_TOKEN=oXlRBm1YnvMy2SbDLbvAdDd5Gq3oBGq
WECHAT_ENCODING_AES_KEY=v88eT3O9bMW897h4btr7v7qvQImlMf31edTQCmuhOhO
```

---

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

### Step 1：更新Prisma Schema

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

# 编辑prisma/schema.prisma
# 1. 在schemas数组中添加 "iit_schema"
# 2. 确保IIT模块的模型定义存在
```

### Step 2：生成Prisma Client

```bash
npx prisma generate

# 预期输出：
# ✔ Generated Prisma Client
```

### Step 3：编译TypeScript

```bash
npm run build

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

### Step 4：构建Docker镜像

```powershell
docker build -t backend-service:v1.4 .

# 预计时间：5分钟
# 预计大小：约850MB
```

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

```powershell
# 设置环境变量文件进行本地测试
docker run --rm -p 3001:3001 `
  -e NODE_ENV=production `
  -e PORT=3001 `
  -e DATABASE_URL="postgresql://..." `
  backend-service:v1.4
```

### 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 backend-service:v1.4 `
  crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/backend-service:v1.4
```

### Step 8：推送到ACR

```powershell
docker push `
  crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/backend-service:v1.4

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

### Step 9：更新SAE环境变量

1. 登录SAE：https://sae.console.aliyun.com/
2. 进入应用：`nodejs-backend-test`
3. 点击【应用配置】→【环境变量】
4. 添加/修改以下变量：
   ```
   OSS_BUCKET=ai-clinical-data
   OSS_BUCKET_STATIC=ai-clinical-static
   OSS_INTERNAL=true
   ```
5. 点击【保存】

### Step 10：SAE部署新版本

1. 点击【部署应用】
2. 配置：
   - **镜像地址**：选择 `backend-service`
   - **镜像版本**：选择 `v1.4`
3. 点击【确认】
4. 等待部署完成（约5-8分钟）

### Step 11：验证部署

```bash
# 健康检查
curl http://172.17.173.73:3001/health

# 通过公网测试
curl http://8.140.53.236/api/v1/health

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

---

## 📋 五、一键部署脚本

### PowerShell脚本

`backend/update-and-deploy.ps1`：

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

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

$ErrorActionPreference = "Stop"

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

# 1. 生成Prisma Client
Write-Host "`n[1/5] 生成Prisma Client..." -ForegroundColor Cyan
npx prisma generate
if ($LASTEXITCODE -ne 0) {
    Write-Host "❌ Prisma生成失败！" -ForegroundColor Red
    exit 1
}
Write-Host "✅ Prisma Client生成成功！" -ForegroundColor Green

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

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

# 4. 打标签
Write-Host "`n[4/5] 打标签..." -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

# 5. 推送到ACR
Write-Host "`n[5/5] 推送到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 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/backend-service:$Version" -ForegroundColor Cyan
```

---

## ⚠️ 六、注意事项

### 6.1 部署前检查

- [ ] Prisma Schema已更新（包含iit_schema）
- [ ] `npx prisma generate` 成功
- [ ] `npm run build` 无错误
- [ ] 环境变量已确认

### 6.2 部署后检查

- [ ] 健康检查通过
- [ ] IIT模块API可访问
- [ ] ASL模块功能正常
- [ ] OSS上传下载正常

### 6.3 可能的问题

1. **IP地址变更**：
   - SAE部署后内网IP可能变化
   - 需要更新前端Nginx的环境变量

2. **数据库连接**：
   - 确保DATABASE_URL正确
   - 检查connection_limit设置

3. **Prisma迁移冲突**：
   - 如果Schema不匹配，可能需要手动调整

---

## 🔄 七、回滚方案

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

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

---

## 📊 八、时间估算

| 步骤 | 预计时间 |
|------|---------|
| 更新Prisma Schema | 5分钟 |
| 生成Prisma Client | 2分钟 |
| 编译TypeScript | 5分钟 |
| 构建Docker镜像 | 5分钟 |
| 推送到ACR | 10分钟 |
| 更新SAE环境变量 | 5分钟 |
| SAE部署 | 10分钟 |
| 验证测试 | 10分钟 |
| **总计** | **52分钟** |

---

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