docs(platform): Add database documentation system and restructure deployment docs

Completed:
- Add 6 core database documents (docs/01-平台基础层/07-数据库/)
  Architecture overview, migration history, environment comparison,
  tech debt tracking, seed data management, PostgreSQL extensions
- Restructure deployment docs: archive 20 legacy files to _archive-2025/
- Create unified daily operations manual (01-日常更新操作手册.md)
- Add pending deployment change tracker (03-待部署变更清单.md)
- Update database development standard to v3.0 (three iron rules)
- Fix Prisma schema type drift: align @db.* annotations with actual DB
  IIT: UUID/Timestamptz(6), SSA: Timestamp(6)/VarChar(20/50/100)
- Add migration: 20260227_align_schema_with_db_types (idempotent ALTER)
- Add Cursor Rule for auto-reminding deployment change documentation
- Update system status guide v6.4 with deployment and DB doc references
- Add architecture consultation docs (Prisma guide, SAE deployment guide)

Technical details:
- Manual migration due to shadow DB limitation (TD-001 in tech debt)
- Deployment docs reduced from 20+ scattered files to 3 core documents
- Cursor Rule triggers on schema.prisma, package.json, Dockerfile changes

Made-with: Cursor
This commit is contained in:
2026-02-27 14:35:25 +08:00
parent 9b8490b4d0
commit 6124c7abc6
48 changed files with 3009 additions and 582 deletions

View File

@@ -0,0 +1,783 @@
# 部署检查清单 - 从0到上线的完整Checklist
> **文档版本:** v1.0
> **创建日期:** 2025-12-14
> **适用场景:** 首次部署到阿里云生产环境
> **预计时间:** 4-5小时实际操作时间
---
## 📋 使用说明
本清单按照部署顺序列出所有必需步骤,每个步骤包含:
- ☐ 复选框(完成后打勾)
- ⏱️ 预计时间
- ⚠️ 关键注意事项
- 🔗 参考文档链接
**建议:打印或复制到笔记软件,逐项完成。**
---
## 阶段1基础设施准备Day 1上午
### 1.1 阿里云账号准备
**实名认证**
- ⏱️ 5分钟
- 阿里云控制台 > 账号管理 > 实名认证
- ⚠️ 企业认证需要营业执照
**账号充值**
- ⏱️ 2分钟
- 建议充值¥500首月成本约¥1,200
- 费用中心 > 充值
**开通服务**
- ⏱️ 5分钟
- 需要开通的服务:
- ✅ SAEServerless应用引擎
- ✅ 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网关
- VPCaiclinical-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
- VPCaiclinical-vpc-prod
- 入方向规则:
- 允许 80/TCP 来源172.16.0.0/12VPC内网
- 允许 22/TCP 来源您的办公室IPSSH管理
- 拒绝 所有 来源0.0.0.0/0
---
### 1.3 RDS PostgreSQL 15 部署
**创建RDS实例**
- ⏱️ 10分钟等待创建15分钟
- RDS控制台 > 创建实例
- 数据库类型PostgreSQL
- 版本15
- 规格rds.pg.s2.large2核4GB
- 存储100GB SSD
- VPCaiclinical-vpc-prod
- 交换机aiclinical-vsw-prod
- 记录内网地址rm-____________.pg.rds.aliyuncs.com
**配置白名单**
- ⏱️ 2分钟
- RDS实例详情 > 数据安全性 > 白名单设置
- 添加白名单分组sae-vpc
- IP地址172.16.0.0/12VPC网段
- ⚠️ **必须用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
- 内网Endpointoss-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: 120000120秒
- 🔗 参考:`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
- VPCaiclinical-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正确
☐ **修改DockerfileWorkers限制**
- ⏱️ 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://前端公网地址
- 应该看到登录页面
---
## 阶段3Dify服务部署Day 2上午
### 3.1 ECS服务器准备
☐ **创建ECS实例**
- ⏱️ 10分钟等待创建5分钟
- ECS控制台 > 创建实例
- 实例规格ecs.c6.xlarge4核8GB
- 镜像Ubuntu 22.04
- VPCaiclinical-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 Keyapp-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小时 | _______ |
| 阶段3Dify服务 | 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