Files

HaHafeng 9c96f75c52 feat(storage): integrate Alibaba Cloud OSS for file persistence - Add OSSAdapter and LocalAdapter with StorageFactory pattern - Integrate PKB module with OSS upload - Rename difyDocumentId to storageKey - Create 4 OSS buckets and development specification

2026-01-22 22:02:20 +08:00

20 KiB

Raw Blame History

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

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

前置准备

✅ 您已经购买的服务

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

💻 您需要安装的工具

Docker Desktop
- 下载地址：https://www.docker.com/products/docker-desktop/
- Windows系统选择 "Docker Desktop for Windows"
- 安装后重启电脑
阿里云CLI（可选）
- 如果不想用命令行，可以全程使用阿里云控制台网页操作

需不需要购买Redis？

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

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

🎯 我的建议

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

原因：

✅ 您的代码已经支持 CACHE_TYPE=memory（内存缓存）
✅ 开发测试阶段，内存缓存完全够用
✅ 等真正上线后，根据实际情况再决定
✅ 节省成本（初期省¥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: 登录阿里云控制台

打开浏览器，访问 https://www.aliyun.com
点击右上角「登录」
选择「云数据库 RDS」

Step 2: 配置白名单

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

Step 3: 创建数据库和用户

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

Step 4: 获取连接地址

点击实例「基本信息」页面
找到「内网地址」（类似：rm-xxxx.mysql.rds.aliyuncs.com）
复制并保存这个地址（后面会用到）

📦 2.2 配置OSS对象存储

Step 1: 创建Bucket

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

Step 2: 创建RAM用户（用于API访问）

阿里云控制台 → 「访问控制RAM」
左侧菜单 → 「用户」 → 「创建用户」
- 登录名称：aiclinical-oss
- 访问方式：勾选「编程访问」
- 点击「确定」

创建成功后，立即保存显示的AccessKey：

AccessKeyId: LTAI5t...（复制保存）
AccessKeySecret: xxxxxx（复制保存，只显示一次！）

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

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

Step 1: 开通服务

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

Step 2: 创建命名空间

左侧菜单 → 「默认实例」 → 「命名空间」
点击「创建命名空间」
- 命名空间：aiclinical
- 点击「确定」

Step 3: 创建镜像仓库

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

Step 4: 获取登录密码

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

📤 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控制台

阿里云控制台 → 「Serverless应用引擎SAE」
选择区域（与RDS、OSS相同）

Step 2: 创建应用

点击「创建应用」
基本信息：
- 应用名称：aiclinical-backend-dev
- 命名空间：默认
- VPC：选择与RDS相同的VPC
- vSwitch：任意选择一个
应用部署配置：
- 应用部署方式：「镜像」
- 镜像来源：「容器镜像服务企业版实例」
- 镜像：选择刚才推送的 registry.cn-hangzhou.aliyuncs.com/aiclinical/backend-dev:v1.0.0
- 镜像版本：v1.0.0
实例规格：
- 实例规格：1核2GB
- 实例数：1个（固定）
网络配置：
- 勾选「公网访问」
- 端口：3001
点击「下一步」

⚙️ 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: 查看部署状态

应用列表中找到 aiclinical-backend-dev
查看状态：
- ❌ 启动中 → 等待
- ❌ 异常 → 查看日志排查问题
- ✅ 运行中 → 成功！

Step 2: 获取公网地址

点击应用名称进入详情
「基本信息」页面，找到「公网SLB地址」
复制地址（类似：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：使用阿里云控制台（推荐新手）

打开OSS控制台
进入 aiclinical-dev Bucket
点击「文件管理」 → 「上传文件」
选择 frontend-v2/dist/ 目录下的所有文件
上传完成后，设置 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静态网站托管

OSS控制台 → aiclinical-dev Bucket
左侧菜单 → 「基础设置」 → 「静态页面」
点击「设置」：
- 默认首页：index.html
- 默认404页：index.html
- 点击「保存」
获取访问地址：
- 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 查看监控数据

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

常见问题解决

❌ 问题1：应用启动失败

症状：

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

解决步骤：

查看日志：

SAE控制台 → 应用详情 → 实时日志
找到红色的 ERROR 日志

常见错误：

错误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

解决步骤：

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

检查环境变量：

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

测试 OSS 连接：

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

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

症状：

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

解决步骤：

检查CORS配置：

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

检查后端地址：

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

测试后端连通性：

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

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

症状：

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

临时方案：

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

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

创建 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"]

构建并推送：

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

在SAE创建新应用 aiclinical-python-dev

修改Node后端环境变量：

EXTRACTION_SERVICE_URL=http://python服务的SAE内网地址:8000

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

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

📊 部署完成检查清单

✅ 后端部署

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
- 登录密码：***（请保密）

📚 下一步

持续集成/持续部署（CI/CD）
- 配置GitHub Actions或Jenkins
- 自动构建和部署
监控告警
- 开通阿里云ARMS监控
- 配置钉钉/邮件告警
正式环境部署
- 创建生产环境Bucket：aiclinical-prod
- 创建生产环境RDS：独立实例
- 创建生产环境SAE应用
- 购买Redis：用于生产环境缓存
- 配置CDN：加速静态资源
域名配置
- 购买域名
- 配置DNS解析
- 申请SSL证书
- 配置HTTPS

💡 成本优化建议

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

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

节省成本技巧

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

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

20 KiB Raw Blame History Unescape Escape

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

📋 目录

前置准备

✅ 您已经购买的服务

💻 您需要安装的工具

需不需要购买Redis？

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

🎯 我的建议

第一步：准备Docker镜像

📦 1.1 创建Dockerfile文件

📦 1.2 创建 .dockerignore 文件

📦 1.3 构建Docker镜像

第二步：配置阿里云服务

🗄️ 2.1 配置RDS数据库

Step 1: 登录阿里云控制台

Step 2: 配置白名单

Step 3: 创建数据库和用户

Step 4: 获取连接地址

📦 2.2 配置OSS对象存储

Step 1: 创建Bucket

Step 2: 创建RAM用户（用于API访问）

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

Step 1: 开通服务

Step 2: 创建命名空间

Step 3: 创建镜像仓库

Step 4: 获取登录密码

📤 2.4 推送镜像到阿里云

第三步：部署到SAE

🚀 3.1 创建SAE应用

Step 1: 进入SAE控制台

Step 2: 创建应用

⚙️ 3.2 配置环境变量

✅ 3.3 配置健康检查

🎉 3.4 验证部署

Step 1: 查看部署状态

Step 2: 获取公网地址

Step 3: 测试接口

第四步：部署前端

🌐 4.1 构建前端静态文件

🚀 4.2 部署前端到OSS

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

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

🌐 4.3 配置OSS静态网站托管

第五步：验证部署

✅ 5.1 全链路测试

测试1：健康检查

测试2：数据库连接

测试3：OSS存储

测试4：前端访问

📊 5.2 查看监控数据

常见问题解决

❌ 问题1：应用启动失败

❌ 问题2：OSS上传失败

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

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

📊 部署完成检查清单

✅ 后端部署

✅ 前端部署

✅ 数据库

🎉 恭喜！部署完成！

📝 记录重要信息

📚 下一步

💡 成本优化建议

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

节省成本技巧

20 KiB

Raw Blame History