# 🚀 阿里云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�?* | ⚠️ 建议购买 | 提升性能，�?00/�?|
| **成熟期用�?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

# 构建镜像（这一步需�?-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. 推送到阿里云（需�?-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�?GB`
   - 实例数：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=请生成一个随机字符串（至�?2位）
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. 将本�?000端口暴露到公�?
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包年优惠**：购�?年可节省15%
2. **闲时关闭SAE**：测试环境夜间可关闭，节�?0%
3. **OSS生命周期**：设�?0天后转低频存�?
4. **不使用Redis**：省¥200/�?

---

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