AIclinicalresearch/docs/05-部署文档/00-部署架构总览.md

AI临床研究平台 - 阿里云部署架构总览

文档版本： v1.0
创建日期： 2025-12-14
目标环境： 阿里云 SAE + RDS PostgreSQL 15 + OSS
架构类型： 云原生 Serverless + 容器化微服务
适用团队： 1-2人初创团队 → 10人成长团队

---

📋 目录

1. 架构全景图
2. 5个核心模块关系
3. 模块与阿里云服务映射
4. 开发环境与部署环境
5. Docker版本管理策略
6. 线上故障快速修复
7. 部署文档导航

---

架构全景图

1. 逻辑架构（用户视角）

┌─────────────────────────────────────────────────────────────────────┐
│                         用户浏览器（Browser）                          │
│                    https://your-domain.com                          │
└────────────────────────────────┬────────────────────────────────────┘
                                 │
                    ┌────────────▼───────────────┐
                    │   前端 SPA (React 19)      │
                    │   - 用户界面               │
                    │   - 路由管理               │
                    │   - API调用                │
                    └────────────┬───────────────┘
                                 │
              ┌──────────────────┼──────────────────┐
              │                  │                  │
    ┌─────────▼──────┐  ┌───────▼───────┐  ┌──────▼──────────┐
    │  Node.js后端   │  │ Python微服务  │  │  Dify RAG平台   │
    │  (Fastify)     │  │  (FastAPI)    │  │  (知识库检索)   │
    │                │  │               │  │                 │
    │ - 业务逻辑     │  │ - PDF解析     │  │ - 文档上传      │
    │ - 权限控制     │  │ - 数据清洗    │  │ - 向量检索      │
    │ - API聚合      │  │ - 文件提取    │  │ - LLM对话       │
    └────────┬───────┘  └───────┬───────┘  └──────┬──────────┘
             │                  │                  │
             │                  │                  │
             └──────────────────┼──────────────────┘
                                │
                    ┌───────────▼────────────┐
                    │  PostgreSQL 15 数据库  │
                    │  (RDS)                 │
                    │                        │
                    │  - 10个Schema隔离      │
                    │  - pg-boss任务队列     │
                    │  - Postgres-Only架构   │
                    └────────────────────────┘

2. 物理架构（阿里云资源）

┌───────────────────────────────────────────────────────────────────────────┐
│                         阿里云 VPC（专有网络）                              │
│                      172.16.0.0/12（内网隔离）                             │
├───────────────────────────────────────────────────────────────────────────┤
│                                                                           │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │              SAE (Serverless Application Engine)                │    │
│  │                      容器化应用部署平台                           │    │
│  ├─────────────────────────────────────────────────────────────────┤    │
│  │                                                                 │    │
│  │  ┌───────────────┐  ┌───────────────┐  ┌──────────────────┐   │    │
│  │  │  前端Nginx    │  │ Node.js后端   │  │ Python微服务     │   │    │
│  │  │  容器应用      │  │  容器应用      │  │  容器应用         │   │    │
│  │  ├───────────────┤  ├───────────────┤  ├──────────────────┤   │    │
│  │  │ Nginx 1.25    │  │ Node.js 22    │  │ Python 3.11      │   │    │
│  │  │ React构建产物 │  │ Fastify 5     │  │ FastAPI 0.104    │   │    │
│  │  │ 健康检查/路由 │  │ Prisma 6      │  │ PyMuPDF/Polars   │   │    │
│  │  └───────┬───────┘  └───────┬───────┘  └────────┬─────────┘   │    │
│  │          │                  │                   │             │    │
│  │          │  内网调用         │  内网调用          │             │    │
│  │          └──────────────────┴───────────────────┘             │    │
│  │                             │                                 │    │
│  └─────────────────────────────┼─────────────────────────────────┘    │
│                                │                                      │
│  ┌──────────────────────────────────────────────────────────┐        │
│  │   ⭐ NAT网关 + EIP（公网出口，必需）                      │        │
│  ├──────────────────────────────────────────────────────────┤        │
│  │  - 为SAE提供公网访问能力                                 │        │
│  │  - 后端调用DeepSeek/OpenAI API                           │        │
│  │  - Python下载公网PDF                                     │        │
│  │  - npm install公网依赖                                   │        │
│  │  - 成本：NAT网关¥60/月 + EIP流量费                       │        │
│  │  - ⚠️ 没有NAT网关，AI功能全部超时！                       │        │
│  └──────────────────────────────────────────────────────────┘        │
│                                │                                      │
│  ┌─────────────────────────────▼──────────────────────────┐          │
│  │        RDS PostgreSQL 15（云数据库）                    │          │
│  │        rds.pg.s2.large (2核4GB)                        │          │
│  ├────────────────────────────────────────────────────────┤          │
│  │  - 数据库名：ai_clinical_research                      │          │
│  │  - 用户：aiclinical_rw（应用专用账号）                 │          │
│  │  - 内网地址：rm-xxxxx.pg.rds.aliyuncs.com:5432       │          │
│  │  - 自动备份：每天凌晨2点 + 日志备份（PITR）            │          │
│  │  - 白名单：172.16.0.0/12（SAE的VPC网段）              │          │
│  └────────────────────────────────────────────────────────┘          │
│                                                                       │
│  ┌──────────────────────────────────────────────────────────┐        │
│  │        OSS (Object Storage Service) 对象存储              │        │
│  │        Bucket: aiclinical-data-prod                      │        │
│  ├──────────────────────────────────────────────────────────┤        │
│  │  - 用户上传文件（PDF、Word、Excel）                      │        │
│  │  - 文献数据（ASL模块）                                   │        │
│  │  - 数据清洗结果（DC模块）                                │        │
│  │  - 数据库备份归档（可选）                                │        │
│  │  - 访问方式：SDK（内网免流量费）                         │        │
│  └──────────────────────────────────────────────────────────┘        │
│                                                                       │
└───────────────────────────────────────────────────────────────────────┘

┌───────────────────────────────────────────────────────────────────────────┐
│                      独立 ECS 服务器（Dify部署）                           │
│                      ecs.c6.xlarge (4核8GB)                               │
├───────────────────────────────────────────────────────────────────────────┤
│  ┌──────────────────────────────────────────────────────────────┐        │
│  │            Dify RAG 平台 (Docker Compose)                    │        │
│  ├──────────────────────────────────────────────────────────────┤        │
│  │  - Dify API (dify/api:0.6.13)                               │        │
│  │  - Dify Web (dify/web:0.6.13)                               │        │
│  │  - PostgreSQL 15 (postgres:15-alpine，Dify专用数据库)        │        │
│  │  - Redis (redis:6-alpine，Dify缓存)                         │        │
│  │  - Weaviate (向量数据库)                                     │        │
│  │  - Nginx (路由层，处理CORS)                                 │        │
│  │  - Sandbox (代码执行沙箱)                                    │        │
│  │                                                              │        │
│  │  内网地址：http://172.16.x.x（通过VPC与SAE互联）            │        │
│  └──────────────────────────────────────────────────────────────┘        │
│                                                                           │
└───────────────────────────────────────────────────────────────────────────┘

3. 数据流向图

