AIclinicalresearch/docs/05-部署文档/01-快速部署SOP-零基础版.md

# AI临床研究平台 - 阿里云快速部署SOP（零基础版）

> **文档版本：** v1.0  
> **创建日期：** 2025-12-16  
> **适用场景：** 从零开始部署到阿里云（不含Dify）  
> **预计时间：** 3-4小时  
> **目标：** 系统能够正常访问，基本功能可用

---

## 📋 部署检查清单

在开始之前，请确认：

- [ ] 已有阿里云账号，且已完成实名认证
- [ ] 账户余额 ≥ 500元（建议1000元，包含3个月运行费用）
- [ ] 已安装Docker Desktop（用于构建镜像）
- [ ] 已安装Git（用于获取代码）
- [ ] 本地能够正常运行项目（数据库已初始化）

---

## 📌 已部署资源快速参考

以下资源已经在阿里云上部署完成，部署过程中可以直接使用这些信息：

### ✅ VPC网络信息
```yaml
VPC ID: vpc-2ze055cptkew9c38w4r06
VPC名称: ai-clinical-vpc
网段: 172.17.0.0/16
地域: 华北2（北京）
交换机ID: vsw-2zevacop039bxrmj6yc0c (可用区F)
         vsw-2zehoeyw9ldncymcyvfwq (可用区A)
安全组ID: sg-2zedk6fi8sgmmcwdu7tu
```

### ✅ RDS PostgreSQL数据库
```yaml
实例ID: pgm-2zex1m2y3r23hdn5
内网地址: pgm-2zex1m2y3r23hdn5.pg.rds.aliyuncs.com:5432
数据库账号: airesearch
数据库密码: Xibahe@fengzhibo117
数据库名称: ai_clinical_research
规格: 2核4GB (pg.n2.2c.1m)
最大连接数: 400
PostgreSQL版本: 15.0
白名单: 172.17.0.0/16 ✅
时区: Asia/Shanghai ✅
```

### ✅ SAE命名空间
```yaml
命名空间ID: cn-beijing:test-airesearch
地域: 华北2（北京）
```

### ✅ OSS对象存储
```yaml
Bucket名称: ai-clinical-research
地域: 华北2（北京）
存储类型: 标准存储
读写权限: 私有
存储冗余类型: 同城冗余存储
外网Endpoint: oss-cn-beijing.aliyuncs.com
内网Endpoint: oss-cn-beijing-internal.aliyuncs.com
Bucket域名（内网）: ai-clinical-research.oss-cn-beijing-internal.aliyuncs.com
创建时间: 2025-12-16 20:22 ✅

# RAM用户访问凭证（用于OSS写入）
RAM用户名: oss-bucket-put-object@1991407246109125.onaliyun.com
AccessKeyId: LTAI5tB2Dt3NdvBL3G7nYGv7
AccessKeySecret: 1iSN9k39RkApP93QjUhC1DcPIeMG4V
UID: 203256565888301026
创建时间: 2025-12-16 20:31:41 ✅

⚠️ 安全警告：AccessKey是敏感信息，请勿提交到公开Git仓库！
```

### ✅ NAT网关与公网访问
```yaml
NAT网关名称: NAT_airesearch
NAT网关ID: ngw-2zeec9ulzgw7ywvx1pst6
SNAT表ID: stb-2zesszmzx1qpwf1cb2bry
公网IP(EIP): 182.92.176.14
创建时间: 2025-12-16 20:58:12 ✅

# SNAT条目配置（2条，覆盖所有交换机）
SNAT条目1:
  ID: snat-2zerlp4z0ed2isvq399gn
  源网段: 172.17.160.0/20
  交换机: vsw-2zevacop039bxrmj6yc0c (可用区F)
  公网IP: 182.92.176.14
  状态: 可用 ✅

SNAT条目2:
  ID: snat-2zegvesjxjwmw7j51m89m
  源网段: 172.17.192.0/20
  交换机: vsw-2zehoeyw9ldncymcyvfwq (可用区A)
  公网IP: 182.92.176.14
  状态: 可用 ✅
```

### ✅ ACR容器镜像服务
```yaml
服务类型: 个人版（免费）
命名空间: ai-clinical
用户名: gofeng117@163.com
Registry密码: fengzhibo117
公网域名: crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com
专有网络域名: crpi-cd5ij4pjt65mweeo-vpc.cn-beijing.personal.cr.aliyuncs.com

# 镜像仓库（3个）
仓库1 - 前端Nginx:
  仓库名称: ai-clinical_frontend-nginx
  公网地址: crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/ai-clinical_frontend-nginx
  专有网络地址: crpi-cd5ij4pjt65mweeo-vpc.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/ai-clinical_frontend-nginx

仓库2 - Python微服务:
  仓库名称: python-extraction
  公网地址: crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/python-extraction
  专有网络地址: crpi-cd5ij4pjt65mweeo-vpc.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/python-extraction

仓库3 - Node.js后端:
  仓库名称: nodejs-backend
  公网地址: crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/nodejs-backend
  专有网络地址: crpi-cd5ij4pjt65mweeo-vpc.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/nodejs-backend

⚠️ 安全警告：Registry密码是敏感信息，请勿提交到公开Git仓库！
```

