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

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

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

---

📋 目录

1. 前置准备
2. 需不需要购买Redis
3. 第一步：准备Docker镜像
4. 第二步：配置阿里云服务
5. 第三步：部署到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/月）

环境变量配置：

# 不使用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（如果不存在）：

# ==================== 构建阶段 ====================
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目录：

# 进入后端目录
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，执行以下命令：

# 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 配置环境变量

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

# ========== 基础配置 ==========
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 配置健康检查

在「健康检查」部分：

检查方式: 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

预期返回：

{
  "status": "ok",
  "database": "connected",
  "timestamp": "2025-12-11T10:30:00.000Z"
}

---

第四步：部署前端

🌐 4.1 构建前端静态文件

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

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

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

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

修改 vite.config.ts：

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')
  }
})

构建生产版本：

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（可选）：

# 下载 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：数据库连接

# 在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
   

   • 需要运行数据库迁移：

     # 本地执行迁移，然后推送到RDS
     npx prisma migrate deploy
     

---

❌ 问题2：OSS上传失败

症状：

• 文件上传返回 403 Forbidden

解决步骤：

1. 检查 RAM 用户权限：

   • 控制台 → RAM → 用户 → 权限
   • 确保有 AliyunOSSFullAccess

2. 检查环境变量：

   OSS_ACCESS_KEY_ID=正确的ID
   OSS_ACCESS_KEY_SECRET=正确的Secret
   OSS_BUCKET=正确的Bucket名称
   

3. 测试 OSS 连接：

   // 在应用日志中查看
   console.log('OSS配置:', {
     region: process.env.OSS_REGION,
     bucket: process.env.OSS_BUCKET
   })
   

---

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

症状：

• 前端显示「网络错误」
• API 请求失败

解决步骤：

1. 检查CORS配置：

   # 在SAE环境变量中确认
   CORS_ORIGIN=*  # 允许所有来源（开发环境）
   

2. 检查后端地址：

   // frontend-v2/vite.config.ts
   proxy: {
     '/api': {
       target: 'http://正确的SAE地址:3001',
       changeOrigin: true
     }
   }
   

3. 测试后端连通性：

   # 在本地PowerShell执行
   curl http://你的SAE地址:3001/health
   

---

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

症状：

• 文件提取失败
• 日志显示 Connection refused to extraction service

临时方案：

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

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

1. 创建 extraction_service/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. 构建并推送：

   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后端环境变量：

   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
维护者： 技术架构师
反馈： 如有问题，请联系技术团队