用户上传文件
    │
    ├──► 前端 (React)
    │         │
    │         ├──► /api/v1/pkb/documents (上传到知识库)
    │         │         │
    │         │         ├──► Node.js后端
    │         │         │         │
    │         │         │         ├──► OSS (存储原始文件)
    │         │         │         └──► Dify API (创建文档向量)
    │         │         │                   │
    │         │         │                   └──► Weaviate (存储向量)
    │         │         │
    │         │         └──► RDS (存储元数据)
    │         │
    │         ├──► /api/v1/asl/literatures (文献筛选)
    │         │         │
    │         │         ├──► Node.js后端
    │         │         │         │
    │         │         │         ├──► Python微服务 (PDF解析)
    │         │         │         │         │
    │         │         │         │         └──► OSS (读取PDF)
    │         │         │         │
    │         │         │         └──► RDS (存储文献数据)
    │         │         │
    │         │         └──► 返回解析结果
    │         │
    │         └──► /api/v1/dc/extraction (数据清洗)
    │                   │
    │                   ├──► Node.js后端
    │                   │         │
    │                   │         ├──► Python微服务 (Polars数据处理)
    │                   │         │         │
    │                   │         │         └──► OSS (读取Excel/CSV)
    │                   │         │
    │                   │         └──► RDS (存储清洗结果)
    │                   │
    │                   └──► 返回清洗结果
    │
    └──► 展示结果

---

5个核心模块关系

1. 模块依赖关系图

┌─────────────────────────────────────────────────────────────────┐
│                    核心依赖层级 (从下到上)                       │
└─────────────────────────────────────────────────────────────────┘

L4: 用户界面层
┌──────────────────────────────────────────────────────┐
│               前端 (React 19 + Vite 7)                │
│  - 调用 Node.js后端的 REST API                        │
│  - 不直接调用 Python微服务和Dify                      │
│  - 通过反向代理 (/api/) 路由到后端                    │
└──────────────────────────────────────────────────────┘
                        ▲
                        │ HTTP/HTTPS
                        │
─────────────────────────────────────────────────────────

L3: 业务逻辑层
┌──────────────────────────────────────────────────────┐
│          Node.js 后端 (Fastify + Prisma)             │
│  - 业务逻辑聚合                                       │
│  - 权限控制                                           │
│  - 调用 Python微服务 (内网HTTP)                      │
│  - 调用 Dify API (内网HTTP)                          │
│  - 数据库访问 (Prisma ORM)                           │
└──────────────────────────────────────────────────────┘
           ▲                  ▲                ▲
           │                  │                │
           │ (内网)            │ (内网)          │ (Prisma)
           │                  │                │
    ┌──────┴────────┐  ┌──────┴──────┐  ┌────▼──────┐
    │ Python微服务   │  │  Dify平台   │  │ PostgreSQL│
    └───────────────┘  └─────────────┘  └───────────┘

─────────────────────────────────────────────────────────

L2: 能力支撑层
┌────────────────────────────┐  ┌────────────────────────────┐
│     Python 微服务           │  │     Dify RAG 平台           │
│  (FastAPI + PyMuPDF)       │  │  (知识库 + LLM)            │
├────────────────────────────┤  ├────────────────────────────┤
│  - PDF解析 (ASL模块)        │  │  - 文档上传分块             │
│  - Docx/Txt提取 (ASL)       │  │  - Embedding向量化          │
│  - 数据清洗 (DC模块)        │  │  - 向量检索                 │
│  - Polars数据处理           │  │  - LLM对话生成              │
│  - OCR识别 (Nougat)         │  │  - RAG流程编排              │
│                            │  │                            │
│  依赖：                    │  │  依赖：                    │
│  - OSS (读取文件)           │  │  - Weaviate (向量存储)      │
│  - RDS (存储结果，可选)     │  │  - PostgreSQL (Dify专用)    │
│                            │  │  - Redis (Dify缓存)         │
└────────────────────────────┘  └────────────────────────────┘
           ▲                                ▲
           │                                │
           └────────────┬───────────────────┘
                        │
─────────────────────────────────────────────────────────

L1: 基础设施层
┌────────────────────┐  ┌────────────────┐  ┌──────────────┐
│  PostgreSQL 15     │  │   OSS对象存储  │  │  Redis (可选) │
│  (RDS)             │  │   (文件存储)   │  │  (Dify专用)   │
├────────────────────┤  ├────────────────┤  ├──────────────┤
│ - 10个Schema隔离   │  │ - PDF文件      │  │ - Dify缓存    │
│ - pg-boss任务队列  │  │ - Word/Excel   │  │ - Dify会话    │
│ - 用户数据         │  │ - 文献数据     │  │              │
│ - 业务数据         │  │ - 清洗结果     │  │ (初期不需要   │
│ - Prisma ORM访问   │  │ - SDK访问      │  │  Redis，可用  │
│                    │  │ - 内网免流量   │  │  Postgres替代)│
└────────────────────┘  └────────────────┘  └──────────────┘

2. 模块间调用关系表

调用方	被调用方	调用方式	调用目的	网络
前端	Node.js后端	HTTP REST API	所有业务功能	公网（HTTPS）
Node.js后端	Python微服务	HTTP REST API	PDF解析、数据清洗	内网（VPC）
Node.js后端	Dify API	HTTP REST API	知识库管理、RAG检索	内网（VPC）
Node.js后端	PostgreSQL	Prisma ORM	数据CRUD、事务	内网（VPC）
Node.js后端	OSS	SDK (ali-oss)	文件上传/下载	内网（VPC）
Python微服务	OSS	SDK (oss2)	读取PDF/Excel	内网（VPC）
Python微服务	PostgreSQL	可选（直接SQL）	读取配置数据	内网（VPC）
Dify	Weaviate	gRPC	向量存储/检索	本地（Dify内部）
Dify	PostgreSQL	原生驱动	Dify元数据	本地（Dify内部）
Dify	Redis	原生驱动	Dify缓存	本地（Dify内部）

关键原则：

• ✅ 单一入口：前端只调用 Node.js后端，不直接调用其他服务
• ✅ 内网通信：SAE内部服务通过内网互联（免流量费，低延迟）
• ✅ 服务隔离：Dify独立部署在ECS，通过内网暴露API
• ✅ 数据持久化：核心数据统一存储在RDS，文件存储在OSS

3. 模块责任边界

模块	核心职责	不负责
前端	- 用户交互 - 页面渲染 - 路由管理 - API调用	❌ 业务逻辑 ❌ 权限校验 ❌ 直接访问数据库/OSS
Node.js后端	- 业务逻辑聚合 - 权限控制 - API网关 - 数据库访问 - 调度微服务	❌ PDF解析 ❌ 数据清洗 ❌ 向量检索
Python微服务	- PDF解析 - 文档提取 - 数据清洗 - OCR识别	❌ 业务逻辑 ❌ 权限控制 ❌ 数据库CRUD
Dify平台	- 知识库管理 - 向量存储 - RAG检索 - LLM对话	❌ 用户认证 ❌ 业务数据存储 ❌ 权限管理
PostgreSQL	- 业务数据持久化 - 事务管理 - 任务队列（pg-boss）	❌ 文件存储 ❌ 缓存（可选）
OSS	- 文件存储 - 静态资源 - 备份归档	❌ 结构化数据 ❌ 实时计算

---

模块与阿里云服务映射

1. 服务映射表

