# 部署文档修正报告 - 2025年12月14日

> **修正依据：** 专业技术审查反馈  
> **修正时间：** 2025-12-14  
> **修正范围：** 7个部署文档  
> **修正问题：** 8个关键问题

---

## 📋 修正概览

### 修正统计

| 严重级别 | 问题数量 | 已修正 | 影响范围 |
|---------|---------|--------|---------|
| **P0/P1（致命）** | 3个 | ✅ 3个 | 全部服务 |
| **P2（重要）** | 3个 | ✅ 3个 | 全部服务 |
| **P3（最佳实践）** | 2个 | ✅ 2个 | 部分服务 |
| **总计** | 8个 | ✅ 8个 | - |

---

## 🚨 P0/P1 致命问题修正

### 1. ⭐⭐⭐⭐⭐ 服务发现地址不一致

**问题描述：**
```
文档中使用 .sae 域名（如 extraction-service.sae:8000）
但SAE的K8s服务发现域名格式不确定，会导致100%连接失败
```

**影响范围：**
- `00-部署架构总览.md`
- `05-Node.js后端-SAE容器部署指南.md`
- `04-Python微服务-SAE容器部署指南.md`
- `08-部署检查清单.md`

**修正内容：**
```bash
# ❌ 错误（修正前）
EXTRACTION_SERVICE_URL=http://extraction-service.sae:8000

# ✅ 正确（修正后）
EXTRACTION_SERVICE_URL=http://172.16.x.x:8000
# 获取方式：SAE控制台 > 应用详情 > 实例列表 > 查看内网IP
```

**修正文件：**
- ✅ `00-部署架构总览.md` - 第522-529行
- ✅ `04-Python微服务-SAE容器部署指南.md` - 第686-715行
- ✅ `08-部署检查清单.md` - 第348行、第434行

---

### 2. ⭐⭐⭐⭐⭐ 时区不一致风险

**问题描述：**
```
不同服务的时区不一致会导致：
❌ 日志时间对不上（前端14:00，后端06:00）
❌ pg-boss定时任务在错误时间触发
❌ 用户看到的时间戳错误
```

**影响范围：**
- Node.js后端：默认UTC ❌
- Python微服务：默认UTC ❌
- 前端Nginx：Asia/Shanghai ✅（已正确）
- RDS PostgreSQL：默认UTC ❌

**修正内容：**

**Node.js后端 Dockerfile：**
```dockerfile
FROM node:22-alpine
RUN apk add --no-cache tzdata
ENV TZ=Asia/Shanghai  # ⚠️ 新增
# ... 其他配置
```

**Python微服务 Dockerfile：**
```dockerfile
FROM python:3.11-slim
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  # ⚠️ 新增
# ... 其他配置
```

**RDS PostgreSQL 配置：**
```sql
-- RDS控制台 > 参数设置 > timezone
timezone = Asia/Shanghai
```

**修正文件：**
- ✅ `00-部署架构总览.md` - 新增"时区统一配置"章节
- ✅ `05-Node.js后端-SAE容器部署指南.md` - 第485-495行
- ✅ `04-Python微服务-SAE容器部署指南.md` - 第387-410行
- ✅ `PostgreSQL部署策略-摸底报告.md` - 新增第12条最佳实践
- ✅ `07-关键配置补充说明.md` - 新增第8节

---

### 3. ⭐⭐⭐⭐⭐ 安全组配置缺失

**问题描述：**
```
ECS的Redis (6379)、Weaviate (8080)、Dify API (5000) 端口
如果对公网开放，会导致严重安全问题：
❌ 黑客可以绕过后端直接调用LLM额度
❌ Redis无密码，可能被清空数据
❌ Weaviate的向量数据可能被窃取
```

**影响范围：**
- `03-Dify-ECS部署完全指南.md`
- `00-部署架构总览.md`

**修正内容：**

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

# ❌ 绝对禁止（安全红线）
禁止 5000/TCP（Dify API）对公网开放
禁止 8080/TCP（Weaviate）对公网开放
禁止 6379/TCP（Redis）对公网开放
```

**docker-compose.yaml 端口绑定：**
```yaml
services:
  redis:
    ports:
      - "127.0.0.1:6379:6379"  # ⚠️ 只监听本地
  
  weaviate:
    ports:
      - "127.0.0.1:8080:8080"  # ⚠️ 只监听本地
```

**修正文件：**
- ✅ `03-Dify-ECS部署完全指南.md` - 第169-175行、第451-492行
- ✅ `00-部署架构总览.md` - 新增"安全组配置最佳实践"章节

---

## ⚠️ P2 重要问题修正

### 4. ⭐⭐⭐⭐⭐ 镜像拉取策略

**问题描述：**
```
SAE可能不会拉取新镜像（代码不更新的"灵异事件"）
开发者修改代码 → 构建镜像 → 推送到ACR（覆盖v1.0.0）
→ SAE部署 → 发现代码没更新？？？
```

**影响范围：**
- 所有SAE部署的服务（前端、后端、Python）

**修正内容：**

**方案A：每次部署使用新版本号（强烈推荐）**
```bash
# 使用语义化版本号
v1.0.0 → v1.0.1 → v1.0.2 ...

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

