Develop/AIclinicalresearch
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(deploy): Complete full system deployment to Aliyun SAE

Browse Source 
Summary:
- Successfully deployed complete system to Aliyun SAE (2025-12-25)
- All services running: Python microservice + Node.js backend + Frontend Nginx + CLB
- Public access available at http://8.140.53.236/

Major Achievements:
1. Python microservice deployed (v1.0, internal IP: 172.17.173.66:8000)
2. Node.js backend deployed (v1.3, internal IP: 172.17.173.73:3001)
   - Fixed 4 critical issues: bash path, config directory, pino-pretty, ES Module
3. Frontend Nginx deployed (v1.0, internal IP: 172.17.173.72:80)
4. CLB load balancer configured (public IP: 8.140.53.236)

New Documentation (9 docs):
- 11-Node.js backend SAE deployment config checklist (21 env vars)
- 12-Node.js backend SAE deployment operation manual
- 13-Node.js backend image fix record (config directory)
- 14-Node.js backend pino-pretty fix
- 15-Node.js backend deployment success summary
- 16-Frontend Nginx deployment success summary
- 17-Complete deployment practical manual 2025 edition (1800 lines)
- 18-Deployment documentation usage guide
- 19-Daily update quick operation manual (670 lines)

Key Fixes:
- Environment variable name correction: EXTRACTION_SERVICE_URL (not PYTHON_SERVICE_URL)
- Dockerfile fix: added COPY config ./config
- Logger configuration: conditional pino-pretty for dev only
- Health check fix: ES Module compatibility (require -> import)

Updated Files:
- System status document updated with full deployment info
- Deployment progress overview updated with latest IPs
- All 3 Docker services' Dockerfiles and configs refined

Verification:
- All health checks passed
- Tool C 7 features working correctly
- Literature screening module functional
- Response time < 1 second

BREAKING CHANGE: Node.js backend internal IP changed from 172.17.173.71 to 172.17.173.73

Closes #deployment-milestone
This commit is contained in:
HaHafeng
2025-12-25 21:24:37 +08:00
parent 691dc2bc98
commit decff0bb1f
125 changed files with 5561 additions and 428 deletions
Download Patch File Download Diff File Expand all files Collapse all files

717
docs/05-部署文档/README.md
View File