### ⚠️ 待部署资源
- [x] NAT网关 ✅ 已创建，SNAT已配置
- [x] OSS存储桶 ✅ 已创建
- [x] ACR容器镜像仓库 ✅ 已创建
- [ ] SAE应用（3个：Python/Node.js/Frontend）

---

## 🎯 部署全流程概览

```
第一阶段：阿里云资源准备（60分钟）
├── 创建VPC网络
├── 创建NAT网关（关键！）
├── 购买RDS PostgreSQL
├── 创建OSS存储桶
└── 创建SAE应用（3个空应用）

第二阶段：数据库初始化（30分钟）
├── 导出本地数据库
├── 通过ECS跳板机连接RDS
└── 导入数据到RDS

第三阶段：Docker镜像准备（60分钟）
├── 创建阿里云容器镜像服务（ACR）
├── 构建Python微服务镜像
├── 构建Node.js后端镜像
└── 构建前端Nginx镜像

第四阶段：SAE应用部署（60分钟）
├── 部署Python微服务
├── 部署Node.js后端
└── 部署前端Nginx

第五阶段：验证与测试（30分钟）
├── 健康检查
├── 功能测试
└── 日志排查
```

**总预计时间：3.5-4小时**

---

## 第一阶段：阿里云资源准备（60分钟）

### 1.1 创建VPC专有网络（10分钟）

**目的：** 为所有云资源提供内网隔离环境

**操作步骤：**

1. 登录阿里云控制台：https://vpc.console.aliyun.com/
2. 点击【创建专有网络】
3. 填写配置：

```yaml
名称: ai-clinical-vpc
地域: 华北2（北京）
IPv4网段: 172.17.0.0/16
```

4. 创建交换机（vSwitch）：

```yaml
名称: ai-clinical-vswitch-1
可用区: 北京 可用区H
IPv4网段: 172.17.0.0/20
```

5. 点击【确定】，等待创建完成（约30秒）

**验证：** 在VPC列表中看到"ai-clinical-vpc"，状态为"可用"

---

### 1.2 创建NAT网关（15分钟）⭐⭐⭐⭐⭐

**目的：** 为SAE容器提供公网访问能力（调用DeepSeek/OpenAI API必需）

**⚠️ 重要警告：** 没有NAT网关，AI功能100%超时！

**✅ 实际NAT网关信息（已部署）：**
```yaml
NAT网关名称: NAT_airesearch
NAT网关ID: ngw-2zeec9ulzgw7ywvx1pst6
地域: 华北2（北京）
VPC: vpc-2ze055cptkew9c38w4r06
SNAT表ID: stb-2zesszmzx1qpwf1cb2bry
创建时间: 2025-12-16 20:58:12 ✅

# 弹性公网IP (EIP)
公网IP: 182.92.176.14 ✅

# SNAT条目配置（2条，覆盖所有交换机）
SNAT条目1:
  ID: snat-2zerlp4z0ed2isvq399gn
  源网段: 172.17.160.0/20
  交换机: vsw-2zevacop039bxrmj6yc0c (可用区F)
  公网IP: 182.92.176.14
  状态: ✅ 可用

SNAT条目2:
  ID: snat-2zegvesjxjwmw7j51m89m
  源网段: 172.17.192.0/20
  交换机: vsw-2zehoeyw9ldncymcyvfwq (可用区A)
  公网IP: 182.92.176.14
  状态: ✅ 可用
```

**⚠️ 如果需要重新创建，操作步骤：**

1. 进入NAT网关控制台：https://vpc.console.aliyun.com/nat
2. 点击【创建NAT网关】
3. 填写配置：

```yaml
地域: 华北2（北京）
VPC: ai-clinical-vpc (vpc-2ze055cptkew9c38w4r06)
规格: 小型（默认，¥60/月）
计费方式: 按量付费
```

4. 购买弹性公网IP（EIP）：
   - 点击【绑定弹性公网IP】
   - 选择【购买并绑定EIP】
   - 带宽：5Mbps（按使用流量计费）
   - 点击【确定】

5. 配置SNAT规则（让SAE能访问公网）：
   - 点击【SNAT管理】→【创建SNAT条目】
   - 选择交换机：为每个交换机创建SNAT条目
   - 交换机1：`vsw-2zevacop039bxrmj6yc0c` (可用区F)
   - 交换机2：`vsw-2zehoeyw9ldncymcyvfwq` (可用区A)
   - 选择公网IP：绑定的EIP
   - 点击【确定】

**验证：** 
- ✅ NAT网关状态为"运行中"
- ✅ EIP已绑定：182.92.176.14
- ✅ SNAT条目状态为"可用"（2条）
- ✅ 覆盖了所有交换机的网段

**成本估算：**
- NAT网关：¥60/月
- EIP：¥0.8/GB流量（预计¥40/月）
- 合计：约¥100/月

---

### 1.3 购买RDS PostgreSQL数据库（20分钟）

**目的：** 托管的PostgreSQL数据库，支持10个Schema隔离

**操作步骤：**

