AIclinicalresearch/docs/05-部署文档/08-部署检查清单.md

# 部署检查清单 - 从0到上线的完整Checklist

> **文档版本：** v1.0  
> **创建日期：** 2025-12-14  
> **适用场景：** 首次部署到阿里云生产环境  
> **预计时间：** 4-5小时（实际操作时间）

---

## 📋 使用说明

本清单按照部署顺序列出所有必需步骤，每个步骤包含：
- ☐ 复选框（完成后打勾）
- ⏱️ 预计时间
- ⚠️ 关键注意事项
- 🔗 参考文档链接

**建议：打印或复制到笔记软件，逐项完成。**

---

## 阶段1：基础设施准备（Day 1上午）

### 1.1 阿里云账号准备

☐ **实名认证**
- ⏱️ 5分钟
- 阿里云控制台 > 账号管理 > 实名认证
- ⚠️ 企业认证需要营业执照

☐ **账号充值**
- ⏱️ 2分钟
- 建议充值：¥500（首月成本约¥1,200）
- 费用中心 > 充值

☐ **开通服务**
- ⏱️ 5分钟
- 需要开通的服务：
  - ✅ SAE（Serverless应用引擎）
  - ✅ RDS（云数据库）
  - ✅ OSS（对象存储）
  - ✅ VPC（专有网络）
  - ✅ NAT网关
  - ✅ ACR（容器镜像服务）
  - ✅ ECS（云服务器，Dify用）

☐ **创建RAM子账号（可选但推荐）**
- ⏱️ 10分钟
- RAM访问控制 > 用户 > 创建用户
- 权限：AliyunSAEFullAccess, AliyunRDSFullAccess, AliyunOSSFullAccess
- ⚠️ 不要用主账号部署，安全风险大

---

### 1.2 VPC网络配置 ⭐⭐⭐⭐⭐

☐ **创建VPC**
- ⏱️ 5分钟
- VPC控制台 > 创建VPC
- 名称：aiclinical-vpc-prod
- 网段：172.16.0.0/12
- 地域：cn-hangzhou（杭州）或就近地域

☐ **创建交换机**
- ⏱️ 3分钟
- VPC详情 > 交换机 > 创建交换机
- 名称：aiclinical-vsw-prod
- 可用区：随机可用区A
- 网段：172.16.0.0/20

☐ **⭐ 创建NAT网关（必需！）**
- ⏱️ 15分钟
- VPC控制台 > NAT网关 > 创建NAT网关
- VPC：aiclinical-vpc-prod
- 交换机：aiclinical-vsw-prod
- 规格：小型
- 计费方式：按使用量计费
- ⚠️ **没有NAT网关，所有AI功能都会超时！**
- 🔗 参考：`07-关键配置补充说明.md` 第1节

☐ **创建并绑定EIP**
- ⏱️ 5分钟
- NAT网关详情 > 弹性公网IP > 绑定EIP
- 创建新EIP
- 带宽：按使用流量
- 记录EIP地址：________________

☐ **配置SNAT条目**
- ⏱️ 3分钟
- NAT网关详情 > SNAT管理 > 创建SNAT条目
- 交换机：aiclinical-vsw-prod
- 公网IP：刚才创建的EIP
- ⚠️ 这一步让SAE可以访问公网

☐ **创建安全组**
- ⏱️ 5分钟
- ECS控制台 > 安全组 > 创建安全组
- 名称：aiclinical-sg-prod
- VPC：aiclinical-vpc-prod
- 入方向规则：
  - 允许 80/TCP 来源：172.16.0.0/12（VPC内网）
  - 允许 22/TCP 来源：您的办公室IP（SSH管理）
  - 拒绝 所有 来源：0.0.0.0/0

---

### 1.3 RDS PostgreSQL 15 部署

☐ **创建RDS实例**
- ⏱️ 10分钟（等待创建15分钟）
- RDS控制台 > 创建实例
- 数据库类型：PostgreSQL
- 版本：15
- 规格：rds.pg.s2.large（2核4GB）
- 存储：100GB SSD
- VPC：aiclinical-vpc-prod
- 交换机：aiclinical-vsw-prod
- 记录内网地址：rm-____________.pg.rds.aliyuncs.com

