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

4.1 KiB

Raw Blame History

集成部署补充指南：填补最后的缝隙

文档版本: 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 作为跳板机。

操作步骤

本地终端执行 (建立 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
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 访问。

4.1 KiB Raw Blame History Unescape Escape