1. 进入RDS控制台：https://rdsnext.console.aliyun.com/
2. 点击【创建实例】
3. 填写配置：

```yaml
付费类型: 包年包月（首月¥70）
地域: 华北2（北京）
可用区: 北京 可用区H
数据库类型: PostgreSQL
版本: 15
系列: 基础版（节省成本，不支持主备切换）
规格: 
  - CPU: 2核
  - 内存: 4GB
  - 存储: 50GB（云盘ESSD）
网络类型: 专有网络（VPC）
VPC: ai-clinical-vpc (vpc-2ze055cptkew9c38w4r06)
交换机: ai-clinical-vswitch-1 (vsw-2zevacop039bxrmj6yc0c)
```

4. 高级配置：

```yaml
数据库账号: airesearch
密码: （设置复杂密码，记录到密码管理器，如：Xibahe@fengzhibo117）
数据库名称: ai_clinical_research
字符集: UTF8
```

5. 点击【立即购买】，等待创建（约5分钟）

**⚠️ 关键配置（创建后）：**

1. **白名单配置**（必须配置，否则无法连接）：
   - 进入实例详情 → 数据安全性 → 白名单设置
   - 点击【修改】
   - 添加：`172.17.0.0/16`（整个VPC网段，不要用单机IP！）
   - 点击【确定】

2. **时区配置**（避免日志时间错乱）：
   - 进入实例详情 → 参数设置
   - 搜索：`timezone`
   - 修改值：`Asia/Shanghai`
   - 点击【提交参数】
   - ✅ **已配置**（可维护时间窗：02:00-06:00 Asia/Shanghai UTC+8）

**✅ 实际RDS信息（已部署）：**
```yaml
实例ID: pgm-2zex1m2y3r23hdn5
内网地址: pgm-2zex1m2y3r23hdn5.pg.rds.aliyuncs.com:5432
数据库账号: airesearch
数据库密码: Xibahe@fengzhibo117
数据库名称: ai_clinical_research
VPC: vpc-2ze055cptkew9c38w4r06 (172.17.0.0/16)
资源组ID: rg-acfm4nrrfnu6tri
规格: 2核4GB (pg.n2.2c.1m)
最大连接数: 400
最大IOPS: 7550
PostgreSQL版本: 15.0
存储类型: 高性能云盘
白名单: 172.17.0.0/16 ✅
时区: Asia/Shanghai (UTC+8) ✅
```

**验证：** 
- ✅ 实例状态为"运行中"
- ✅ 白名单已包含VPC网段 (172.17.0.0/16)
- ✅ 时区已设置为 Asia/Shanghai
- ✅ 可维护时间窗：02:00-06:00（夜间维护不影响白天使用）

---

### 1.4 创建OSS存储桶（10分钟）

**目的：** 存储文献PDF、稿件文档等文件

**✅ 实际OSS信息（已部署）：**
```yaml
Bucket名称: ai-clinical-research
地域: 华北2（北京）
存储类型: 标准存储
读写权限: 私有
存储冗余类型: 同城冗余存储
外网Endpoint: oss-cn-beijing.aliyuncs.com
内网Endpoint: oss-cn-beijing-internal.aliyuncs.com
Bucket域名（内网）: ai-clinical-research.oss-cn-beijing-internal.aliyuncs.com
创建时间: 2025-12-16 20:22 ✅
访问控制: 文件不可以被公共访问 ✅
```

**⚠️ 如果需要重新创建，操作步骤：**

1. 进入OSS控制台：https://oss.console.aliyun.com/
2. 点击【创建Bucket】
3. 填写配置：

```yaml
Bucket名称: ai-clinical-research（全局唯一）
地域: 华北2（北京）
存储类型: 标准存储
读写权限: 私有（默认）
存储冗余类型: 同城冗余存储（推荐）
版本控制: 不开启
```

4. **推荐的目录结构**（应用会自动创建）：

```
asl/        # AI文献筛选模块
  ├── source/      # 原始PDF文件
  └── extracted/   # 解析结果JSON
pkb/        # 个人知识库模块
  └── documents/   # 知识库文档
dc/         # 数据清洗模块
  ├── raw/         # 原始数据文件
  └── cleaned/     # 清洗后的数据
```

5. **OSS访问授权配置**

**✅ 方案A：使用AccessKey（已创建，推荐初期使用）**
```yaml
RAM用户: oss-bucket-put-object@1991407246109125.onaliyun.com
AccessKeyId: LTAI5tB2Dt3NdvBL3G7nYGv7
AccessKeySecret: 1iSN9k39RkApP93QjUhC1DcPIeMG4V
权限: OSS Bucket写入权限
```

**⚠️ 安全警告：**
- AccessKey是敏感信息，等同于密码
- 请勿将AccessKey提交到Git仓库
- 只在SAE环境变量中配置，不要写入代码
- 定期轮换AccessKey（建议每3个月）

**方案B：使用RAM角色（推荐生产环境）**
- 进入RAM控制台：https://ram.console.aliyun.com/
- 创建角色：AliyunSAEDefaultRole（SAE默认角色）
- 授予权限：AliyunOSSFullAccess
- 优势：无需管理AccessKey，更安全