☐ **配置白名单**
- ⏱️ 2分钟
- RDS实例详情 > 数据安全性 > 白名单设置
- 添加白名单分组：sae-vpc
- IP地址：172.16.0.0/12（VPC网段）
- ⚠️ **必须用VPC网段，不能用单机IP！**
- 🔗 参考：`PostgreSQL部署策略-摸底报告.md`

☐ **创建数据库账号**
- ⏱️ 3分钟
- RDS实例详情 > 账号管理 > 创建账号
- 账号名：aiclinical_rw
- 密码：（16位强密码，记录到密码管理器）
- 账号类型：普通账号
- 授权数据库：稍后创建

☐ **创建数据库**
- ⏱️ 2分钟
- RDS实例详情 > 数据库管理 > 创建数据库
- 数据库名：ai_clinical_research
- 字符集：UTF8
- 授权账号：aiclinical_rw（读写）

☐ **配置自动备份**
- ⏱️ 3分钟
- RDS实例详情 > 备份恢复 > 备份设置
- 数据备份保留：7天
- 日志备份保留：7天（⚠️ 必须开启，支持PITR）
- 备份周期：每天
- 备份时间：02:00-04:00（凌晨）

☐ **导入数据库（pg_dump）**
- ⏱️ 5分钟
- 本地执行：
  ```bash
  # 1. 导出本地数据库
  docker exec ai-clinical-postgres pg_dump -U postgres -d ai_clinical_research \
    --format=plain --no-owner --no-acl --encoding=UTF8 \
    > backup_$(date +%Y%m%d_%H%M%S).sql
  
  # 2. 导入到RDS（需要ECS跳板机或临时开启公网）
  psql -h rm-xxxxx.pg.rds.aliyuncs.com \
       -p 5432 \
       -U aiclinical_rw \
       -d ai_clinical_research \
       -f backup_20251214_100000.sql
  ```
- 🔗 参考：`PostgreSQL部署策略-摸底报告.md` 第4节

☐ **验证数据库导入**
- ⏱️ 3分钟
- 连接RDS，执行：
  ```sql
  -- 验证Schema
  \dn
  -- 应该看到10个Schema
  
  -- 验证表数量
  SELECT schemaname, COUNT(*) 
  FROM pg_tables 
  WHERE schemaname NOT IN ('pg_catalog', 'information_schema') 
  GROUP BY schemaname;
  -- platform_schema: 8, aia_schema: 5, pkb_schema: 5, asl_schema: 6, dc_schema: 6
  
  -- 验证数据
  SELECT COUNT(*) FROM platform_schema.users;
  -- 应该有3条（或你的实际数量）
  ```

---

### 1.4 OSS对象存储配置

☐ **创建OSS Bucket**
- ⏱️ 5分钟
- OSS控制台 > Bucket列表 > 创建Bucket
- Bucket名称：aiclinical-data-prod
- 地域：cn-hangzhou（与VPC同地域）
- 读写权限：私有（Private）⚠️ 必须私有
- 版本控制：关闭
- 服务端加密：关闭（可选）

☐ **配置生命周期规则（可选）**
- ⏱️ 3分钟
- Bucket详情 > 基础设置 > 生命周期
- 规则名称：delete-temp-files
- 应用范围：uploads/temp/
- 操作：删除
- 天数：30天（临时文件30天后自动删除）

☐ **创建RAM角色（推荐）**
- ⏱️ 10分钟
- RAM访问控制 > 角色 > 创建角色
- 角色类型：普通服务角色
- 受信服务：SAE
- 角色名称：AliyunSAEDefaultRole
- 权限策略：AliyunOSSFullAccess
- ⚠️ 使用RAM角色比AccessKey更安全

☐ **记录OSS配置信息**
- Bucket名称：aiclinical-data-prod
- 地域：cn-hangzhou
- 内网Endpoint：oss-cn-hangzhou-internal.aliyuncs.com
- AccessKey ID：（如果不用RAM角色）
- AccessKey Secret：（如果不用RAM角色）

---

### 1.5 ACR容器镜像仓库配置

☐ **创建命名空间**
- ⏱️ 3分钟
- 容器镜像服务 > 命名空间 > 创建命名空间
- 命名空间：aiclinical
- 类型：私有