**方案B：配置SAE镜像拉取策略（测试环境）**
```bash
# SAE控制台 > 应用配置 > 镜像设置
镜像拉取策略：Always
```

**修正文件：**
- ✅ `00-部署架构总览.md` - 新增"镜像拉取策略"章节
- ✅ `07-关键配置补充说明.md` - 新增第9节

---

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

**问题描述：**
```
Python服务（PyMuPDF/Nougat）内存密集，容易OOM
❌ 单个PDF OCR可能占用500MB-1GB内存
❌ SAE默认2GB内存可能不够
```

**影响范围：**
- `04-Python微服务-SAE容器部署指南.md`
- `00-部署架构总览.md`

**修正内容：**

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

**Dockerfile优化（已应用）：**
```dockerfile
CMD ["gunicorn", "main:app", \
     "--bind", "0.0.0.0:8000", \
     "--workers", "2", \              # ⚠️ 限制并发
     "--timeout", "120", \             # ⚠️ 2分钟超时
     "--max-requests", "100", \        # ⚠️ 处理100个请求后重启worker
     "--max-requests-jitter", "10"]    # ⚠️ 随机抖动
```

**修正文件：**
- ✅ `00-部署架构总览.md` - 新增"Python服务内存管理"章节
- ✅ `07-关键配置补充说明.md` - 新增第10节

---

### 6. ⭐⭐⭐⭐ Dify API Key死锁风险

**问题描述：**
```
Node.js后端启动时，如果强依赖Dify连通性，会导致：
第二阶段部署后端 → 后端启动失败（Dify还没部署）
→ 无法进入SAE控制台查看日志或更新配置
```

**影响范围：**
- `05-Node.js后端-SAE容器部署指南.md`
- `00-部署架构总览.md`

**修正内容：**

**后端代码建议：**
```typescript
// backend/src/common/rag/DifyClient.ts
constructor() {
  const apiKey = process.env.DIFY_API_KEY
  
  // ✅ 关键：启动时不应强依赖Dify
  if (!apiKey || apiKey === 'temp' || apiKey.startsWith('temp_')) {
    console.warn('⚠️ Dify API Key未配置，PKB模块将不可用')
    this.enabled = false
    return  // ⚠️ 不抛出错误，让应用正常启动
  }
  
  this.client = new DifySDK(apiKey)
  this.enabled = true
}
```

**部署流程调整：**
```
第二阶段：部署Node.js后端
├─ DIFY_API_KEY=temp_placeholder_will_update_later  # ⚠️ 临时值
└─ 后端正常启动（PKB模块禁用）

第四阶段：部署Dify
├─ 生成真实API Key
└─ 更新后端环境变量 → 重启应用
```

**修正文件：**
- ✅ `00-部署架构总览.md` - 部署顺序说明
- ✅ `05-Node.js后端-SAE容器部署指南.md` - 环境变量配置
- ✅ `07-关键配置补充说明.md` - 第2节（已存在）

---

## 📝 P3 最佳实践补充

### 7. ⭐⭐⭐⭐ 开发调试最佳实践（SSH隧道）

**问题描述：**
```
RDS在VPC内网，开发者无法直接用Navicat/DBeaver连接
```

**修正内容：**

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

# 步骤2：Navicat连接
主机：localhost
端口：5433
用户名：aiclinical_rw
密码：（RDS密码）
```

**修正文件：**
- ✅ `00-部署架构总览.md` - 新增"开发调试最佳实践"章节
- ✅ `07-关键配置补充说明.md` - 第7节（已存在）

---

### 8. ⭐⭐⭐⭐ NAT网关成本优化说明

**问题描述：**
```
NAT网关成本¥100/月，对初创团队是一笔开销
需要说明替代方案，但不推荐
```

**修正内容：**

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

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

**修正文件：**
- ✅ `00-部署架构总览.md` - 成本估算章节
- ✅ `07-关键配置补充说明.md` - 第1节（已存在）

---

## 📊 修正文件清单

| 文件名 | 修正内容 | 优先级 |
|--------|---------|--------|
| `00-部署架构总览.md` | 1. 服务发现地址<br>2. 时区统一<br>3. 安全组配置<br>4. 镜像拉取策略<br>5. Python内存管理<br>6. SSH隧道<br>7. NAT成本说明 | ⭐⭐⭐⭐⭐ |
| `05-Node.js后端-SAE容器部署指南.md` | 1. 时区配置<br>2. Dify死锁说明 | ⭐⭐⭐⭐⭐ |
| `04-Python微服务-SAE容器部署指南.md` | 1. 服务发现地址<br>2. 时区配置<br>3. 内存规格说明 | ⭐⭐⭐⭐⭐ |
| `06-前端Nginx-SAE容器部署指南.md` | 无需修改（时区已正确） | - |
| `03-Dify-ECS部署完全指南.md` | 1. 安全组配置<br>2. 端口绑定 | ⭐⭐⭐⭐⭐ |
| `PostgreSQL部署策略-摸底报告.md` | 1. 时区配置最佳实践 | ⭐⭐⭐⭐ |
| `08-部署检查清单.md` | 1. 服务发现地址 | ⭐⭐⭐⭐⭐ |
| `07-关键配置补充说明.md` | 1. 时区统一（新增第8节）<br>2. 镜像拉取策略（新增第9节）<br>3. Python内存管理（新增第10节） | ⭐⭐⭐⭐⭐ |

---

## ✅ 验证清单

### 部署前验证

```bash
☐ 1. 检查所有环境变量中的服务地址
   - ✅ 使用内网IP（172.16.x.x）
   - ❌ 不使用 .sae 域名