**验证：** 
- ✅ Bucket已创建成功
- ✅ 内网Endpoint：`oss-cn-beijing-internal.aliyuncs.com`
- ✅ Bucket域名：`ai-clinical-research.oss-cn-beijing-internal.aliyuncs.com`
- ✅ RAM用户已创建，AccessKey已生成

---

### 1.5 创建容器镜像服务ACR（5分钟）

**目的：** 存储Docker镜像，供SAE拉取部署

**✅ 实际ACR信息（已部署）：**

```yaml
服务类型: 个人版（免费）
命名空间: ai-clinical
用户名: gofeng117@163.com
Registry密码: fengzhibo117
公网域名: crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com
专有网络域名: crpi-cd5ij4pjt65mweeo-vpc.cn-beijing.personal.cr.aliyuncs.com

# 镜像仓库（3个）
仓库1 - 前端Nginx:
  仓库名称: ai-clinical_frontend-nginx
  公网地址: crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/ai-clinical_frontend-nginx
  专有网络地址: crpi-cd5ij4pjt65mweeo-vpc.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/ai-clinical_frontend-nginx
  类型: 私有
  状态: ✅ 已创建

仓库2 - Python微服务:
  仓库名称: python-extraction
  公网地址: crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/python-extraction
  专有网络地址: crpi-cd5ij4pjt65mweeo-vpc.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/python-extraction
  类型: 私有
  状态: ✅ 已创建

仓库3 - Node.js后端:
  仓库名称: nodejs-backend
  公网地址: crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/nodejs-backend
  专有网络地址: crpi-cd5ij4pjt65mweeo-vpc.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/nodejs-backend
  类型: 私有
  状态: ✅ 已创建
```

**⚠️ 如果需要重新创建，操作步骤：**

1. 进入容器镜像服务控制台：https://cr.console.aliyun.com/
2. 选择【个人版】（免费）
3. 设置Registry密码（用于docker login）
4. 创建命名空间：`ai-clinical`
5. 创建3个镜像仓库（类型：私有，代码源：本地仓库）

**验证：** 
- ✅ 3个仓库创建成功
- ✅ Registry地址：`crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com`
- ✅ 专有网络地址：`crpi-cd5ij4pjt65mweeo-vpc.cn-beijing.personal.cr.aliyuncs.com`

**⚠️ 安全警告：**
- Registry密码是敏感信息，等同于Docker镜像访问权限
- 请勿将密码提交到Git仓库
- 定期轮换密码（建议每3个月）

---

## 第二阶段：数据库初始化（30分钟）

### 2.1 导出本地数据库（5分钟）

**在本地项目根目录执行：**

```bash
# 确保Docker正在运行
docker ps

# 导出数据库
docker exec ai-clinical-postgres pg_dump \
  -U postgres \
  -d ai_clinical_research \
  --no-owner \
  --no-acl \
  --clean \
  --if-exists \
  > rds_init.sql

# 验证文件大小（应该有几百KB）
ls -lh rds_init.sql
```

**验证：** `rds_init.sql` 文件存在，且大小 > 100KB

---

### 2.2 通过ECS跳板机连接RDS（15分钟）

**⚠️ 为什么需要跳板机？**
- RDS在VPC内网，本地电脑无法直接连接
- 需要一台ECS服务器作为"桥梁"

**操作步骤：**

**方案A：使用现有Dify ECS（如果已有）**

跳过ECS创建步骤，直接使用Dify的ECS作为跳板机。

**方案B：创建临时ECS（推荐初期使用）**

1. 进入ECS控制台，创建按量付费实例：

```yaml
地域: 华北2（北京）
规格: ecs.t6-c1m1.large（1核1GB，¥0.05/小时）
镜像: Ubuntu 22.04
网络: ai-clinical-vpc (vpc-2ze055cptkew9c38w4r06) / ai-clinical-vswitch-1
安全组: sg-2zedk6fi8sgmmcwdu7tu（允许22端口SSH）
购买时长: 按量付费
```

2. 在本地创建SSH隧道：

```bash
# 替换以下参数：
# - ECS_PUBLIC_IP: ECS的公网IP

ssh -N -L 5433:pgm-2zex1m2y3r23hdn5.pg.rds.aliyuncs.com:5432 \
  root@ECS_PUBLIC_IP

# 输入ECS密码，成功后命令会"卡住"（正常现象）
# 保持这个终端窗口打开
```

**验证：** 打开新终端，执行：

```bash
# 测试RDS连接（通过SSH隧道）
psql -h localhost -p 5433 -U airesearch -d ai_clinical_research

# 输入密码：Xibahe@fengzhibo117
# 如果成功连接，说明隧道已建立
```

---

### 2.3 导入数据到RDS（10分钟）

**在新终端窗口执行：**

```bash
# 导入数据（通过SSH隧道）
psql -h localhost -p 5433 \
  -U airesearch \
  -d ai_clinical_research \
  -f rds_init.sql

# 输入密码：Xibahe@fengzhibo117

# 验证导入成功
psql -h localhost -p 5433 \
  -U airesearch \
  -d ai_clinical_research \
  -c "\dt platform_schema.*"

# 应该看到 platform_schema 下的表
```