☐ **配置访问凭证**
- ⏱️ 2分钟
- 容器镜像服务 > 访问凭证 > 设置固定密码
- 用户名：（阿里云账号）
- 密码：（设置一个强密码）
- 记录登录命令：
  ```bash
  docker login --username=your-account registry.cn-hangzhou.aliyuncs.com
  ```

---

## 阶段2：核心服务部署（Day 1下午）

### 2.1 Node.js后端部署

☐ **本地代码准备**
- ⏱️ 10分钟
- 确保代码最新：`git pull origin main`
- 安装依赖：`cd backend && npm install`
- 编译代码：`npm run build`
- 验证编译：`ls dist/` 应该有编译后的JS文件

☐ **Prisma反向同步（重要）**
- ⏱️ 5分钟
- 连接RDS，执行：
  ```bash
  cd backend
  # 修改 .env 为RDS连接
  DATABASE_URL=postgresql://aiclinical_rw:password@rm-xxxxx.pg.rds.aliyuncs.com:5432/ai_clinical_research
  
  # 反向同步
  npx prisma db pull
  
  # 生成Prisma Client
  npx prisma generate
  ```
- 🔗 参考：`05-Node.js后端-SAE容器部署指南.md` 第4节

☐ **修改HTTP Client超时配置**
- ⏱️ 5分钟
- 编辑 `backend/src/common/http/httpClient.ts`
- 设置timeout: 120000（120秒）
- 🔗 参考：`07-关键配置补充说明.md` 第3节

☐ **修改Dify Client容错处理**
- ⏱️ 5分钟
- 编辑 `backend/src/common/rag/DifyClient.ts`
- 添加临时Key容错逻辑
- 🔗 参考：`07-关键配置补充说明.md` 第2节

☐ **构建Docker镜像**
- ⏱️ 5分钟
- ```bash
  cd backend
  docker build -t backend:v1.0.0 .
  ```
- 验证镜像：`docker images | grep backend`

☐ **本地测试镜像**
- ⏱️ 5分钟
- ```bash
  docker run -p 3001:3001 \
    -e DATABASE_URL="postgresql://..." \
    -e NODE_ENV=production \
    backend:v1.0.0
  ```
- 测试健康检查：`curl http://localhost:3001/health`

☐ **推送到ACR**
- ⏱️ 3分钟
- ```bash
  docker tag backend:v1.0.0 registry.cn-hangzhou.aliyuncs.com/aiclinical/backend:v1.0.0
  docker push registry.cn-hangzhou.aliyuncs.com/aiclinical/backend:v1.0.0
  ```

☐ **创建SAE应用**
- ⏱️ 10分钟
- SAE控制台 > 应用列表 > 创建应用
- 应用名称：aiclinical-backend
- 部署方式：容器镜像
- 镜像地址：registry.cn-hangzhou.aliyuncs.com/aiclinical/backend:v1.0.0
- VPC：aiclinical-vpc-prod
- 交换机：aiclinical-vsw-prod
- 实例规格：1核2GB
- 实例数量：最小2，最大10
- 健康检查：HTTP /health

☐ **配置环境变量（关键）**
- ⏱️ 10分钟
- SAE应用详情 > 环境变量
- 必需变量：
  ```bash
  # 数据库
  DATABASE_URL=postgresql://aiclinical_rw:password@rm-xxxxx.pg.rds.aliyuncs.com:5432/ai_clinical_research?connection_limit=10&pool_timeout=10
  
  # OSS
  STORAGE_TYPE=oss
  OSS_REGION=cn-hangzhou
  OSS_BUCKET=aiclinical-data-prod
  OSS_ACCESS_KEY_ID=LTAI5***
  OSS_ACCESS_KEY_SECRET=***
  
  # 缓存/队列（Postgres-Only）
  CACHE_TYPE=postgres
  QUEUE_TYPE=pgboss
  
  # Dify（⚠️ 临时值）
  DIFY_API_URL=http://172.16.x.x/v1
  DIFY_API_KEY=temp_placeholder_will_update_later
  
  # Python微服务（稍后填写）
  EXTRACTION_SERVICE_URL=http://172.16.x.x:8000  # ⚠️ 使用Python服务的内网IP（从SAE控制台获取）
  
  # LLM API
  DEEPSEEK_API_KEY=sk-***
  
  # 其他
  NODE_ENV=production
  PORT=3001
  JWT_SECRET=（生成一个强密钥）
  ```