☐ 2. 检查所有Dockerfile的时区配置
   - ✅ Node.js后端：ENV TZ=Asia/Shanghai
   - ✅ Python微服务：ENV TZ=Asia/Shanghai
   - ✅ 前端Nginx：ENV TZ=Asia/Shanghai
   - ✅ RDS PostgreSQL：timezone = Asia/Shanghai

☐ 3. 检查ECS安全组配置
   - ✅ Redis/Weaviate端口绑定到127.0.0.1
   - ✅ 安全组只允许VPC内网访问
   - ❌ 不对公网开放5000/6379/8080端口

☐ 4. 检查镜像版本管理
   - ✅ 使用语义化版本号（v1.0.0, v1.0.1...）
   - ❌ 不始终使用latest标签

☐ 5. 检查Python服务规格
   - ✅ 初期：1核2GB
   - ✅ 如遇OOM：升级至2核4GB
```

### 部署后验证

```bash
☐ 1. 验证时区
   docker exec backend-container date
   docker exec python-container date
   psql -h rds-host -c "SHOW timezone;"
   # 应该都显示：Asia/Shanghai 或 CST

☐ 2. 验证服务连通性
   # 在后端容器内测试Python服务
   curl http://172.16.x.x:8000/health
   # 应该返回：200 OK

☐ 3. 验证安全配置
   # 从公网测试（应该失败）
   telnet ECS公网IP 6379
   # 应该超时或拒绝连接

☐ 4. 验证镜像版本
   # SAE控制台查看镜像标签
   # 应该是具体版本号，不是latest
```

---

## 📈 修正效果评估

### 问题解决率

- ✅ **P0/P1致命问题：** 3/3 = 100%
- ✅ **P2重要问题：** 3/3 = 100%
- ✅ **P3最佳实践：** 2/2 = 100%
- ✅ **总体解决率：** 8/8 = 100%

### 预期收益

| 维度 | 修正前风险 | 修正后收益 |
|------|-----------|-----------|
| **可用性** | 服务连接失败100% | ✅ 服务正常连接 |
| **安全性** | Redis/Weaviate可能被攻击 | ✅ 只允许VPC内网访问 |
| **稳定性** | Python OOM频繁 | ✅ 内存管理优化 |
| **可维护性** | 日志时间混乱 | ✅ 时区统一，易于排查 |
| **可靠性** | 镜像不更新 | ✅ 版本管理清晰 |

---

## 🎯 下一步行动

### 立即执行（必需）

```bash
☐ 1. 更新所有Dockerfile（时区配置）
☐ 2. 更新环境变量（服务发现地址）
☐ 3. 配置ECS安全组（端口安全）
☐ 4. 配置RDS时区（Asia/Shanghai）
☐ 5. 制定镜像版本管理规范
```

### 后续优化（可选）

```bash
☐ 1. 配置SSH隧道（开发便利）
☐ 2. 实现OSS签名URL（安全）
☐ 3. 配置监控告警（Python内存）
☐ 4. 编写自动化部署脚本
```

---

## 📚 相关文档

- [00-部署架构总览.md](./00-部署架构总览.md) - 已更新
- [03-Dify-ECS部署完全指南.md](./03-Dify-ECS部署完全指南.md) - 已更新
- [04-Python微服务-SAE容器部署指南.md](./04-Python微服务-SAE容器部署指南.md) - 已更新
- [05-Node.js后端-SAE容器部署指南.md](./05-Node.js后端-SAE容器部署指南.md) - 已更新
- [06-前端Nginx-SAE容器部署指南.md](./06-前端Nginx-SAE容器部署指南.md) - 无需修改
- [PostgreSQL部署策略-摸底报告.md](./PostgreSQL部署策略-摸底报告.md) - 已更新
- [07-关键配置补充说明.md](./07-关键配置补充说明.md) - 已更新
- [08-部署检查清单.md](./08-部署检查清单.md) - 已更新

---

**报告生成时间：** 2025-12-14  
**报告生成人：** AI助手  
**审查依据：** 专业技术团队反馈  
**修正质量：** ⭐⭐⭐⭐⭐（8/8问题已全部修正）