**验证：**
- 看到 `platform_schema.users` 表
- 看到 `aia_schema.*` 表
- 看到 `_prisma_migrations` 表

**⚠️ 重要：** pg-boss的6个表（job/queue等）不在导出文件中，会在应用首次启动时自动创建。

---

## 第三阶段：Docker镜像构建与推送（60分钟）

### 3.1 登录阿里云容器镜像服务

**在本地终端执行：**

```bash
# 登录ACR个人版（使用真实信息）
docker login --username=gofeng117@163.com crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com

# 输入密码：fengzhibo117
# 看到 "Login Succeeded" 表示登录成功
```

**⚠️ 注意事项：**
- 个人版使用自定义域名，不是标准的 `registry.cn-beijing.aliyuncs.com`
- 用户名：`gofeng117@163.com`（完整邮箱地址）
- 密码：`fengzhibo117`（Registry密码，不是阿里云账号密码）

---

### 3.2 构建Python微服务镜像（15分钟）

**在项目根目录执行：**

```bash
cd extraction_service

# 构建镜像（确保Dockerfile存在）
docker build -t ai-clinical/python-extraction:v1.0.0 .

# 打标签（使用真实ACR地址）
docker tag ai-clinical/python-extraction:v1.0.0 \
  crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/python-extraction:v1.0.0

docker tag ai-clinical/python-extraction:v1.0.0 \
  crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/python-extraction:latest

# 推送到ACR
docker push crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/python-extraction:v1.0.0
docker push crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/python-extraction:latest

cd ..
```

**验证：** 
- 在ACR控制台看到镜像，标签为 `v1.0.0` 和 `latest`
- 镜像地址：`crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/python-extraction:v1.0.0`

---

### 3.3 构建Node.js后端镜像（20分钟）

**⚠️ 重要前置步骤：复制Prisma目录**

```bash
# 在项目根目录执行
cp -r prisma backend/

# 验证
ls backend/prisma/schema.prisma  # 应该存在
```

**构建镜像：**

```bash
cd backend

# 构建镜像
docker build -t ai-clinical/nodejs-backend:v1.0.0 .

# 打标签并推送（使用真实ACR地址）
docker tag ai-clinical/nodejs-backend:v1.0.0 \
  crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/nodejs-backend:v1.0.0

docker tag ai-clinical/nodejs-backend:v1.0.0 \
  crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/nodejs-backend:latest

docker push crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/nodejs-backend:v1.0.0
docker push crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/nodejs-backend:latest

cd ..
```

**验证：** 
- ACR控制台看到Node.js镜像
- 镜像地址：`crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/nodejs-backend:v1.0.0`

---

### 3.4 构建前端Nginx镜像（25分钟）

**在项目根目录执行：**

```bash
cd frontend-v2

# 构建镜像（包含React构建 + Nginx打包）
docker build -t ai-clinical/frontend-nginx:v1.0.0 .

# 打标签并推送（使用真实ACR地址，注意仓库名称带下划线）
docker tag ai-clinical/frontend-nginx:v1.0.0 \
  crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/ai-clinical_frontend-nginx:v1.0.0

docker tag ai-clinical/frontend-nginx:v1.0.0 \
  crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/ai-clinical_frontend-nginx:latest

docker push crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/ai-clinical_frontend-nginx:v1.0.0
docker push crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/ai-clinical_frontend-nginx:latest

cd ..
```

**⚠️ 注意：** 前端仓库名称是 `ai-clinical_frontend-nginx`（带下划线），与后端不同。

**验证：** 
- ACR控制台看到3个镜像仓库，每个都有 `v1.0.0` 和 `latest` 标签
- 前端镜像地址：`crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/ai-clinical_frontend-nginx:v1.0.0`

---

## 第四阶段：SAE应用部署（60分钟）

### 4.1 部署Python微服务（15分钟）

**操作步骤：**

1. 进入SAE控制台：https://sae.console.aliyun.com/
2. 点击【创建应用】
3. 基础配置：

```yaml
应用名称: python-extraction-service
命名空间: cn-beijing:test-airesearch（已创建）
地域: 华北2（北京）
VPC: ai-clinical-vpc (vpc-2ze055cptkew9c38w4r06)
安全组: sg-2zedk6fi8sgmmcwdu7tu
```

4. 应用配置：

```yaml
技术栈: 容器镜像
镜像: crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/python-extraction:v1.0.0
镜像拉取策略: Always（重要！）
版本: v1.0.0
```

**⚠️ 重要：** 使用个人版ACR地址，不是标准的 `registry.cn-beijing.aliyuncs.com`

5. 应用实例：

```yaml
CPU: 1核
内存: 2GB
实例数: 1
```

6. 高级配置：

```yaml
端口: 8000
健康检查: HTTP
  - 路径: /health
  - 初始延迟: 30秒
  - 超时: 3秒
  - 检查间隔: 5秒

环境变量: （暂时为空，Python微服务是纯计算服务）
```

7. 点击【创建】，等待部署（约5分钟）