@@ -1,472 +1,405 @@
# AI临床研究平台 - 阿里云部署文档导航
# 🚀 AI临床研究平台 - 部署文档中心
> **文档版本：** v2.0
> **最后更新：** 2025-12-14
> **文档总数：** 11份
> **部署目标：** 阿里云 SAE + RDS PostgreSQL 15 + OSS
> **适用团队：** 1-2人初创团队 → 10人成长团队
> **最后更新**：2025-12-25
> **部署状态**：✅ 完全成功，所有服务运行正常
> **公网访问**：http://8.140.53.236/
---
## 📋 文档清单
## 🎯 快速开始（3分钟找到你需要的文档）
### 🎯 必读文档（按阅读顺序）
### 我要做什么？
| # | 文档名称 | 用途 | 阅读时间 | 优先级 |
|---|---------|------|---------|--------|
| 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** | 历史文档（待更新） |
| 你的目标 | 推荐文档 | 预计时间 |
|---------|---------|---------|
| 🔥 **日常更新代码（最常用）** | [19-日常更新快速操作手册](./19-日常更新快速操作手册.md) ⭐⭐⭐⭐⭐ | 20-25分钟 |
| 🚀 **完整部署系统** | [17-完整部署实战手册-2025版](./17-完整部署实战手册-2025版.md) | 3.5-6小时 |
| 🔍 **查询IP/密码等信息** | [00-部署进度总览](./00-部署进度总览.md) | 1分钟 |
| 📚 **学习部署原理** | [01-快速部署SOP-零基础版](./01-快速部署SOP-零基础版.md) | 4小时 |
| 🐍 **部署Python服务** | [09-Python微服务-SAE部署操作手册](./09-Python微服务-SAE部署操作手册.md) | 35分钟 |
| 🟢 **部署Node.js后端** | [12-Node.js后端-SAE部署操作手册](./12-Node.js后端-SAE部署操作手册.md) | 50分钟 |
| 🎨 **部署前端Nginx** | [07-前端Nginx-SAE部署操作手册](./07-前端Nginx-SAE部署操作手册.md) | 30分钟 |
| ❌ **遇到问题排查** | [15-Node.js后端-部署成功总结](./15-Node.js后端-部署成功总结.md) | 按需 |
| 📖 **不知道看哪个文档** | [18-部署文档使用指南](./18-部署文档使用指南.md) | 5分钟 |
---
## 🚀 快速开始
## 🔥 日常更新操作（高频使用）⭐⭐⭐⭐⭐
### 新团队首次部署（推荐路径）
### [19-日常更新快速操作手册.md](./19-日常更新快速操作手册.md)
```
阶段0：准备工作（30分钟）
├─ 阅读《00-部署架构总览》
├─ 阅读《07-关键配置补充说明》⚠️ 必读
└─ 打印《08-部署检查清单》
**⚡ 最常用的文档！适合日常功能更新和快速迭代！**
阶段1：基础设施（Day 1上午，2小时）
├─ VPC + NAT网关（⚠️ 必需）
├─ RDS PostgreSQL 15
├─ OSS Bucket
└─ 参考：08-部署检查清单 第1部分
**为什么推荐**：
- ✅ 短小精悍（670行），关键信息密集
- ✅ 可直接复制执行的命令
- ✅ 包含一键更新脚本
- ✅ 适合团队协作和AI助手使用
阶段2：核心服务（Day 1下午，2小时）
├─ Node.js后端（临时Dify配置）
├─ Python微服务
├─ 前端
└─ 参考：08-部署检查清单 第2部分
**包含内容**：
- **更新Node.js后端**（20-25分钟）- 最常用！
```bash
编译 → 构建镜像 → 推送ACR → SAE部署 → 验证
```
- **更新前端Nginx**（15-20分钟）
- **更新Python服务**（30分钟）
- **修改环境变量**（5分钟）- 高频操作！
- **查看日志**（1分钟）
- **回滚操作**（7分钟）
- **一键更新脚本**（自动化）
阶段3：Dify服务（Day 2上午，1小时）
├─ ECS部署Dify
├─ 生成API Key
└─ 更新后端配置
└─ 参考：08-部署检查清单 第3部分
**适合人群**：
- 🎯 日常开发迭代的开发人员
- 🎯 需要快速部署更新的运维人员
- 🎯 团队新成员快速上手
- 🎯 AI助手执行部署任务
阶段4：测试验证（Day 2下午，1小时）
└─ 参考：08-部署检查清单 第4部分
总计：约6小时（实际操作时间）
**快速示例**：
```bash
# 更新Node.js后端到v1.5
cd backend
npm run build
docker build -t backend-service:v1.5 .
docker push crpi-xxx.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/backend-service:v1.5
# 然后在SAE控制台部署新版本
```
---
## ⚠️ 关键注意事项（必读！）
## ⭐ 核心文档（新手必看）
### 🚨 致命问题（P0/P1）- 不解决会导致系统不可用
### 1️⃣ 完整部署实战手册（强烈推荐）⭐⭐⭐⭐⭐
1. **NAT网关缺失** ⭐⭐⭐⭐⭐
- 问题：SAE无公网出口，AI功能全部超时
- 解决：创建NAT网关 + EIP + SNAT条目
- 成本：¥100/月
- 参考：`07-关键配置补充说明.md` 第1节
**[17-完整部署实战手册-2025版.md](./17-完整部署实战手册-2025版.md)**
2. **Dify API Key死锁** ⭐⭐⭐⭐⭐
- 问题：后端需要Key，但Key需要Dify先启动
- 解决：分阶段部署，先用临时Key
- 参考：`07-关键配置补充说明.md` 第2节
**为什么推荐**：
- ✅ 基于2025-12-25实际部署经历编写
- ✅ 包含所有遇到的问题及解决方案
- ✅ 1800行详细步骤，可直接复制命令
- ✅ 跟着做就能成功！
3. **HTTP超时未配置** ⭐⭐⭐⭐
- 问题：Python服务慢，后端连接泄漏
- 解决：设置timeout=120秒
- 参考：`07-关键配置补充说明.md` 第3节
**包含内容**：
- 完整部署流程（VPC→RDS→Python→Node.js→前端→CLB）
- 4个关键问题修复（环境变量、config、pino-pretty、ES Module）
- 关键经验总结（重启vs部署、环境变量命名等）
- 快速命令参考
- 完整链路测试
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节
**适合人群**：
- 🎯 要快速部署的人
- 🎯 重新部署或迁移的人
- 🎯 想了解实际坑点的人
---
## 📊 文档更新记录
### 2️⃣ 部署进度总览（日常必备）⭐⭐⭐⭐⭐
### v2.0 (2025-12-14) - 关键问题修正版
**[00-部署进度总览.md](./00-部署进度总览.md)**
**新增文档：**
- ✅ `07-关键配置补充说明.md`（813行）- 修正6个致命问题
- ✅ `08-部署检查清单.md`（784行）- 完整操作清单
- ✅ `README.md`（本文档）- 部署文档导航
**为什么推荐**：
- ✅ 所有资源信息的索引中心
- ✅ 快速查询IP、密码、环境变量
- ✅ 文档导航指南
- ✅ 部署状态追踪
**更新文档：**
- ✅ `00-部署架构总览.md`
- 物理架构图增加NAT网关
- 成本估算更新（¥1,200/月）
- 部署顺序增加分阶段说明
- 风险分析增加详细解决方案
**包含内容**：
- SAE应用内网IP地址
- RDS数据库连接信息
- OSS AccessKey
- ACR镜像仓库地址
- 环境变量配置清单
- 快速命令参考
**核心改进：**
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行）
**适合场景**：
- 🔍 忘记IP地址
- 🔍 忘记数据库密码
- 🔍 需要查询资源配置
- 🔍 需要找相关文档
---
## 📖 详细文档说明
### 3️⃣ 部署文档使用指南⭐⭐⭐⭐
### 1. 00-部署架构总览.md ⭐⭐⭐⭐⭐
**[18-部署文档使用指南.md](./18-部署文档使用指南.md)**
**用途：** 理解整体架构，5个模块的关系，阿里云服务映射
**为什么推荐**：
- ✅ 快速导航，找到需要的文档
- ✅ 不同场景的阅读路径
- ✅ 关键信息速查表
- ✅ 最佳实践建议
**核心内容：**
- 3个架构图（逻辑/物理/数据流）
- 5个模块依赖关系（L1-L4层级）
- 模块与阿里云服务映射（SAE/RDS/OSS/ECS）
- 开发环境 vs 部署环境
- Docker版本管理策略
- 线上故障快速修复（4种方案）
**适合人群：** 所有人（技术负责人、开发、运维）
**关键章节：**
- 第1章：架构全景图（必读）
- 第2章：5个核心模块关系
- 第3章：模块与阿里云服务映射
- 第6章：线上故障快速修复（⭐ 重点）
**适合人群**：
- 📖 不知道从哪个文档开始看
- 📖 想快速找到特定信息
- 📖 想了解文档结构
---
### 2. 07-关键配置补充说明.md ⚠️⭐⭐⭐⭐⭐
## 📁 完整文档列表
**用途：** 修正原文档遗漏的6个致命问题
### 🎯 核心指南（3个）
1. [README.md](./README.md) - 本文档，总入口
2. [00-部署进度总览.md](./00-部署进度总览.md) - 资源速查、文档索引
3. [18-部署文档使用指南.md](./18-部署文档使用指南.md) - 快速导航
**核心内容：**
- 🚨 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防护
### 🚀 完整部署（2个）
1. [17-完整部署实战手册-2025版.md](./17-完整部署实战手册-2025版.md) - ⭐ 实战版（推荐）
2. [01-快速部署SOP-零基础版.md](./01-快速部署SOP-零基础版.md) - 学习版
**适合人群：** 所有人（⚠️ 部署前必读）
### 🔧 服务部署手册（4个）
1. [09-Python微服务-SAE部署操作手册.md](./09-Python微服务-SAE部署操作手册.md)
2. [12-Node.js后端-SAE部署操作手册.md](./12-Node.js后端-SAE部署操作手册.md)
3. [07-前端Nginx-SAE部署操作手册.md](./07-前端Nginx-SAE部署操作手册.md)
4. [08-PostgreSQL数据库部署操作手册.md](./08-PostgreSQL数据库部署操作手册.md)
**修复时间：** 约40分钟（必需修复）
### 📖 技术详解（4个）
1. [04-Python微服务-SAE容器部署指南.md](./04-Python微服务-SAE容器部署指南.md)
2. [05-Node.js后端-SAE容器部署指南.md](./05-Node.js后端-SAE容器部署指南.md)
3. [06-前端Nginx-SAE容器部署指南.md](./06-前端Nginx-SAE容器部署指南.md)
4. [10-Node.js后端-Docker镜像构建手册.md](./10-Node.js后端-Docker镜像构建手册.md)
### 📝 配置清单（1个）
1. [11-Node.js后端-SAE部署配置清单.md](./11-Node.js后端-SAE部署配置清单.md) - 21个环境变量详解
### 🐛 问题修复（4个）
1. [13-Node.js后端-镜像修复记录.md](./13-Node.js后端-镜像修复记录.md) - config目录问题
2. [14-Node.js后端-pino-pretty问题修复.md](./14-Node.js后端-pino-pretty问题修复.md) - 日志配置问题
3. [15-Node.js后端-部署成功总结.md](./15-Node.js后端-部署成功总结.md) - ⭐ 完整问题汇总
4. [16-前端Nginx-部署成功总结.md](./16-前端Nginx-部署成功总结.md) - 前端部署总结
---
### 3. 08-部署检查清单.md ⭐⭐⭐⭐⭐
## 🎉 部署成功证明
**用途：** 逐步操作清单，确保不遗漏任何步骤
### 当前部署状态（2025-12-25）
**核心内容：**
- 阶段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：可选优化
| 服务 | 状态 | 内网地址 | 公网访问 |
|------|------|---------|---------|
| RDS PostgreSQL | ✅ 运行中 | `pgm-2zex1m2y3r23hdn5.pg.rds.aliyuncs.com:5432` | ❌ |
| Python微服务 | ✅ 运行中 | `172.17.173.66:8000` | ❌ |
| Node.js后端 | ✅ 运行中 | `172.17.173.73:3001` | ❌ |
| 前端Nginx | ✅ 运行中 | `172.17.173.72:80` | ✅ |
| CLB负载均衡 | ✅ 运行中 | - | `http://8.140.53.236/` |
**使用方式：** 打印或复制到笔记，逐项打勾
### 功能验证
- ✅ 前端页面正常访问
- ✅ 用户登录功能正常
- ✅ 文献筛查模块正常
- ✅ 数据清洗工具C的7大功能全部正常
- ✅ 文件上传功能正常
- ✅ AI对话功能正常
- ✅ 数据库连接正常
- ✅ Python服务调用正常
- ✅ 响应时间 < 1秒
---
### 4. PostgreSQL部署策略-摸底报告.md ⭐⭐⭐⭐⭐
## ⚠️ 关键经验（必读）
**用途：** 深入理解PostgreSQL 15数据库架构和部署策略
### 1. 环境变量名必须精确
**核心内容：**
- 本地数据库真实情况（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分钟
**❌ 错误配置**：
```bash
PYTHON_SERVICE_URL=http://172.17.173.66:8000
```
### 后端开发工程师
```
☐ 1. 00-部署架构总览（30分钟）- 理解架构
☐ 2. 07-关键配置补充说明（20分钟）- 修正问题
☐ 3. PostgreSQL部署策略（30分钟）- 数据库详解
☐ 4. 05-Node.js后端部署（30分钟）- 详细步骤
☐ 5. 04-Python微服务部署（25分钟）- Python服务
总计：135分钟（2.5小时）
**✅ 正确配置**：
```bash
EXTRACTION_SERVICE_URL=http://172.17.173.66:8000
```
### 前端开发工程师
**教训**：代码中使用的是 `EXTRACTION_SERVICE_URL`，环境变量名一个字母都不能错！
---
### 2. 区分"重启应用"和"部署应用"
| 操作 | 用途 | IP是否变 | 何时使用 |
|------|------|---------|---------|
| **重启应用** | 重启容器 | ❌ 不会变 | 修改环境变量、调整配置 |
| **部署应用** | 更新镜像 | ✅ 会变更 | 更新代码、更新镜像版本 |
**教训**：只修改环境变量时，用"重启应用"，避免IP变更导致其他服务配置失效！
---
### 3. Dockerfile必须包含config目录
**问题**：
```
☐ 1. 00-部署架构总览（30分钟）- 理解架构
☐ 2. 07-关键配置补充说明（10分钟）- Nginx配置
☐ 3. 06-前端Nginx部署（25分钟）- 详细步骤
总计：65分钟
ENOENT: no such file or directory, open '/app/config/agents.yaml'
```
### 运维工程师
```
☐ 1. 00-部署架构总览（30分钟）- 理解架构
☐ 2. 07-关键配置补充说明（20分钟）- 必读
☐ 3. 08-部署检查清单（边部署边查看）- 操作清单
☐ 4. 所有独立部署文档（各30分钟）- 详细步骤
总计：阅读2小时 + 部署6小时
**解决**：
```dockerfile
# ✅ 必须添加
COPY config ./config
```
---
## 💡 常见问题（FAQ）
### 4. 使用VPC地址拉取镜像（省钱）
### Q1: 必须先读哪几份文档？
**SAE拉取镜像时**：
```bash
# ✅ 正确（VPC地址，免流量费）
crpi-xxx-vpc.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/backend-service:v1.3
**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/月
# ❌ 不推荐（公网地址，收流量费）
crpi-xxx.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/backend-service:v1.3
```
---
## 📞 获取帮助
## 💡 快速命令参考
### 遇到问题？
### 登录ACR
```bash
docker login --username=gofeng117@163.com \
--password=fengzhibo117 \
crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com
```
1. **查看故障排查章节**：每个独立文档都有详细的故障排查
2. **检查关键配置**：`07-关键配置补充说明.md`
3. **查看审查报告**：`CTO代码审查报告.md` 和 `集成部署补充指南.md`
### 构建并推送镜像
```bash
# Node.js后端
cd backend
npm run build
docker build -t backend-service:v1.3 .
docker tag backend-service:v1.3 \
crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/backend-service:v1.3
docker push crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/backend-service:v1.3
```
### 反馈建议
### 健康检查
```bash
# Python服务
curl http://172.17.173.66:8000/api/health
如果文档有遗漏或错误，欢迎反馈！
# Node.js后端
curl http://172.17.173.73:3001/health
# 前端Nginx
curl http://172.17.173.72:80/health
# 公网访问
curl http://8.140.53.236/
```
---
**文档维护人：** AI助手
**最后更新：** 2025-12-14
**版本：** v2.0
## 📊 部署架构图
```
用户浏览器
↓ HTTP (公网)
CLB负载均衡器 (8.140.53.236)
↓ HTTP (内网)
前端Nginx (172.17.173.72:80)
↓ HTTP (内网, /api/v1/)
Node.js后端 (172.17.173.73:3001)
↓ HTTP (内网, /api/dc/)
Python服务 (172.17.173.66:8000)
↓ SQL (内网)
RDS PostgreSQL (pgm-2zex1m2y3r23hdn5.pg.rds.aliyuncs.com:5432)
```
---
## 🆘 需要帮助？
### 常见问题
**Q：我是新手，从哪里开始？**
- A：直接看 [17-完整部署实战手册-2025版](./17-完整部署实战手册-2025版.md)
**Q：只想更新代码，不想全部重新部署？**
- A：看对应服务的操作手册（如 [12-Node.js后端-SAE部署操作手册](./12-Node.js后端-SAE部署操作手册.md)）
**Q：遇到报错了怎么办？**
- A：先看 [17-完整部署实战手册-2025版](./17-完整部署实战手册-2025版.md) 第9节
**Q：忘记密码或IP地址了？**
- A：查 [00-部署进度总览](./00-部署进度总览.md)
**Q：不知道看哪个文档？**
- A：看 [18-部署文档使用指南](./18-部署文档使用指南.md)
---
## 🎯 推荐阅读路径
### 路径1：首次完整部署（新手）
```
17-完整部署实战手册-2025版.md（主线）
↓
00-部署进度总览.md（查资源信息）
↓
15-Node.js后端-部署成功总结.md（遇到问题时）
```
**预计时间**：3.5 - 6小时
---
### 路径2：更新某个服务（熟练）
```
对应服务的操作手册（如12-Node.js后端-SAE部署操作手册.md）
↓
00-部署进度总览.md（查ACR地址）
```
**预计时间**：15 - 30分钟
---
### 路径3：修改环境变量
```
11-Node.js后端-SAE部署配置清单.md（确认变量名）
↓
SAE控制台修改
↓
重启应用（不是部署应用！）
```
**预计时间**：5分钟
---
## 📞 技术支持
- **开发团队**：内部文档体系
- **阿里云工单**：https://workorder.console.aliyun.com/
- **紧急问题**：先查文档，99%的问题都有解决方案
---
## 🎉 总结
**恭喜您找到了完整的部署文档！**
### 3个核心文档记住它们
1. **本文档（README）** - 总入口，快速导航
2. **[17-完整部署实战手册-2025版](./17-完整部署实战手册-2025版.md)** - 部署必看
3. **[00-部署进度总览](./00-部署进度总览.md)** - 信息速查
### 部署成功的3个关键
1. ✅ 环境变量名必须精确匹配代码
2. ✅ 区分"重启应用"和"部署应用"
3. ✅ 按顺序部署，每步都要验证
---
> **最后更新**：2025-12-25
> **部署状态**：✅ 完全成功
> **公网访问**：http://8.140.53.236/
> **维护人员**：开发团队
🚀 **开始部署吧！祝您顺利！**
**核心理念：架构清晰、安全第一、步骤详细、易于上手** ⭐⭐⭐