Files

HaHafeng 19f9c5ea93 docs(deployment): Fix 8 critical deployment issues and enhance documentation

Summary of fixes:
- Fix service discovery address (change .sae domain to internal IP)
- Unify timezone configuration (Asia/Shanghai for all services)
- Enhance ECS security group configuration (Redis/Weaviate port binding)
- Add image pull strategy best practices
- Add Python service memory management guidelines
- Update Dify API Key deployment strategy (avoid deadlock)
- Add SSH tunnel for RDS database access
- Add NAT gateway cost optimization explanation

Modified files (7 docs):
- 00-部署架构总览.md (enhanced with 7 sections)
- 03-Dify-ECS部署完全指南.md (security hardening)
- 04-Python微服务-SAE容器部署指南.md (timezone + service discovery)
- 05-Node.js后端-SAE容器部署指南.md (timezone configuration)
- PostgreSQL部署策略-摸底报告.md (timezone best practice)
- 07-关键配置补充说明.md (3 new sections)
- 08-部署检查清单.md (service address fix)

New files:
- 文档修正报告-20251214.md (comprehensive fix report)
- Review documents from technical team

Impact:
- Fixed 3 P0/P1 critical issues (100% connection failure risk)
- Fixed 3 P2 important issues (stability and maintainability)
- Added 2 P3 best practices (developer convenience)

Status: All deployment documents reviewed and corrected, ready for production deployment

2025-12-14 13:25:28 +08:00

19 KiB

Raw Blame History

部署检查清单 - 从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分钟

本地执行：

# 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，执行：

-- 验证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分钟
容器镜像服务 > 访问凭证 > 设置固定密码
用户名：（阿里云账号）
密码：（设置一个强密码）

记录登录命令：

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，执行：

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分钟

cd backend
docker build -t backend:v1.0.0 .

验证镜像：docker images | grep backend

☐ 本地测试镜像

⏱️ 5分钟

docker run -p 3001:3001 \
  -e DATABASE_URL="postgresql://..." \
  -e NODE_ENV=production \
  backend:v1.0.0

测试健康检查：curl http://localhost:3001/health

☐ 推送到ACR

⏱️ 3分钟

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应用详情 > 环境变量

必需变量：

# 数据库
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分钟

# 健康检查
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镜像较大）

cd extraction_service
docker build -t python-service:v1.0.0 .

☐ 本地测试镜像

⏱️ 5分钟

docker run -p 8000:8000 python-service:v1.0.0
curl http://localhost:8000/health

☐ 推送到ACR

⏱️ 5分钟

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分钟

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分钟

cd frontend-v2
docker build -t frontend:v1.0.0 .

☐ 推送到ACR

⏱️ 3分钟

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分钟

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分钟
```
ssh root@ECS公网IP
```

☐ 安装Docker

⏱️ 5分钟

curl -fsSL https://get.docker.com | bash
systemctl start docker
systemctl enable docker
docker --version

☐ 安装Docker Compose

⏱️ 3分钟

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分钟

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分钟

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分钟
```
cp .env.example .env
vi .env
```

关键配置：

# 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分钟（首次启动需要拉取镜像）

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

修改：

DIFY_API_URL=http://172.16.x.x/v1  # ECS内网IP
DIFY_API_KEY=app-xxxxxxxxxxxxxxxxxxxxx  # 真实Key

保存 > 重启应用

☐ 测试PKB功能

⏱️ 5分钟

# 创建知识库
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

19 KiB Raw Blame History Unescape Escape

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

📋 使用说明

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

1.1 阿里云账号准备

1.2 VPC网络配置 ⭐⭐⭐⭐⭐

1.3 RDS PostgreSQL 15 部署

1.4 OSS对象存储配置

1.5 ACR容器镜像仓库配置

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

2.1 Node.js后端部署

2.2 Python微服务部署

2.3 前端部署

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

3.1 ECS服务器准备

3.2 Dify部署

3.3 Dify配置

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

4.1 功能测试

4.2 性能测试

4.3 监控配置

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

5.1 可选优化

5.2 文档整理

总结

时间统计

成本统计

下一步

19 KiB

Raw Blame History