**验证：**
- 应用状态为"运行中"
- 健康检查通过
- 记录内网地址（格式：`172.17.x.x:8000`）

---

### 4.2 部署Node.js后端（20分钟）

**操作步骤：**

1. 创建新应用：`nodejs-backend-service`
2. 应用配置：

```yaml
镜像: crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/nodejs-backend:v1.0.0
镜像拉取策略: Always
CPU: 2核
内存: 4GB
实例数: 1
端口: 3001
```

**⚠️ 重要：** 使用个人版ACR地址

3. **环境变量配置（⭐⭐⭐⭐⭐ 重要）：**

```bash
# ==================== 数据库配置 ====================
# ⚠️ 注意：密码中的 @ 符号必须转义为 %40
DATABASE_URL=postgresql://airesearch:Xibahe%40fengzhibo117@pgm-2zex1m2y3r23hdn5.pg.rds.aliyuncs.com:5432/ai_clinical_research
# ✅ 已使用实际RDS信息（密码已转义）

# ==================== 存储配置 ====================
STORAGE_TYPE=oss
OSS_REGION=oss-cn-beijing
OSS_BUCKET=ai-clinical-research
OSS_ENDPOINT=oss-cn-beijing-internal.aliyuncs.com
# ✅ OSS配置已使用实际Bucket信息
# Bucket域名: ai-clinical-research.oss-cn-beijing-internal.aliyuncs.com

# OSS访问凭证（方案A：使用AccessKey）
OSS_ACCESS_KEY_ID=LTAI5tB2Dt3NdvBL3G7nYGv7
OSS_ACCESS_KEY_SECRET=1iSN9k39RkApP93QjUhC1DcPIeMG4V
# ⚠️ 注意：AccessKey是敏感信息，请勿提交到Git！

# OSS访问凭证（方案B：使用RAM角色，更安全）
# 在SAE控制台配置RAM角色：AliyunSAEDefaultRole
# 优势：无需在环境变量中配置AccessKey

# ==================== 微服务地址 ====================
EXTRACTION_SERVICE_URL=http://172.17.x.x:8000
# ⚠️ 替换：172.17.x.x（从Python微服务控制台获取内网IP）

DIFY_API_URL=http://placeholder/v1
DIFY_API_KEY=temp_placeholder
# ⚠️ 暂不部署Dify，使用占位符（PKB模块会自动禁用）

# ==================== LLM配置 ====================
DEEPSEEK_API_KEY=sk-xxxxxxxx
# ⚠️ 替换为真实的DeepSeek API Key

# ==================== 应用配置 ====================
NODE_ENV=production
PORT=3001
```

4. **启动命令（重要！）：**

```bash
/bin/sh -c "npx prisma migrate deploy && node dist/index.js"
```

**⚠️ 说明：** 
- `npx prisma migrate deploy`：部署数据库迁移
- `node dist/index.js`：启动应用

5. 健康检查：

```yaml
路径: /health
初始延迟: 60秒（留时间给Prisma迁移）
超时: 5秒
```

6. 点击【创建】，等待部署（约10分钟）

**验证：**
- 查看"实时日志"，看到：
  ```
  ✅ Prisma migrate deploy 完成
  ✅ pg-boss 自动创建6个表
  ✅ 应用启动成功，监听 0.0.0.0:3001
  ```
- 健康检查通过
- 记录内网地址（格式：`172.17.x.x:3001`）

**⚠️ 如果启动失败：**

常见原因：
1. DATABASE_URL错误 → 检查密码、RDS地址
   - 当前RDS：pgm-2zex1m2y3r23hdn5.pg.rds.aliyuncs.com
   - 用户名：airesearch
   - 密码中有特殊字符@，URL中需要转义为 %40
2. 白名单未配置 → ✅ 已确认配置：172.17.0.0/16
3. Prisma迁移失败 → 查看日志，确认数据库权限

**⚠️ 密码特殊字符转义（重要）：**
```bash
# 原始密码：Xibahe@fengzhibo117
# @ 符号需要转义为 %40

# 错误写法（会导致连接失败）：
DATABASE_URL=postgresql://airesearch:Xibahe@fengzhibo117@pgm-2zex1m2y3r23hdn5.pg.rds.aliyuncs.com:5432/ai_clinical_research

# 正确写法：
DATABASE_URL=postgresql://airesearch:Xibahe%40fengzhibo117@pgm-2zex1m2y3r23hdn5.pg.rds.aliyuncs.com:5432/ai_clinical_research
```

---

### 4.3 部署前端Nginx（15分钟）

**操作步骤：**

1. 创建新应用：`frontend-nginx`
2. 应用配置：

```yaml
镜像: crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/ai-clinical_frontend-nginx:v1.0.0
镜像拉取策略: Always
CPU: 1核
内存: 2GB
实例数: 1
端口: 80
```

**⚠️ 重要：** 
- 使用个人版ACR地址
- 注意仓库名称是 `ai-clinical_frontend-nginx`（带下划线）

3. **环境变量配置：**

```bash
# 后端服务地址（内网）
BACKEND_SERVICE_HOST=172.17.x.x
BACKEND_SERVICE_PORT=3001
# ⚠️ 替换：172.17.x.x（从Node.js后端控制台获取内网IP）
```