核心模块	阿里云服务	规格配置	成本估算	部署文档
前端 (React)	SAE容器实例	0.5核1GB × 1实例	¥50/月	06-前端Nginx-SAE容器部署指南
Node.js后端	SAE容器实例	1核2GB × 2实例（弹性）	¥200/月	05-Node.js后端-SAE容器部署指南
Python微服务	SAE容器实例	1核2GB × 1实例（⚠️ 如OOM升至4GB）	¥100-200/月	04-Python微服务-SAE容器部署指南
Dify平台	ECS服务器	4核8GB（独立）	¥300/月	03-Dify-ECS部署完全指南
PostgreSQL 15	RDS PostgreSQL	2核4GB (rds.pg.s2.large)	¥400/月	PostgreSQL部署策略-摸底报告
文件存储	OSS标准存储	按量付费（50GB）	¥10/月	（各模块文档中包含）
⭐ NAT网关	NAT网关 + EIP	小规格NAT + 按量EIP	¥60-100/月	⚠️ 必需（SAE访问公网）
容器镜像	ACR容器镜像仓库	个人版（免费）	¥0/月	（各模块文档中包含）
VPC网络	VPC专有网络	默认配置	¥0/月	（各模块文档中包含）
域名/CDN	（可选）未来配置	-	¥50/月	-

总成本估算： ¥1,200-1,350/月（初期配置，含NAT网关）

⚠️ 成本优化说明：

• NAT网关（¥100/月）是生产环境标配，不建议省略
• 替代方案：SAE绑定EIP（¥30-50/月，部分地域支持，稳定性较差）或ECS做SNAT（¥0，配置复杂，不推荐）
• Python服务如遇OOM，需升级至4GB内存（增加¥100/月）

2. SAE与5个模块的关系

2.1 SAE部署的模块（3个）

┌────────────────────────────────────────────────────────────────┐
│              SAE (Serverless Application Engine)               │
│                      弹性伸缩 + 按需付费                        │
├────────────────────────────────────────────────────────────────┤
│                                                                │
│  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────┐│
│  │  前端Nginx容器   │  │ Node.js后端容器  │  │ Python容器   ││
│  ├──────────────────┤  ├──────────────────┤  ├──────────────┤│
│  │ 实例数：1        │  │ 实例数：2-10     │  │ 实例数：1-3  ││
│  │ CPU: 0.5核       │  │ CPU: 1核         │  │ CPU: 1核     ││
│  │ 内存: 1GB        │  │ 内存: 2GB        │  │ 内存: 2GB    ││
│  │ 健康检查: /      │  │ 健康检查: /health│  │ 健康检查: /health││
│  │ 自动伸缩: 关闭   │  │ 自动伸缩: 开启   │  │ 自动伸缩: 开启││
│  └──────────────────┘  └──────────────────┘  └──────────────┘│
│                                                                │
│  共同特性：                                                    │
│  ✅ Docker容器部署（镜像从ACR拉取）                            │
│  ✅ 内网互联（免流量费）                                       │
│  ✅ 自动扩缩容（基于CPU/内存/QPS）                             │
│  ✅ 滚动发布（零停机部署）                                     │
│  ✅ 健康检查（自动重启异常实例）                               │
│  ✅ 日志自动收集（stdout/stderr → SLS）                        │
│  ✅ 环境变量注入（DATABASE_URL等敏感信息）                     │
│                                                                │
└────────────────────────────────────────────────────────────────┘

SAE的核心价值：

1. 弹性伸缩：流量高峰自动扩容，低谷自动缩容
2. 按需付费：只为实际使用的资源付费
3. 零运维：无需管理服务器，自动故障转移
4. 快速部署：从镜像启动实例<30秒

2.2 非SAE部署的模块（2个）

模块	部署方式	原因
Dify平台	ECS + Docker Compose	- 服务复杂（7个容器） - 需要稳定IP（内网调用） - 独立数据库/Redis - 不需要弹性伸缩
PostgreSQL 15	RDS托管服务	- 企业级数据库 - 自动备份/PITR - 高可用（主从） - 无需自己运维

3. OSS与5个模块的关系

3.1 OSS使用场景

模块	使用OSS的场景	读/写	Bucket目录结构
Node.js后端	- 用户上传文件 - 文档管理 - 临时文件中转	读/写	/uploads/{userId}/{fileId}.pdf
Python微服务	- 读取PDF进行解析 - 读取Excel进行清洗 - 写入处理结果	读/写	/asl/literatures/ /dc/extracted/
Dify平台	- （可选）上传文档到OSS - Dify内部使用本地存储	不使用	-
前端	- 不直接访问OSS - 通过后端API上传/下载	不使用	-
PostgreSQL	- （可选）备份归档到OSS	不使用	/backups/

3.2 OSS Bucket设计

aiclinical-data-prod (Bucket名称)
│
├── uploads/                          # 用户上传的原始文件
│   ├── {userId}/
│   │   ├── {fileId}.pdf
│   │   ├── {fileId}.docx
│   │   └── {fileId}.xlsx
│   │
├── asl/                              # ASL智能文献模块
│   ├── literatures/                  # 文献PDF
│   │   └── {projectId}/{litId}.pdf
│   ├── extracted/                    # 提取的文本
│   │   └── {projectId}/{litId}.json
│   │
├── dc/                               # DC数据清洗模块
│   ├── raw/                          # 原始数据文件
│   │   └── {taskId}/data.xlsx
│   ├── cleaned/                      # 清洗后的数据
│   │   └── {taskId}/result.xlsx
│   │
├── pkb/                              # PKB个人知识库模块
│   ├── documents/                    # 知识库文档
│   │   └── {kbId}/{docId}.pdf
│   │
└── backups/                          # 数据库备份（可选）
    └── {date}/ai_clinical_research.sql.gz

OSS配置要点：

• ✅ 内网访问：SAE通过内网访问OSS（免流量费）
• ✅ 权限控制：使用RAM角色授权，不暴露AccessKey
• ✅ 生命周期：临时文件30天后自动删除
• ✅ 跨域配置：如果前端直传，需配置CORS

4. RDS与5个模块的关系

4.1 RDS访问权限

模块	数据库名称	访问用户	权限	连接方式
Node.js后端	ai_clinical_research	aiclinical_rw	SELECT/INSERT/UPDATE/DELETE	Prisma ORM
Python微服务	ai_clinical_research	aiclinical_rw（可选）	SELECT（只读配置）	psycopg2（可选）
Dify平台	❌ 不使用主RDS	-	-	Dify使用独立PostgreSQL
前端	❌ 不直接访问	-	-	通过后端API
PostgreSQL	-	postgres（超级用户）	ALL	仅用于迁移/备份

连接池配置：

总连接数：400（RDS默认）
├── Node.js后端：200 (2实例 × 10连接/实例，预留180)
├── Python微服务：50 (1实例 × 5连接/实例，预留45)
├── pg-boss：50 (后台任务)
├── 预留：100 (管理、备份、临时扩容)

---

开发环境与部署环境

1. 环境对比表

维度	本地开发环境	阿里云部署环境
前端	Vite Dev Server (localhost:3000)	SAE Nginx容器 (HTTPS)
Node.js后端	tsx watch (localhost:3001)	SAE容器 (内网 + 公网)
Python微服务	uvicorn (localhost:8000)	SAE容器 (内网)
Dify平台	Docker Compose (localhost)	ECS Docker Compose (内网)
PostgreSQL	Docker (localhost:5432)	RDS (内网地址)
OSS	本地文件系统 (./uploads)	阿里云OSS
Redis	❌ 不使用（Postgres-Only）	❌ 不使用（Dify独立Redis）

2. 开发与部署的平滑迁移

2.1 配置管理策略

项目根目录/
│
├── backend/
│   ├── .env.local              # 本地开发配置（不提交Git）
│   ├── .env.example            # 配置模板（提交Git）
│   └── src/config/env.ts       # 配置加载逻辑
│
├── frontend-v2/
│   ├── .env.local              # 本地开发配置
│   ├── .env.production         # 生产环境配置模板
│   └── vite.config.ts          # Vite配置
│
└── extraction_service/
    ├── .env.local              # 本地开发配置
    └── app/config.py           # Python配置加载

