# 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�?GB (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条目配置�?条，覆盖所有交换机�?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

# 镜像仓库�?个）
仓库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应用�?个：Python/Node.js/Frontend�?
---

## 🎯 部署全流程概�?
```
第一阶段：阿里云资源准备�?0分钟�?├── 创建VPC网络
├── 创建NAT网关（关键！�?├── 购买RDS PostgreSQL
├── 创建OSS存储�?└── 创建SAE应用�?个空应用�?
第二阶段：数据库初始化（30分钟�?├── 导出本地数据�?├── 通过ECS跳板机连接RDS
└── 导入数据到RDS

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

第四阶段：SAE应用部署�?0分钟�?├── 部署Python微服�?├── 部署Node.js后端
└── 部署前端Nginx

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

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

---

## 第一阶段：阿里云资源准备�?0分钟�?
### 1.1 创建VPC专有网络�?0分钟�?
**目的�?* 为所有云资源提供内网隔离环境

**操作步骤�?*

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网关�?5分钟）⭐⭐⭐⭐⭐

**目的�?* 为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条目配置�?条，覆盖所有交换机�?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�?   - 带宽�?Mbps（按使用流量计费�?   - 点击【确定�?
5. 配置SNAT规则（让SAE能访问公网）�?   - 点击【SNAT管理】→【创建SNAT条目�?   - 选择交换机：为每个交换机创建SNAT条目
   - 交换�?：`vsw-2zevacop039bxrmj6yc0c` (可用区F)
   - 交换�?：`vsw-2zehoeyw9ldncymcyvfwq` (可用区A)
   - 选择公网IP：绑定的EIP
   - 点击【确定�?
**验证�?* 
- �?NAT网关状态为"运行�?
- �?EIP已绑定：182.92.176.14
- �?SNAT条目状态为"可用"�?条）
- �?覆盖了所有交换机的网�?
**成本估算�?*
- NAT网关：�?0/�?- EIP：�?.8/GB流量（预计�?0/月）
- 合计：约¥100/�?
---

### 1.3 购买RDS PostgreSQL数据库（20分钟�?
**目的�?* 托管的PostgreSQL数据库，支持10个Schema隔离

**操作步骤�?*

1. 进入RDS控制台：https://rdsnext.console.aliyun.com/
2. 点击【创建实例�?3. 填写配置�?
```yaml
付费类型: 包年包月（首月�?0�?地域: 华北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�?GB (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
- �?可维护时间窗�?2: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�?分钟�?
**目的�?* 存储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

# 镜像仓库�?个）
仓库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�?5分钟�?
**⚠️ 为什么需要跳板机�?*
- RDS在VPC内网，本地电脑无法直接连�?- 需要一台ECS服务器作�?桥梁"

**操作步骤�?*

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

跳过ECS创建步骤，直接使用Dify的ECS作为跳板机�?
**方案B：创建临时ECS（推荐初期使用）**

1. 进入ECS控制台，创建按量付费实例�?
```yaml
地域: 华北2（北京）
规格: ecs.t6-c1m1.large�?�?GB，�?.05/小时�?镜像: Ubuntu 22.04
网络: ai-clinical-vpc (vpc-2ze055cptkew9c38w4r06) / ai-clinical-vswitch-1
安全�? sg-2zedk6fi8sgmmcwdu7tu（允�?2端口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�?0分钟�?
**在新终端窗口执行�?*

```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�?个表（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后端镜像�?0分钟�?
**⚠️ 重要前置步骤：复制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镜像�?5分钟�?
**在项目根目录执行�?*

```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控制台看�?个镜像仓库，每个都有 `v1.0.0` �?`latest` 标签
- 前端镜像地址：`crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/ai-clinical_frontend-nginx:v1.0.0`

---

## 第四阶段：SAE应用部署�?0分钟�?
### 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后端�?0分钟�?
**操作步骤�?*

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
# ⚠️ 替换�?72.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�?5分钟�?
**操作步骤�?*

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
# ⚠️ 替换�?72.17.x.x（从Node.js后端控制台获取内网IP�?```

4. 健康检查：

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

5. **配置公网访问（重要！）：**
   - 在应用详�?�?基本信息 �?公网访问
   - 点击【开启�?   - 获得公网域名（格式：`xxxx.cn-beijing.alicontainer.com`�?
6. 点击【创建】，等待部署（约5分钟�?
**验证�?*
- 应用状态为"运行�?
- 通过公网域名访问，看到登录页�?
---

## 第五阶段：验证与测试�?0分钟�?
### 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 功能测试�?5分钟�?
#### 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 日志排查�?0分钟�?
#### 查看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请求日志�?00/404/500状态码�?```

---

## 🚨 常见问题与解决方�?
### 问题1：后端无法连接数据库

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

**解决方案�?*

1. 检查RDS白名单：
   ```
   RDS控制�?�?数据安全�?�?白名单设�?   确保包含�?72.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：前端调用后�?04

**症状�?* 浏览器控制台显示 `/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�?GB/50GB | ¥200-300 | 包年包月（已购买）|
| **SAE - Python** | 1�?GB × 1实例 | ¥60 | 按量付费（闲时�?�?|
| **SAE - Node.js** | 2�?GB × 1实例 | ¥120 | 按量付费 |
| **SAE - Frontend** | 1�?GB × 1实例 | ¥60 | 按量付费 |
| **NAT网关** | 小型 | ¥60 | 固定费用（已创建）|
| **EIP流量�?* | 5Mbps | ¥40 | 按使用量计费（已配置）|
| **OSS存储** | 10GB | ¥2 | ¥0.12/GB/月（已创建）|
| **ACR容器镜像** | 个人�?| ¥0 | 免费 |
| **总计** | - | **¥542-622/�?* | 初创团队成本 |

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

---

## 🎯 下一步工�?
### 短期�?周内�?
- [ ] 绑定自定义域名（阿里云域名服�?+ SAE绑定�?- [ ] 配置HTTPS证书（Let's Encrypt免费证书�?- [ ] 配置OSS CDN加速（前端静态资源加速）
- [ ] 开启RDS自动备份（数据安全第一�?
### 中期�?个月内）

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

- [ ] 多实例部署（提升高可用性）
- [ ] 数据库读写分离（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实时日志�?0%的问题能从日志中发现�?2. 检查环境变量配置（DATABASE_URL、服务地址等）
3. 验证网络连通性（VPC、白名单、NAT网关�?4. 参考详细部署文档（每个模块有独立的完整指南�?
**文档版本�?* v1.0  
**最后更新：** 2025-12-16  
**维护者：** AI临床研究平台技术团�?