AIclinicalresearch/docs/05-部署文档/_archive-2025首次部署/02-SAE部署完全指南(产品经理版).md

# 🚀 阿里云SAE部署完全指南（产品经理版）

> **文档版本：** v1.0  
> **创建日期：** 2025-12-11  
> **适用人群：** 无部署经验的产品经理、项目负责人  
> **预计时间：** 2-3小时（包含等待时间）  
> **难度等级：** ⭐⭐ 简单（保姆级教程）

---

## 📋 目录

1. [前置准备](#前置准备)
2. [需不需要购买Redis](#需不需要购买redis)
3. [第一步：准备Docker镜像](#第一步准备docker镜像)
4. [第二步：配置阿里云服务](#第二步配置阿里云服务)
5. [第三步：部署到SAE](#第三步部署到sae)
6. [第四步：部署前端](#第四步部署前端)
7. [第五步：验证部署](#第五步验证部署)
8. [常见问题解决](#常见问题解决)

---

## 前置准备

### ✅ 您已经购买的服务

| 服务 | 状态 | 说明 |
|------|------|------|
| **阿里云SAE** | ✅ 已购买 | Serverless应用引擎 |
| **云数据库RDS PostgreSQL** | ✅ 已购买 | 数据库服务 |
| **对象存储OSS** | ✅ 已购买 | 文件存储服务 |

### 💻 您需要安装的工具

1. **Docker Desktop**
   - 下载地址：https://www.docker.com/products/docker-desktop/
   - Windows系统选择 "Docker Desktop for Windows"
   - 安装后重启电脑

2. **阿里云CLI（可选）**
   - 如果不想用命令行，可以全程使用阿里云控制台网页操作

---

## 需不需要购买Redis？

### 📊 答案：**初期不需要，未来可能需要**

| 场景 | 是否需要Redis | 说明 |
|------|--------------|------|
| **开发测试环境** | ❌ 不需要 | 使用内存缓存即可 |
| **初期用户<100人** | ❌ 不需要 | 使用内存缓存足够 |
| **中期用户100-1000人** | ⚠️ 建议购买 | 提升性能，¥200/月 |
| **成熟期用户>1000人** | ✅ 必须购买 | 必须使用Redis |

### 🎯 我的建议

**现在创建开发测试环境，不要购买Redis**

原因：
1. ✅ 您的代码已经支持 `CACHE_TYPE=memory`（内存缓存）
2. ✅ 开发测试阶段，内存缓存完全够用
3. ✅ 等真正上线后，根据实际情况再决定
4. ✅ 节省成本（初期省¥200/月）

**环境变量配置：**
```bash
# 不使用Redis
CACHE_TYPE=memory

# 未来需要时，只需改为：
CACHE_TYPE=redis
REDIS_HOST=r-xxxx.redis.rds.aliyuncs.com
REDIS_PASSWORD=your_password
```

---

## 第一步：准备Docker镜像

### 📦 1.1 创建Dockerfile文件

在 `AIclinicalresearch/backend/` 目录下创建文件 `Dockerfile`（如果不存在）：

```dockerfile
# ==================== 构建阶段 ====================
FROM node:22-alpine AS builder

WORKDIR /app

# 复制依赖文件
COPY package*.json ./
COPY prisma ./prisma/

# 安装依赖（npm ci 比 npm install 更稳定）
RUN npm ci

# 复制源代码
COPY . .

# 生成 Prisma Client
RUN npx prisma generate

# 构建 TypeScript → JavaScript
RUN npm run build

# ==================== 运行阶段（精简镜像）====================
FROM node:22-alpine

WORKDIR /app

# 复制依赖文件
COPY package*.json ./
COPY prisma ./prisma/

# 只安装生产依赖（体积更小）
RUN npm ci --only=production

# 生成 Prisma Client
RUN npx prisma generate

# 从构建阶段复制编译后的代码
COPY --from=builder /app/dist ./dist

# 复制配置文件
COPY prompts ./prompts
COPY config ./config

# 创建非root用户（安全）
RUN addgroup -g 1001 -S nodejs && \
    adduser -S nodejs -u 1001
USER nodejs

# 暴露端口
EXPOSE 3001

# 健康检查（SAE需要）
HEALTHCHECK --interval=30s --timeout=3s --start-period=40s --retries=3 \
  CMD node -e "require('http').get('http://localhost:3001/health', (r) => {process.exit(r.statusCode === 200 ? 0 : 1)})"

# 启动应用
CMD ["node", "dist/index.js"]
```

### 📦 1.2 创建 .dockerignore 文件

在 `backend/` 目录下创建 `.dockerignore`：

```
node_modules
dist
npm-debug.log
.env
.env.*
uploads
*.md
.git
.gitignore
tests
```

### 📦 1.3 构建Docker镜像

**打开PowerShell（管理员模式），进入backend目录：**

```powershell
# 进入后端目录
cd D:\MyCursor\AIclinicalresearch\backend

# 构建镜像（这一步需要5-10分钟）
docker build -t aiclinical-backend:dev .

# 查看镜像是否构建成功
docker images | Select-String "aiclinical-backend"
```

**预期输出：**
```
aiclinical-backend   dev    xxxx   2 minutes ago   xxx MB
```

---

## 第二步：配置阿里云服务

### 🗄️ 2.1 配置RDS数据库

#### Step 1: 登录阿里云控制台
1. 打开浏览器，访问 https://www.aliyun.com
2. 点击右上角「登录」
3. 选择「云数据库 RDS」

#### Step 2: 配置白名单
1. 点击您的RDS实例
2. 左侧菜单 → 「数据安全性」 → 「白名单设置」
3. 点击「添加白名单分组」
   - 分组名称：`SAE应用`
   - 白名单IP：先填 `0.0.0.0/0`（允许所有，测试用）
   - **⚠️ 正式上线后要改为SAE的VPC网段**

#### Step 3: 创建数据库和用户
1. 左侧菜单 → 「数据库管理」
2. 点击「创建数据库」
   - 数据库名称：`aiclinical_dev`
   - 字符集：`UTF8`
   - 点击「确定」

3. 左侧菜单 → 「账号管理」
4. 点击「创建账号」
   - 账号名称：`aiclinical`
   - 账号类型：普通账号
   - 密码：设置一个强密码（记住它！）
   - 授权数据库：选择 `aiclinical_dev`，权限「读写」
   - 点击「确定」

#### Step 4: 获取连接地址
1. 点击实例「基本信息」页面
2. 找到「内网地址」（类似：`rm-xxxx.mysql.rds.aliyuncs.com`）
3. **复制并保存这个地址**（后面会用到）

---

### 📦 2.2 配置OSS对象存储

#### Step 1: 创建Bucket
1. 阿里云控制台 → 「对象存储OSS」
2. 点击「Bucket列表」 → 「创建Bucket」
   - Bucket名称：`aiclinical-dev`（小写字母+数字+横杠）
   - 区域：选择与RDS相同的区域（如：华东1）
   - 存储类型：「标准存储」
   - 读写权限：「私有」
   - 其他选项默认
   - 点击「确定」

#### Step 2: 创建RAM用户（用于API访问）
1. 阿里云控制台 → 「访问控制RAM」
2. 左侧菜单 → 「用户」 → 「创建用户」
   - 登录名称：`aiclinical-oss`
   - 访问方式：勾选「编程访问」
   - 点击「确定」

3. 创建成功后，**立即保存显示的AccessKey**：
   ```
   AccessKeyId: LTAI5t...（复制保存）
   AccessKeySecret: xxxxxx（复制保存，只显示一次！）
   ```

4. 给用户授权：
   - 点击用户名称 → 「权限管理」 → 「添加权限」
   - 选择权限：`AliyunOSSFullAccess`
   - 点击「确定」

---

### 🐳 2.3 配置容器镜像服务（ACR）

#### Step 1: 开通服务
1. 阿里云控制台 → 「容器镜像服务」
2. 如果提示开通，点击「立即开通」（**免费**）

#### Step 2: 创建命名空间
1. 左侧菜单 → 「默认实例」 → 「命名空间」
2. 点击「创建命名空间」
   - 命名空间：`aiclinical`
   - 点击「确定」

#### Step 3: 创建镜像仓库
1. 左侧菜单 → 「镜像仓库」 → 「创建镜像仓库」
   - 仓库名称：`backend-dev`
   - 命名空间：选择 `aiclinical`
   - 摘要：`AI临床研究平台后端-开发环境`
   - 仓库类型：「私有」
   - 代码源：「本地仓库」
   - 点击「下一步」→「创建」

#### Step 4: 获取登录密码
1. 右上角点击用户头像 → 「AccessKey管理」
2. 或者：容器镜像服务 → 右上角「设置访问凭证」
3. 设置镜像仓库登录密码（记住它！）

---

### 📤 2.4 推送镜像到阿里云

**打开PowerShell，执行以下命令：**

```powershell
# 1. 登录阿里云容器镜像服务
# 替换<你的阿里云账号>为你的阿里云登录邮箱或用户名
docker login --username=<你的阿里云账号> registry.cn-hangzhou.aliyuncs.com

# 输入密码（就是刚才设置的镜像仓库登录密码）

# 2. 给镜像打标签
# 替换 <你的命名空间> 为 aiclinical
docker tag aiclinical-backend:dev `
  registry.cn-hangzhou.aliyuncs.com/aiclinical/backend-dev:v1.0.0

# 3. 推送到阿里云（需要3-5分钟）
docker push registry.cn-hangzhou.aliyuncs.com/aiclinical/backend-dev:v1.0.0
```

**推送成功标志：**
```
v1.0.0: digest: sha256:xxxx size: xxxx
```

---

## 第三步：部署到SAE

### 🚀 3.1 创建SAE应用

#### Step 1: 进入SAE控制台
1. 阿里云控制台 → 「Serverless应用引擎SAE」
2. 选择区域（与RDS、OSS相同）

#### Step 2: 创建应用
1. 点击「创建应用」
2. **基本信息**：
   - 应用名称：`aiclinical-backend-dev`
   - 命名空间：默认
   - VPC：选择与RDS相同的VPC
   - vSwitch：任意选择一个

3. **应用部署配置**：
   - 应用部署方式：「镜像」
   - 镜像来源：「容器镜像服务企业版实例」
   - 镜像：选择刚才推送的 `registry.cn-hangzhou.aliyuncs.com/aiclinical/backend-dev:v1.0.0`
   - 镜像版本：`v1.0.0`

4. **实例规格**：
   - 实例规格：`1核2GB`
   - 实例数：1个（固定）

5. **网络配置**：
   - 勾选「公网访问」
   - 端口：`3001`

6. 点击「下一步」

---

### ⚙️ 3.2 配置环境变量

在「高级设置」页面，找到「环境变量」：

```bash
# ========== 基础配置 ==========
NODE_ENV=development
PORT=3001
SERVICE_NAME=aiclinical-backend-dev
LOG_LEVEL=debug

# ========== 数据库配置 ==========
# 替换为您的RDS地址
DATABASE_URL=postgresql://aiclinical:你的密码@rm-xxxx.mysql.rds.aliyuncs.com:5432/aiclinical_dev

# ========== 存储配置 ==========
STORAGE_TYPE=oss
OSS_REGION=oss-cn-hangzhou
OSS_BUCKET=aiclinical-dev
OSS_ACCESS_KEY_ID=你的AccessKeyId
OSS_ACCESS_KEY_SECRET=你的AccessKeySecret

# ========== 缓存配置（不使用Redis）==========
CACHE_TYPE=memory
QUEUE_TYPE=memory

# ========== LLM配置 ==========
DEEPSEEK_API_KEY=你的DeepSeek API Key
DEEPSEEK_BASE_URL=https://api.deepseek.com

DASHSCOPE_API_KEY=你的通义千问 API Key

CLOSEAI_API_KEY=你的CloseAI API Key
CLOSEAI_OPENAI_BASE_URL=https://api.openai-proxy.org/v1
CLOSEAI_CLAUDE_BASE_URL=https://api.openai-proxy.org/anthropic

# ========== Dify配置（如果使用）==========
DIFY_API_KEY=你的Dify API Key
DIFY_API_URL=https://api.dify.ai/v1

# ========== 安全配置 ==========
JWT_SECRET=请生成一个随机字符串（至少32位）
CORS_ORIGIN=*

# ========== Python微服务配置 ==========
# 暂时先用公网地址，后续改为SAE内网
EXTRACTION_SERVICE_URL=http://你的Python服务地址:8000
```

**⚠️ 重要提示：**
- 替换所有 `你的XXX` 为真实的值
- JWT_SECRET 可以用在线工具生成：https://www.random.org/strings/
- 环境变量设置错误是部署失败的主要原因！

---

### ✅ 3.3 配置健康检查

在「健康检查」部分：

```yaml
检查方式: HTTP
检查路径: /health
端口: 3001
初始延迟: 30秒
检查间隔: 10秒
超时时间: 3秒
不健康阈值: 3次
健康阈值: 2次
```

点击「创建应用」，等待3-5分钟。

---

### 🎉 3.4 验证部署

#### Step 1: 查看部署状态
1. 应用列表中找到 `aiclinical-backend-dev`
2. 查看状态：
   - ❌ 启动中 → 等待
   - ❌ 异常 → 查看日志排查问题
   - ✅ 运行中 → 成功！

#### Step 2: 获取公网地址
1. 点击应用名称进入详情
2. 「基本信息」页面，找到「公网SLB地址」
3. 复制地址（类似：`http://123.456.789.0:3001`）

#### Step 3: 测试接口
打开浏览器，访问：
```
http://<你的SAE公网地址>/health
```

**预期返回：**
```json
{
  "status": "ok",
  "database": "connected",
  "timestamp": "2025-12-11T10:30:00.000Z"
}
```

---

## 第四步：部署前端

### 🌐 4.1 构建前端静态文件

**打开PowerShell，进入frontend-v2目录：**

```powershell
# 进入前端目录
cd D:\MyCursor\AIclinicalresearch\frontend-v2

# 安装依赖（如果还没安装）
npm install

# 修改 API 地址
# 打开 vite.config.ts，配置代理或直接修改 API_BASE_URL
```

**修改 `vite.config.ts`：**

```typescript
export default defineConfig({
  server: {
    proxy: {
      '/api': {
        target: 'http://你的SAE后端地址:3001',  // ← 改成你的SAE地址
        changeOrigin: true,
      },
    },
  },
  // 构建时的环境变量
  define: {
    'import.meta.env.VITE_API_BASE_URL': JSON.stringify('http://你的SAE后端地址:3001')
  }
})
```

**构建生产版本：**

```powershell
npm run build
```

构建完成后，在 `dist/` 目录生成静态文件。

---

### 🚀 4.2 部署前端到OSS

#### 方案A：使用阿里云控制台（推荐新手）

1. 打开OSS控制台
2. 进入 `aiclinical-dev` Bucket
3. 点击「文件管理」 → 「上传文件」
4. 选择 `frontend-v2/dist/` 目录下的**所有文件**
5. 上传完成后，设置 `index.html` 为默认首页

#### 方案B：使用OSS命令行工具

**安装ossutil（可选）：**
```powershell
# 下载 ossutil
# Windows: https://gosspublic.alicdn.com/ossutil/ossutil64.exe

# 配置
.\ossutil64.exe config
# 输入 AccessKeyId、AccessKeySecret、Endpoint（如 oss-cn-hangzhou.aliyuncs.com）

# 上传前端文件
.\ossutil64.exe cp -r .\dist\ oss://aiclinical-dev/frontend/ --update
```

---

### 🌐 4.3 配置OSS静态网站托管

1. OSS控制台 → `aiclinical-dev` Bucket
2. 左侧菜单 → 「基础设置」 → 「静态页面」
3. 点击「设置」：
   - 默认首页：`index.html`
   - 默认404页：`index.html`
   - 点击「保存」

4. 获取访问地址：
   - Bucket概览页面，找到「Bucket域名」
   - 外网访问地址：`http://aiclinical-dev.oss-cn-hangzhou.aliyuncs.com/`

---

## 第五步：验证部署

### ✅ 5.1 全链路测试

#### 测试1：健康检查
```
访问：http://你的SAE地址:3001/health
预期：返回 {"status":"ok"}
```

#### 测试2：数据库连接
```powershell
# 在SAE控制台 → 应用详情 → 实时日志
# 查看是否有 "✅ 数据库连接成功" 日志
```

#### 测试3：OSS存储
```
访问：http://你的SAE地址:3001/api/v1/test/upload
上传一个测试文件，查看是否成功
```

#### 测试4：前端访问
```
访问：http://aiclinical-dev.oss-cn-hangzhou.aliyuncs.com/
查看页面是否正常显示
```

---

### 📊 5.2 查看监控数据

1. SAE控制台 → 应用详情 → 「监控大盘」
2. 查看：
   - CPU使用率
   - 内存使用率
   - QPS（每秒请求数）
   - 响应时间

---

## 常见问题解决

### ❌ 问题1：应用启动失败

**症状：**
- 应用状态显示「异常」
- 健康检查失败

**解决步骤：**

1. **查看日志：**
   ```
   SAE控制台 → 应用详情 → 实时日志
   找到红色的 ERROR 日志
   ```

2. **常见错误：**

   **错误A：数据库连接失败**
   ```
   Error: Connection refused
   ```
   - 检查 `DATABASE_URL` 格式是否正确
   - 检查 RDS 白名单是否包含 SAE 的 IP
   - 检查 RDS 用户名密码是否正确

   **错误B：环境变量缺失**
   ```
   DATABASE_URL is required
   ```
   - 检查环境变量是否配置完整
   - 重新部署应用

   **错误C：Prisma 连接失败**
   ```
   Prisma Client initialization failed
   ```
   - 需要运行数据库迁移：
     ```bash
     # 本地执行迁移，然后推送到RDS
     npx prisma migrate deploy
     ```

---

### ❌ 问题2：OSS上传失败

**症状：**
- 文件上传返回 403 Forbidden

**解决步骤：**

1. 检查 RAM 用户权限：
   - 控制台 → RAM → 用户 → 权限
   - 确保有 `AliyunOSSFullAccess`

2. 检查环境变量：
   ```bash
   OSS_ACCESS_KEY_ID=正确的ID
   OSS_ACCESS_KEY_SECRET=正确的Secret
   OSS_BUCKET=正确的Bucket名称
   ```

3. 测试 OSS 连接：
   ```javascript
   // 在应用日志中查看
   console.log('OSS配置:', {
     region: process.env.OSS_REGION,
     bucket: process.env.OSS_BUCKET
   })
   ```

---

### ❌ 问题3：前端无法访问后端

**症状：**
- 前端显示「网络错误」
- API 请求失败

**解决步骤：**

1. 检查CORS配置：
   ```bash
   # 在SAE环境变量中确认
   CORS_ORIGIN=*  # 允许所有来源（开发环境）
   ```

2. 检查后端地址：
   ```javascript
   // frontend-v2/vite.config.ts
   proxy: {
     '/api': {
       target: 'http://正确的SAE地址:3001',
       changeOrigin: true
     }
   }
   ```

3. 测试后端连通性：
   ```bash
   # 在本地PowerShell执行
   curl http://你的SAE地址:3001/health
   ```

---

### ❌ 问题4：Python微服务无法连接

**症状：**
- 文件提取失败
- 日志显示 `Connection refused to extraction service`

**临时方案：**

目前Python微服务还在本地运行，需要以下两种方案之一：

**方案A：Python服务也部署到SAE（推荐）**

1. 创建 `extraction_service/Dockerfile`：
   ```dockerfile
   FROM python:3.10-slim
   
   WORKDIR /app
   
   COPY requirements.txt .
   RUN pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
   
   COPY . .
   
   EXPOSE 8000
   
   CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]
   ```

2. 构建并推送：
   ```powershell
   cd extraction_service
   docker build -t aiclinical-python:dev .
   docker tag aiclinical-python:dev `
     registry.cn-hangzhou.aliyuncs.com/aiclinical/python-dev:v1.0.0
   docker push registry.cn-hangzhou.aliyuncs.com/aiclinical/python-dev:v1.0.0
   ```

3. 在SAE创建新应用 `aiclinical-python-dev`

4. 修改Node后端环境变量：
   ```bash
   EXTRACTION_SERVICE_URL=http://python服务的SAE内网地址:8000
   ```

**方案B：使用内网穿透（临时开发）**

1. 使用ngrok或frp等工具
2. 将本地8000端口暴露到公网
3. 修改环境变量为公网地址

---

## 📊 部署完成检查清单

### ✅ 后端部署

- [ ] Docker镜像构建成功
- [ ] 镜像推送到阿里云ACR
- [ ] RDS数据库配置完成
- [ ] RDS白名单已添加
- [ ] OSS Bucket创建完成
- [ ] RAM用户权限配置正确
- [ ] SAE应用创建成功
- [ ] 环境变量配置完整
- [ ] 健康检查通过
- [ ] `/health` 接口返回正常

### ✅ 前端部署

- [ ] 前端代码构建成功
- [ ] API地址配置正确
- [ ] 文件上传到OSS
- [ ] 静态网站托管开启
- [ ] 前端页面可访问
- [ ] 前后端通信正常

### ✅ 数据库

- [ ] 数据库迁移执行成功
- [ ] Schema创建完成
- [ ] 测试数据插入成功

---

## 🎉 恭喜！部署完成！

### 📝 记录重要信息

请将以下信息保存到安全的地方：

```
【开发测试环境】

后端地址：http://你的SAE地址:3001
前端地址：http://aiclinical-dev.oss-cn-hangzhou.aliyuncs.com

RDS连接信息：
- 地址：rm-xxxx.mysql.rds.aliyuncs.com
- 数据库：aiclinical_dev
- 用户名：aiclinical
- 密码：***（请保密）

OSS信息：
- Bucket：aiclinical-dev
- AccessKeyId：LTAI5t***
- AccessKeySecret：***（请保密）

ACR镜像仓库：
- 命名空间：aiclinical
- 仓库：backend-dev, python-dev
- 登录密码：***（请保密）
```

---

## 📚 下一步

1. **持续集成/持续部署（CI/CD）**
   - 配置GitHub Actions或Jenkins
   - 自动构建和部署

2. **监控告警**
   - 开通阿里云ARMS监控
   - 配置钉钉/邮件告警

3. **正式环境部署**
   - 创建生产环境Bucket：`aiclinical-prod`
   - 创建生产环境RDS：独立实例
   - 创建生产环境SAE应用
   - 购买Redis：用于生产环境缓存
   - 配置CDN：加速静态资源

4. **域名配置**
   - 购买域名
   - 配置DNS解析
   - 申请SSL证书
   - 配置HTTPS

---

## 💡 成本优化建议

### 开发测试环境（当前配置）

| 服务 | 规格 | 月费 | 说明 |
|------|------|------|------|
| SAE | 1C2G × 1实例 | ¥150 | 按量付费 |
| RDS | 2C4G 通用版 | ¥300 | 包年更优惠 |
| OSS | 100GB存储 | ¥10 | 按实际使用 |
| ACR | 免费额度 | ¥0 | 无需付费 |
| **合计** | | **¥460/月** | |

### 节省成本技巧

1. **RDS包年优惠**：购买1年可节省15%
2. **闲时关闭SAE**：测试环境夜间可关闭，节省50%
3. **OSS生命周期**：设置90天后转低频存储
4. **不使用Redis**：省¥200/月

---

**文档版本：** v1.0  
**最后更新：** 2025-12-11  
**维护者：** 技术架构师  
**反馈：** 如有问题，请联系技术团队