配置加载优先级：

环境变量 > .env.local > .env > 代码默认值

2.2 环境变量对比

本地开发 (.env.local)：

# 数据库
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/ai_clinical_research

# 存储
STORAGE_TYPE=local
LOCAL_STORAGE_DIR=./uploads

# 缓存/队列
CACHE_TYPE=memory
QUEUE_TYPE=memory

# 微服务
DIFY_API_URL=http://localhost/v1
EXTRACTION_SERVICE_URL=http://localhost:8000

阿里云部署（SAE环境变量配置）：

# 数据库（⚠️ 敏感信息，SAE加密存储）
DATABASE_URL=postgresql://aiclinical_rw:强密码@rm-xxxxx.pg.rds.aliyuncs.com:5432/ai_clinical_research?connection_limit=10&pool_timeout=10

# 存储（OSS）
STORAGE_TYPE=oss
OSS_REGION=cn-hangzhou
OSS_BUCKET=aiclinical-data-prod
OSS_ACCESS_KEY_ID=LTAI5***（SAE环境变量）
OSS_ACCESS_KEY_SECRET=***（SAE加密）

# 缓存/队列（Postgres-Only）
CACHE_TYPE=postgres
QUEUE_TYPE=pgboss

# 微服务（内网地址）⚠️ 使用内网IP，不要用.sae域名
DIFY_API_URL=http://172.16.x.x/v1
EXTRACTION_SERVICE_URL=http://172.16.x.x:8000
# ⚠️ 注意：
# - 172.16.x.x 需要替换为实际的内网IP
# - 获取方式：SAE控制台 > 应用详情 > 实例列表 > 查看内网IP
# - ❌ 不要使用 .sae 或 .cluster.local 域名（K8s服务发现需要额外配置）

# 生产环境标识
NODE_ENV=production

3. 持续部署流程（CI/CD）

3.1 整体流程图

┌──────────────────────────────────────────────────────────────────┐
│                   开发者本地开发                                   │
│  1. 修改代码                                                      │
│  2. 本地测试（npm run dev / pytest）                             │
│  3. Git提交（git commit -m "feat: xxx"）                         │
│  4. 推送到远程仓库（git push origin main）                        │
└────────────────────────────┬─────────────────────────────────────┘
                             │
                             ▼
┌──────────────────────────────────────────────────────────────────┐
│               CI/CD 流水线（未来：GitHub Actions）                 │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │ Stage 1: 构建与测试                                         │ │
│  ├────────────────────────────────────────────────────────────┤ │
│  │  - npm install / pip install                               │ │
│  │  - npm run build / docker build                            │ │
│  │  - npm test / pytest                                       │ │
│  │  - Lint检查 (eslint / flake8)                              │ │
│  └────────────────────────────────────────────────────────────┘ │
│                             │                                    │
│                             ▼                                    │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │ Stage 2: Docker镜像构建                                     │ │
│  ├────────────────────────────────────────────────────────────┤ │
│  │  - docker build -t frontend:v1.2.3                         │ │
│  │  - docker build -t backend:v1.2.3                          │ │
│  │  - docker build -t python-service:v1.2.3                   │ │
│  └────────────────────────────────────────────────────────────┘ │
│                             │                                    │
│                             ▼                                    │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │ Stage 3: 推送到ACR容器镜像仓库                               │ │
│  ├────────────────────────────────────────────────────────────┤ │
│  │  - docker tag ... registry.cn-hangzhou.aliyuncs.com/...   │ │
│  │  - docker push registry.cn-hangzhou.aliyuncs.com/...      │ │
│  └────────────────────────────────────────────────────────────┘ │
│                             │                                    │
│                             ▼                                    │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │ Stage 4: 部署到SAE                                          │ │
│  ├────────────────────────────────────────────────────────────┤ │
│  │  - SAE触发滚动部署                                          │ │
│  │  - 健康检查 -> 切换流量                                     │ │
│  │  - 自动回滚（如果失败）                                     │ │
│  └────────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────────┘
                             │
                             ▼
┌──────────────────────────────────────────────────────────────────┐
│                   生产环境运行                                     │
│  - 健康检查监控                                                   │
│  - 日志收集分析                                                   │
│  - 性能指标监控                                                   │
└──────────────────────────────────────────────────────────────────┘

3.2 初期手工部署流程（推荐）

阶段1：初期（1-2人团队，前3个月）

# ===== 前端部署 =====
cd frontend-v2
npm run build                                    # 构建生产版本
docker build -t frontend:v1.0.0 .                # 构建Docker镜像
docker tag frontend:v1.0.0 registry.cn-hangzhou.aliyuncs.com/your-namespace/frontend:v1.0.0
docker push registry.cn-hangzhou.aliyuncs.com/your-namespace/frontend:v1.0.0
# 在SAE控制台点击"部署" -> 选择新镜像 -> 确认

# ===== 后端部署 =====
cd backend
npm run build                                    # 编译TypeScript
docker build -t backend:v1.0.0 .
docker tag backend:v1.0.0 registry.cn-hangzhou.aliyuncs.com/your-namespace/backend:v1.0.0
docker push registry.cn-hangzhou.aliyuncs.com/your-namespace/backend:v1.0.0
# 在SAE控制台点击"部署" -> 选择新镜像 -> 确认

# ===== Python微服务部署 =====
cd extraction_service
docker build -t python-service:v1.0.0 .
docker tag python-service:v1.0.0 registry.cn-hangzhou.aliyuncs.com/your-namespace/python-service:v1.0.0
docker push registry.cn-hangzhou.aliyuncs.com/your-namespace/python-service:v1.0.0
# 在SAE控制台点击"部署" -> 选择新镜像 -> 确认

优势：

• ✅ 简单直接，学习成本低
• ✅ 完全可控，出错容易排查
• ✅ 无需配置CI/CD工具

阶段2：成长期（3-10人团队，3个月后）

配置GitHub Actions或阿里云云效自动化部署。

3.3 部署频率建议

模块	部署频率	建议时间	回滚策略
前端	每周1-2次	周五下午	SAE一键回滚（保留3个版本）
Node.js后端	每周1-2次	周五下午	SAE一键回滚 + 数据库回滚脚本
Python微服务	每2周1次	周五下午	SAE一键回滚
Dify平台	按需（很少）	周末	Docker Compose重启旧镜像
PostgreSQL	按需（迁移）	周末凌晨	RDS快照恢复

4. 开发到部署的检查清单

4.1 代码准备

☐ 1. 本地测试通过
   ├─ npm run dev / uvicorn正常运行
   ├─ 核心功能手工测试
   └─ 单元测试/集成测试通过（如果有）

☐ 2. 代码审查
   ├─ Lint检查通过（eslint / flake8）
   ├─ 代码格式化（prettier / black）
   └─ 无敏感信息泄漏（.env文件不提交）

☐ 3. 环境变量确认
   ├─ 所有生产环境变量已配置到SAE
   ├─ 数据库连接字符串正确（含connection_limit）
   └─ OSS/Dify等外部服务地址正确

4.2 Docker镜像构建

☐ 4. Dockerfile优化
   ├─ 使用多阶段构建（减小镜像体积）
   ├─ 基础镜像版本固定（如 node:22-alpine，不用latest）
   ├─ 非root用户运行（安全）
   └─ 健康检查配置正确

☐ 5. 镜像构建与测试
   ├─ docker build成功
   ├─ docker run本地测试通过
   ├─ 镜像大小合理（前端<100MB，后端<300MB，Python<1GB）
   └─ 镜像打标签（版本号）