☐ **部署应用**
- ⏱️ 5分钟（等待部署10分钟）
- SAE控制台 > 部署
- 等待实例启动
- 查看日志：应该看到"数据库连接成功"

☐ **验证后端服务**
- ⏱️ 3分钟
- ```bash
  # 健康检查
  curl http://aiclinical-backend.sae:3001/health
  # 应该返回 200 OK
  
  # 测试用户注册
  curl -X POST http://aiclinical-backend.sae:3001/api/v1/auth/register \
    -H "Content-Type: application/json" \
    -d '{"email":"test@example.com","password":"Test123456","name":"测试用户"}'
  # 应该返回 200 OK
  ```

---

### 2.2 Python微服务部署

☐ **本地代码准备**
- ⏱️ 5分钟
- `cd extraction_service`
- 确保requirements.txt正确

☐ **修改Dockerfile（Workers限制）**
- ⏱️ 2分钟
- 编辑 `extraction_service/Dockerfile`
- CMD设置workers=2
- 🔗 参考：`07-关键配置补充说明.md` 第6节

☐ **构建Docker镜像**
- ⏱️ 10分钟（Python镜像较大）
- ```bash
  cd extraction_service
  docker build -t python-service:v1.0.0 .
  ```

☐ **本地测试镜像**
- ⏱️ 5分钟
- ```bash
  docker run -p 8000:8000 python-service:v1.0.0
  curl http://localhost:8000/health
  ```

☐ **推送到ACR**
- ⏱️ 5分钟
- ```bash
  docker tag python-service:v1.0.0 registry.cn-hangzhou.aliyuncs.com/aiclinical/python-service:v1.0.0
  docker push registry.cn-hangzhou.aliyuncs.com/aiclinical/python-service:v1.0.0
  ```

☐ **创建SAE应用**
- ⏱️ 10分钟
- 应用名称：aiclinical-python-service
- 镜像：registry.cn-hangzhou.aliyuncs.com/aiclinical/python-service:v1.0.0
- 实例规格：1核2GB（⚠️ 不要低于2GB）
- 实例数量：最小1，最大3

☐ **配置环境变量**
- ⏱️ 3分钟
- ```bash
  OSS_REGION=cn-hangzhou
  OSS_BUCKET=aiclinical-data-prod
  OSS_ACCESS_KEY_ID=***
  OSS_ACCESS_KEY_SECRET=***
  ```

☐ **部署并验证**
- ⏱️ 5分钟
- 部署应用
- 测试：`curl http://172.16.x.x:8000/health`（使用实际内网IP）

---

### 2.3 前端部署

☐ **本地代码准备**
- ⏱️ 10分钟
- `cd frontend-v2`
- `npm install`
- `npm run build`

☐ **修改nginx.conf（文件大小限制）**
- ⏱️ 2分钟
- 编辑 `frontend-v2/nginx.conf.template`
- 添加 `client_max_body_size 50M;`
- 🔗 参考：`07-关键配置补充说明.md` 第5节

☐ **构建Docker镜像**
- ⏱️ 5分钟
- ```bash
  cd frontend-v2
  docker build -t frontend:v1.0.0 .
  ```

☐ **推送到ACR**
- ⏱️ 3分钟
- ```bash
  docker tag frontend:v1.0.0 registry.cn-hangzhou.aliyuncs.com/aiclinical/frontend:v1.0.0
  docker push registry.cn-hangzhou.aliyuncs.com/aiclinical/frontend:v1.0.0
  ```

☐ **创建SAE应用**
- ⏱️ 10分钟
- 应用名称：aiclinical-frontend
- 镜像：registry.cn-hangzhou.aliyuncs.com/aiclinical/frontend:v1.0.0
- 实例规格：0.5核1GB
- 实例数量：1