4. 健康检查：

```yaml
路径: /health
初始延迟: 10秒
超时: 3秒
```

5. **配置公网访问（重要！）：**
   - 在应用详情 → 基本信息 → 公网访问
   - 点击【开启】
   - 获得公网域名（格式：`xxxx.cn-beijing.alicontainer.com`）

6. 点击【创建】，等待部署（约5分钟）

**验证：**
- 应用状态为"运行中"
- 通过公网域名访问，看到登录页面

---

## 第五阶段：验证与测试（30分钟）

### 5.1 健康检查验证（5分钟）

**Python微服务：**

```bash
# 在本地终端执行（替换为实际公网地址，如果开启了）
# 或通过Node.js后端间接验证

# 直接测试（如果Python开启了公网）
curl http://python-service-public-url/health

# 预期响应：
{"status":"healthy"}
```

**Node.js后端：**

```bash
curl http://backend-public-url/health

# 预期响应：
{"status":"ok","database":"connected","timestamp":"..."}
```

**前端Nginx：**

```bash
curl http://frontend-public-url/health

# 预期响应：
{"status":"ok"}
```

---

### 5.2 功能测试（15分钟）

#### 5.2.1 用户登录测试

1. 访问前端公网地址：`http://xxxxx.cn-beijing.alicontainer.com`
2. 使用测试账号登录：
   - 账号：`admin@test.com`
   - 密码：`admin123`（或你本地数据库中的密码）
3. 验证：成功跳转到主页，显示用户名

#### 5.2.2 文献筛选测试（ASL模块）

1. 进入【AI智能文献】模块
2. 创建新项目：
   ```yaml
   项目名称: 测试项目
   研究主题: 糖尿病治疗
   ```
3. 上传测试文献（小文件，< 5MB）
4. 验证：
   - 文件上传到OSS成功
   - 后端调用Python服务解析PDF
   - 数据库中生成记录

#### 5.2.3 数据清洗测试（DC模块）

1. 进入【数据清洗】模块
2. 上传测试Excel文件
3. 验证：
   - OSS上传成功
   - Python服务处理数据
   - 下载清洗结果

---

### 5.3 日志排查（10分钟）

#### 查看SAE实时日志

**Python微服务：**

```
SAE控制台 → python-extraction-service → 日志 → 实时日志

查看是否有错误日志（ERROR/WARN）
```

**Node.js后端：**

```
SAE控制台 → nodejs-backend-service → 日志 → 实时日志

关键日志：
✅ Prisma connected
✅ pg-boss started
✅ Server listening on 0.0.0.0:3001
```

**前端Nginx：**

```
SAE控制台 → frontend-nginx → 日志 → 访问日志

查看HTTP请求日志（200/404/500状态码）
```

---

## 🚨 常见问题与解决方案

### 问题1：后端无法连接数据库

**症状：** Node.js日志显示 `connection timeout` 或 `FATAL: no pg_hba.conf entry`

**解决方案：**

1. 检查RDS白名单：
   ```
   RDS控制台 → 数据安全性 → 白名单设置
   确保包含：172.17.0.0/16（VPC网段）
   ```

2. 检查DATABASE_URL：
   ```bash
   # ✅ 正确格式（特殊字符已转义）：
   postgresql://airesearch:Xibahe%40fengzhibo117@pgm-2zex1m2y3r23hdn5.pg.rds.aliyuncs.com:5432/ai_clinical_research
   
   # 常见错误：
   - 密码中的 @ 符号未转义为 %40（最常见！）
   - RDS地址错误（应该用内网地址）
   - 数据库名称错误
   
   # 特殊字符转义规则：
   @ -> %40
   # -> %23
   $ -> %24
   % -> %25
   ```

---

### 问题2：后端调用Python微服务超时

**症状：** 日志显示 `ECONNREFUSED` 或 `timeout`

**解决方案：**

1. 检查Python微服务内网地址：
   ```
   SAE控制台 → python-extraction-service → 基本信息 → 内网地址
   复制IP地址（格式：172.17.x.x）
   ```

2. 更新Node.js后端环境变量：
   ```bash
   EXTRACTION_SERVICE_URL=http://172.17.x.x:8000
   ```

3. 重启Node.js后端应用

---

### 问题3：前端调用后端404

**症状：** 浏览器控制台显示 `/api/xxx 404`

**解决方案：**

1. 检查前端环境变量：
   ```bash
   # 确认 BACKEND_SERVICE_HOST 是Node.js的内网IP
   BACKEND_SERVICE_HOST=172.17.x.x
   BACKEND_SERVICE_PORT=3001
   ```

2. 检查Nginx配置（已内置在镜像中）：
   ```nginx
   location /api/ {
       proxy_pass http://${BACKEND_SERVICE_HOST}:${BACKEND_SERVICE_PORT};
   }
   ```

3. 重启前端应用

---

### 问题4：文件上传到OSS失败

**症状：** 上传文件时报错 `OSS access denied`

**解决方案：**