4.3 部署到SAE

☐ 6. 部署前准备
   ├─ 备份数据库（RDS手动快照）
   ├─ 通知团队（如果是重大变更）
   └─ 准备回滚方案

☐ 7. SAE部署
   ├─ 推送镜像到ACR
   ├─ SAE选择新镜像版本
   ├─ 滚动发布（灰度发布，逐个实例替换）
   └─ 观察日志和监控

☐ 8. 部署后验证
   ├─ 健康检查端点返回200
   ├─ 核心功能冒烟测试
   ├─ 日志无ERROR
   └─ 监控指标正常（CPU/内存/响应时间）

☐ 9. 回滚准备（如果失败）
   ├─ SAE一键回滚到上一版本
   ├─ 数据库恢复快照（如果有Schema变更）
   └─ 排查问题日志

---

Docker版本管理策略

1. 镜像版本命名规范

1.1 语义化版本 (Semantic Versioning)

格式：{服务名}:{主版本}.{次版本}.{修订版本}[-{环境}]

示例：
frontend:1.0.0          # 生产版本
frontend:1.0.0-dev      # 开发版本
frontend:1.1.0          # 功能更新
frontend:1.1.1          # Bug修复

版本号规则：

• 主版本 (Major)：重大架构变更，不兼容旧版本（如 1.x.x → 2.x.x）
• 次版本 (Minor)：新增功能，向下兼容（如 1.0.x → 1.1.x）
• 修订版本 (Patch)：Bug修复，完全兼容（如 1.0.0 → 1.0.1）

1.2 标签策略

标签类型	示例	用途	保留策略
版本号	v1.2.3	正式发布版本	永久保留
latest	latest	最新稳定版	自动更新
dev	dev	开发测试版	滚动保留最近10个
Git SHA	sha-a1b2c3d	特定提交版本	按需保留
日期	20251214	按日期归档	保留30天

完整示例：

# 构建时打多个标签
docker build -t frontend:v1.2.3 \
             -t frontend:latest \
             -t frontend:sha-a1b2c3d \
             -t frontend:20251214 \
             .

# 推送到ACR
docker tag frontend:v1.2.3 registry.cn-hangzhou.aliyuncs.com/aiclinical/frontend:v1.2.3
docker tag frontend:v1.2.3 registry.cn-hangzhou.aliyuncs.com/aiclinical/frontend:latest
docker push registry.cn-hangzhou.aliyuncs.com/aiclinical/frontend:v1.2.3
docker push registry.cn-hangzhou.aliyuncs.com/aiclinical/frontend:latest

2. 本地版本管理

2.1 本地是否需要版本管理？

答案：初期不需要，成长期建议轻量管理。

阶段	本地管理策略	原因
初期（1-2人）	❌ 不需要	- 开发者少，口头协调即可 - 本地镜像只用于测试 - 直接推送到ACR统一管理
成长期（3-10人）	✅ 轻量管理	- 使用Git标签管理版本 - package.json/pyproject.toml记录版本 - 本地镜像定期清理

2.2 本地镜像清理

# 查看本地镜像
docker images | grep frontend

# 删除未使用的镜像（保留最近3个版本）
docker image prune -a --filter "until=720h"  # 删除30天前的镜像

# 删除所有未使用的镜像（危险，慎用）
docker image prune -a

建议清理频率：

• 开发机：每周清理一次
• CI/CD服务器：每次构建后自动清理

3. ACR容器镜像仓库管理

3.1 镜像仓库结构

阿里云容器镜像服务 (ACR)
├── 命名空间: aiclinical（团队共享）
│   │
│   ├── 仓库: frontend
│   │   ├── latest（自动更新）
│   │   ├── v1.0.0
│   │   ├── v1.0.1
│   │   ├── v1.1.0
│   │   └── ... (保留最近20个版本)
│   │
│   ├── 仓库: backend
│   │   ├── latest
│   │   ├── v1.0.0
│   │   ├── v1.0.1
│   │   └── ...
│   │
│   ├── 仓库: python-service
│   │   ├── latest
│   │   ├── v1.0.0
│   │   └── ...
│   │
│   └── 仓库: dify (可选，如果自定义构建)
│       └── v0.6.13
│
└── 个人版免费配额：3个命名空间，无限仓库数，300GB存储/月

3.2 镜像生命周期管理

保留策略：

规则1: 保留最新的20个版本标签
规则2: 保留所有带"v"前缀的正式版本（v1.0.0、v1.1.0等）
规则3: 自动清理30天前的dev/test标签
规则4: latest标签永久保留

ACR配置示例（控制台配置）：

容器镜像服务 > 仓库管理 > frontend > 生命周期规则
├─ 规则1: 保留最近20个版本
│   ├─ 类型: 按数量保留
│   ├─ 保留数量: 20
│   └─ 标签匹配: *
│
└─ 规则2: 清理旧的dev标签
    ├─ 类型: 按时间清理
    ├─ 保留时间: 30天
    └─ 标签匹配: *-dev

4. 版本与Git的关系

4.1 Git标签与Docker标签同步

# 开发流程
git add .
git commit -m "feat: add user profile page"
git push origin main

# 发布版本时创建Git标签
git tag -a v1.2.3 -m "Release v1.2.3: Add user profile"
git push origin v1.2.3

# 构建Docker镜像（版本号与Git标签一致）
docker build -t frontend:v1.2.3 .
docker tag frontend:v1.2.3 registry.cn-hangzhou.aliyuncs.com/aiclinical/frontend:v1.2.3
docker push registry.cn-hangzhou.aliyuncs.com/aiclinical/frontend:v1.2.3

4.2 自动版本号管理（可选）

方法1：从 package.json 读取版本号

// frontend-v2/package.json
{
  "name": "aiclinical-frontend",
  "version": "1.2.3",
  ...
}

# 构建脚本自动读取版本号
VERSION=$(node -p "require('./package.json').version")
docker build -t frontend:v$VERSION .

方法2：从Git提交SHA生成版本号

# 使用Git SHA作为版本号（适合CI/CD）
GIT_SHA=$(git rev-parse --short HEAD)
docker build -t frontend:sha-$GIT_SHA .

5. 版本管理工具推荐

工具	用途	适用阶段
Git Tags	代码版本管理	✅ 所有阶段
package.json/pyproject.toml	应用版本声明	✅ 所有阶段
Docker Labels	镜像元数据标记	✅ 成长期+
语义化版本工具 (semantic-release)	自动版本号生成	可选（成熟期）
Harbor/ACR版本管理	镜像仓库治理	✅ 成长期+

---

线上故障快速修复

1. 故障分级与修复策略

故障等级	影响范围	修复策略	预期RTO	示例
P0（致命）	全站不可用	立即回滚	<5分钟	数据库连接失败、应用启动失败
P1（严重）	核心功能不可用	回滚或热修复	<30分钟	用户无法登录、文件上传失败
P2（一般）	部分功能异常	热修复或下个版本	<2小时	某个页面报错、样式错乱
P3（轻微）	用户体验问题	下个版本修复	<1天	文案错误、图标缺失

2. 修复方案对比

