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
This commit is contained in:
2025-12-14 13:25:28 +08:00
parent fa72beea6c
commit 19f9c5ea93
114 changed files with 12994 additions and 33 deletions

View File

@@ -0,0 +1,95 @@
# **CTO 代码审查报告AI临床研究平台部署架构**
审核对象5份独立部署文档 (Dify/Python/Node/Frontend/PostgreSQL)
审核人:虚拟架构师
结论A- (优秀)。架构设计符合云原生理念,成本与扩展性平衡良好。但存在网络出口和依赖闭环两个关键风险点需解决。
## **1\. 模块级深度审计 (Module-Level Audit)**
### **✅ 1.1 前端 Nginx (SAE)**
* **优点**多阶段构建优秀体积小环境变量注入方案envsubst非常专业解决了静态页面无法动态配置后端的难题。
* **修正建议**
* 确认 nginx.conf 中开启 gzip这对 React 大体积 JS 文件至关重要。
* 检查 Nginx 的 client\_max\_body\_size 配置。医疗 PDF/Excel 可能超过默认的 1MB建议设置为 50M。
### **✅ 1.2 后端 Node.js (SAE)**
* **优点**Prisma "反向同步" 流程非常务实解决了开发习惯不规范的问题。Postgres-Only 的架构极大地降低了运维负担。
* **修正建议**
* **连接泄漏风险**Python 服务如果响应慢,后端的 HTTP Client 设置超时了吗?建议设置 timeout: 30s防止后端连接数堆积。
### **✅ 1.3 Python 微服务 (SAE)**
* **优点**:明确指出了 libGL 等系统依赖问题,这是 Python 容器化最大的坑,文档已提前规避。
* **修正建议**
* **OOM 风险**Python 进程(尤其是 PyMuPDF/OCR非常吃内存。在 2G 内存限制下务必限制并发数Gunicorn Workers 不要超过 2 个)。
### **✅ 1.4 Dify (ECS)**
* **优点**:选择了 ECS 部署以保证数据私有化,同时使用 Swap 防止 OOM非常懂行。
* **修正建议**
* **安全性**ECS 的 Redis 端口 (6379) 和 Weaviate 端口 (8080) **绝对不要**对公网开放。仅允许 localhost 和 VPC 内网访问。
### **✅ 1.5 数据库 (RDS)**
* **优点**Schema 隔离设计极佳。
* **修正建议**
* **Dify 数据库隔离**:确认 Dify 使用的是独立的 dify\_prod 库,不要和业务表混在 ai\_clinical\_research 库中,防止 Dify 升级脚本误删业务表。
## **2\. 跨模块集成风险 (Integration Risks)**
### **🚨 风险一SAE 的"孤岛效应" (Internet Access)**
* **问题**SAE 部署在 VPC 内,默认**没有公网出口**。
* **场景**:后端调用 DeepSeek API、Python 下载公网 PDF、NPM 安装依赖(构建时)。
* **对策**:必须在 VPC 中配置 **NAT 网关** (推荐) 或确保 SAE 有绑定公网 IP 的能力。**否则上线当天所有 AI 功能都会超时。**
### **🔄 风险二:部署依赖死锁 (Deployment Deadlock)**
* **现象**
1. 后端启动需要 DIFY\_API\_KEY。
2. DIFY\_API\_KEY 需要 Dify 启动并人工登录后才能生成。
3. 后端如果配置了"健康检查失败则重启",在填入 Key 之前会无限重启。
* **对策**:首次部署时,后端环境变量 DIFY\_API\_KEY 可以先填个假值(如 temp让服务跑起来。等 Dify 部署好拿到真 Key 后,更新 SAE 配置并重启。
### **🌐 风险三:前端与 Dify 的跨域 (CORS)**
* **问题**:前端直接调用后端(通过 Nginx 代理)没问题。但如果前端需要**直接嵌入** Dify 的 Web UI如 iframe或直接调用 Dify API绕过后端会遇到 CORS。
* **对策**:坚持\*\*"所有请求走后端"\*\*的原则。前端 \-\> Nginx \-\> 后端 \-\> Dify。不要让前端直连 Dify既安全又避免 CORS。
## **3\. 架构关系图谱**
\[浏览器\]
| (HTTPS)
v
\[SAE: 前端 Nginx\]
| (反向代理 /api)
v
\[SAE: 后端 Node.js\] \--(内网HTTP)--\> \[SAE: Python 微服务\]
| | (内网HTTP)
| v
| \[ECS: Dify API\] \<--\> \[ECS: Weaviate/Redis\]
|
\+--(TCP Connection)--\> \[RDS PostgreSQL 15\]
| | (Schema: platform, asl, dc...)
| \+ (Database: dify\_prod)
|
\+--(HTTPS)--\> \[OSS 对象存储\]
|
\+--(NAT网关)--\> \[互联网: DeepSeek/OpenAI\]
## **4\. 给 1-2 人团队的生存建议**
1. **省钱黑科技**
* SAE 2.0 有**闲置计费**功能。开发环境(测试环境)务必开启,没人用时不收 CPU/内存 费。
* RDS 购买**通用型** (2核4G) 即可,不要买独享型,够用很久。
2. **不要自建监控**
* 直接用阿里云 **ARMS** (应用实时监控服务) 的免费额度或基础版。不要自己搭 Prometheus \+ Grafana维护成本太高。
3. **数据备份是底线**
* RDS 开启自动备份保留7天
* ECS 上的 Dify docker-compose.yaml 和 .env 文件,务必在本地或 Git 私有仓库备份一份。ECS 没了可以重买,配置文件没了就得重配。
4. **开发效率**
* 利用 ECS 做**跳板机**,本地直连 RDS 开发。不要每次都写代码去查数据。
**最终结论**:这套架构设计得非常扎实,完全可以支撑从 0 到 10 万用户的规模。请重点解决 **"SAE 访问公网 (NAT)"** 这个问题,即可开始部署。