1. **方案A：使用AccessKey（已配置）**
   ```bash
   # 确认Node.js后端环境变量已配置：
   OSS_ACCESS_KEY_ID=LTAI5tB2Dt3NdvBL3G7nYGv7
   OSS_ACCESS_KEY_SECRET=1iSN9k39RkApP93QjUhC1DcPIeMG4V
   ```
   
   **验证方法：**
   - SAE控制台 → nodejs-backend-service → 应用设置 → 环境变量
   - 检查是否包含 `OSS_ACCESS_KEY_ID` 和 `OSS_ACCESS_KEY_SECRET`

2. **方案B：使用RAM角色（推荐生产环境）**
   ```
   SAE控制台 → 应用设置 → 高级设置 → RAM角色
   选择：AliyunSAEDefaultRole
   确保该角色有 AliyunOSSFullAccess 权限
   ```
   
   **优势：**
   - 无需在环境变量中配置AccessKey
   - 更安全，避免AccessKey泄露风险
   - 支持自动轮换凭证

3. **检查RAM用户权限：**
   ```
   RAM控制台 → 用户 → oss-bucket-put-object@1991407246109125.onaliyun.com
   确认权限：PutObject（写入权限）
   ```

---

### 问题5：AI功能无法调用（DeepSeek API超时）

**症状：** LLM对话功能报错 `network timeout`

**解决方案：**

1. **检查NAT网关SNAT规则：**
   ```
   VPC控制台 → NAT网关 → NAT_airesearch → SNAT管理
   
   ✅ 已确认配置：
   - 交换机F (vsw-2zevacop039bxrmj6yc0c): 172.17.160.0/20 → 182.92.176.14 (可用)
   - 交换机A (vsw-2zehoeyw9ldncymcyvfwq): 172.17.192.0/20 → 182.92.176.14 (可用)
   ```

2. **验证公网访问能力：**
   ```bash
   # 在SAE应用实例中执行命令（通过WebIDE）：
   curl https://api.deepseek.com/v1/models
   
   # 应该返回模型列表，而不是 timeout
   ```

3. **如果SNAT未生效：**
   - 检查EIP是否已绑定
   - 检查SNAT条目状态是否为"可用"
   - 重启SAE应用

---

## 📊 成本估算

| 资源 | 规格 | 月成本 | 说明 |
|------|------|-------|------|
| **RDS PostgreSQL** | 2核4GB/50GB | ¥200-300 | 包年包月（已购买）|
| **SAE - Python** | 1核2GB × 1实例 | ¥60 | 按量付费（闲时¥0） |
| **SAE - Node.js** | 2核4GB × 1实例 | ¥120 | 按量付费 |
| **SAE - Frontend** | 1核2GB × 1实例 | ¥60 | 按量付费 |
| **NAT网关** | 小型 | ¥60 | 固定费用（已创建）|
| **EIP流量费** | 5Mbps | ¥40 | 按使用量计费（已配置）|
| **OSS存储** | 10GB | ¥2 | ¥0.12/GB/月（已创建）|
| **ACR容器镜像** | 个人版 | ¥0 | 免费 |
| **总计** | - | **¥542-622/月** | 初创团队成本 |

**节省成本建议：**
1. RDS购买包年包月（首月¥70，续费¥200/月）
2. 开发环境只开1个SAE实例（其他实例缩容到0）
3. 使用SAE的"闲时停机"功能（晚上自动停机）

---

## 🎯 下一步工作

### 短期（1周内）

- [ ] 绑定自定义域名（阿里云域名服务 + SAE绑定）
- [ ] 配置HTTPS证书（Let's Encrypt免费证书）
- [ ] 配置OSS CDN加速（前端静态资源加速）
- [ ] 开启RDS自动备份（数据安全第一）

### 中期（1个月内）

- [ ] 部署Dify平台（启用PKB个人知识库功能）
- [ ] 配置监控告警（ARMS应用监控）
- [ ] 优化数据库索引（提升查询性能）
- [ ] 实施CI/CD自动化部署（GitHub Actions）

### 长期（3个月后）

- [ ] 多实例部署（提升高可用性）
- [ ] 数据库读写分离（RDS主备版）
- [ ] OSS生命周期管理（自动清理临时文件）
- [ ] 性能优化与成本优化

---

## 📚 相关文档

- [部署架构总览](./00-部署架构总览.md)
- [Python微服务部署指南](./04-Python微服务-SAE容器部署指南.md)
- [Node.js后端部署指南](./05-Node.js后端-SAE容器部署指南.md)
- [前端Nginx部署指南](./06-前端Nginx-SAE容器部署指南.md)
- [PostgreSQL部署策略](./PostgreSQL部署策略-摸底报告.md)
- [关键配置补充说明](./07-关键配置补充说明.md)
- [部署检查清单](./08-部署检查清单.md)

---

## 🆘 紧急联系

**如果遇到无法解决的问题：**

1. 查看SAE实时日志（90%的问题能从日志中发现）
2. 检查环境变量配置（DATABASE_URL、服务地址等）
3. 验证网络连通性（VPC、白名单、NAT网关）
4. 参考详细部署文档（每个模块有独立的完整指南）

**文档版本：** v1.0  
**最后更新：** 2025-12-16  
**维护者：** AI临床研究平台技术团队