修复方法	适用场景	操作步骤	优点	缺点	推荐度
方案1：SAE一键回滚	P0/P1故障	SAE控制台点击"回滚"	✅ 最快（<5分钟） ✅ 零风险	❌ 回到旧版本，新功能丢失	⭐⭐⭐⭐⭐
方案2：热修复（重新部署完整镜像）	P1/P2故障	修改代码→构建镜像→推送→部署	✅ 彻底修复 ✅ 保留新功能	❌ 慢（10-30分钟） ❌ 需要完整构建	⭐⭐⭐⭐
方案3：单文件热更新（不推荐）	❌ 不推荐	SSH进容器→修改文件	✅ 快	❌ 容器重启后丢失 ❌ 无版本记录 ❌ 违反Docker理念	⭐
方案4：配置热更新	配置错误	SAE环境变量→重启应用	✅ 快（<5分钟） ✅ 无需重新构建	❌ 只适用于配置问题	⭐⭐⭐⭐

3. 详细修复流程

3.1 方案1：SAE一键回滚（推荐）⭐⭐⭐⭐⭐

适用场景：

• 新版本部署后发现严重Bug
• 性能急剧下降
• 功能完全不可用

操作步骤：

步骤1: 登录阿里云控制台 → SAE
步骤2: 选择问题应用（如 aiclinical-backend）
步骤3: 点击"部署历史"
步骤4: 找到上一个稳定版本（如 v1.2.2）
步骤5: 点击"回滚"按钮
步骤6: 确认 → SAE自动执行滚动回滚
步骤7: 观察健康检查和日志
步骤8: 验证功能恢复

预计时间：3-5分钟

SAE回滚机制：

回滚过程（滚动回滚，零停机）
├── 阶段1: 从ACR拉取旧版本镜像
├── 阶段2: 启动1个旧版本实例
├── 阶段3: 健康检查通过后，切换流量到旧实例
├── 阶段4: 逐步停止新版本实例
├── 阶段5: 全部实例回滚完成
└── 时间：2-3分钟（2实例的情况）

回滚后的处理：

☐ 1. 验证核心功能恢复
☐ 2. 通知团队回滚完成
☐ 3. 分析故障原因（日志/监控）
☐ 4. 修复Bug（本地测试充分）
☐ 5. 重新部署修复版本

3.2 方案2：热修复（重新部署完整Docker镜像）⭐⭐⭐⭐

适用场景：

• 无法回滚（旧版本也有问题）
• Bug已定位且修复简单
• 需要保留新功能

操作步骤：

# ===== 场景：后端API返回500错误 =====

# 步骤1: 本地复现问题
npm run dev
# 测试API: POST /api/v1/users
# 错误日志: TypeError: Cannot read property 'email' of undefined

# 步骤2: 修复代码
# backend/src/modules/users/userService.ts
# 修复：添加空值校验
if (!userData || !userData.email) {
  throw new Error('Email is required')
}

# 步骤3: 本地测试通过
npm run dev
# 重新测试API → 200 OK

# 步骤4: 构建新镜像（版本号升级）
npm run build
docker build -t backend:v1.2.4 .  # 修订版本号+1

# 步骤5: 推送到ACR
docker tag backend:v1.2.4 registry.cn-hangzhou.aliyuncs.com/aiclinical/backend:v1.2.4
docker push registry.cn-hangzhou.aliyuncs.com/aiclinical/backend:v1.2.4

# 步骤6: SAE部署
# 控制台 → 部署 → 镜像版本: v1.2.4 → 确认 → 滚动发布

# 步骤7: 观察部署过程
# SAE日志实时查看 → 无ERROR → 健康检查通过

# 步骤8: 验证修复
curl -X POST https://api.your-domain.com/api/v1/users \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com"}'
# 返回: 200 OK

# 步骤9: 更新Git
git add .
git commit -m "hotfix: add email validation in userService"
git tag v1.2.4
git push origin main
git push origin v1.2.4

预计时间：10-30分钟

代码修复: 5分钟
构建镜像: 3-5分钟（Node.js后端）
推送镜像: 1-2分钟
SAE部署: 2-3分钟
验证: 2分钟
Git提交: 1分钟

3.3 方案3：单文件热更新（❌不推荐，仅紧急情况）

为什么不推荐？

1. ❌ 容器重启后丢失：容器是无状态的，重启后修改消失
2. ❌ 无版本记录：无法追溯修改历史
3. ❌ 多实例不一致：SAE有多个实例，只修改一个实例无效
4. ❌ 违反Docker理念：容器应该是不可变的

如果必须使用（极端紧急情况）：

# ⚠️ 仅供紧急情况参考，不推荐

# 步骤1: 登录SAE实例（通过云助手）
# SAE控制台 → 实例列表 → 登录实例

# 步骤2: 找到文件位置
cd /app
ls -la

# 步骤3: 修改文件
vi src/modules/users/userService.js
# 修改错误的代码

# 步骤4: 重启应用（SAE会自动重启）
# ⚠️ 注意：这个修改只在当前实例生效，重启后丢失

# 步骤5: 立即准备正式修复（方案2）
# 本地修改 → 构建镜像 → 部署

总结：除非系统完全崩溃且无法回滚，否则不要使用单文件热更新！

3.4 方案4：配置热更新（环境变量）⭐⭐⭐⭐

适用场景：

• 数据库连接字符串错误
• API密钥/Token过期
• 外部服务地址变更
• Feature Flag开关

操作步骤：

# 场景：Dify API地址配置错误

步骤1: SAE控制台 → 选择应用 → 环境变量
步骤2: 找到错误的变量
    DIFY_API_URL=http://172.16.1.100/v1  # ❌ 错误IP

步骤3: 修改为正确值
    DIFY_API_URL=http://172.16.2.50/v1   # ✅ 正确IP

步骤4: 保存 → SAE提示"需要重启应用"
步骤5: 点击"重启应用" → 滚动重启（零停机）
步骤6: 观察日志 → 连接成功
步骤7: 验证功能恢复

预计时间：3-5分钟

环境变量修改的注意事项：

• ✅ 修改后必须重启应用才能生效
• ✅ 滚动重启，不影响服务可用性
• ⚠️ 敏感信息（密码）修改后，记得更新本地 .env.example
• ⚠️ 如果涉及数据库迁移，确保数据库已准备好

4. 故障预防与监控

4.1 预防措施

☐ 1. 充分的本地测试
   ├─ 核心功能手工测试
   ├─ 边界条件测试
   └─ 与生产环境类似的数据测试

☐ 2. 灰度发布（SAE支持）
   ├─ 先部署到1个实例（10%流量）
   ├─ 观察10-30分钟
   └─ 无问题后全量发布

☐ 3. 健康检查完善
   ├─ /health 端点检查数据库连接
   ├─ /health 端点检查外部服务（Dify/OSS）
   └─ 健康检查失败自动重启

☐ 4. 监控告警
   ├─ 错误日志告警（SLS）
   ├─ API响应时间告警（ARMS）
   └─ 数据库连接数告警（RDS监控）

☐ 5. 自动化测试（未来）
   ├─ 单元测试（Jest / Pytest）
   ├─ 集成测试（Supertest / Playwright）
   └─ CI/CD中自动执行

4.2 监控指标

指标类型	监控指标	告警阈值	处理措施
应用监控	错误率	>5%	立即查看日志，考虑回滚
应用监控	API响应时间	>2秒	检查数据库慢查询、外部服务
应用监控	健康检查失败	>3次	自动重启实例，检查依赖服务
数据库监控	连接数	>80%	检查连接泄漏，增加连接池
数据库监控	慢查询	>1秒	优化SQL，添加索引
容器监控	CPU使用率	>70%	检查死循环，考虑扩容
容器监控	内存使用率	>80%	检查内存泄漏，重启实例

