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:
114
docs/05-部署文档/集成部署补充指南：填补最后的缝隙.md
Normal file
114
docs/05-部署文档/集成部署补充指南：填补最后的缝隙.md
Normal file
@@ -0,0 +1,114 @@
|
||||
# **集成部署补充指南：填补最后的缝隙**
|
||||
|
||||
文档版本: v1.0
|
||||
目标: 解决 5 个独立模块集成时的网络连通性、发布效率和成本问题。
|
||||
|
||||
## **🛑 关键问题 1：SAE 的外网访问 (调用 DeepSeek/OpenAI)**
|
||||
|
||||
现状：部署在 VPC 内的 SAE 默认无法访问公网。
|
||||
后果：后端调用 DeepSeek 接口会超时；Python 服务无法下载公网 PDF。
|
||||
|
||||
### **方案 A：NAT 网关 (标准生产方案，推荐)**
|
||||
|
||||
* **操作**：在 VPC 控制台创建一个 **公网 NAT 网关**，并绑定一个 **EIP**。配置 SNAT 条目，允许交换机内的实例访问公网。
|
||||
* **成本**：NAT 网关租赁费 \+ EIP 流量费/带宽费。
|
||||
* **优点**：稳定，无需修改应用配置。
|
||||
|
||||
### **方案 B：SAE 绑定公网 IP (省钱方案)**
|
||||
|
||||
* **操作**：在 SAE 应用配置 \-\> 网络配置 中，查看是否支持开启 **公网访问** 或绑定 EIP。
|
||||
* **注意**：SAE 某些旧版本或特定地域可能不支持直接绑定 EIP。如果不支持，必须用方案 A。
|
||||
|
||||
## **🛠️ 关键问题 2：跳板机配置 (如何直连 RDS)**
|
||||
|
||||
为了方便开发人员使用 Navicat/DBeaver 管理 RDS 数据，利用 **Dify ECS** 作为跳板机。
|
||||
|
||||
### **操作步骤**
|
||||
|
||||
1. **本地终端执行** (建立 SSH 隧道):
|
||||
\# 格式: ssh \-L 本地端口:RDS地址:RDS端口 root@ECS公网IP
|
||||
ssh \-N \-L 5433:rm-xxxxx.pg.rds.aliyuncs.com:5432 root@\<ECS\_PUBLIC\_IP\> \-i your-key.pem
|
||||
|
||||
2. **Navicat 连接配置**:
|
||||
* 主机: localhost
|
||||
* 端口: 5433
|
||||
* 用户/密码: RDS 的账号密码
|
||||
* *原理：流量通过 ECS 转发到内网 RDS。*
|
||||
|
||||
## **🚀 关键问题 3：一键发布脚本 (NoOps 神器)**
|
||||
|
||||
为 1-2 人团队定制的极简发布脚本。保存为 deploy.sh。
|
||||
|
||||
\#\!/bin/bash
|
||||
set \-e
|
||||
|
||||
\# \================= 配置区 \=================
|
||||
ACR\_REGISTRY="registry.cn-hangzhou.aliyuncs.com"
|
||||
NAMESPACE="clinical-research"
|
||||
TIMESTAMP=$(date \+%Y%m%d%H%M)
|
||||
|
||||
\# 颜色
|
||||
GREEN='\\033\[0;32m'
|
||||
NC='\\033\[0m'
|
||||
|
||||
function build\_and\_push() {
|
||||
SERVICE\_NAME=$1
|
||||
DIR\_NAME=$2
|
||||
|
||||
echo \-e "${GREEN}\>\>\> 开始构建 $SERVICE\_NAME ...${NC}"
|
||||
|
||||
\# 进入目录
|
||||
cd $DIR\_NAME
|
||||
|
||||
\# 1\. 构建镜像
|
||||
IMAGE\_URL="$ACR\_REGISTRY/$NAMESPACE/$SERVICE\_NAME:$TIMESTAMP"
|
||||
docker build \-t $IMAGE\_URL .
|
||||
|
||||
\# 2\. 推送镜像
|
||||
echo \-e "${GREEN}\>\>\> 推送镜像到 ACR ...${NC}"
|
||||
docker push $IMAGE\_URL
|
||||
|
||||
\# 3\. 输出更新指引 (如果安装了 aliyun-cli 可以自动更新，否则手动)
|
||||
echo \-e "${GREEN}\>\>\> ✅ $SERVICE\_NAME 镜像已就绪:${NC}"
|
||||
echo $IMAGE\_URL
|
||||
echo "请在 SAE 控制台将 \[$SERVICE\_NAME\] 的镜像版本更新为: $TIMESTAMP"
|
||||
|
||||
\# 回到根目录
|
||||
cd ..
|
||||
echo "----------------------------------------"
|
||||
}
|
||||
|
||||
\# \================= 主流程 \=================
|
||||
|
||||
\# 1\. 部署 Python 微服务
|
||||
\# build\_and\_push "extraction-service" "extraction\_service"
|
||||
|
||||
\# 2\. 部署 Node.js 后端 (记得先同步 Prisma)
|
||||
\# cp \-r prisma backend/prisma
|
||||
build\_and\_push "backend-service" "backend"
|
||||
\# rm \-rf backend/prisma
|
||||
|
||||
\# 3\. 部署前端
|
||||
\# build\_and\_push "frontend-service" "frontend-v2"
|
||||
|
||||
echo \-e "${GREEN}🎉 所有构建任务完成！${NC}"
|
||||
|
||||
## **🔐 关键问题 4：OSS 权限与路径规划**
|
||||
|
||||
为了防止文件混乱，建议在 Bucket 内划分明确的目录结构，并通过 IAM Policy 限制权限（可选）。
|
||||
|
||||
**推荐目录结构**:
|
||||
|
||||
clinical-research-files/
|
||||
├── pkb/ \# 个人知识库文件
|
||||
│ └── {userId}/ \# 按用户隔离
|
||||
├── asl/ \# 文献筛选文件
|
||||
│ └── {projectId}/ \# 按项目隔离
|
||||
├── dc/ \# 数据清洗文件
|
||||
│ └── {tempId}/ \# 临时上传
|
||||
└── system/ \# 系统资源
|
||||
|
||||
**应用代码逻辑**:
|
||||
|
||||
* **私有读写**: Bucket 权限设为 **Private**。
|
||||
* **前端访问**: 后端使用 ossClient.signatureUrl() 生成带有效期的 URL (如 1 小时) 返回给前端。**严禁前端直接通过公网 URL 访问。**
|
||||
Reference in New Issue
Block a user