HaHafeng
19f9c5ea93
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
473 lines
13 KiB
Markdown
473 lines
13 KiB
Markdown
# AI临床研究平台 - 阿里云部署文档导航
|
||
|
||
> **文档版本：** v2.0
|
||
> **最后更新：** 2025-12-14
|
||
> **文档总数：** 11份
|
||
> **部署目标：** 阿里云 SAE + RDS PostgreSQL 15 + OSS
|
||
> **适用团队：** 1-2人初创团队 → 10人成长团队
|
||
|
||
---
|
||
|
||
## 📋 文档清单
|
||
|
||
### 🎯 必读文档（按阅读顺序）
|
||
|
||
| # | 文档名称 | 用途 | 阅读时间 | 优先级 |
|
||
|---|---------|------|---------|--------|
|
||
| 1 | **00-部署架构总览.md** | 理解整体架构和模块关系 | 30分钟 | ⭐⭐⭐⭐⭐ |
|
||
| 2 | **⚠️ 07-关键配置补充说明.md** | 修正致命问题（NAT/安全/超时） | 20分钟 | ⭐⭐⭐⭐⭐ |
|
||
| 3 | **08-部署检查清单.md** | 逐步操作清单 | 边部署边查看 | ⭐⭐⭐⭐⭐ |
|
||
|
||
### 📖 独立部署文档（按部署顺序）
|
||
|
||
| # | 文档名称 | 部署对象 | 阅读时间 | 部署时间 |
|
||
|---|---------|---------|---------|---------|
|
||
| 4 | **PostgreSQL部署策略-摸底报告.md** | RDS PostgreSQL 15 | 20分钟 | 10分钟 |
|
||
| 5 | **05-Node.js后端-SAE容器部署指南.md** | Node.js后端 | 30分钟 | 20-30分钟 |
|
||
| 6 | **04-Python微服务-SAE容器部署指南.md** | Python微服务 | 25分钟 | 20-30分钟 |
|
||
| 7 | **06-前端Nginx-SAE容器部署指南.md** | React前端 | 25分钟 | 15-20分钟 |
|
||
| 8 | **03-Dify-ECS部署完全指南.md** | Dify RAG平台 | 30分钟 | 30-60分钟 |
|
||
|
||
### 📚 参考文档
|
||
|
||
| # | 文档名称 | 用途 |
|
||
|---|---------|------|
|
||
| 9 | **CTO代码审查报告.md** | 架构审查和问题识别 |
|
||
| 10 | **集成部署补充指南.md** | 集成问题解决方案 |
|
||
| 11 | **01-部署架构设计.md** | 历史文档（待更新） |
|
||
|
||
---
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 新团队首次部署（推荐路径）
|
||
|
||
```
|
||
阶段0：准备工作（30分钟）
|
||
├─ 阅读《00-部署架构总览》
|
||
├─ 阅读《07-关键配置补充说明》⚠️ 必读
|
||
└─ 打印《08-部署检查清单》
|
||
|
||
阶段1：基础设施（Day 1上午，2小时）
|
||
├─ VPC + NAT网关（⚠️ 必需）
|
||
├─ RDS PostgreSQL 15
|
||
├─ OSS Bucket
|
||
└─ 参考：08-部署检查清单 第1部分
|
||
|
||
阶段2：核心服务（Day 1下午，2小时）
|
||
├─ Node.js后端（临时Dify配置）
|
||
├─ Python微服务
|
||
├─ 前端
|
||
└─ 参考：08-部署检查清单 第2部分
|
||
|
||
阶段3：Dify服务（Day 2上午，1小时）
|
||
├─ ECS部署Dify
|
||
├─ 生成API Key
|
||
└─ 更新后端配置
|
||
└─ 参考：08-部署检查清单 第3部分
|
||
|
||
阶段4：测试验证（Day 2下午，1小时）
|
||
└─ 参考：08-部署检查清单 第4部分
|
||
|
||
总计：约6小时（实际操作时间）
|
||
```
|
||
|
||
---
|
||
|
||
## ⚠️ 关键注意事项（必读！）
|
||
|
||
### 🚨 致命问题（P0/P1）- 不解决会导致系统不可用
|
||
|
||
1. **NAT网关缺失** ⭐⭐⭐⭐⭐
|
||
- 问题：SAE无公网出口，AI功能全部超时
|
||
- 解决：创建NAT网关 + EIP + SNAT条目
|
||
- 成本：¥100/月
|
||
- 参考：`07-关键配置补充说明.md` 第1节
|
||
|
||
2. **Dify API Key死锁** ⭐⭐⭐⭐⭐
|
||
- 问题：后端需要Key，但Key需要Dify先启动
|
||
- 解决：分阶段部署，先用临时Key
|
||
- 参考：`07-关键配置补充说明.md` 第2节
|
||
|
||
3. **HTTP超时未配置** ⭐⭐⭐⭐
|
||
- 问题：Python服务慢，后端连接泄漏
|
||
- 解决：设置timeout=120秒
|
||
- 参考：`07-关键配置补充说明.md` 第3节
|
||
|
||
4. **ECS端口安全** ⭐⭐⭐⭐⭐
|
||
- 问题：Redis/Weaviate对公网开放
|
||
- 解决：只监听127.0.0.1
|
||
- 参考：`07-关键配置补充说明.md` 第4节
|
||
|
||
5. **Python Workers过多** ⭐⭐⭐⭐⭐
|
||
- 问题：PyMuPDF吃内存，OOM崩溃
|
||
- 解决：workers=2，不超过2GB/0.8GB
|
||
- 参考：`07-关键配置补充说明.md` 第6节
|
||
|
||
6. **Nginx文件大小限制** ⭐⭐⭐⭐
|
||
- 问题：医疗PDF大文件上传失败
|
||
- 解决：client_max_body_size 50M
|
||
- 参考：`07-关键配置补充说明.md` 第5节
|
||
|
||
---
|
||
|
||
## 📊 文档更新记录
|
||
|
||
### v2.0 (2025-12-14) - 关键问题修正版
|
||
|
||
**新增文档：**
|
||
- ✅ `07-关键配置补充说明.md`（813行）- 修正6个致命问题
|
||
- ✅ `08-部署检查清单.md`（784行）- 完整操作清单
|
||
- ✅ `README.md`（本文档）- 部署文档导航
|
||
|
||
**更新文档：**
|
||
- ✅ `00-部署架构总览.md`
|
||
- 物理架构图增加NAT网关
|
||
- 成本估算更新（¥1,200/月）
|
||
- 部署顺序增加分阶段说明
|
||
- 风险分析增加详细解决方案
|
||
|
||
**核心改进：**
|
||
1. ⚠️ NAT网关配置（P0，必需）
|
||
2. ⚠️ 部署依赖死锁解决（P1）
|
||
3. ⚠️ HTTP超时配置（P1）
|
||
4. ⚠️ 安全配置强化（P0）
|
||
5. ⚠️ OOM防护（P1）
|
||
6. ⚠️ 文件上传限制（P2）
|
||
|
||
**审查来源：**
|
||
- `CTO代码审查报告.md`：识别3个致命问题
|
||
- `集成部署补充指南.md`：提供实战解决方案
|
||
|
||
### v1.0 (2025-12-13) - 初始版本
|
||
|
||
**文档清单：**
|
||
- `00-部署架构总览.md`（1,345行）
|
||
- `PostgreSQL部署策略-摸底报告.md`（1,327行）
|
||
- `03-Dify-ECS部署完全指南.md`（1,189行）
|
||
- `04-Python微服务-SAE容器部署指南.md`（1,524行）
|
||
- `05-Node.js后端-SAE容器部署指南.md`（2,178行）
|
||
- `06-前端Nginx-SAE容器部署指南.md`（2,064行）
|
||
|
||
---
|
||
|
||
## 📖 详细文档说明
|
||
|
||
### 1. 00-部署架构总览.md ⭐⭐⭐⭐⭐
|
||
|
||
**用途：** 理解整体架构，5个模块的关系，阿里云服务映射
|
||
|
||
**核心内容：**
|
||
- 3个架构图（逻辑/物理/数据流）
|
||
- 5个模块依赖关系（L1-L4层级）
|
||
- 模块与阿里云服务映射（SAE/RDS/OSS/ECS）
|
||
- 开发环境 vs 部署环境
|
||
- Docker版本管理策略
|
||
- 线上故障快速修复（4种方案）
|
||
|
||
**适合人群：** 所有人（技术负责人、开发、运维）
|
||
|
||
**关键章节：**
|
||
- 第1章：架构全景图（必读）
|
||
- 第2章：5个核心模块关系
|
||
- 第3章：模块与阿里云服务映射
|
||
- 第6章：线上故障快速修复（⭐ 重点）
|
||
|
||
---
|
||
|
||
### 2. 07-关键配置补充说明.md ⚠️⭐⭐⭐⭐⭐
|
||
|
||
**用途：** 修正原文档遗漏的6个致命问题
|
||
|
||
**核心内容：**
|
||
- 🚨 P0/P1致命问题（6个）
|
||
1. SAE孤岛效应 - NAT网关配置
|
||
2. 部署依赖死锁 - Dify API Key
|
||
3. HTTP Client超时 - 120秒配置
|
||
4. ECS端口安全 - Redis/Weaviate
|
||
5. Nginx文件大小 - 50MB限制
|
||
6. Python Workers - OOM防护
|
||
|
||
**适合人群：** 所有人（⚠️ 部署前必读）
|
||
|
||
**修复时间：** 约40分钟（必需修复）
|
||
|
||
---
|
||
|
||
### 3. 08-部署检查清单.md ⭐⭐⭐⭐⭐
|
||
|
||
**用途：** 逐步操作清单，确保不遗漏任何步骤
|
||
|
||
**核心内容：**
|
||
- 阶段1：基础设施（2小时）
|
||
- VPC + NAT网关 ⚠️
|
||
- RDS PostgreSQL 15
|
||
- OSS Bucket
|
||
- ACR容器镜像仓库
|
||
- 阶段2：核心服务（2小时）
|
||
- Node.js后端（临时Dify配置）
|
||
- Python微服务
|
||
- 前端
|
||
- 阶段3：Dify服务（1小时）
|
||
- ECS部署
|
||
- API Key生成
|
||
- 后端配置更新
|
||
- 阶段4：测试验证（1小时）
|
||
- 阶段5：可选优化
|
||
|
||
**使用方式：** 打印或复制到笔记，逐项打勾
|
||
|
||
---
|
||
|
||
### 4. PostgreSQL部署策略-摸底报告.md ⭐⭐⭐⭐⭐
|
||
|
||
**用途：** 深入理解PostgreSQL 15数据库架构和部署策略
|
||
|
||
**核心内容：**
|
||
- 本地数据库真实情况（10个Schema隔离）
|
||
- Prisma与数据库差异（pg-boss表自愈机制）
|
||
- 数据库连接方式（DATABASE_URL + 连接池）
|
||
- 首次部署方案（pg_dump vs Prisma migrate）
|
||
- 未来更新策略（新表/修改字段/新模块）
|
||
- RDS备份策略（4道防线）
|
||
- 最佳实践与禁止操作
|
||
|
||
**适合人群：** 后端开发、DBA、运维
|
||
|
||
**关键发现：**
|
||
- ✅ pg-boss表会自动创建，无需担心
|
||
- ✅ 推荐pg_dump全量导入（10分钟完成）
|
||
- ✅ RDS自动备份足够，初期不需要ECS脚本
|
||
|
||
---
|
||
|
||
### 5. 05-Node.js后端-SAE容器部署指南.md ⭐⭐⭐⭐⭐
|
||
|
||
**用途：** Node.js后端详细部署步骤
|
||
|
||
**核心内容：**
|
||
- 为什么选择SAE容器部署
|
||
- 后端服务分析（Node 22 + Fastify + Prisma）
|
||
- **⭐ Prisma反向同步**（关键，解决Schema不一致）
|
||
- Dockerfile多阶段构建
|
||
- SAE应用配置（环境变量、健康检查）
|
||
- 数据库部署策略（pg_dump + prisma db pull）
|
||
- 端到端测试
|
||
- 监控与故障排查
|
||
|
||
**适合人群：** 后端开发、运维
|
||
|
||
**关键章节：**
|
||
- 第4章：Prisma反向同步（必读）
|
||
- 第5章：Dockerfile（生产环境Prisma CLI）
|
||
- 第8章：SAE应用配置（环境变量）
|
||
|
||
---
|
||
|
||
### 6. 04-Python微服务-SAE容器部署指南.md ⭐⭐⭐⭐
|
||
|
||
**用途：** Python微服务详细部署步骤
|
||
|
||
**核心内容：**
|
||
- 为什么选择SAE容器（系统依赖问题）
|
||
- Python服务分析（PyMuPDF + Nougat + Polars）
|
||
- Dockerfile多阶段构建（系统依赖安装）
|
||
- **⚠️ Workers限制**（防止OOM）
|
||
- SAE应用配置
|
||
- 端到端测试
|
||
|
||
**适合人群：** Python开发、运维
|
||
|
||
**关键注意：**
|
||
- ⚠️ workers=2（不要超过，会OOM）
|
||
- ⚠️ 内存至少2GB
|
||
- ⚠️ 系统依赖（libGL等）必须在Dockerfile中安装
|
||
|
||
---
|
||
|
||
### 7. 06-前端Nginx-SAE容器部署指南.md ⭐⭐⭐⭐
|
||
|
||
**用途：** React前端详细部署步骤
|
||
|
||
**核心内容：**
|
||
- 为什么选择SAE Nginx容器
|
||
- 前端服务分析（React 19 + Vite 7）
|
||
- Dockerfile多阶段构建
|
||
- **nginx.conf.template**（SPA路由 + 反向代理）
|
||
- SAE应用配置（envsubst动态配置）
|
||
- 端到端测试
|
||
|
||
**适合人群：** 前端开发、运维
|
||
|
||
**关键配置：**
|
||
- ⚠️ client_max_body_size 50M
|
||
- ⚠️ try_files $uri /index.html（SPA路由）
|
||
- ⚠️ envsubst动态注入后端地址
|
||
|
||
---
|
||
|
||
### 8. 03-Dify-ECS部署完全指南.md ⭐⭐⭐⭐
|
||
|
||
**用途：** Dify RAG平台详细部署步骤
|
||
|
||
**核心内容：**
|
||
- 为什么选择ECS（复杂服务，独立数据库）
|
||
- ECS准备（Docker + Docker Compose）
|
||
- **⚠️ Swap配置**（防止OOM）
|
||
- docker-compose.yaml配置（7个服务）
|
||
- **⚠️ 端口安全**（Redis/Weaviate只监听localhost）
|
||
- Nginx路由层（CORS处理）
|
||
- 故障排查
|
||
|
||
**适合人群：** 运维、后端开发
|
||
|
||
**关键安全：**
|
||
- ⚠️ Redis: 127.0.0.1:6379:6379
|
||
- ⚠️ Weaviate: 127.0.0.1:8080:8080
|
||
- ⚠️ 独立数据库（不要和业务库混用）
|
||
|
||
---
|
||
|
||
### 9. CTO代码审查报告.md 📚
|
||
|
||
**用途：** 识别架构问题和风险点
|
||
|
||
**核心发现：**
|
||
- 🚨 SAE孤岛效应（NAT网关）
|
||
- 🔄 部署依赖死锁（Dify Key）
|
||
- 🌐 CORS问题（前端直连Dify）
|
||
- 🔐 端口安全（Redis/Weaviate）
|
||
|
||
**评分：** A-（优秀，但有关键问题需解决）
|
||
|
||
---
|
||
|
||
### 10. 集成部署补充指南.md 📚
|
||
|
||
**用途：** 集成部署的实战解决方案
|
||
|
||
**核心内容：**
|
||
- NAT网关配置（两种方案）
|
||
- SSH隧道配置（跳板机）
|
||
- 一键发布脚本（可选）
|
||
- OSS权限规划
|
||
|
||
---
|
||
|
||
## 🎯 不同角色的阅读建议
|
||
|
||
### 技术负责人/CTO
|
||
|
||
```
|
||
☐ 1. 00-部署架构总览（30分钟）- 理解整体架构
|
||
☐ 2. 07-关键配置补充说明（20分钟）- 识别风险
|
||
☐ 3. CTO代码审查报告（10分钟）- 审查视角
|
||
☐ 4. 成本估算：¥1,200/月
|
||
|
||
总计：60分钟
|
||
```
|
||
|
||
### 后端开发工程师
|
||
|
||
```
|
||
☐ 1. 00-部署架构总览（30分钟）- 理解架构
|
||
☐ 2. 07-关键配置补充说明（20分钟）- 修正问题
|
||
☐ 3. PostgreSQL部署策略（30分钟）- 数据库详解
|
||
☐ 4. 05-Node.js后端部署（30分钟）- 详细步骤
|
||
☐ 5. 04-Python微服务部署（25分钟）- Python服务
|
||
|
||
总计：135分钟（2.5小时）
|
||
```
|
||
|
||
### 前端开发工程师
|
||
|
||
```
|
||
☐ 1. 00-部署架构总览（30分钟）- 理解架构
|
||
☐ 2. 07-关键配置补充说明（10分钟）- Nginx配置
|
||
☐ 3. 06-前端Nginx部署（25分钟）- 详细步骤
|
||
|
||
总计：65分钟
|
||
```
|
||
|
||
### 运维工程师
|
||
|
||
```
|
||
☐ 1. 00-部署架构总览（30分钟）- 理解架构
|
||
☐ 2. 07-关键配置补充说明（20分钟）- 必读
|
||
☐ 3. 08-部署检查清单（边部署边查看）- 操作清单
|
||
☐ 4. 所有独立部署文档（各30分钟）- 详细步骤
|
||
|
||
总计：阅读2小时 + 部署6小时
|
||
```
|
||
|
||
---
|
||
|
||
## 💡 常见问题（FAQ）
|
||
|
||
### Q1: 必须先读哪几份文档？
|
||
|
||
**A:** 3份必读（按顺序）：
|
||
1. `00-部署架构总览.md`（理解整体）
|
||
2. `07-关键配置补充说明.md`（修正致命问题）⚠️
|
||
3. `08-部署检查清单.md`（逐步操作）
|
||
|
||
### Q2: 为什么NAT网关这么重要？
|
||
|
||
**A:** SAE部署在VPC内网，没有NAT网关：
|
||
- ❌ 后端无法调用DeepSeek/OpenAI API
|
||
- ❌ Python无法下载公网PDF
|
||
- ❌ npm install无法下载公网依赖
|
||
- **结果：所有AI功能不可用！**
|
||
|
||
### Q3: Dify API Key的鸡生蛋问题怎么解决？
|
||
|
||
**A:** 分阶段部署：
|
||
1. 后端先用临时Key（`temp_placeholder`）
|
||
2. 部署Dify并生成真实Key
|
||
3. 更新后端环境变量并重启
|
||
|
||
### Q4: 为什么Python workers只能设置2个？
|
||
|
||
**A:** PyMuPDF + Nougat OCR非常吃内存：
|
||
- 单个worker：~800MB内存
|
||
- SAE配置：2GB内存
|
||
- workers=2：安全值（2 × 800MB = 1.6GB < 2GB）
|
||
- workers=3：会OOM崩溃
|
||
|
||
### Q5: 部署需要多长时间？
|
||
|
||
**A:**
|
||
- 首次部署：6小时（实际操作）
|
||
- 后续更新：10-30分钟（镜像重新部署）
|
||
|
||
### Q6: 总成本多少？
|
||
|
||
**A:** ¥1,200-1,250/月（初期配置）
|
||
- SAE：¥350/月
|
||
- RDS：¥400/月
|
||
- ECS（Dify）：¥300/月
|
||
- NAT网关：¥100/月
|
||
- OSS：¥10/月
|
||
|
||
---
|
||
|
||
## 📞 获取帮助
|
||
|
||
### 遇到问题？
|
||
|
||
1. **查看故障排查章节**：每个独立文档都有详细的故障排查
|
||
2. **检查关键配置**：`07-关键配置补充说明.md`
|
||
3. **查看审查报告**：`CTO代码审查报告.md` 和 `集成部署补充指南.md`
|
||
|
||
### 反馈建议
|
||
|
||
如果文档有遗漏或错误，欢迎反馈！
|
||
|
||
---
|
||
|
||
**文档维护人：** AI助手
|
||
**最后更新：** 2025-12-14
|
||
**版本：** v2.0
|
||
|
||
**核心理念：架构清晰、安全第一、步骤详细、易于上手** ⭐⭐⭐
|