5. 故障修复决策树

                    ┌─────────────────┐
                    │  发现线上故障   │
                    └────────┬────────┘
                             │
                    ┌────────▼────────┐
                    │ 影响范围评估？   │
                    └────┬────────────┘
                         │
              ┌──────────┼──────────┐
              │                     │
      ┌───────▼────────┐    ┌──────▼────────┐
      │  全站不可用     │    │ 部分功能异常  │
      │  (P0/P1)       │    │  (P2/P3)      │
      └───────┬────────┘    └──────┬────────┘
              │                     │
      ┌───────▼────────┐    ┌──────▼────────┐
      │ 能否快速定位？  │    │ 能否快速修复？ │
      └───┬────────┬───┘    └──┬────────┬───┘
          │ No     │ Yes       │ Yes    │ No
          │        │           │        │
    ┌─────▼──┐ ┌──▼─────┐ ┌──▼──┐ ┌───▼────┐
    │ 立即   │ │ 是配置 │ │ 热修│ │ 下个版 │
    │ 回滚   │ │ 问题？ │ │ 复  │ │ 本修复 │
    └────────┘ └──┬──┬──┘ └─────┘ └────────┘
                  │  │
            ┌─────▼──▼────┐
            │ 修改环境变量 │
            │ + 重启应用   │
            └──────────────┘

---

部署文档导航

📚 独立部署文档清单

#	文档名称	部署对象	目标环境	预计时间
1	PostgreSQL部署策略-摸底报告	PostgreSQL 15数据库	RDS PostgreSQL 15	10分钟（pg_dump导入）
2	Dify-ECS部署完全指南	Dify RAG平台	ECS + Docker Compose	30-60分钟
3	Python微服务-SAE容器部署指南	Python微服务	SAE容器实例	20-30分钟
4	Node.js后端-SAE容器部署指南	Node.js后端	SAE容器实例	20-30分钟
5	前端Nginx-SAE容器部署指南	React前端	SAE容器实例	15-20分钟

总部署时间： 约2-3小时（从0到全部上线）

🎯 部署顺序建议

第一阶段：基础设施（Day 1）⭐ 必需
├── 1. 创建VPC和安全组 (10分钟)
├── 2. ⭐ 创建NAT网关 + 绑定EIP (15分钟) ← 新增，必需！
├── 3. 部署RDS PostgreSQL 15 (10分钟，等待实例创建15分钟)
├── 4. 导入数据库（pg_dump） (5分钟)
└── 5. 创建OSS Bucket (5分钟)
    └── 配置生命周期、权限

第二阶段：核心服务（Day 1）⚠️ 临时配置
├── 6. 部署Node.js后端到SAE (20分钟)
│   └── ⚠️ DIFY_API_KEY=temp（临时值，等Dify部署后更新）
├── 7. 部署Python微服务到SAE (20分钟)
└── 8. 端到端测试（后端API + Python服务） (15分钟)

第三阶段：用户界面（Day 2）
├── 9. 部署前端到SAE (15分钟)
└── 10. 完整功能测试（不含PKB模块） (30分钟)

第四阶段：Dify服务（Day 2-3）⭐ PKB模块必需
├── 11. 部署Dify到ECS (60分钟)
├── 12. 登录Dify生成API Key (5分钟)
├── 13. 更新后端DIFY_API_KEY环境变量 (5分钟)
└── 14. 测试PKB知识库功能 (15分钟)

总计：约4-5小时（实际操作时间，不含等待）

📖 如何使用这些文档？

新团队首次部署

步骤1: 阅读本《部署架构总览》
   ├─ 理解整体架构
   ├─ 理解模块依赖关系
   └─ 熟悉阿里云服务

步骤2: 按顺序阅读独立部署文档
   ├─ PostgreSQL部署策略（理解数据库架构）
   ├─ Node.js后端部署（核心服务）
   ├─ Python微服务部署（能力支撑）
   ├─ 前端Nginx部署（用户界面）
   └─ Dify部署（可选，PKB模块需要）

步骤3: 准备阿里云账号和资源
   ├─ 实名认证
   ├─ 充值（建议¥500起步）
   ├─ 创建RAM子账号（安全）
   └─ 开通SAE/RDS/OSS/ACR服务

步骤4: 按第一阶段→第二阶段→第三阶段顺序部署
   └─ 每个阶段完成后测试验证

步骤5: 监控与优化
   ├─ 配置告警规则
   ├─ 观察7天运行情况
   └─ 根据实际情况调整规格

已有系统维护

日常开发部署:
├─ 修改代码
├─ 本地测试
├─ 构建Docker镜像
├─ 推送到ACR
└─ SAE控制台部署

线上故障处理:
├─ 参考"线上故障快速修复"章节
├─ P0/P1: 立即回滚
├─ P2/P3: 热修复或下个版本
└─ 故障复盘，更新文档

新模块上线:
├─ 参考对应的独立部署文档
├─ 确认依赖服务（数据库/OSS/其他服务）
├─ 灰度发布（先1个实例）
└─ 全量发布

🔗 文档间的引用关系

00-部署架构总览.md (本文档)
│
├──► PostgreSQL部署策略-摸底报告.md
│    ├─ 数据库架构详解
│    ├─ pg_dump导入流程
│    ├─ 备份策略
│    └─ 最佳实践
│
├──► 03-Dify-ECS部署完全指南.md
│    ├─ Docker Compose配置
│    ├─ Nginx路由层
│    ├─ Swap配置
│    └─ 故障排查
│
├──► 04-Python微服务-SAE容器部署指南.md
│    ├─ Dockerfile多阶段构建
│    ├─ 系统依赖安装（PyTorch/OpenCV）
│    ├─ SAE配置
│    └─ 内网调用
│
├──► 05-Node.js后端-SAE容器部署指南.md
│    ├─ Prisma反向同步（db pull）
│    ├─ 数据库连接池
│    ├─ 优雅关闭
│    └─ 环境变量配置
│
└──► 06-前端Nginx-SAE容器部署指南.md
     ├─ SPA路由配置
     ├─ API反向代理
     ├─ 静态资源缓存
     └─ envsubst动态配置

---

🛡️ 安全与最佳实践

1. 时区统一配置 ⭐⭐⭐⭐⭐

问题： 不同服务的时区不一致会导致：

• 日志时间对不上（前端14:00，后端06:00）
• pg-boss定时任务在错误时间触发
• 用户看到的时间戳错误

解决： 所有服务统一使用 Asia/Shanghai 时区

# backend/Dockerfile - Node.js后端
FROM node:22-alpine AS runtime
RUN apk add --no-cache tzdata
ENV TZ=Asia/Shanghai
# ... 其他配置

# extraction_service/Dockerfile - Python微服务
FROM python:3.11-slim AS runtime
RUN apt-get update && apt-get install -y tzdata
ENV TZ=Asia/Shanghai
RUN ln -snf /usr/share/zoneinfo/$TZ /etc/localtime && echo $TZ > /etc/timezone
# ... 其他配置

# frontend-v2/Dockerfile - 前端（已配置）
FROM nginx:1.25-alpine
RUN apk add --no-cache tzdata
ENV TZ=Asia/Shanghai
# ... 其他配置

-- RDS PostgreSQL 时区配置
-- RDS控制台 > 参数设置 > timezone
timezone = Asia/Shanghai

验证时区：

# 查看容器时区
docker exec <container-id> date
# 应该显示：Sat Dec 14 14:30:00 CST 2024

# 查看RDS时区
psql -c "SHOW timezone;"
# 应该显示：Asia/Shanghai

2. 安全组配置最佳实践 ⭐⭐⭐⭐⭐

ECS安全组配置（Dify服务器）

正确配置：

# ECS控制台 > 安全组 > 配置规则