☐ **配置环境变量**
- ⏱️ 2分钟
- ```bash
  BACKEND_SERVICE_HOST=aiclinical-backend.sae
  BACKEND_SERVICE_PORT=3001
  ```

☐ **部署并验证**
- ⏱️ 5分钟
- 部署应用
- 浏览器访问：http://前端公网地址
- 应该看到登录页面

---

## 阶段3：Dify服务部署（Day 2上午）

### 3.1 ECS服务器准备

☐ **创建ECS实例**
- ⏱️ 10分钟（等待创建5分钟）
- ECS控制台 > 创建实例
- 实例规格：ecs.c6.xlarge（4核8GB）
- 镜像：Ubuntu 22.04
- VPC：aiclinical-vpc-prod
- 交换机：aiclinical-vsw-prod
- 安全组：aiclinical-sg-prod
- 公网IP：分配（用于管理和Dify访问）
- 记录公网IP：________________

☐ **SSH登录ECS**
- ⏱️ 2分钟
- ```bash
  ssh root@ECS公网IP
  ```

☐ **安装Docker**
- ⏱️ 5分钟
- ```bash
  curl -fsSL https://get.docker.com | bash
  systemctl start docker
  systemctl enable docker
  docker --version
  ```

☐ **安装Docker Compose**
- ⏱️ 3分钟
- ```bash
  curl -L "https://github.com/docker/compose/releases/download/v2.20.0/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
  chmod +x /usr/local/bin/docker-compose
  docker-compose --version
  ```

☐ **配置Swap（防止OOM）**
- ⏱️ 5分钟
- ```bash
  fallocate -l 4G /swapfile
  chmod 600 /swapfile
  mkswap /swapfile
  swapon /swapfile
  echo '/swapfile none swap sw 0 0' >> /etc/fstab
  swapon --show
  ```
- 🔗 参考：`03-Dify-ECS部署完全指南.md` 第4节

---

### 3.2 Dify部署

☐ **下载Dify**
- ⏱️ 5分钟
- ```bash
  cd /opt
  git clone https://github.com/langgenius/dify.git
  cd dify/docker
  ```

☐ **修改docker-compose.yaml（端口安全）**
- ⏱️ 5分钟
- 编辑 `docker-compose.yaml`
- Redis端口：`127.0.0.1:6379:6379`
- Weaviate端口：`127.0.0.1:8080:8080`
- ⚠️ 只有Nginx对外（80端口）
- 🔗 参考：`07-关键配置补充说明.md` 第4节

☐ **配置.env文件**
- ⏱️ 10分钟
- ```bash
  cp .env.example .env
  vi .env
  ```
- 关键配置：
  ```bash
  # Redis
  REDIS_HOST=redis
  REDIS_PORT=6379
  
  # PostgreSQL
  DB_HOST=db
  DB_PORT=5432
  DB_DATABASE=dify
  DB_USERNAME=postgres
  DB_PASSWORD=（生成强密码）
  
  # Weaviate
  WEAVIATE_ENDPOINT=http://weaviate:8080
  
  # 其他
  SECRET_KEY=（生成强密钥）
  ```

☐ **启动Dify**
- ⏱️ 10分钟（首次启动需要拉取镜像）
- ```bash
  docker-compose up -d
  docker-compose logs -f
  # 等待所有服务启动（约2-3分钟）
  ```

☐ **验证Dify服务**
- ⏱️ 3分钟
- 浏览器访问：http://ECS公网IP
- 应该看到Dify欢迎页面

---

### 3.3 Dify配置

☐ **注册管理员账号**
- ⏱️ 2分钟
- 首次访问会提示注册
- 邮箱：admin@your-company.com
- 密码：（强密码）

☐ **创建API Key**
- ⏱️ 3分钟
- 登录Dify
- 设置 > API密钥 > 创建密钥
- 名称：Backend Service
- 复制API Key：app-xxxxxxxxxxxxxxxxxxxxx
- ⚠️ 妥善保存，只显示一次

☐ **更新后端环境变量**
- ⏱️ 5分钟
- SAE控制台 > aiclinical-backend > 环境变量
- 修改：
  ```bash
  DIFY_API_URL=http://172.16.x.x/v1  # ECS内网IP
  DIFY_API_KEY=app-xxxxxxxxxxxxxxxxxxxxx  # 真实Key
  ```
- 保存 > 重启应用

☐ **测试PKB功能**
- ⏱️ 5分钟
- ```bash
  # 创建知识库
  curl -X POST http://前端地址/api/v1/pkb/knowledge-bases \
    -H "Authorization: Bearer USER_TOKEN" \
    -d '{"name":"测试知识库"}'
  # 应该返回 200 OK
  ```

---

## 阶段4：端到端测试（Day 2下午）

### 4.1 功能测试

☐ **用户注册/登录**
- ⏱️ 5分钟
- 前端注册新用户
- 登录成功

☐ **AI对话（AIA模块）**
- ⏱️ 5分钟
- 创建项目
- 发起对话
- 验证DeepSeek API调用成功

☐ **知识库（PKB模块）**
- ⏱️ 10分钟
- 创建知识库
- 上传PDF文档
- 验证Dify处理成功

☐ **文献筛选（ASL模块）**
- ⏱️ 10分钟
- 创建筛选项目
- 上传PDF
- 验证Python服务解析成功

☐ **数据清洗（DC模块）**
- ⏱️ 10分钟
- 上传Excel
- 执行清洗
- 验证Polars处理成功

---

### 4.2 性能测试

☐ **响应时间**
- ⏱️ 10分钟
- API响应时间 < 2秒
- 页面加载时间 < 3秒

☐ **并发测试**
- ⏱️ 10分钟
- 使用Apache Bench或JMeter
- 模拟10个并发用户
- 验证无错误

---

### 4.3 监控配置

☐ **配置日志收集**
- ⏱️ 10分钟
- SAE自动收集stdout/stderr
- 验证日志可查看

☐ **配置告警规则**
- ⏱️ 15分钟
- 云监控 > 告警规则
- CPU > 70%
- 内存 > 80%
- 错误日志 > 10条/分钟

---

## 阶段5：优化与文档（Day 3）

### 5.1 可选优化

☐ **配置SSH隧道（开发便利）**
- ⏱️ 10分钟
- 🔗 参考：`07-关键配置补充说明.md` 第7节

☐ **实现OSS签名URL（安全）**
- ⏱️ 30分钟
- 🔗 参考：`07-关键配置补充说明.md` 第8节

☐ **配置域名（可选）**
- ⏱️ 30分钟
- 购买域名
- 配置DNS解析
- 配置HTTPS证书

---

### 5.2 文档整理

☐ **记录配置信息**
- ⏱️ 20分钟
- 创建 `部署配置清单.xlsx`
- 记录所有密码、地址、Key

☐ **备份配置文件**
- ⏱️ 10分钟
- Dify的 `.env` 和 `docker-compose.yaml`
- 上传到私有Git仓库或加密存储

☐ **编写运维手册**
- ⏱️ 30分钟
- 日常操作流程
- 故障处理流程
- 联系人信息

---

## 总结

### 时间统计

| 阶段 | 预计时间 | 实际时间 |
|------|---------|---------|
| 阶段1：基础设施 | 2小时 | _______ |
| 阶段2：核心服务 | 2小时 | _______ |
| 阶段3：Dify服务 | 1小时 | _______ |
| 阶段4：测试 | 1小时 | _______ |
| 阶段5：优化 | 可选 | _______ |
| **总计** | **6小时** | _______ |

### 成本统计

| 服务 | 规格 | 月成本 |
|------|------|--------|
| SAE前端 | 0.5核1GB×1 | ¥50 |
| SAE后端 | 1核2GB×2 | ¥200 |
| SAE Python | 1核2GB×1 | ¥100 |
| RDS PostgreSQL | 2核4GB | ¥400 |
| ECS Dify | 4核8GB | ¥300 |
| OSS | 50GB | ¥10 |
| NAT网关 | 小型+EIP | ¥100 |
| **总计** | - | **¥1,160/月** |

### 下一步

☐ 观察7天稳定性
☐ 根据监控数据调整资源
☐ 准备故障演练
☐ 编写用户手册

---

**恭喜！你已经完成了从0到1的部署！** 🎉

**文档创建人：** AI助手  
**最后更新：** 2025-12-14  
**版本：** v1.0