# ✅ 入方向规则（Inbound）
允许 80/TCP    来源：172.16.0.0/12   # Nginx（VPC内网访问）
允许 22/TCP    来源：您的办公室公网IP # SSH管理
拒绝 所有       来源：0.0.0.0/0       # 默认拒绝

⚠️ 安全红线（绝对禁止）：

# ❌ 禁止 5000/TCP（Dify API）对公网开放
# 后果：黑客可绕过后端消耗LLM额度

# ❌ 禁止 8080/TCP（Weaviate）对公网开放
# 后果：向量数据可能被窃取

# ❌ 禁止 6379/TCP（Redis）对公网开放
# 后果：Redis无密码，可能被清空

# ✅ 正确：docker-compose.yaml中端口绑定
services:
  redis:
    ports:
      - "127.0.0.1:6379:6379"  # 只监听本地
  weaviate:
    ports:
      - "127.0.0.1:8080:8080"  # 只监听本地

验证安全配置：

# 从公网测试（应该失败）
telnet ECS公网IP 6379
# 应该超时或拒绝连接

# 从VPC内测试（应该成功）
curl http://172.16.x.x  # Dify内网地址
# 应该返回 Dify 响应

🔗 详细配置： 参考 03-Dify-ECS部署完全指南.md

3. 镜像拉取策略 ⭐⭐⭐⭐⭐

问题： SAE可能不会拉取新镜像（代码不更新的"灵异事件"）

# 场景：
开发者修改代码 → 构建镜像 → 推送到ACR（覆盖v1.0.0）
→ SAE部署 → 发现代码没更新？？？

# 原因：
SAE默认镜像拉取策略可能是 IfNotPresent
如果本地已有 v1.0.0，不会重新拉取

解决方案：

方案	适用环境	优势	劣势
方案A：版本号管理	生产环境	版本可追溯，稳定	需手动递增版本号
方案B：Always拉取	测试环境	始终最新，方便	每次重启拉取，慢

方案A：每次部署使用新版本号（强烈推荐）

# 使用语义化版本号
v1.0.0 → v1.0.1 → v1.0.2 ...

# 或使用时间戳
v20251214-1430 → v20251214-1530 ...

# 或使用Git SHA
v-a1b2c3d → v-b2c3d4e ...

方案B：配置SAE镜像拉取策略

# SAE控制台 > 应用配置 > 镜像设置
镜像拉取策略：Always

# ⚠️ 注意：
# - 每次重启都会拉取镜像（启动稍慢）
# - 适合测试环境，不推荐生产环境

4. 开发调试最佳实践

本地连接RDS数据库（SSH隧道）

场景： 开发人员需要用Navicat/DBeaver查看RDS数据

问题： RDS在VPC内网，本地无法直接访问

解决： 通过ECS建立SSH隧道

# 步骤1：建立SSH隧道
ssh -N -L 5433:rm-xxxxx.pg.rds.aliyuncs.com:5432 \
    root@ECS公网IP \
    -i ~/.ssh/dify-ecs.pem

# 参数说明：
# -N: 不执行远程命令，只建立隧道
# -L: 本地端口转发
# 5433: 本地监听端口（避免与本地PostgreSQL 5432冲突）
# rm-xxxxx: RDS内网地址
# 5432: RDS端口

# 步骤2：Navicat/DBeaver连接配置
主机：localhost
端口：5433
用户名：aiclinical_rw
密码：（RDS密码）
数据库：ai_clinical_research

# 步骤3：测试连接
# 应该成功连接到RDS！

后台运行（可选）：

# 方法1：nohup后台运行
nohup ssh -N -L 5433:rm-xxxxx.pg.rds.aliyuncs.com:5432 \
    root@ECS-IP -i key.pem > /dev/null 2>&1 &

# 方法2：保持隧道运行（新终端窗口）
ssh -N -L 5433:rm-xxxxx.pg.rds.aliyuncs.com:5432 \
    root@ECS-IP -i key.pem
# 保持此终端窗口打开

🔗 详细步骤参考： 07-关键配置补充说明.md 第7节

5. Python服务内存管理 ⭐⭐⭐⭐

问题： Python服务（PyMuPDF/Nougat）内存密集，容易OOM

场景	CPU	内存	Workers	适用情况
基础版	1核	2GB	2	简单PDF解析
标准版	2核	4GB	3	包含OCR（Nougat）
增强版	2核	8GB	4	大量OCR + 高并发

⚠️ 重要提示：

• 如果遇到OOM（Out of Memory），优先升级内存至4GB
• 或者限制Gunicorn并发数：--workers 1 --threads 2
• PyMuPDF + Nougat OCR单个请求可能占用500MB-1GB内存

Dockerfile优化（已应用）：

CMD ["gunicorn", "main:app", \
     "--bind", "0.0.0.0:8000", \
     "--workers", "2", \
     "--timeout", "120", \
     "--max-requests", "100", \
     "--max-requests-jitter", "10"]

🔗 详细配置： 参考 04-Python微服务-SAE容器部署指南.md

6. NAT网关成本优化

当前方案：NAT网关（推荐）

成本：NAT网关¥60/月 + EIP流量费¥30-50/月 = ¥90-110/月
优势：稳定可靠，生产环境标配
劣势：成本相对较高

替代方案（不推荐，仅供参考）：

方案	成本	稳定性	复杂度	推荐度
NAT网关	¥100/月	⭐⭐⭐⭐⭐	低	⭐⭐⭐⭐⭐（推荐）
SAE绑定EIP	¥30-50/月	⭐⭐⭐	中	⭐⭐⭐（部分地域）
ECS做SNAT	¥0（复用ECS）	⭐⭐	高	⭐⭐（不推荐）

建议： 初创团队不要在这里省钱，NAT网关是生产环境的标配。

---

📝 总结与建议

核心架构特点

1. ✅ 云原生Serverless架构

   • 前端/后端/Python全部容器化部署到SAE
   • 弹性伸缩，按需付费
   • 零运维，自动故障转移

2. ✅ 微服务隔离

   • 5个核心模块职责清晰
   • 内网通信，免流量费
   • 独立部署，互不影响

3. ✅ 数据安全可控

   • PostgreSQL 10个Schema隔离
   • RDS自动备份 + PITR
   • VPC内网隔离，白名单控制

4. ✅ 适合初创团队

   • 1-2人可运维
   • 手工部署简单直接
   • 成本可控（¥1,100/月起）

下一步行动

☐ 第1周：基础设施搭建
   ├─ 阿里云账号准备
   ├─ VPC/RDS/OSS创建
   └─ 数据库导入

☐ 第2周：核心服务部署
   ├─ Node.js后端上线
   ├─ Python微服务上线
   ├─ 前端上线
   └─ 端到端测试

☐ 第3周：可选服务 + 监控
   ├─ Dify部署（如需PKB模块）
   ├─ 配置监控告警
   └─ 压力测试

☐ 第4周：稳定性优化
   ├─ 根据监控数据调整资源
   ├─ 故障演练（回滚、修复）
   └─ 文档完善

持续改进建议

阶段	改进方向	优先级
3个月内	- 完善监控告警 - 编写运维手册 - 故障演练	⭐⭐⭐⭐⭐
6个月内	- 配置CI/CD - 自动化测试 - 性能优化	⭐⭐⭐⭐
1年内	- 跨地域灾备 - 容器编排升级（ACK） - 微服务治理	⭐⭐⭐

---

文档创建人： AI助手
最后更新： 2025-12-14
版本： v1.0

核心理念：架构清晰、职责分离、云原生、易于运维 ⭐⭐⭐